Aspire Project V2 Migration

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. 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.