Migration Guide
13.6 — generated output and dashboard names
Section titled “13.6 — generated output and dashboard names”What changed
Section titled “What changed”1. Generated diagrams moved under a single root.
| Before 13.6 | 13.6 | |
|---|---|---|
AspireC4DiagramOptions.OutputDirectory |
./likec4/gen/ |
./.aspirec4/likec4/ |
AspireC4EfDiagramOptions.OutputDirectory |
./erd/gen/ |
./.aspirec4/erd/ |
Everything AspireC4 generates now sits beneath one .aspirec4/ directory in the AppHost, and AspireC4
writes the .gitignore files that keep the generated parts out of git, so remove the old
**/likec4/gen/, **/erd/gen/ and **/erd/gen/vendor/ entries rather than replacing them. A
hand-written **/.aspirec4/ entry still works, but it also hides the exported images, which are meant to
be committed; see Source control.
Delete the stale likec4/gen/ and erd/gen/ directories after upgrading — nothing writes to them any
more, so they will sit there as untracked leftovers.
2. The diagram resources nest under a shared dashboard parent.
This only applies when more than one diagram is registered. With just AddAspireC4(), the dashboard is
unchanged: a single aspirec4 row, exactly as before.
Before 13.6 13.6, with WithEntityFrameworkDiagram()aspirec4 aspirec4 <- parent rowaspirec4-er ├── aspirec4-likec4 <- renamedaspirec4-er-server └── aspirec4-er └── aspirec4-er-serverThe architecture diagram’s resource is renamed from aspirec4 to aspirec4-likec4, so anything that
addresses it by name needs updating — integration tests, ResourceNotificationService watchers,
GetResource("aspirec4") lookups, and anything matching on dashboard resource names. If you passed a
name to AddAspireC4("my-diagram"), the same applies: the parent takes my-diagram and the diagram
becomes my-diagram-likec4.
The inner server resources (aspirec4-server, aspirec4-er-server) keep their names, which are derived
from the name you supplied rather than the renamed row.
Legacy mode (keeping the pre-13.6 behaviour)
Section titled “Legacy mode (keeping the pre-13.6 behaviour)”WithLegacyLayout() reverts both changes together — the output paths and the dashboard names. This
is the switch to reach for when an upgrade must change nothing else:
builder.AddAspireC4(configure: options => options.WithLegacyLayout());or, without touching code:
{ "AspireC4": { "UseLegacyLayout": true }}The same setting works as an environment variable when you cannot edit appsettings.json:
AspireC4__UseLegacyLayout=trueOne switch covers the whole integration: the ER diagram follows the architecture diagram rather than
exposing a second setting that could disagree with it. With it set, ./likec4/gen/ and ./erd/gen/ are
the defaults again, and the diagrams stay flat as aspirec4 and aspirec4-er with no parent row.
Notes:
- An
OutputDirectoryyou set yourself always wins over either default, legacy or not. - One switch covers both diagrams: there is no separate ER setting, so the architecture and ER diagrams cannot disagree about which layout is in use.
- It has no effect on
ProjectDirectory. Pointing AspireC4 at a hand-authored LikeC4 project always writes generated output beneath the project being served, because it has to. - Unlike most options, this one is read from configuration when the builder runs, not only when the
runtime options are resolved — it fixes the paths and resource names before anything else starts, so
an
appsettingsoverride has to be visible that early or the server would mount one directory while the model was written to another.
Migrating off the shim
Section titled “Migrating off the shim”- Remove
WithLegacyLayout()(or the configuration entry). - Remove the old
.gitignoreentries — AspireC4 writes its own — and delete the old directories. - Update anything that refers to the
aspirec4resource by name toaspirec4-likec4, but only if you register a second diagram.
Once legacy mode is off, ./likec4/gen/ and ./erd/gen/ are no longer written. Delete them so they do
not linger as untracked leftovers.
Generated output no longer needs ignoring, and is not rewritten
Section titled “Generated output no longer needs ignoring, and is not rewritten”Two behaviour changes with no code to change:
- AspireC4 writes its own
.gitignorefiles into the directories it generates into, naming only its own files, and never overwrites one it did not write. Remove repository entries for.aspirec4/; keep a deliberate**/.aspirec4/only if you also mean to hide the exported images.WithoutGitIgnoreFileGeneration()opts out. - Files are written only when their content changes, and the generated headers no longer carry a timestamp, so restarting an unchanged application leaves every file — and its modified time — alone. Tooling that parsed the timestamp out of a header will find none.
A separate LikeC4 project that depended on a committed model.gen.c4 should move its .c4 files into a
likec4-extensions/ folder beside the AppHost, which is now included automatically; see
Extending the generated model.
Source generator migration
Section titled “Source generator migration”This section covers breaking changes introduced by the migration of the source generator to the current Purview.SourceGeneratorFramework incremental APIs. Existing applications should review the following when upgrading:
- Aspire AppHost dependency is explicit. Aspire AppHosts must reference
Aspire.Hosting.AppHost; relying on the AppHost SDK alone producesASPIRE002. - Only one registry class is supported per assembly. Merge multiple
[LikeC4Registry]classes into one class. - Registry declaration styles cannot be mixed per type. For example, choose either a
Tagsnested class or[KnownType(LikeC4RegistryType.Tag)]fields. Mixing both now producesASPIREC4005. - Strict settings are severity-based. Replace older boolean-only assumptions with
suggestion,warning,error,all, orallincludingmetadata.trueremains accepted as an alias for error-level validation. - Metadata validation is opt-in at the global level. Use
allincludingmetadata, or apply an explicit metadata severity through[Severity]/[KnownType]. Plainalldoes not validate metadata keys. - Generated source files are split by type. The generator now emits
LikeC4RegistryAttribute.g.cs,KnownTypeAttribute.g.cs,SeverityAttribute.g.cs,LikeC4RegistryType.g.cs, andLikeC4Severity.g.csinstead of a combinedLikeC4RegistryAttributes.g.cs. This affects generator snapshot tests and tooling that inspected hint names; normal application source code is unaffected. - Do not define generated registry types manually. Remove compatibility copies of
LikeC4RegistryAttribute,KnownTypeAttribute,SeverityAttribute,LikeC4RegistryType, orLikeC4Severityto avoid duplicate-type errors. - Generator packaging is automatic. Consumers should reference only
AspireC4.Hosting; remove direct references toAspireC4.SourceGeneratorsorPurview.SourceGeneratorFrameworkthat were added solely to make the AspireC4 generator run. - TypeScript APIs are generated by Aspire. TypeScript AppHosts import from
.aspire/modules/aspire.mjs; generated files must not be copied between projects or edited manually. Runaspire restoreafter upgrading AspireC4 so the exported API matches the installed integration version.