AspireC4.Hosting 13.3.0-prerelease.2

AspireC4.Hosting

AspireC4.Hosting is an Aspire extension library that auto-generates live LikeC4 architecture diagrams from the Aspire resource graph. Diagrams update in real-time as resources start, stop, or produce errors — and each element links back to the corresponding Aspire dashboard page.

Prerequisites

• Docker (required by default) — the LikeC4 server runs as a ghcr.io/likec4/likec4 container sidecar.
• Alternatively, use .WithLocalCLI() to run via a locally-installed Node.js CLI (npx, pnpm, yarn, bun, or deno).

Quick start

// AppHost/Program.cs
var builder = DistributedApplication.CreateBuilder(args);

// Add your services ...
var api = builder.AddProject<Projects.MyApi>("my-api");

// Register the LikeC4 visualization sidecar.
builder.AddAspireC4();

builder.Build().Run();

This:

1. Writes a ./likec4/model.gen.c4 file from the Aspire resource graph.
2. Starts a ghcr.io/likec4/likec4 Docker container serving the live diagram.
3. Watches for resource state changes and regenerates the file automatically.

How it works

Data flow

Aspire resources
     │
     ▼
LikeC4ModelBuilder.Build()   ← resource states, dashboard URL
     │
     ▼
LikeC4DSLGenerator.Generate()
     │
     ▼
./likec4/model.gen.c4         ← written to disk (and Docker volume)
     │
     ▼
ghcr.io/likec4/likec4        ← serves the diagram, hot-reloads on file change

Resource state colours

Each Aspire resource is represented as a LikeC4 element. Its colour reflects the live runtime state:

Dashboard deep-links

When IncludeAspireDashboardLinks is enabled (the default), each LikeC4 element receives two links:

• Dashboard: Console Logs → /consolelogs/resource/{name}
• Dashboard: Structured Logs → /structuredlogs/resource/{name}

How links are constructed

Links are built at runtime once the Aspire dashboard resource reaches the Running state. The lifecycle hook watches ResourceNotificationService for the "aspire-dashboard" resource and extracts the first non-internal URL's scheme://authority.

With a browser token (default Aspire setup):

https://localhost:15086/login?t=<encoded-token>&returnUrl=<encoded-path>

The token comes from configuration["AppHost:BrowserToken"]. The login redirect authenticates the browser before navigating to the resource page, matching Aspire's dashboard auth flow.

Without a browser token:

https://localhost:15086/consolelogs/resource/my-api

Security

• The browser token is read from IConfiguration (injected by Aspire's AppHost process). It is not written to any file — it is only embedded in the generated .c4 file as part of the link URLs.
• The generated .c4 file is a local development artifact; treat it with the same care as other AppHost output files.
• Links are only injected once the dashboard base URL is discovered; diagrams generated before the dashboard starts will not contain links (regeneration fires automatically when the dashboard starts).

Disabling dashboard links

builder.AddAspireC4(options =>
{
    options.IncludeAspireDashboardLinks = false;
});

Configuration reference

All options are set on AspireC4DiagramOptions:

Alternative modes

Local CLI (WithLocalCLI)

Uses a locally-installed likec4 CLI (via npx/pnpm/yarn/bun/deno) instead of the Docker container:

builder.AddAspireC4().WithLocalCLI();

Hide from dashboard (WithHideFromDashboard)

Removes the LikeC4 sidecar resource from the Aspire dashboard resource list and surfaces the diagram URL as a link and command on each ProjectResource:

builder.AddAspireC4().WithHideFromDashboard();

Exclusion

A resource is excluded from the diagram if:

• It carries an ExcludeFromLikeC4Annotation, OR
• Its ResourceSnapshotAnnotation.InitialSnapshot.IsHidden == true (Aspire internal resources).

The LikeC4 sidecar resource itself is always excluded.

Limitations

• Static diagram tool: LikeC4 renders a static (file-based) diagram. State updates require a HMR refresh.
• Dashboard URL discovery: If the Aspire dashboard hasn't started yet when the first diagram is generated, dashboard links will be absent until the dashboard reaches Running and triggers a regeneration.
• Browser token in generated file: The Aspire browser token appears in the .c4 file embedded in dashboard link URLs. Do not commit the generated file to source control.
• Windows HMR relay: On Windows, a TCP relay bridges the fixed host port 24678 to the dynamically-allocated Docker port for Hot Module Replacement.