silver-octo-spoon/wolverine/AFrameArchitectureSample/.agents/skills/aspire/references/aspire-13-3-breaking-changes.md

Aspire 13.3 Breaking Changes — Agent Reference

Single, agent-facing scrub list of every 13.3 breaking change that may affect agent-generated code, scripts, CI snippets, or skill routing. Source: Aspire 13.3 release notes.

Use this page when reviewing AppHost code, CI YAML, or shell snippets for 13.3 compatibility. Agents must scrub for these patterns before recommending or generating code.

Quick scrub table

Change	Migration
--log-level → --pipeline-log-level on aspire publish / aspire deploy	Update CI/CD scripts to use --pipeline-log-level <level>.
Dashboard MCP server removed along with ASPIRE_DASHBOARD_MCP_ENDPOINT_URL	Use AppHost-level MCP via aspire agent init. See Dashboard MCP migration.
NameOutput → NameOutputReference (Azure Network resources)	Replace every *.NameOutput with *.NameOutputReference.
OtlpEndpointEnvironmentVariableName property removed	Remove the property; OTLP endpoint env var is managed automatically.
AksSkuTier enum removed	Delete the reference. AKS control-plane defaults to Free SKU.
AddAndPublishPromptAgent API removed	Use AddPromptAgent — returns a working AzurePromptAgentResource.
Kubernetes Ingress / Gateway routing types moved namespaces	Update using directives where these types are referenced directly.
package.json engines.node no longer drives Node image selection	Pin Node version explicitly via WithDockerfile or your Dockerfile base image.
dotnet new aspire-py-starter removed	Use aspire new aspire-py-starter (template moved to Aspire CLI; .NET SDK no longer required).
TypeScript per-kind withEnvironment* helpers @deprecated	Use unified withEnvironment(name, value). See TS withEnvironment migration.
CLI telemetry --format json schema aligned with MCP tool format	Update parsers consuming --format json from telemetry commands.
ASPIREEXTENSION001 JS diagnostic ID renamed to ASPIREJAVASCRIPT001	Update #pragma warning disable and any code-search rules.
Docker Swarm UpdateConfig property types changed	Update generated/hand-written Swarm overrides.
aspire init no longer wires up the AppHost	Follow with aspireify (in-plugin sibling skill or project-local copy).
In-dashboard GitHub Copilot UI removed	Replaced by aspire agent init-driven agentic flow (works with Copilot, Claude, Cursor, any MCP/skill agent).

TypeScript withEnvironment migration

Per-kind helpers are still generated for backward compatibility but marked @deprecated and slated for removal. Replace every call site with the unified API.

Old method (deprecated)	Replacement
withEnvironmentExpression(name, expr)	withEnvironment(name, expr)
withEnvironmentEndpoint(name, endpoint)	withEnvironment(name, endpoint)
withEnvironmentParameter(name, param)	withEnvironment(name, param)
withEnvironmentConnectionString(name, resource)	withEnvironment(name, resource)
withEnvironmentFromOutput(name, output)	withEnvironment(name, output)
withEnvironmentFromKeyVaultSecret(name, secret)	withEnvironment(name, secret)

The unified withEnvironment(name, value) accepts any of: a plain string, ReferenceExpression, EndpointReference, parameter builder, connection string resource builder, or IExpressionValue — one method handles every value kind.

Dashboard MCP migration

The Aspire dashboard no longer hosts an MCP server, and the ASPIRE_DASHBOARD_MCP_ENDPOINT_URL environment variable has been removed. AI coding agents now connect to your Aspire app through an AppHost-level MCP server plus skills wired up by aspire agent init.

# Replace any prior dashboard-MCP setup with:
aspire agent init

Detection covers GitHub Copilot, Claude, Cursor, and any other agent that supports skills or MCP. The previous in-dashboard GitHub Copilot UI has been removed in favor of this flow.

If a script or environment file still sets ASPIRE_DASHBOARD_MCP_ENDPOINT_URL, delete it.

aspire init no longer wires the AppHost

In 13.3, aspire init drops a skeleton (aspire.config.json + AppHost stub) and installs the aspireify agent skill, but does not wire resources, projects, or integrations on its own.

Workflow:

1. aspire init --language csharp|typescript --non-interactive
2. Hand off to the aspireify skill (in-plugin sibling or project-local .agents/skills/aspireify/SKILL.md) to scan the repo, propose a resource graph, edit the AppHost, wire Aspire.ServiceDefaults + OTel, and validate via aspire start.

Skills shipped in this plugin:

• aspire-init — owns the skeleton drop and template choice.
• aspireify — owns the wiring step after the skeleton lands.

Migration from Aspire 13.2 to 13.3

Mirror of the upstream checklist plus the items above. Run through each step before recommending Aspire-related changes against an existing repo.

1. Update the CLI — aspire update --self.
2. Update your projects — aspire update from the repo root (modifies project package references; get user approval before running in CI).
3. Audit --log-level usage in CI/CD pipelines and rename to --pipeline-log-level.
4. Search for breaking-change identifiers in AppHost code:
   • NameOutput → NameOutputReference
   • AddAndPublishPromptAgent → AddPromptAgent
   • AksSkuTier → delete (defaults to Free)
   • OtlpEndpointEnvironmentVariableName → delete
   • ASPIREEXTENSION001 → ASPIREJAVASCRIPT001
5. Replace dotnet new aspire-py-starter with aspire new aspire-py-starter.
6. Rerun aspire agent init if you previously relied on the dashboard MCP server or its ASPIRE_DASHBOARD_MCP_ENDPOINT_URL env var.
7. Re-pin Node versions in Dockerfiles if you were relying on package.json engines.node for base-image selection.
8. Rewire AppHost via aspireify if the repo went through aspire init on 13.3 — the skeleton is unwired by design.
9. Replace deprecated TS withEnvironment* helpers with the unified withEnvironment(name, value) (see migration table).
10. Update Kubernetes Ingress / Gateway using directives if your AppHost references the moved types directly.
11. Update consumers of --format json from CLI telemetry commands to the new MCP-aligned schema.
12. Update Docker Swarm overrides for the new UpdateConfig property types.