Azure Queue Storage

Azure Queue Storage is a service for storing large amounts of unstructured data. The Aspire Azure Blob Storage integration enables you to connect to existing Azure Storage instances or create new instances from applications with the mcr.microsoft.com/azure-storage/azurite container image.

Hosting integration

The Aspire Azure Storage hosting integration models the various storage resources as the following types:

• AzureStorageResource: Represents an Azure Storage resource.
• AzureStorageEmulatorResource: Represents an Azure Storage emulator resource (Azurite).
• AzureQueueStorageQueueResource: Represents an Azure Queue storage resource.

To access these types and APIs for expressing them, add the 📦 Aspire.Hosting.Azure.Storage NuGet package in the AppHost project.

Aspire CLI

Aspire CLI — Aspire.Hosting.Azure.Storage paketi ekle

aspire add azure-storage

Aspire CLI etkileşimlidir; istendiğinde uygun sonucu seçin:

Aspire CLI — Örnek çıktı

Select an integration to add:

> azure-storage (Aspire.Hosting.Azure.Storage)
> Other results listed as selectable options...

Not

Yalnızca tek sonuç varsa otomatik seçilir. Sürümü yine de onaylayın.

apphost.cs (C# file-based app)

C# — AppHost.cs

#:package Aspire.Hosting.Azure.Storage@*

PackageReference (*.csproj)

XML — Aspire.Hosting.Azure.Storage paket referansı ekle

<PackageReference Include="Aspire.Hosting.Azure.Storage" Version="*" />

Add Azure Queue Storage resource

In your AppHost project, register the Azure Queue Storage integration by chaining a call to AddQueues on the IResourceBuilder<IAzureStorageResource> instance returned by AddAzureStorage. The following example demonstrates how to add an Azure Queue Storage resource named storage and a queue named queues:

C# — AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

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

builder.AddProject<Projects.ExampleProject>()
    .WithReference(queues)
    .WaitFor(queues);

// After adding all resources, run the app...

The preceding code:

• Adds an Azure Storage resource named storage.
• Chains a call to RunAsEmulator to configure the storage resource to run locally using an emulator. The emulator in this case is Azurite.
• Adds a blob container named queues to the storage resource.
• Adds the queues resource to the ExampleProject and waits for it to be ready before starting the project.

Dikkat

When you call AddAzureStorage, it implicitly calls AddAzureProvisioning—which adds support for generating Azure resources dynamically during app startup. The app must configure the appropriate subscription and location. For more information, see Local provisioning: Configuration.

Connect to an existing Azure Storage account

You might have an existing Azure Storage account that you want to connect to. You can chain a call to annotate that your AzureStorageResource is an existing resource:

C# — AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

var existingStorageName = builder.AddParameter("existingStorageName");
var existingStorageResourceGroup = builder.AddParameter("existingStorageResourceGroup");

var storageaccount = builder.AddAzureStorage("storage")
    .AsExisting(existingStorageName, existingStorageResourceGroup)
    .AddQueues("queues");

builder.AddProject<Projects.ExampleProject>()
    .WithReference(storageaccount);

// After adding all resources, run the app...

Caution

When you call RunAsExisting, PublishAsExisting, or AsExisting methods to work with resources that are already present in your Azure subscription, you must add certain configuration values to your AppHost to ensure that Aspire can locate them. The necessary configuration values include SubscriptionId, AllowResourceGroupCreation, ResourceGroup, and Location. If you don’t set them, “Missing configuration” errors appear in the Aspire dashboard. For more information about how to set them, see Use existing Azure resources.

Configure Azurite container

There are various configurations available to container resources, for example, you can configure the container’s ports, environment variables, it’s lifetime, and more.

Configure Azurite container ports

By default, the Azurite container when configured by Aspire, exposes the following endpoints:

Endpoint	Container port	Host port
blob	10000	dynamic
queue	10001	dynamic
table	10002	dynamic

The port that they’re listening on is dynamic by default. When the container starts, the ports are mapped to a random port on the host machine. To configure the endpoint ports, chain calls on the container resource builder provided by the RunAsEmulator method as shown in the following example:

C# — AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

var storage = builder.AddAzureStorage("storage")
  .RunAsEmulator(azurite =>
  {
      azurite.WithBlobPort(27000)
            .WithQueuePort(27001)
            .WithTablePort(27002);
  });

// After adding all resources, run the app...

The preceding code configures the Azurite container’s existing blob, queue, and table endpoints to listen on ports 27000, 27001, and 27002, respectively. The Azurite container’s ports are mapped to the host ports as shown in the following table:

Endpoint name	Port mapping (container:host)
blob	10000:27000
queue	10001:27001
table	10002:27002

Configure Azurite container with persistent lifetime

To configure the Azurite container with a persistent lifetime, call the WithLifetime method on the Azurite container resource and pass ContainerLifetime.Persistent:

C# — AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

var storage = builder.AddAzureStorage("storage")
    .RunAsEmulator(azurite =>
    {
        azurite.WithLifetime(ContainerLifetime.Persistent);
    });

// After adding all resources, run the app...

Configure Azurite container with data volume

To add a data volume to the Azure Storage emulator resource, call the WithDataVolume method on the Azure Storage emulator resource:

C# — AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

var storage = builder.AddAzureStorage("storage")
    .RunAsEmulator(azurite =>
    {
        azurite.WithDataVolume();
    });

// After adding all resources, run the app...

The data volume is used to persist the Azurite data outside the lifecycle of its container. The data volume is mounted at the /data path in the Azurite container and when a name parameter isn’t provided, the name is formatted as .azurite/{resource name}. For more information on data volumes and details on why they’re preferred over bind mounts, see Docker docs: Volumes.

Configure Azurite container with data bind mount

To add a data bind mount to the Azure Storage emulator resource, call the WithDataBindMount method:

C# — AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

var storage = builder.AddAzureStorage("storage")
    .RunAsEmulator(azurite =>
    {
        azurite.WithDataBindMount("../azurite/data");
    });

// After adding all resources, run the app...

Caution

Data bind mounts have limited functionality compared to volumes, which offer better performance, portability, and security, making them more suitable for production environments. However, bind mounts allow direct access and modification of files on the host system, ideal for development and testing where real-time changes are needed.

Data bind mounts rely on the host machine’s filesystem to persist the Azurite data across container restarts. The data bind mount is mounted at the ../azurite/data path on the host machine relative to the AppHost directory (IDistributedApplicationBuilder.AppHostDirectory) in the Azurite container. For more information on data bind mounts, see Docker docs: Bind mounts.

Connect to storage resources

When the Aspire AppHost runs, the storage resources can be accessed by external tools, such as the Azure Storage Explorer. If your storage resource is running locally using Azurite, it will automatically be picked up by the Azure Storage Explorer.

Note

The Azure Storage Explorer discovers Azurite storage resources assuming the default ports are used. If you’ve configured the Azurite container to use different ports, you’ll need to configure the Azure Storage Explorer to connect to the correct ports.

To connect to the storage resource from Azure Storage Explorer, follow these steps:

1. Run the Aspire AppHost.

2. Open the Azure Storage Explorer.

3. View the Explorer pane.

4. Select the Refresh all link to refresh the list of storage accounts.

5. Expand the Emulator & Attached node.

6. Expand the Storage Accounts node.

7. You should see a storage account with your resource’s name as a prefix:

   

You’re free to explore the storage account and its contents using the Azure Storage Explorer. For more information on using the Azure Storage Explorer, see Get started with Storage Explorer.

Client integration

To get started with the Aspire Azure Queue Storage client integration, install the 📦 Aspire.Azure.Storage.Queues NuGet package:

.NET CLI

.NET CLI — Add Aspire.Azure.Storage.Queues package

dotnet add package Aspire.Azure.Storage.Queues

Program.cs (C# file-based app)

Program.cs

#:package Aspire.Azure.Storage.Queues@*

PackageReference (*.csproj)

XML — Add Aspire.Azure.Storage.Queues package reference

<PackageReference Include="Aspire.Azure.Storage.Queues" Version="*" />

Add Azure Queue Storage client

In the Program.cs file of your client-consuming project, call the AddAzureQueueClient extension method to register a QueueServiceClient for dependency injection. The method takes a connection name parameter:

builder.AddAzureQueueClient("queues");

You can then retrieve the QueueServiceClient instance using dependency injection:

public class ExampleService(QueueServiceClient client)
{
    // Use client...
}

Configuration

The Azure Queue Storage integration provides multiple options to configure the QueueServiceClient.

Use a connection string

When using a connection string from the ConnectionStrings configuration section, provide the name when calling AddAzureQueueClient:

builder.AddAzureQueueClient("queues");

Two connection formats are supported:

Service URI

The recommended approach is to use a ServiceUri, which works with the Credential property. If no credential is configured, the DefaultAzureCredential is used:

{
  "ConnectionStrings": {
    "queues": "https://{account_name}.queue.core.windows.net/"
  }
}

Connection string

Alternatively, an Azure Storage connection string can be used:

{
  "ConnectionStrings": {
    "queues": "AccountName=myaccount;AccountKey=myaccountkey"
  }
}

Use configuration providers

The Azure Queue Storage integration supports Microsoft.Extensions.Configuration. It loads the AzureStorageQueuesSettings and QueueClientOptions from configuration using the Aspire:Azure:Storage:Queues key. Example appsettings.json:

{
  "Aspire": {
    "Azure": {
      "Storage": {
        "Queues": {
          "DisableHealthChecks": true,
          "DisableTracing": false,
          "ClientOptions": {
            "Diagnostics": {
              "ApplicationId": "myapp"
            }
          }
        }
      }
    }
  }
}

Use named configuration

The Azure Queue Storage integration supports named configuration for multiple instances:

{
  "Aspire": {
    "Azure": {
      "Storage": {
        "Queues": {
          "queue1": {
            "DisableHealthChecks": true,
            "ClientOptions": {
              "Diagnostics": {
                "ApplicationId": "myapp1"
              }
            }
          },
          "queue2": {
            "DisableTracing": true,
            "ClientOptions": {
              "Diagnostics": {
                "ApplicationId": "myapp2"
              }
            }
          }
        }
      }
    }
  }
}

Use the connection names when calling AddAzureQueueClient:

builder.AddAzureQueueClient("queue1");
builder.AddAzureQueueClient("queue2");

Use inline delegates

You can also pass the Action<AzureStorageQueuesSettings> delegate to set up options inline:

builder.AddAzureQueueClient(
    "queues",
    settings => settings.DisableHealthChecks = true);

You can also configure the QueueClientOptions:

builder.AddAzureQueueClient(
    "queues",
    configureClientBuilder: clientBuilder =>
        clientBuilder.ConfigureOptions(
            options => options.Diagnostics.ApplicationId = "myapp"));

Client integration health checks

By default, Aspire integrations enable health checks for all services. The Azure Queue Storage integration:

• Adds the health check when DisableHealthChecks is false, which attempts to connect to the Azure Queue Storage.
• Integrates with the /health HTTP endpoint, which specifies all registered health checks must pass for app to be considered ready to accept traffic.

Observability and telemetry

Logging

The Azure Queue Storage integration uses the following log categories:

• Azure.Core
• Azure.Identity

Tracing

The Azure Queue Storage integration emits the following tracing activities using OpenTelemetry:

• Azure.Storage.Queues.QueueClient

Metrics

The Azure Queue Storage integration currently doesn’t support metrics by default due to limitations with the Azure SDK.