Azure Developer CLI (azd)

Цей контент ще не доступний вашою мовою.

The Azure Developer CLI (azd) is a developer-oriented command-line tool that can provision Azure resources and deploy applications from your local environment or CI/CD pipelines. It integrates with Aspire by consuming the deployment manifest format to understand your app model and automatically provision the corresponding Azure resources.

When to use azd

While aspire deploy is the recommended path, azd remains useful in several scenarios:

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.

Prerequisites

Azure Developer CLI installed
An active Azure subscription — create one for free
Aspire CLI installed

Basic workflow

Initialize your project — run azd init from your AppHost directory. When prompted, select Use code in the current directory so azd detects the Aspire app model.
Initialize azd in the AppHost directory
```
azd init
```
Provision and deploy — run azd up to provision the required Azure resources and deploy your application in a single step. This combines the azd provision and azd deploy commands.
Provision infrastructure and deploy
```
azd up
```
Redeploy without reprovisioning — after the initial deployment, use azd deploy to push code changes without reprovisioning infrastructure.
Deploy updated code
```
azd deploy
```

`aspire deploy` vs `azd` comparison

Feature	`aspire deploy`	`azd`
Azure Container Apps	✅	✅
Azure App Service	✅	❌
Infrastructure provisioning	Built-in	Built-in
CI/CD pipeline setup	Manual	`azd pipeline config`
Environment management	State caching	`azd env`
Manifest dependency	No	Yes

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:

Select your programming language

var builder = DistributedApplication.CreateBuilder(args);

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

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

const builder = await createBuilder();

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

Environments and configuration

The azd CLI has its own environment management system that maps to Aspire environments. Understanding how these two systems connect helps you deploy the same application to multiple targets like staging and production.

azd environments

Each azd environment is a named configuration scope stored under .azure/{name}/ in your project. Create and switch between environments with:

azd env new staging
azd env new production
azd env select staging

Each environment stores its own:

Configuration — .azure/{name}/config.json for infrastructure parameters (subscription, location, resource group)
Environment variables — .azure/{name}/.env for deployment-specific values
Secrets — referenced through a local vault in ~/.azd/vaults/

How azd passes the environment to Aspire

When azd invokes your AppHost to generate the deployment manifest, it passes the DOTNET_ENVIRONMENT value from the active azd environment’s .env file to the AppHost process. This means your AppHost’s builder.Environment.EnvironmentName reflects that value.

To configure this, set DOTNET_ENVIRONMENT in your azd environment:

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

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

Parameters in Aspire and azd 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.

Deploy to multiple environments

To deploy the same application to staging and production with different Azure resources:

Create environments:

azd env new staging
azd env new production

Configure the Aspire environment for each:

azd env select staging
azd env set DOTNET_ENVIRONMENT staging

azd env select production
azd env set DOTNET_ENVIRONMENT production

Deploy to staging — azd prompts for subscription, location, and any required parameters on the first deployment:
Terminal window
```
azd env select staging
azd up
```
Deploy to production — switch environments and deploy. Each environment provisions its own independent set of Azure resources:
Terminal window
```
azd env select production
azd up
```

Each environment maintains completely separate state — different resource groups, different secrets, different configuration. The AppHost receives the environment name through DOTNET_ENVIRONMENT, so any environment-based branching in your AppHost code (resource topology, parameter defaults) applies automatically.

Deployment manifest

The azd tool relies on the deployment manifest format to understand your application topology. The manifest is a JSON document generated from the AppHost that describes resources, bindings, and parameters. It’s produced automatically when azd invokes the AppHost during deployment.