Skip to content
Purview Dev logo

13.6 — generated output and dashboard names

Section titled “13.6 — generated output and dashboard names”

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 row
aspirec4-er ├── aspirec4-likec4 <- renamed
aspirec4-er-server └── aspirec4-er
└── aspirec4-er-server

The 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=true

One 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 OutputDirectory you 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 appsettings override has to be visible that early or the server would mount one directory while the model was written to another.
  1. Remove WithLegacyLayout() (or the configuration entry).
  2. Remove the old .gitignore entries — AspireC4 writes its own — and delete the old directories.
  3. Update anything that refers to the aspirec4 resource by name to aspirec4-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 .gitignore files 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.

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 produces ASPIRE002.
  • 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 Tags nested class or [KnownType(LikeC4RegistryType.Tag)] fields. Mixing both now produces ASPIREC4005.
  • Strict settings are severity-based. Replace older boolean-only assumptions with suggestion, warning, error, all, or allincludingmetadata. true remains 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]. Plain all does 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, and LikeC4Severity.g.cs instead of a combined LikeC4RegistryAttributes.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, or LikeC4Severity to avoid duplicate-type errors.
  • Generator packaging is automatic. Consumers should reference only AspireC4.Hosting; remove direct references to AspireC4.SourceGenerators or Purview.SourceGeneratorFramework that 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. Run aspire restore after upgrading AspireC4 so the exported API matches the installed integration version.