The .NET Aspire Azure Storage hosting integration provides extension methods for adding Azure Storage resources including blobs, queues, tables, and data lakes to your distributed application.
Installation
Install the Azure Storage hosting integration package in your AppHost project:
dotnet add package Aspire.Hosting.Azure.Storage
Prerequisites
- Azure subscription - create one for free
- Azure CLI installed and authenticated
- Owner access to the target subscription for role assignments
Configuration
Configure Azure provisioning settings in user secrets:
dotnet user-secrets set "Azure:SubscriptionId" "your-subscription-id"
dotnet user-secrets set "Azure:ResourceGroupPrefix" "myapp"
dotnet user-secrets set "Azure:Location" "eastus"
Usage
Add Blob Storage
In your AppHost project (AppHost.cs):
var builder = DistributedApplication.CreateBuilder(args);
var storage = builder.AddAzureStorage("storage");
var blobs = storage.AddBlobs("blobs");
var api = builder.AddProject<Projects.Api>("api")
.WithReference(blobs);
builder.Build().Run();
Consume in Service
In your service project:
dotnet add package Aspire.Azure.Storage.Blobs
Program.cs:
builder.AddAzureBlobServiceClient("blobs");
API Reference
AddAzureStorage
Adds an Azure Storage account resource to the application model.
public static IResourceBuilder<AzureStorageResource> AddAzureStorage(
this IDistributedApplicationBuilder builder,
string name)
Parameters
name - The name of the resource.
Returns
A reference to the IResourceBuilder<AzureStorageResource>.
AddBlobs
Adds Azure Blob Storage to the storage account.
public static IResourceBuilder<AzureBlobStorageResource> AddBlobs(
this IResourceBuilder<AzureStorageResource> builder,
string name)
AddQueues
Adds Azure Queue Storage to the storage account.
public static IResourceBuilder<AzureQueueStorageResource> AddQueues(
this IResourceBuilder<AzureStorageResource> builder,
string name)
AddTables
Adds Azure Table Storage to the storage account.
public static IResourceBuilder<AzureTableStorageResource> AddTables(
this IResourceBuilder<AzureStorageResource> builder,
string name)
Configuration Examples
Using the Emulator (Azurite)
For local development, use the Azurite emulator:
var storage = builder.AddAzureStorage("storage")
.RunAsEmulator();
var blobs = storage.AddBlobs("blobs");
Multiple Storage Services
var storage = builder.AddAzureStorage("storage");
var blobs = storage.AddBlobs("blobs");
var queues = storage.AddQueues("queues");
var tables = storage.AddTables("tables");
var api = builder.AddProject<Projects.Api>("api")
.WithReference(blobs)
.WithReference(tables);
var worker = builder.AddProject<Projects.Worker>("worker")
.WithReference(queues);
Blob Containers
Add and reference specific blob containers:
var storage = builder.AddAzureStorage("storage");
var imagesContainer = storage.AddBlobContainer("images");
var documentsContainer = storage.AddBlobContainer("documents");
var api = builder.AddProject<Projects.Api>("api")
.WithReference(imagesContainer)
.WithReference(documentsContainer);
builder.AddAzureBlobContainerClient("images");
builder.AddAzureBlobContainerClient("documents");
Queues
Add and reference specific queues:
var storage = builder.AddAzureStorage("storage");
var ordersQueue = storage.AddQueue("orders");
var notificationsQueue = storage.AddQueue("notifications");
var worker = builder.AddProject<Projects.Worker>("worker")
.WithReference(ordersQueue)
.WithReference(notificationsQueue);
builder.AddAzureQueue("orders");
builder.AddAzureQueue("notifications");
Data Lake Storage
var storage = builder.AddAzureStorage("storage");
var dataLake = storage.AddDataLake("datalake");
var fileSystem = storage.AddDataLakeFileSystem("filesystem");
var analytics = builder.AddProject<Projects.Analytics>("analytics")
.WithReference(dataLake)
.WithReference(fileSystem);
builder.AddAzureDataLakeServiceClient("datalake");
builder.AddAzureDataLakeFileSystemClient("filesystem");
Connection Properties
When you reference Azure Storage resources using WithReference, the following connection properties are made available to the consuming project.
Azure Storage Account
The Azure Storage account resource doesn’t expose connection properties directly. Reference sub-resources instead.
Blob Storage
| Property Name | Description |
|---|
Uri | The URI of the blob storage service, with the format https://mystorageaccount.blob.core.windows.net/ |
ConnectionString | Emulator only. The connection string for the blob storage service |
Blob Container
The Blob Container resource inherits all properties from its parent AzureBlobStorageResource and adds:
| Property Name | Description |
|---|
BlobContainerName | The name of the blob container |
Queue Storage
| Property Name | Description |
|---|
Uri | The URI of the queue storage service, with the format https://mystorageaccount.queue.core.windows.net/ |
ConnectionString | Emulator only. The connection string for the queue storage service |
Queue
The Queue resource inherits all properties from its parent AzureQueueStorageResource and adds:
| Property Name | Description |
|---|
QueueName | The name of the queue |
ConnectionString | Emulator only. The connection string for the queue |
Table Storage
| Property Name | Description |
|---|
Uri | The URI of the table storage service, with the format https://mystorageaccount.table.core.windows.net/ |
ConnectionString | The connection string for the table storage service |
Data Lake Storage
| Property Name | Description |
|---|
Uri | The URI of the data lake storage service, with the format https://mystorageaccount.dfs.core.windows.net/ |
Data Lake File System
The Data Lake FileSystem resource inherits all properties from its parent AzureDataLakeStorageResource and adds:
| Property Name | Description |
|---|
DataLakeFileSystemName | The name of the data lake file system |
Environment Variables
Aspire exposes each property as an environment variable named [RESOURCE]_[PROPERTY]. For instance:
- The
Uri property of a resource called blobs becomes BLOBS_URI
- The
BlobContainerName property becomes BLOBS_BLOBCONTAINERNAME
Deployment
Local Development with Emulator
var storage = builder.AddAzureStorage("storage")
.RunAsEmulator();
var blobs = storage.AddBlobs("blobs");
Development with Azure Resources
var storage = builder.AddAzureStorage("storage");
var blobs = storage.AddBlobs("blobs");
Production Deployment
Use Azure Developer CLI to deploy:
Common Patterns
Environment-Specific Configuration
var storage = builder.AddAzureStorage("storage");
if (builder.Environment.IsDevelopment())
{
storage.RunAsEmulator();
}
var blobs = storage.AddBlobs("blobs");
File Upload Service
var storage = builder.AddAzureStorage("storage");
var uploads = storage.AddBlobContainer("uploads");
var thumbnails = storage.AddBlobContainer("thumbnails");
var uploadApi = builder.AddProject<Projects.UploadApi>("upload-api")
.WithReference(uploads);
var imageProcessor = builder.AddProject<Projects.ImageProcessor>("processor")
.WithReference(uploads)
.WithReference(thumbnails);
Queue-Based Processing
var storage = builder.AddAzureStorage("storage");
var processingQueue = storage.AddQueue("processing");
var blobs = storage.AddBlobs("blobs");
var api = builder.AddProject<Projects.Api>("api")
.WithReference(processingQueue)
.WithReference(blobs);
var worker = builder.AddProject<Projects.Worker>("worker")
.WithReference(processingQueue)
.WithReference(blobs);
Emulator Requirements
The Azurite emulator requires:
- Docker Desktop (on Windows, Linux, or macOS)
- Sufficient disk space for the emulator image
Azurite supports blob, queue, and table storage. Data Lake Storage is not supported in the emulator.
Additional Resources
