Aspire Project v2 migration

Migrate supported legacy .NET project resources to the experimental DotnetProjectResource model without silently changing application behavior. This skill first applies to AppHosts targeting Aspire 13.6 or newer.

Approval boundary: A request such as "migrate to Project v2" authorizes an assessment, not unseen edits. Present the exact per-resource and per-file plan, then obtain approval before changing AppHost, package, project-reference, or application files. Apply only explicitly approved subsets.

Hard gates

1. Identify one exact AppHost and preserve unrelated local changes.
2. Resolve the AppHost's actual Aspire SDK/hosting version from project files, central package management, file directives, or resolved polyglot configuration.
3. Stop without edits if versions are older than 13.6, unresolved, or conflicting. Do not infer eligibility from the Aspire CLI version, .NET SDK, or service TargetFramework, and do not upgrade Aspire implicitly.
4. Verify the installed/resolved packages expose every needed API, including AddDotnetProject, publishing, EF, and Blazor capabilities used by the app. Development packages are development-build evidence, not released-package evidence.
5. Never manually edit generated .aspire/modules/ files.
6. Use aspire docs search and aspire docs api search ... --language csharp|typescript before relying on unfamiliar or preview API shapes.
7. For TypeScript, require the resolved generated addDotnetProject(name, path, options?: DotnetProjectOptions) API with a flat DTO. Older handle-only target builds are a capability stop, not a second supported migration path. Legacy source ProjectResourceOptions values remain RPC handles.

The publishing and TypeScript options changes are merged upstream, but a 13.6 version label alone does not prove that a consumer's packages contain them. See compatibility-and-validation.md for the merged API baseline and publishing boundaries.

Project-Local Skill Override

If .agents/skills/aspire-project-v2-migration/SKILL.md exists, warn the user and defer to that project-local skill while retaining these safety gates.

Workflow

1. Inventory actual behavior

Keep the assessment read-only in the application workspace. Inspect source and already-resolved metadata; do not restore, build, run, or regenerate SDK files before approval, even for capability discovery. If preparation is necessary to verify eligibility or APIs, describe that prerequisite and request approval for it rather than silently modifying the workspace.

Inspect the selected AppHost and every legacy candidate:

• AddProject<Projects.T>, path/directory AddProject, AddCSharpApp, and polyglot equivalents.
• Documented Blazor gateway patterns and attached EF operations.
• Names, paths, options, application arguments, environment callbacks, endpoints, launch settings, references, waits, health checks, replicas, build/publish configuration, and deployment annotations.
• AppHost ProjectReference / file-based #:project edges and every consumer of generated project metadata. Resolve Projects.* through real IProjectMetadata, project-reference metadata, and AspireProjectMetadataTypeName; never guess a path from a type name.
• Custom code coupled to ProjectResource, including casts, constraints, GetProjectResources(), publishers, image managers, direct constructors, or specialized subclasses.
• SDK selection, custom build properties, build-only requirements, file-app AOT settings, and existing local changes.
• For Blazor gateway publishing, the effective before/after target framework, SDK, runtime/base image and OS/platform, process user, working directory, entrypoint, and port configuration. The AppHost's target framework does not establish the packaged gateway file app's publishing framework.

An already migrated app or an app with no matching resources is a no-op.

2. Classify and propose

Present a table before editing:

Explain:

• ASPIREDOTNETPROJECT001 is an experimental API diagnostic.
• Project v2 resources have executable-based identity and coordinated initial builds.
• Known publishing or validation differences, especially Blazor gateway publishing, EF custom build inputs, and cross-OS file-app Native AOT.
• Exactly which files and resource subset would change and which legacy resources would remain.

Ask for approval of that exact plan. Do not migrate a "safe-looking" subset until the subset and retained resources are explicitly approved.

For a Blazor gateway, approval of the API replacement or "Dockerfile to SDK" switch alone is not approval of an implicit framework, base-image, or process-user change. List the resolved deployment differences and obtain explicit approval for them before editing. Briefly explain runtime/OS compatibility and non-root file/volume-permission implications; a list of changed values alone is not informed approval. If those values cannot be established read-only, classify the gateway as decision-required and request approval for the preparation needed to resolve them. Do not invent defaults or assume deployment equivalence. Preserve exact prerelease identifiers from the resolved evidence when reporting or requesting approval: for example, say .NET 11 RC1 and 11.0.0-rc.1, not the less specific .NET 11 RC or 11.0 prerelease. Approval applies to the specific resolved runtime and image, not merely its release channel. End that assessment with the gateway decision: request approval for specific bounded discovery, or ask whether to retain the gateway/review an owned publishing policy. Asking only about API edits does not resolve the gateway approval boundary.

Before sending an assessment with an unresolved gateway, check the final question: it must explicitly ask the user to choose gateway bounded discovery or gateway retention plus owned publishing-policy review. Never end with only API-edit approval while the gateway is still decision-required.

