Skip to content

Migration Guide

Stable AspireC4 Reviewed 2026-09-16 purview-dev/aspirec4 architecture architecture-as-code architecture-diagrams aspire aspire-dashboard aspire-dotnet aspire-hosting aspnetcore c4 c4-model developer-experience devex diagram diagrams dotnet likec4 roslyn source-generator visualization

Migration Guide

Section titled “Migration Guide”

This guide 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 13.5 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.

See also

Section titled “See also”