.NET Aspire — azd Environments Explained

azd env new dev doesn’t create anything in Azure. It creates a local config file. Here’s what actually happens—and why it matters for your Aspire deployment.

azd Environments vs Azure Resources

An azd environment is NOT an Azure resource—it’s a local configuration profile that tells azd which subscription, region, and settings to use when deploying.

Aspect	azd Environment	Azure Resource Group
Location	`~/.azd/environments/{name}/` (local)	Azure portal (cloud)
Created by	`azd env new`	`azd up`
Contains	Config files, `.env` variables, deployment settings	Actual cloud resources (containers, DBs, registries)
Deleted by	`rm -rf ~/.azd/environments/{name}`	`azd down`

What `azd env new` Does

When you run:

azd env new dev

azd creates a local folder structure with your deployment configuration:

~/.azd/environments/dev/
├── .env                  # Environment variables
├── config.json           # Deployment metadata
└── .azure/               # Azure-specific settings

It prompts for:

Azure subscription (which account to bill)
Azure region (where to deploy)
Environment name (dev, staging, prod)

No Azure resources are created yet. This is just local configuration.

What `azd up` Actually Does

This is when real Azure resources get created:

azd up

Resources provisioned automatically:

Resource Group — Container for all resources
Container Apps Environment — Hosts your Aspire services
Azure Container Registry — Stores your container images
Database Account — Your app’s data layer
Static Web App — Serves your frontend
Application Insights — Monitoring and telemetry
Managed Identities — Secure service-to-service auth
Networking & Security — HTTPS, CORS, service discovery

Resource Naming Convention

azd generates consistent resource names using the {type}-{project}-{env} pattern:

Resource Type	Pattern	Example
Resource Group	`rg-{project}-{env}`	`rg-myapp-dev`
Container Apps Env	`cae-{project}-{env}`	`cae-myapp-dev`
Container Registry	`acr{project}{env}`	`acrmyappdev`
Database	`cosmos-{project}-{env}`	`cosmos-myapp-dev`
Static Web App	`swa-{project}-{env}`	`swa-myapp-dev`
App Insights	`ai-{project}-{env}`	`ai-myapp-dev`

Essential Environment Commands

# Create a new environment (local config only)
azd env new <environment-name>

# List all local environments
azd env list

# Switch to a different environment
azd env select <environment-name>

# View current environment variables
azd env get-values

# Set a variable for the current environment
azd env set <KEY> <VALUE>

# Deploy everything for current environment
azd up

# Remove all Azure resources (keep local config)
azd down

# Update only application code (without re-provisioning)
azd deploy

Deployment Workflow

The complete flow from local development to production:

Create Environment: azd env new dev (configuration only)
Deploy Everything: azd up (creates all Azure resources)
Make Changes: Edit code locally
Update Deployment: azd deploy (updates application, keeps infrastructure)
Clean Up: azd down (removes all Azure resources)

Why This Matters for Aspire

With Aspire’s AppHost and azd’s orchestration, you get Infrastructure as Code without writing infrastructure code. Aspire defines your services; azd deploys them consistently.