Skip to main content
The .NET Aspire Azure hosting integrations provide extension methods for adding Azure services to your distributed application with automatic provisioning and configuration.

​
Core Azure Package

The core Azure hosting library provides foundational capabilities for working with Azure resources: 
dotnet add package Aspire.Hosting.Azure
This package includes:
  • Azure provisioning infrastructure
  • Bicep template support
  • Azure authentication and credential management
  • Common Azure resource patterns

​
Azure Provisioning

Azure hosting integrations support automatic development-time provisioning, eliminating manual resource configuration.

​
Configuration

Set up Azure provisioning by configuring these values in user secrets: 
{
  "Azure": {
    "SubscriptionId": "<your subscription id>",
    "ResourceGroupPrefix": "<prefix for the resource group>",
    "Location": "<azure location>"
  }
}

​
Setting User Secrets

In your AppHost project directory: 
dotnet user-secrets set "Azure:SubscriptionId" "your-subscription-id"
dotnet user-secrets set "Azure:ResourceGroupPrefix" "myapp"
dotnet user-secrets set "Azure:Location" "eastus"
Developers must have Owner access to the target subscription so that role assignments can be configured for the provisioned resources.

​
Available Azure Integrations

​
Azure Cosmos DB

Globally distributed, multi-model database service. 
dotnet add package Aspire.Hosting.Azure.CosmosDB
Learn more about Azure Cosmos DB integration

​
Azure Storage

Blob, queue, table, and data lake storage services. 
dotnet add package Aspire.Hosting.Azure.Storage
Learn more about Azure Storage integration

​
Azure Service Bus

Enterprise messaging service with queues and publish-subscribe topics. 
dotnet add package Aspire.Hosting.Azure.ServiceBus
Learn more about Azure Service Bus integration

​
Other Azure Services

Additional Azure hosting integrations are available:
  • Azure Key Vault - Secrets and certificate management
  • Azure Event Hubs - Big data streaming and event ingestion
  • Azure SQL Database - Managed SQL Server database
  • Azure PostgreSQL - Managed PostgreSQL database
  • Azure Redis Cache - Managed Redis cache
  • Azure App Configuration - Application configuration service
  • Azure Application Insights - Application performance monitoring
  • Azure SignalR Service - Real-time messaging service
  • Azure Web PubSub - Publish-subscribe messaging for web apps

​
Using Bicep Templates

The core Azure hosting library supports custom Bicep templates for resources not covered by specific integrations: 
var builder = DistributedApplication.CreateBuilder(args);

var customResource = builder.AddBicepTemplate("myresource", "template.bicep")
                            .WithParameter("location", "eastus")
                            .WithParameter("sku", "Standard");

var api = builder.AddProject<Projects.Api>("api")
                 .WithReference(customResource);

​
Bicep Template Example

Create a template.bicep file: 
param location string
param sku string

resource storageAccount 'Microsoft.Storage/storageAccounts@2021-09-01' = {
  name: 'storage${uniqueString(resourceGroup().id)}'
  location: location
  sku: {
    name: sku
  }
  kind: 'StorageV2'
}

output endpoint string = storageAccount.properties.primaryEndpoints.blob

​
Authentication

Azure hosting integrations use Azure Identity for authentication:
  • Local Development: Uses your Azure CLI credentials or Visual Studio/VS Code authentication
  • Production: Uses managed identities when deployed to Azure

​
Local Development Setup

Ensure you’re authenticated with Azure: 
az login
az account set --subscription "your-subscription-id"

​
Deployment Modes

​
Local Development

Run Azure resources locally using emulators when available: 
var cosmos = builder.AddAzureCosmosDB("cosmos")
                    .RunAsEmulator();

var storage = builder.AddAzureStorage("storage")
                     .RunAsEmulator();

​
Cloud Development

Provision real Azure resources for development: 
var cosmos = builder.AddAzureCosmosDB("cosmos");
var storage = builder.AddAzureStorage("storage");
Resources are automatically provisioned when you run the AppHost.

​
Production Deployment

Deploy to Azure using: 
azd deploy
The Azure Developer CLI (azd) handles resource provisioning and application deployment.

​
Connection String Management

Azure integrations automatically manage connection strings using:
  • Managed Identity: Preferred for production (no secrets in configuration)
  • Access Keys: Used for emulators and when explicitly configured
  • Connection Strings: Generated automatically for compatible services

​
Common Patterns

​
Multi-Service Application

var builder = DistributedApplication.CreateBuilder(args);

var storage = builder.AddAzureStorage("storage");
var blobs = storage.AddBlobs("blobs");
var queues = storage.AddQueues("queues");

var cosmos = builder.AddAzureCosmosDB("cosmos")
                    .AddDatabase("catalogdb");

var serviceBus = builder.AddAzureServiceBus("messaging");

var api = builder.AddProject<Projects.Api>("api")
                 .WithReference(blobs)
                 .WithReference(cosmos)
                 .WithReference(serviceBus);

var worker = builder.AddProject<Projects.Worker>("worker")
                    .WithReference(queues)
                    .WithReference(serviceBus);

​
Environment-Specific Configuration

var builder = DistributedApplication.CreateBuilder(args);

var storage = builder.AddAzureStorage("storage");

if (builder.Environment.IsDevelopment())
{
    storage.RunAsEmulator();
}

var api = builder.AddProject<Projects.Api>("api")
                 .WithReference(storage);

​
Resource Naming

Azure resources are named automatically using:
  • Resource name from AddXxx method
  • Environment name
  • Unique suffix for global uniqueness
You can customize naming: 
var storage = builder.AddAzureStorage("storage")
                     .WithName("myappstorage");

​
Next Steps

Azure Cosmos DB

Add globally distributed NoSQL database

Azure Storage

Add blob, queue, and table storage

Azure Service Bus

Add enterprise messaging

Azure Developer CLI

Learn about azd for deployment

Build docs developers (and LLMs) love

Get started for freeTalk to us