Skip to main content

Local Development

.NET Aspire provides a unified dashboard for all services:

cd Wayd.AppHost
dotnet run

Benefits:

  • Unified telemetry dashboard (traces, metrics, logs)
  • Automatic OpenTelemetry instrumentation
  • Dynamic port assignment with service discovery

The dashboard opens in your browser once the host is up, already signed in. Aspire itself only prints the link — Visual Studio is what opens it on Windows, so dotnet run and aspire run on Linux and macOS would otherwise leave you to click it. The AppHost opens it on every platform, and stands down when Visual Studio is launching one so Windows doesn't get two tabs. It is at https://localhost:17153 (http://localhost:15206 with the http launch profile).

Set WAYD_NO_LAUNCH_BROWSER=true to keep it from opening. On Linux it honours $BROWSER when your desktop sets one, falling back to xdg-open.

Use the proxy ports, not the ones the processes bind​

Aspire's orchestrator (dcp) listens on the configured ports and forwards to whatever port each service actually bound. Use those:

ServiceAddress
Clienthttp://localhost:3000
APIhttp://localhost:5150, https://localhost:7021

Reaching a service on the port its process bound — which is dynamic, and is what a port scan or the process list will show you — works for the API but breaks the client: the browser then sends an origin the API's CORS allowlist does not contain, so every request fails, including the login page's own call to /api/auth/providers. The symptom is a page that renders with nothing on it and a console full of CORS errors, which reads like a code fault and is not one.

A stale NEXT_PUBLIC_API_BASE_URL in .env.local produces the same symptom for a different reason, and is worth ruling out second rather than first: NEXT_PUBLIC_* values are inlined at build time, so removing one does nothing until .next is cleared and the client rebuilt.

Startup gate and dashboard commands​

Before the API starts, the AppHost runs it once as resources setup, which provisions the Wolverine outbox tables in the wolverine schema; the API waits for that run to finish. The wayd-api resource's Actions → Commands add the read-only JasperFx verbs (check-env, describe, codegen preview) and Reset Database.

Resetting the database​

Reset Database is the only supported way to reset a local database. It asks for confirmation, stops the API, drops and recreates the database, and starts the API again, which re-applies migrations and reference data and prints a new first-run token. Every row is lost.

The AppHost reads its target from DatabaseSettings:ConnectionString in database.json and the API's user secrets — not from database.Development.json — so set the connection string in user secrets (see Prerequisites → Database), or the command fails with no database to reset. Don't drop a Wayd database any other way.

Common Tasks​

Adding a Database Migration​

dotnet ef migrations add <MigrationName> \
  --project "Wayd.Infrastructure/src/Wayd.Infrastructure.Migrators.MSSQL" \
  --startup-project "Wayd.Web/src/Wayd.Web.Api"

Running Tests​

# All tests — the integration suites start SQL Server containers, so Docker must be running
dotnet test Wayd.slnx

# Only the tests that need no Docker
./.github/scripts/dotnet-test-projects.sh unit

# Specific project
dotnet test "Wayd.Services/Wayd.Work/tests/Wayd.Work.Application.Tests/Wayd.Work.Application.Tests.csproj"

# Filtered tests, within one project
dotnet test "<project>" --filter "FullyQualifiedName~ProjectServiceTests"

# Frontend tests
cd Wayd.Web/src/wayd.web.reactclient
npm test

See Testing for the unit/integration split, test traits, and the shared-container conventions.

Architecture Tests​

dotnet test Wayd.ArchitectureTests/Wayd.ArchitectureTests.csproj

These tests enforce Clean Architecture dependency rules across the solution.

VS Code Launch Configurations​

  • Compound: Launch Wayd on Host - Runs API and client natively
  • Compound: Launch Wayd with Compose - Full stack via Docker Compose
  • Debug Wayd API on Host, Docker: Attach to API in Docker - The API alone
  • Next.js: debug server-side / client-side / full stack, Browser: Launch Wayd React Client in Chrome - The client alone

Debugging​

  • Backend: Attach to the Wayd.Web.Api process or use VS Code launch config
  • Frontend: Use browser DevTools or VS Code debugger
  • Logs: Check Aspire dashboard or Seq (Docker) for structured logs