Configuration
Configure the diagram through AspireC4DiagramOptions. Pass a callback to AddAspireC4:
builder.AddAspireC4(options => options .WithTitle("My App") .WithAutoIcons(false) .WithHideFromDashboard("Architecture"));Options reference
Section titled “Options reference”| Property | Default | Description |
|---|---|---|
GeneratedViewId |
null (index) |
LikeC4 view ID emitted in the generated .c4 file (e.g. view index { ... }). Change it if the ID conflicts with a hand-authored view. |
DefaultViewId |
"index" |
View ID used in the /view/{id} URL the Aspire dashboard links to. null/empty links to the server root instead. |
Title |
null |
Title shown in the LikeC4 application. |
ViewTitle |
"Architecture" |
Title shown in the generated view. |
ViewDescription |
null |
Optional view description (Markdown supported by recent LikeC4 versions). |
OutputDirectory |
"./.aspirec4/likec4/" |
Directory where the generated .c4 file is written. |
ProjectDirectory |
null |
An existing hand-authored LikeC4 project to generate into and serve. Set with WithLikeC4ProjectFolder(path). See Generated Output. |
UseLegacyLayout |
false |
Restores the pre-13.6 output paths (./likec4/gen/, ./erd/gen/) and flat dashboard resource names. Set with WithLegacyLayout(). A compatibility shim — see Migration. |
FileName |
"model.gen" |
Generated file name without extension. |
DisableHMR |
false |
Disable the Hot Module Replacement channel. |
HMRPort |
null (dynamic) |
Fixed HMR port when the LikeC4 server supports configurable ports (v1.57+); ignored on older versions, which always use port 24678. |
ContainerImageTag |
null (latest) |
Pin the ghcr.io/likec4/likec4 image tag (ignored with .WithLocalCLI()). |
CheckLatestImageVersion |
true |
When using the latest tag, run a throwaway container at startup to resolve the actual version so version-gated features (e.g. HMR port mode) are configured correctly. |
AutoIconsEnabled |
true |
Infer LikeC4 icons from resource type and name. |
HideFromDashboard |
false |
Hide the sidecar from the dashboard and surface the diagram as a link/command on project resources. |
DashboardLinkDisplayName |
"Architecture Diagram" |
Display name for the diagram link/command when hidden from the dashboard. |
RelationshipKindSyntax |
Dot |
DSL syntax for typed relationships: Dot (SOURCE .KIND TARGET) or Bracket (SOURCE -[KIND]-> TARGET). |
FormatGeneratedFile |
false |
Run npx likec4 format --files <file> after writing the generated file. Failures are ignored. |
ExternalProcessTimeoutSeconds |
30 |
Max seconds to wait for the external formatter process before killing it. |
UseDotIfAvailable |
true |
Use GraphViz’ dot executable for more accurate icon inference when on PATH. |
ElementKindSpecs |
[] |
Custom element kind specifications emitted in the specification {} block (style, notation, technology). |
RelationshipKindSpecs |
[] |
Custom relationship kind specifications emitted in the specification {} block (technology). |
AutoIncludeAspireMetadata |
All |
Which Aspire metadata is auto-injected: None, Metadata (aspire-name, aspire-type), Links (endpoint URLs), or All. |
NormaliseMetadataBehaviour |
Normalise |
How invalid characters in metadata keys are handled: Normalise, NormaliseLowercase, or Throw. |
AdditionalDSLFiles |
[] |
Extra user-managed .c4 files copied into the output directory and synced to the container volume. |
AdditionalDSLFolders |
[] |
Directories scanned recursively for .c4 files, added to include.paths in the generated config. |
ImageAliases |
{} |
Image alias definitions (keys start with @) written to the imageAliases section of the generated config. |
GenerateConfigFile |
true |
Generate a likec4.config.json in the output directory. |
GenerateGitIgnoreFile |
true |
Write a .gitignore beside the generated files naming exactly what AspireC4 writes, and one in the image directory ignoring only the export stamps. A .gitignore AspireC4 did not write is never touched. See Source control. |
ExtensionsDirectory |
"./likec4-extensions" |
A folder of hand-written .c4 files, relative to the AppHost directory, included automatically when it exists. null/empty turns the convention off. See Extending the generated model. |
IncludeAspireDashboardLinks |
true |
Add links from each element to the Aspire dashboard console/structured-logs pages (requires AutoIncludeAspireMetadata.Links). |
IncludeAspireTokenInDashboardLinks |
false |
Security risk — embed the Aspire browser token in dashboard links. See below. |
StateTagMap |
{} |
Override the aspire-run-state-* tag applied for a given resource state; null suppresses the tag. |
IncludeDefaultStateStyles |
true |
Emit default style element.tag = #aspire-run-state-* {} rules in the generated view. |
IncludeAspireC4InternalResource |
false |
Include the internal AspireC4 server resource in the diagram (for debugging). |
ExcludedResourceTypes |
{ParameterResource} |
Resource types excluded from the diagram (type and subclasses). |
IconResolvers |
[] |
Custom icon resolvers evaluated before built-in icon inference. |
ConfigFileMetadata |
{} |
Additional metadata included in the generated likec4.config.json. |
Fluent methods
Section titled “Fluent methods”Every property has a corresponding fluent With* method, for example:
WithGeneratedViewId(string?),WithDefaultViewId(string?)WithTitle(string?),WithViewTitle(string),WithViewDescription(string?)WithOutputDirectory(string),WithFileName(string)WithLikeC4ProjectFolder(string),WithLegacyLayout()WithHMRDisabled(bool = true)WithContainerImageTag(string?),WithCheckLatestImageVersion(bool = true)WithAutoIcons(bool = true)WithHideFromDashboard(string displayName = "Architecture Diagram")WithRelationshipKindSyntax(LikeC4RelationshipKindSyntax)WithFormatGeneratedFile(bool = true)WithAutoIncludeAspireMetadata(AspireMetadataInclusion)WithNormaliseMetadataBehaviour(NormaliseMetadataBehaviour)WithoutConfigFileGeneration(),WithoutGitIgnoreFileGeneration()WithExtensionsFolder(string),WithoutExtensionsFolder()WithAspireDashboardLinks(bool = true),WithAspireTokenInDashboardLinks(bool = true)WithDefaultStateStyles(bool = true),WithStateTag(string state, string? tag)WithUseDotIfAvailable(bool)WithIconResolver(Func<IconResolverContext, string?>)WithElementKindSpec(LikeC4ElementKindSpec),WithRelationshipKindSpec(...)WithAdditionalDSLFile(string),WithAdditionalDSLFolder(string),WithImageAliasFolder(string, string)WithExcludedResourceType<T>(),WithoutExcludedResourceType<T>()WithIncludeAspireC4InternalResource(bool)
See Advanced Configuration for the folder, alias, resolver, and spec extensions, and Source Generator Validation for the AspireC4Strict MSBuild property.
Common examples
Section titled “Common examples”Hide the sidecar from the dashboard
Section titled “Hide the sidecar from the dashboard”builder.AddAspireC4(options => options.WithHideFromDashboard());Disable hot reload
Section titled “Disable hot reload”builder.AddAspireC4(options => options.WithHMRDisabled());Pin the LikeC4 container version
Section titled “Pin the LikeC4 container version”builder.AddAspireC4(options => options.WithContainerImageTag("1.57"));Keep the pre-13.6 layout (legacy mode)
Section titled “Keep the pre-13.6 layout (legacy mode)”If you are upgrading and need the old output paths and dashboard names unchanged, turn on legacy mode:
builder.AddAspireC4(options => options.WithLegacyLayout());or, without touching code:
{ "AspireC4": { "UseLegacyLayout": true }}Legacy mode restores ./likec4/gen/ and ./erd/gen/ and keeps the dashboard rows flat as
aspirec4 and aspirec4-er, with no shared parent and no -likec4 suffix. It is a compatibility
shim, not an alternative layout, and will be removed in a future major version.
- An
OutputDirectoryyou set explicitly always wins over the legacy default. - There is no separate setting for the ER diagram: it follows this one.
- It does not affect
WithLikeC4ProjectFolder(...); generated output always stays beneath the hand-authored project.
See Migration for the complete before/after and the steps to move off the shim.
Security note — dashboard tokens in links
Section titled “Security note — dashboard tokens in links”IncludeAspireTokenInDashboardLinks embeds the Aspire browser token in generated dashboard links. Only enable this if you understand the implications: the token grants the same access as a browser session and is written into the diagram file, which may be shared or stored in source control. Keep it disabled for normal development, and consider excluding the generated file from source control if you enable it.