End the assessment with an actual approval request, not just a description of what approval would mean. Use the host's user-question tool when available; otherwise ask explicitly whether the user approves the listed resource and file changes. Wait for the answer before editing. An unavailable user is not approval.

After approval, capture the legacy behavior in a disposable copy when validation is authorized and feasible. Use the same qualified toolchain before and after; report pre-existing failures rather than attributing them to the migration.

3. Apply approved mappings

Load migration-patterns.md and follow its exact language-specific mappings.

• Add Aspire.Hosting.Dotnet at a version compatible with the already-targeted AppHost, preserving central package management and repository conventions.
• For TypeScript, use the flat DotnetProjectOptions object. Preserve the established values from legacy source; do not redesign addProject, addCSharpApp, or the shared ProjectResourceOptions handle.
• Use the Aspire CLI's normal integration acquisition/regeneration flow when available; do not hand-edit generated SDK modules.
• Preserve fluent configuration and application arguments in their original runtime role.
• Update only straightforward local IResourceBuilder<ProjectResource> annotations tied to approved resources. Do not broadly rewrite public/custom contracts.
• C# migrations must handle ASPIREDOTNETPROJECT001 narrowly so the edited AppHost compiles. Prefer paired #pragma warning disable ASPIREDOTNETPROJECT001 / #pragma warning restore ASPIREDOTNETPROJECT001 immediately around the approved Project v2 declarations. Use a project-level NoWarn only when repository convention and the approved migration scope make that equally narrow. Never suppress unrelated diagnostics or leave an unbounded disable. The AddEFMigrations overload selected for IDotnetProgramResource also requires a paired ASPIREPROJECTS001 suppression around that EF declaration; the legacy overload did not. Include this compilation-required edit in the approval scope. Preserve existing ASPIREBLAZOR001 scopes where the client/gateway calls need them.

4. Clean project references conservatively

Remove an AppHost ProjectReference or #:project only when it is proven to exist exclusively for approved migrated resources and no generated metadata consumer remains. Retain:

• code/library references and service-to-library references;
• edges used by unmigrated resources, EF migration metadata, Blazor WASM metadata, conditional code, or other Projects.* consumers;
• ambiguous references and build-only edges whose intent is not established.

ReferenceOutputAssembly="false" does not prevent an AppHost reference from participating in the build and is not a substitute for safe cleanup.

5. Preserve build and runtime intent

Keep runtime WithEnvironment values at runtime. Add WithBuildEnvironment only for an established, approved MSBuild input; never move environment configuration wholesale or treat runtime working directory as build context.

Use WithContainerBuildOptions for supported image identity, destination, format, and target-platform settings. Do not translate those settings into prohibited build-environment properties.

6. Validate and report

After approved edits:

1. Restore/build through repository conventions.
2. Start the exact AppHost with aspire start --non-interactive --isolated --apphost <path> when isolation is needed.
3. Use aspire wait <resource> --apphost <path> --non-interactive and structured Aspire inspection, not manual polling.
4. Validate preserved names, paths, arguments, environment, endpoints, references, waits, replicas, launch profiles, and publishing intent.
5. Separate compile, local-run, generated publish artifacts, and image-build evidence. aspire publish is not proof that an image was built. Run only the authorized validation stages; never push images or deploy as an implicit check. Do not claim unexecuted, skipped, or unavailable checks passed. For approved gateway image changes, verify the exact accepted target contract and unchanged behavior separately. Report the intentional differences, not "image parity"; a smoke-test pass does not authorize new framework/user changes.
6. Run the migration assessment again to prove idempotence: no duplicate package, resource, suppression, or configuration edits.

Report migrated, intentionally retained, and blocked resources, plus actual validation and manual follow-up. Preserve the user's edits if validation fails.

Compatibility boundaries

Load compatibility-and-validation.md for the full decision matrix. Never automatically replace:

• Azure Functions or unknown specialized ProjectResource subtypes;
• F# or Visual Basic services;
• direct new ProjectResource(...);
• custom publishers, image managers, casts, generic constraints, or GetProjectResources() consumers without a user decision;
• file-app build-only environment or file-app EF CLI operations.

IDotnetProgramResource is an identity marker. It does not by itself configure publishing; SupportsDotnetProgramPublishing() is a capability check, not a reason to rewrite every ProjectResource constraint.

For every file-based .cs candidate, the assessment must explicitly state that it requires .NET 10+, does not support WithBuildEnvironment or EF CLI operations, keeps runtime WithEnvironment values unchanged, and preserves Native AOT unless the user separately approves PublishAot=false or chooses a target-OS publishing environment.

Do not disable file-app Native AOT, replace a custom publishing model, or promise unfinished watch/hot-reload/partial-run behavior without explicit evidence and approval.

Routing