how-to/build-locally.md

How to Build Locally

This guide covers building Dynaplex components and services for local development.

Quick Start

# Build everything
dotnet build acsis-core.slnx

# Run via Aspire AppHost
dotnet run --project projects/bbu-rfid/src/Acsis.Dynaplex.Projects.BbuRfid/

Development Builds

Build the Entire Solution

# Clean everything first
dotnet clean acsis-core.slnx

# Build all components and services
dotnet build acsis-core.slnx

# Build with verbose output for debugging
dotnet build acsis-core.slnx --verbosity detailed

# Restore packages only
dotnet restore acsis-core.slnx

Build Individual Components

# Build a specific component
dotnet build engines/core-data/src/Acsis.Dynaplex.Engines.CoreData.Abstractions/
dotnet build engines/core-data/src/Acsis.Dynaplex.Engines.CoreData/

# Build all components in parallel
find engines/ -name "*.csproj" -not -path "*/test/*" | xargs -P 4 -I {} dotnet build {}

Build the Aspire AppHost

# Build the orchestrator
dotnet build projects/bbu-rfid/src/Acsis.Dynaplex.Projects.BbuRfid/

# Run the orchestrator (starts all services)
dotnet run --project projects/bbu-rfid/src/Acsis.Dynaplex.Projects.BbuRfid/

# Run with specific environment
dotnet run --project projects/bbu-rfid/src/Acsis.Dynaplex.Projects.BbuRfid/ --environment Development

Build the UI Component

# Navigate to UI directory
cd engines/assettrak-ui/src/assettrak-ui/

# Install dependencies
npm install

# Development build (with hot reload)
npm run dev

# Production build
npm run build
npm start

Understanding the Build Process

Service Projects

Each component is now a standalone ASP.NET Core service:

<!-- Acsis.Dynaplex.Engines.MyFeature/Acsis.Dynaplex.Engines.MyFeature.csproj -->
<Project Sdk="Microsoft.NET.Sdk.Web">
    <PropertyGroup>
        <TargetFramework>net9.0</TargetFramework>
    </PropertyGroup>

    <ItemGroup>
        <!-- Reference your own abstractions -->
        <ProjectReference Include="$(MyFeatureAbstractions)" />
    </ItemGroup>
</Project>

Aspire Orchestration

The AppHost coordinates all services:

// In projects/bbu-rfid/src/Acsis.Dynaplex.Projects.BbuRfid/Program.cs
var builder = DistributedApplication.CreateBuilder(args);

// Add PostgreSQL
var postgres = builder.AddPostgres("postgres")
    .WithPgAdmin();

var db = postgres.AddDatabase("acsis");

// Add component services
var coreData = builder.AddProject<Acsis_Components_CoreData>("core-data")
    .WithReference(db);

var identity = builder.AddProject<Acsis_Components_Identity>("identity")
    .WithReference(db)
    .WithReference(coreData);

builder.Build().Run();

Build Configurations

Debug vs Release

# Debug build (default, includes symbols)
dotnet build acsis-core.slnx

# Release build (optimized, no symbols)
dotnet build acsis-core.slnx --configuration Release

# Publish for deployment
dotnet publish projects/bbu-rfid/src/Acsis.Dynaplex.Projects.BbuRfid/ \
    -c Release \
    -o ./publish

Environment-Specific Builds

# Development
ASPNETCORE_ENVIRONMENT=Development dotnet build

# Staging
ASPNETCORE_ENVIRONMENT=Staging dotnet build

# Production
ASPNETCORE_ENVIRONMENT=Production dotnet build

Build Optimization

Parallel Builds

# Use all available CPU cores
dotnet build acsis-core.slnx --maxcpucount:0

# Limit to 4 parallel processes
dotnet build acsis-core.slnx --maxcpucount:4

Incremental Builds

# Incremental build (default - faster)
dotnet build

# Full rebuild (slower but ensures consistency)
dotnet build --no-incremental

Build Graph

# Use build graph for optimal build order
dotnet build --graph acsis-core.slnx

Troubleshooting

Build Fails

Check for errors:

dotnet build acsis-core.slnx 2>&1 | tee build.log

Common issues:

Missing NuGet packages → Run dotnet restore
Circular dependencies → Check project references
Analyzer errors (ACSIS0001) → Only reference .Abstractions projects

Slow Builds

Enable binary logging to analyze:

dotnet build --verbosity normal \
    --logger:"Microsoft.Build.Logging.BinaryLogger,Microsoft.Build.Logging;buildlog.binlog"

# View with MSBuild Structured Log Viewer: https://msbuildlog.com/

Clean Build

When incremental builds cause issues:

# Clean everything
dotnet clean acsis-core.slnx

# Delete bin/obj folders
find . -type d \( -name "bin" -o -name "obj" \) -exec rm -rf {} +

# Rebuild
dotnet build acsis-core.slnx

Running Locally

Via Aspire AppHost

# Start all services
dotnet run --project projects/bbu-rfid/src/Acsis.Dynaplex.Projects.BbuRfid/

# Access Aspire Dashboard
open https://localhost:15045

Individual Service

# Run single component service
dotnet run --project engines/core-data/src/Acsis.Dynaplex.Engines.CoreData/

# Access service Swagger UI
open https://localhost:40443/swagger

With Docker Compose (Local Infrastructure)

# Start PostgreSQL, MQTT broker, etc.
docker-compose -f docker-compose.dev.yml up -d

# Run services
dotnet run --project projects/bbu-rfid/src/Acsis.Dynaplex.Projects.BbuRfid/

Development Workflow

Make changes to component code
Build the affected component(s)
Run tests for those components
Run via AppHost to test integration
Verify in Aspire Dashboard

# Example workflow
dotnet build engines/core-data/
dotnet test engines/core-data/test/
dotnet run --project projects/bbu-rfid/src/Acsis.Dynaplex.Projects.BbuRfid/

Next Steps

Deploy your application - Production deployment
Run tests - Testing guide
Troubleshoot issues - Common problems

Quick Reference

Task	Command
Build everything	`dotnet build acsis-core.slnx`
Build component	`dotnet build engines/{name}/`
Run AppHost	`dotnet run --project projects/bbu-rfid/src/Acsis.Dynaplex.Projects.BbuRfid/`
Clean build	`dotnet clean && dotnet build`
Build + run	`dotnet build && dotnet run --project projects/bbu-rfid/src/Acsis.Dynaplex.Projects.BbuRfid/`
View logs	Check Aspire Dashboard at https://localhost:15045

Documentation