Generated Output
AspireC4 writes a LikeC4 project into the output directory (./.aspirec4/likec4/ by default) and serves it with the LikeC4 server.
Every AspireC4 diagram writes beneath the same ./.aspirec4/ root in the AppHost directory — the architecture diagram into likec4/, the ER diagram into erd/, both diagrams’ images into images/. AspireC4 writes the .gitignore files that keep the generated parts out of git itself, so your repository needs no entry for it; see Source control.
| File | Purpose |
|---|---|
model.gen.c4 |
The generated model — see below. |
likec4.config.json |
LikeC4 project configuration (name, title, include.paths, imageAliases, metadata). Generated when GenerateConfigFile is true. |
Additional .c4 files |
Any files registered through WithAdditionalDSLFile are copied here; LikeC4 discovers all .c4 files in the project directory automatically. |
The ER diagram writes its own files beneath ./.aspirec4/erd/ — schema.gen.json (or .mmd, .dbml,
.d2, depending on the renderer) plus the viewer assets. It is a separate diagram with its own options;
see Entity Framework Core ER Diagrams.
Exporting images
Section titled “Exporting images”Both diagrams export to the same ./.aspirec4/images/ folder: the architecture diagram writes one PNG
per view with an architecture- prefix, the ER diagram writes schema.svg and schema.png. Export runs
in the background and only when the output would differ, so startup is never delayed and an unchanged
diagram renders nothing.
The images are the one piece of generated output worth committing — a diagram in a pull request is
documentation. The screenshots embedded in this repository’s READMEs and wiki pages are kept in
docs/images/screenshots/, captured from the sample AppHost; see its README.md for the file list and how
to refresh them. See Configuration for ImageExportDirectory, ImageFormats and
WithoutImageExport().
Source control
Section titled “Source control”AspireC4 writes a .gitignore beside what it generates, so a repository that adopts it needs no
ignore entry and sees nothing change from one run to the next:
| Directory | Ignored | Kept visible to git |
|---|---|---|
likec4/ |
model.gen.c4, the generated likec4.config.json, copies of WithAdditionalDSLFile sources |
anything else you put there |
erd/ |
the diagram (schema.gen.*), the viewer (index.html, app.js), vendor/ |
anything else you put there |
images/ |
the .aspirec4-* stamp files only |
the exported images |
Why the split:
- The models are build output, not source. The architecture model is a picture of a running system — endpoint ports, dashboard links and each resource’s run state legitimately differ between runs — so tracking it guarantees a dirty working tree. The ER model is regenerated from whatever the projects were last built with.
- The images are documentation. A diagram in a pull request is worth reviewing, and an image is replaced only when its bytes change, so they do not churn.
- Exact names, not
*. Each.gitignorelists the files AspireC4 writes, anchored to its directory, so a directory you share with your own files —WithOutputDirectory("./docs/architecture")— never hides them. - Yours are never touched. If a
.gitignorethat AspireC4 did not write is already there, it is left alone and a line in the log says so. AspireC4 recognises its own by the first line,# Written by AspireC4.
To commit the generated model deliberately, turn this off with WithoutGitIgnoreFileGeneration() (or
"AspireC4": { "GenerateGitIgnoreFile": false }; the ER diagram has its own
WithoutGitIgnoreFileGeneration()). Because files are only written when they change, you then see a diff
only when the model really did — but the architecture model’s ports and run states are real changes,
so expect them. If what you need is your own LikeC4 files kept beside the generated model, the
extensions folder below does that without committing generated output.
Extending the generated model
Section titled “Extending the generated model”Anything the Aspire resource graph cannot describe — people, external systems, descriptions, extra
relationships, more views — goes in a likec4-extensions/ folder beside the AppHost. AspireC4 picks it
up automatically when it exists: the folder is added to the generated likec4.config.json as an include
path and mounted into the LikeC4 container, exactly as WithAdditionalDSLFolder would.
MyApp.AppHost/ likec4-extensions/ <- yours: committed, included automatically people.c4 extend.c4 .aspirec4/ <- generated: ignored by AspireC4's own .gitignore filesGenerated elements are named after their Aspire resources — builder.AddProject<Projects.Api>("api")
becomes api, and a dash becomes an underscore — so hand-written files can extend them and draw
relationships to them:
specification { element person}
model { customer = person 'Customer' customer -> api 'Places orders'
extend api { link https://wiki.example.com/api 'Runbook' }}The names only change if the resources do. WithExtensionsFolder("./architecture") uses another
folder (relative to the AppHost directory, or absolute), and WithoutExtensionsFolder() turns the
convention off; both are also "AspireC4": { "ExtensionsDirectory": ... }. The convention does not apply
with WithLikeC4ProjectFolder, whose project already holds your files.
This is the replacement for a separate LikeC4 project that read a committed model.gen.c4: move its
.c4 files into the extensions folder and the generated model is always beside them, current, and never
committed.
Generating into your own LikeC4 project
Section titled “Generating into your own LikeC4 project”WithLikeC4ProjectFolder(path) points AspireC4 at a LikeC4 project you already maintain. That directory is what the LikeC4 server serves, so the project’s own likec4.config.json, .c4 sources and views are all in play, and the generated model joins them as one more file:
builder.AddAspireC4(configure: options => options .WithLikeC4ProjectFolder("../../architecture"));architecture/ <- served by LikeC4 likec4.config.json <- yours, never written to model.c4 <- hand-authored .aspirec4/ model.gen.c4 <- generatedGenerated output goes to .aspirec4/ beneath the project so it stays out of your hand-curated files. Set OutputDirectory as well if you want it elsewhere — an explicit value is always honoured. No likec4.config.json is generated for such a project: if it has one, overwriting it would discard settings AspireC4 knows nothing about; if it has none, the config is optional to LikeC4 anyway.
Attaching Aspire state to elements you already declared
Section titled “Attaching Aspire state to elements you already declared”WithLikeC4Element(id) maps an Aspire resource onto an element your project already declares, so the live state lands on that element instead of a duplicate appearing beside it:
builder.AddProject<Projects.Api>("api") .WithLikeC4Element("cloud.backend.api");The generated model then emits an extend block rather than a declaration:
model { extend cloud.backend.api { #aspire-run-state-running link http://localhost:5123 'Endpoint: http' metadata { aspire-name 'api' } }}Every reference follows the mapping — relationships, nesting and view groups all use the fully-qualified id — and the element’s kind is not re-declared in the generated specification {}, because your project already declares it.
AspireC4 never reads your .c4 sources, so it cannot tell you at build time that an id does not exist — LikeC4 reports that itself, with a proper source location.
The generated .c4 file
Section titled “The generated .c4 file”The file starts with an auto-generated header and is split into specification {}, model {}, and views {} blocks:
specification {}declares every element kind, relationship kind, and tag used in the model, plus any specs fromElementKindSpecs/RelationshipKindSpecs. WhenIncludeDefaultStateStylesis enabled, all known state tags are declared up-front so the block is stable regardless of the current resource states.model {}emits each element as<id> = <kind> 'label' { ... }with tags, technology, summary, description, icon, links, and metadata, plus relationships using the configuredRelationshipKindSyntax(SOURCE .KIND TARGETorSOURCE -[KIND]-> TARGET).views {}emits theindexview (or theGeneratedViewId) with its title/description,group 'label' { include ... }blocks,include *, andstyle element.tag = #aspire-run-state-* {}rules for the built-in state styles.
Regeneration behavior
Section titled “Regeneration behavior”- The file is written before the application starts.
- At runtime, resource state changes trigger a debounced regeneration (300 ms), so the diagram reflects the current state of each resource.
- A file is written only when its bytes would change. That is checked against the file already on disk, not just the last write of this run, so restarting an unchanged application touches nothing — no content, no timestamp. The header carries no timestamp for the same reason.
- In publish mode (
aspire publish), the file is generated once and the server is not started.
Formatting
Section titled “Formatting”When FormatGeneratedFile is true, AspireC4 runs npx likec4 format --files <file> against the generated file immediately after writing it. The formatter modifies the file in place so the on-disk copy is human-readable; the formatted content is also what is synced to the container workspace. Failures are silently ignored. ExternalProcessTimeoutSeconds caps how long this can block startup (default 30 s).
Config file
Section titled “Config file”likec4.config.json uses the LikeC4 $schema and includes:
name— the LikeC4 project name (unique within the workspace).title— whenTitleis set.include.paths— for eachAdditionalDSLFoldersentry (LikeC4 recursively scans the folder for.c4files).imageAliases— for eachImageAliasesentry (keys start with@).metadata— for eachConfigFileMetadataentry.
Set WithoutConfigFileGeneration() (or GenerateConfigFile = false) to manage likec4.config.json manually, for example when the output directory is already part of a hand-curated LikeC4 project.
- Auto icons (
AutoIconsEnabled, defaulttrue): icons are inferred from the resource type and name using the bundled icon manifest. - Custom resolvers (
IconResolvers): evaluated in registration order before built-in inference; the first non-nullresult wins. Each resolver receives anIconResolverContextexposing the visibleResourceand theHiddenOriginalAzure resource (when a local surrogate was created viaRunAsContainer()). - GraphViz
dot(UseDotIfAvailable, defaulttrue): whendotis onPATH, LikeC4 uses it for more accurate inference (e.g. database icons) and can infer icons from container/component relationships.
Version detection
Section titled “Version detection”When the container image tag resolves to latest (default), CheckLatestImageVersion (default true) runs a throwaway container at startup to call likec4 --version and resolve the actual version. The resolved version configures version-gated features (such as configurable HMR ports) and is surfaced as a LikeC4 Version property on the dashboard resource. Set it to false for faster startup if you pin an explicit tag or accept possible misconfiguration.
Live state reflection
Section titled “Live state reflection”Each element is tagged aspire-run-state-<state> based on the live Aspire resource state, and the default view styles color it accordingly:
| State tag | Default style |
|---|---|
aspire-run-state-starting |
sky |
aspire-run-state-waiting |
sky |
aspire-run-state-running |
green |
aspire-run-state-stopping |
slate, 60% opacity |
aspire-run-state-exited |
muted, 30% opacity |
aspire-run-state-finished |
muted, 30% opacity |
aspire-run-state-runtimeunhealthy |
amber |
aspire-run-state-failedtostart |
red |
Override per-state tags with WithStateTag(state, tag) (pass null to suppress), and disable the built-in style rules with WithDefaultStateStyles(false) if you prefer to style state tags in your own DSL.