azure-storage-queues-integration.md

title	description	ms.date	uid
.NET Aspire Azure Queue Storage integration	This article describes the .NET Aspire Azure Queue Storage integration features and capabilities.	12/09/2024	storage/azure-queue-storage-integration

.NET Aspire Azure Queue Storage integration

[!INCLUDE includes-hosting-and-client]

Azure Queue Storage is a service for storing large numbers of messages that can be accessed from anywhere in the world via authenticated calls. The .NET Aspire Azure Queue Storage integration enables you to connect to existing Azure Queue Storage instances or create new instances from .NET applications.

Hosting integration

[!INCLUDE storage-app-host]

Add Azure Queue Storage resource

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

var builder = DistributedApplication.CreateBuilder(args);

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

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

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

The preceding code:

• Adds an Azure Storage resource named storage.
• Adds a queue named queues to the storage resource.
• Adds the storage resource to the ExampleProject and waits for it to be ready before starting the project.

[!INCLUDE storage-hosting-health-checks]

Client integration

To get started with the .NET Aspire Azure Queue Storage client integration, install the 📦 Aspire.Azure.Storage.Queues NuGet package in the client-consuming project, that is, the project for the application that uses the Azure Queue Storage client. The Azure Queue Storage client integration registers a xref:Azure.Storage.Queues.QueueServiceClient instance that you can use to interact with Azure Queue Storage.

.NET CLI

dotnet add package Aspire.Azure.Storage.Queues

PackageReference

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

---

Add Azure Queue Storage client

In the :::no-loc text="Program.cs"::: file of your client-consuming project, call the xref:Microsoft.Extensions.Hosting.AspireQueueStorageExtensions.AddAzureQueueClient%2A extension method on any xref:Microsoft.Extensions.Hosting.IHostApplicationBuilder to register a QueueServiceClient for use via the dependency injection container. The method takes a connection name parameter.

builder.AddAzureQueueClient("queue");

You can then retrieve the QueueServiceClient instance using dependency injection. For example, to retrieve the client from a service:

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

Configuration

The .NET Aspire Azure Queue Storage integration provides multiple options to configure the QueueServiceClient based on the requirements and conventions of your project.

Use a connection string

When using a connection string from the ConnectionStrings configuration section, you can provide the name of the connection string when calling xref:Microsoft.Extensions.Hosting.AspireQueueStorageExtensions.AddAzureQueueClient*:

builder.AddAzureQueueClient("queue");

Then the connection string is retrieved from the ConnectionStrings configuration section, and two connection formats are supported:

Service URI

The recommended approach is to use a ServiceUri, which works with the xref:Aspire.Azure.Storage.Queues.AzureStorageQueuesSettings.Credential?displayProperty=nameWithType property to establish a connection. If no credential is configured, the xref:Azure.Identity.DefaultAzureCredential?displayProperty=fullName is used.

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

Connection string

Alternatively, an Azure Storage connection string can be used.

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

For more information, see Configure Azure Storage connection strings.

Use configuration providers

The .NET Aspire Azure Queue Storage integration supports xref:Microsoft.Extensions.Configuration?displayProperty=fullName. It loads the xref:Aspire.Azure.Storage.Queues.AzureStorageQueuesSettings and xref:Azure.Storage.Queues.QueueClientOptions from configuration by using the Aspire:Azure:Storage:Queues key. The following snippet is an example of a :::no-loc text="appsettings.json"::: file that configures some of the options:

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

For the complete Azure Storage Queues client integration JSON schema, see Aspire.Azure.Data.Queues/ConfigurationSchema.json.

Use inline delegates

You can also pass the Action<AzureStorageQueuesSettings> configureSettings delegate to set up some or all the options inline, for example to configure health checks:

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

You can also set up the xref:Azure.Storage.Queues.QueueClientOptions using Action<IAzureClientBuilder<QueueServiceClient, QueueClientOptions>> configureClientBuilder delegate, the second parameter of the AddAzureQueueClient method. For example, to set the first part of user-agent headers for all requests issues by this client:

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

Client integration health checks

By default, .NET Aspire integrations enable health checks for all services. For more information, see .NET Aspire integrations overview.

The .NET Aspire Azure Queue Storage integration:

• Adds the health check when xref:Aspire.Azure.Storage.Queues.AzureStorageQueuesSettings.DisableHealthChecks?displayProperty=nameWithType 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.

[!INCLUDE integration-observability-and-telemetry]

Logging

The .NET Aspire Azure Queue Storage integration uses the following log categories:

• Azure.Core
• Azure.Identity

Tracing

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

• Azure.Storage.Queues.QueueClient

Metrics

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

See also

• Azure Queue Storage docs
• .NET Aspire integrations
• .NET Aspire GitHub repo