Use existing azd workflows

The Azure Developer CLI (azd) is still supported with Aspire for existing workflows, but it is no longer the recommended default deployment path.

Recommended path: aspire deploy

For new Azure deployments, use aspire deploy. It keeps the deployment flow inside Aspire, supports more Azure targets, and avoids the legacy manifest-based path. Start with Deploy to Azure.

When to use azd

While aspire deploy is the recommended path, azd still makes sense when:

• You have existing azd workflows and infrastructure templates you want to continue using.
• You need azd pipeline config for automated CI/CD setup with GitHub Actions or Azure DevOps.
• You want to use azd environment management features to manage multiple deployment environments.
• You’re working with teams already familiar with azd conventions and tooling.

Use azd docs for the azd workflow

This page does not duplicate azd’s full operational workflow. For install, initialization, provisioning, deployment, environment management, and CI/CD setup, use the Azure Developer CLI docs:

• Install azd
• Initialize an existing app with azd
• Provision and deploy with azd up
• Manage environments with azd env
• Configure CI/CD with azd pipeline config

Resource naming

The aspire deploy path and azd use different resource naming schemes by default. If you’re upgrading from an existing azd deployment to aspire deploy, use WithAzdResourceNaming() to preserve the original naming convention. This avoids creating duplicate Azure resources:

C#

AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

builder.AddAzureContainerAppEnvironment("env")
    .WithAzdResourceNaming();

TypeScript

apphost.ts

import { createBuilder } from './.modules/aspire.js';

const builder = await createBuilder();

const env = await builder.addAzureContainerAppEnvironment('env');
await env.withAzdResourceNaming();

Environments and configuration

azd has its own environment system, and that environment context can flow into your AppHost. When azd invokes the AppHost, it passes the DOTNET_ENVIRONMENT value from the active azd environment’s .env file to the AppHost process.

To configure this, set DOTNET_ENVIRONMENT in your azd environment:

Set the Aspire environment for an azd environment

azd env set DOTNET_ENVIRONMENT staging
azd up
# → AppHost runs with DOTNET_ENVIRONMENT=staging
# → builder.Environment.IsEnvironment("staging") returns true

Caution

The azd environment name (azd env select staging) does not automatically set DOTNET_ENVIRONMENT. You must explicitly set DOTNET_ENVIRONMENT in each azd environment. Without it, the AppHost defaults to Production.

Your AppHost code can branch on this value to vary topology or configuration per environment, as described in the Environments guide.

How parameters work with azd

Aspire parameters and azd inputs follow different paths:

Parameter type	How it reaches Azure resources
Aspire parameters (AddParameter)	Resolved by the AppHost through .NET configuration when generating the manifest. Use appsettings.{env}.json or environment variables.
azd infrastructure inputs (Bicep parameters)	Prompted by azd provision and stored in .azure/{name}/config.json. Used by azd directly during Bicep deployment — not passed to the AppHost.
Secrets	Prompted by azd provision and stored in a local vault. Injected into Bicep parameters during provisioning.

Note

azd infrastructure inputs stored in .azure/{name}/config.json are consumed as Bicep parameters during provisioning. They are not passed to the AppHost process. If the same value must be available in both your AppHost code and your infrastructure, define it as an Aspire parameter and provide it through .NET configuration or an environment variable.

Manifest compatibility

azd currently consumes the legacy deployment manifest behind the scenes. Treat that manifest as an implementation detail, not as part of the recommended Aspire deployment model. In most cases, you do not need to generate, inspect, or edit it directly.

Caution

The deployment manifest format is deprecated and no longer being evolved. New Azure deployment features land in the aspire deploy path.

If you’re maintaining an existing azd integration or debugging legacy manifest generation, see Legacy deployment manifest format.

See also

• Deploy to Azure — recommended deployment path
• Environments
• Legacy deployment manifest format
• Azure Developer CLI documentation