.NET Aspire Azure 队列存储集成

项目
03/09/2025

包括： 托管集成和 Client 集成

Azure 队列存储是一项服务，用于存储大量可以通过经过身份验证的调用从世界上任何地方访问的消息。通过 .NET AspireAzure 队列存储集成，可以连接到现有的 Azure 队列存储实例，或从 .NET 应用程序中创建新实例。

托管集成

各种存储资源的托管集成将 .NET.NET AspireAzure 存储模型化为以下类型：

AzureStorageResource：表示 Azure 存储资源。
AzureStorageEmulatorResource：表示 Azure 存储模拟器资源（Azurite）。
AzureBlobStorageResource：表示 Azure Blob 存储资源。
AzureQueueStorageResource: 表示 Azure 队列存储资源。
AzureTableStorageResource：表示 Azure 表存储资源。

若要访问这些类型和 API 来表达它们，请在应用程序宿主项目中添加 📦Aspire.Hosting.Azure.Storage NuGet 包。

.NET CLI
PackageReference

dotnet add package Aspire.Hosting.Azure.Storage

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

有关详细信息，请参阅 dotnet 添加包或管理 .NET 应用程序中的包依赖性。

添加 Azure 存储资源

在应用主机项目中，调用 AddAzureStorage 添加并返回 Azure 存储资源生成器。

var builder = DistributedApplication.CreateBuilder(args);

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

// An Azure Storage resource is required to add any of the following:
//
// - Azure Blob storage resource.
// - Azure Queue storage resource.
// - Azure Table storage resource.

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

将 AzureStorageResource 添加到应用主机时，它会公开其他有用的 API 来添加 Azure Blob、队列和表格存储资源。换句话说，在添加任何其他存储资源之前，必须添加 AzureStorageResource。

重要

调用 AddAzureStorage时，它会隐式调用 AddAzureProvisioning，这增加了在应用启动期间动态生成 Azure 资源的支持。应用必须配置相应的订阅和位置。有关详细信息，请参阅本地预配：配置。

生成的预配 Bicep

如果你是 Bicep的新手，它是一种用于定义 Azure 资源的领域专用语言。使用 .NET.NET Aspire，无需手动编写 Bicep，而是预配 API 会为你生成 Bicep。发布应用时，生成的 Bicep 文件将会与清单文件一同输出。添加 Azure 存储资源时，将生成以下 Bicep：

@description('The location for the resource(s) to be deployed.')
param location string = resourceGroup().location

param principalType string

param principalId string

resource storage 'Microsoft.Storage/storageAccounts@2024-01-01' = {
  name: take('storage${uniqueString(resourceGroup().id)}', 24)
  kind: 'StorageV2'
  location: location
  sku: {
    name: 'Standard_GRS'
  }
  properties: {
    accessTier: 'Hot'
    allowSharedKeyAccess: false
    minimumTlsVersion: 'TLS1_2'
    networkAcls: {
      defaultAction: 'Allow'
    }
  }
  tags: {
    'aspire-resource-name': 'storage'
  }
}

resource blobs 'Microsoft.Storage/storageAccounts/blobServices@2024-01-01' = {
  name: 'default'
  parent: storage
}

resource storage_StorageBlobDataContributor 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
  name: guid(storage.id, principalId, subscriptionResourceId('Microsoft.Authorization/roleDefinitions', 'ba92f5b4-2d11-453d-a403-e96b0029c9fe'))
  properties: {
    principalId: principalId
    roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', 'ba92f5b4-2d11-453d-a403-e96b0029c9fe')
    principalType: principalType
  }
  scope: storage
}

resource storage_StorageTableDataContributor 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
  name: guid(storage.id, principalId, subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '0a9a7e1f-b9d0-4cc4-a60d-0319b160aaa3'))
  properties: {
    principalId: principalId
    roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '0a9a7e1f-b9d0-4cc4-a60d-0319b160aaa3')
    principalType: principalType
  }
  scope: storage
}

resource storage_StorageQueueDataContributor 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
  name: guid(storage.id, principalId, subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '974c5e8b-45b9-4653-ba55-5f855dd0fb88'))
  properties: {
    principalId: principalId
    roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '974c5e8b-45b9-4653-ba55-5f855dd0fb88')
    principalType: principalType
  }
  scope: storage
}

output blobEndpoint string = storage.properties.primaryEndpoints.blob

output queueEndpoint string = storage.properties.primaryEndpoints.queue

output tableEndpoint string = storage.properties.primaryEndpoints.table

前面的 Bicep 是一个模块，它预配了具有以下默认值的 Azure 存储帐户：

kind：存储帐户的类型。默认值为 StorageV2。
sku：存储帐户的 SKU。默认值为 Standard_GRS。
properties：存储帐户的属性：
- accessTier：存储帐户的访问层。默认值为 Hot。
- allowSharedKeyAccess：一个布尔值，该值指示存储帐户是否允许使用帐户访问密钥授权请求。默认值为 false。
- minimumTlsVersion：存储帐户支持的最低 TLS 版本。默认值为 TLS1_2。
- networkAcls：存储帐户的网络访问控制列表。默认值为 { defaultAction: 'Allow' }。

除了存储帐户之外，它还会创建一个 Blob 容器。

以下角色分配将添加到存储帐户，以授予应用程序访问权限。请参阅有关内置 Azure 基于角色的访问控制 (Azure RBAC) 角色的更多信息：

角色/ID	描述
存储 Blob 数据贡献者 `ba92f5b4-2d11-453d-a403-e96b0029c9fe`	读取、写入和删除 Azure 存储容器和 Blob。
存储表数据贡献者 `0a9a7e1f-b9d0-4cc4-a60d-0319b160aaa3`	读取、写入和删除 Azure 存储表和实体。
存储队列数据贡献者 `974c5e8b-45b9-4653-ba55-5f855dd0fb88`	读取、写入和删除 Azure 存储队列和队列消息。

生成的 Bicep 只是一个起点，可以根据您的具体需求进行定制。

自定义预配基础结构

所有 .NET AspireAzure 资源都是 AzureProvisioningResource 类型的子类。此类型通过提供流畅的 API 来配置 ConfigureInfrastructure<T>(IResourceBuilder<T>, Action<AzureResourceInfrastructure>) 资源，并使用 Azure API，从而实现生成的 Bicep 的自定义。例如，可以配置 kind、sku、properties等。以下示例演示如何自定义 Azure 存储资源：

builder.AddAzureStorage("storage")
    .ConfigureInfrastructure(infra =>
    {
        var storageAccount = infra.GetProvisionableResources()
                                  .OfType<StorageAccount>()
                                  .Single();

        storageAccount.AccessTier = StorageAccountAccessTier.Cool;
        storageAccount.Sku = new StorageSku { Name = StorageSkuName.PremiumZrs };
        storageAccount.Tags.Add("ExampleKey", "Example value");
    });

前面的代码：

将调用链接到 ConfigureInfrastructure API：
- infra 参数是 AzureResourceInfrastructure 类型的实例。
- 通过调用 GetProvisionableResources() 方法检索可预配资源。
- 单个 StorageAccount 被检索。
- StorageAccount.AccessTier 分配给 StorageAccountAccessTier.Cool。
- StorageAccount.Sku 被分配给一个新的 StorageSku，其 Name 为 PremiumZrs。
- 标记将添加到存储帐户中，其密钥为 ExampleKey，值为 Example value。

还有更多配置选项可用于自定义 Azure 存储资源。有关详细信息，请参阅 Azure.Provisioning.Storage。

连接到现有的 Azure 存储帐户

您可能有一个现有的 Azure 存储帐户需要连接。与其表示新的 Azure 存储资源，不如向应用主机添加连接字符串。若要将连接添加到现有 Azure 存储帐户，请调用 AddConnectionString 方法：

var builder = DistributedApplication.CreateBuilder(args);

var blobs = builder.AddConnectionString("blobs");

builder.AddProject<Projects.WebApplication>("web")
       .WithReference(blobs);

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

注意

连接字符串用于表示各种连接信息，包括数据库连接、消息代理、终结点 URI 和其他服务。在 .NET.NET Aspire 名词中，术语“连接字符串”用于表示任何类型的连接信息。

连接字符串是在应用主机的配置中配置的，通常在部分下的 ConnectionStrings下。应用主机将此连接字符串作为环境变量注入到所有依赖资源中，例如：

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

依赖资源可以通过调用 GetConnectionString 方法并传递连接名称作为参数来访问注入的连接字符串，在本例中为 "blobs"。 GetConnectionString API 是 IConfiguration.GetSection("ConnectionStrings")[name]的简写。

添加 Azure 存储模拟器资源

若要添加 Azure 存储模拟器资源，请将对 IResourceBuilder<AzureStorageResource> 的调用链接到 RunAsEmulator API：

var builder = DistributedApplication.CreateBuilder(args);

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

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

调用 RunAsEmulator时，它将存储资源配置为使用模拟器在本地运行。本例中使用的模拟器是 Azurite。 Azurite 开源模拟器为测试您的 Azure Blob 存储、队列存储和表存储应用提供了一个免费的本地环境，它是 .NET AspireAzure 托管集成的理想搭档。 Azurite 未作为独立应用安装，而是作为容器供 .NET.NET Aspire 使用。当您将容器添加到应用主机时，会在应用主机启动时创建并启动容器，就像前面的示例中所示的 mcr.microsoft.com/azure-storage/azurite 映像一样。有关详细信息，请参阅容器资源生命周期。

配置 Azurite 容器

容器资源可以使用各种配置，例如，可以配置容器的端口、环境变量、生存期等。

配置 Azurite 容器端口

默认情况下，.NET.NET Aspire配置 Azurite 容器时，会公开以下终结点：

端点	集装箱港口	主机端口
`blob`	一万	动态
`queue`	10001	动态
`table`	10002	动态

默认情况下，他们正在侦听的端口是动态的。容器启动时，其端口会映射到主机上的一个随机端口。若要配置终结点端口，请对 RunAsEmulator 方法提供的容器资源生成器进行链式调用，如以下示例所示：

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...

前面的代码将 Azurite 容器的现有 blob、queue和 table 终结点分别配置为侦听端口 27000、27001和 27002。 Azurite 容器的端口已经映射到主机端口，具体如下表所示：

终结点名称	端口映射（`container:host`）
`blob`	`10000:27000`
`queue`	`10001:27001`
`table`	`10002:27002`

配置持久生存期的 Azurite 容器

若要使用持久性生存期配置 Azurite 容器，请在 Azurite 容器资源上调用 WithLifetime 方法，并传递 ContainerLifetime.Persistent：

var builder = DistributedApplication.CreateBuilder(args);

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

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

有关详细信息，请参阅容器资源生存期。

使用数据卷配置 Azurite 容器

若要将数据卷添加到 Azure 存储模拟器资源，请在 WithDataVolume 存储模拟器资源上调用 Azure 方法：

var builder = DistributedApplication.CreateBuilder(args);

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

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

数据卷用于在容器生命周期之外持久化 Azurite 数据。数据卷装载在 Azurite 容器中的 /data 路径，如果未提供 name 参数，则名称的格式为 .azurite/{resource name}。有关数据卷的具体信息以及它们为何比绑定装载更受欢迎的原因，请参阅 Docker 文档：卷。

使用数据绑定挂载配置 Azurite 容器

若要将数据绑定装载添加到 Azure 存储模拟器资源，请调用 WithDataBindMount 方法：

var builder = DistributedApplication.CreateBuilder(args);

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

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

重要

与卷相比，绑定挂载的功能有限，卷提供了更好的性能、可移植性和安全性，使它们更适合用于生产环境。但是，绑定装载允许直接访问和修改主机系统上的文件，非常适合在需要实时更改的情况下进行开发和测试。

数据绑定挂载依赖于主机的文件系统，以便在容器重启时保留 Azurite 数据。在 Azurite 容器中，数据挂载在主机的 ../Azurite/Data 路径上，该路径是相对于应用主机目录（IDistributedApplicationBuilder.AppHostDirectory）的。有关数据绑定装载的详细信息，请参阅 Docker 文档：绑定装载。

连接到存储资源

.NET .NET Aspire 应用主机运行时，可以通过外部工具（例如 Azure 存储资源管理器）访问存储资源。如果存储资源使用 Azurite 在本地运行，Azure 存储资源管理器会自动检测到它。

注意

Azure 存储资源管理器将在使用默认端口的情况下自动发现 Azurite 存储资源。如果已将 Azurite 容器配置为使用不同的端口，则需要配置 Azure 存储资源管理器以连接到正确的端口。

若要从 Azure 存储资源管理器连接到存储资源，请执行以下步骤：

运行 .NET.NET Aspire 应用主机。
打开 Azure 存储资源管理器。
查看 资源管理器 窗格。
选择“刷新所有 链接以刷新存储帐户列表。
展开 模拟器与附加 节点。
展开 存储帐户 节点。
您应该看到一个以您的资源名称作为前缀的存储帐户。

可以使用 Azure 存储资源管理器免费浏览存储帐户及其内容。有关使用 Azure 存储资源管理器的详细信息，请参阅存储资源管理器入门。

添加 Azure 队列存储资源

在应用主机项目中，通过将调用链接到 Azure返回的 AddQueues 实例上的 IResourceBuilder<IAzureStorageResource> 来注册 AddAzureStorage 队列存储集成。以下示例演示如何添加名为 Azure 的 storage 队列存储资源，以及名为 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...

前面的代码：

添加名为 Azure的 storage 存储资源。
将名为 queues 的队列添加到存储资源。
将 storage 资源添加到 ExampleProject，并在启动项目之前等待它准备就绪。

主机托管集成运行状况检查

Azure 存储托管集成会自动为存储资源添加运行状况检查。只有在作为模拟器运行时才会添加该容器，并验证 Azurite 容器正在运行且可以建立连接。托管集成依赖于 📦 AspNetCore.HealthChecksAzure.Storage.Blobs NuGet 包。

Client 集成

若要开始 .NET AspireAzure 队列存储客户端集成，请在使用客户端的项目中安装 📦Aspire.Azure.Storage.Queues NuGet 包，即应用程序使用 Azure 队列存储客户端的项目。 Azure 队列存储客户端的集成中会注册一个 QueueServiceClient 实例，可用于与 Azure 队列存储进行交互。

.NET CLI
PackageReference

dotnet add package Aspire.Azure.Storage.Queues

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

添加 Azure 队列存储客户端

在您的客户端消费项目中的 Program.cs 文件中，对任何 AddAzureQueueClient 调用 IHostApplicationBuilder 扩展方法，以注册 QueueServiceClient，以便通过依赖注入容器进行使用。该方法采用连接名称参数。

builder.AddAzureQueueClient("queue");

然后，可以使用依赖项注入检索 QueueServiceClient 实例。例如若要从服务检索客户信息：

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

配置

.NET Aspire Azure 队列存储集成提供了多个选项，用于根据项目的要求和约定配置 QueueServiceClient。

使用连接字符串

使用 ConnectionStrings 配置部分中的连接字符串时，可以在调用 AddAzureQueueClient时提供连接字符串的名称：

builder.AddAzureQueueClient("queue");

然后，从 ConnectionStrings 配置部分检索连接字符串，支持两种连接格式：

服务统一资源标识符 (URI)

建议的方法是使用 ServiceUri，ServiceUri会与属性配合以建立连接。如果未配置凭据，则使用 Azure.Identity.DefaultAzureCredential。

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

连接字符串

或者，可以使用 Azure 存储连接字符串。

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

有关详细信息，请参阅配置 Azure 存储连接字符串。

使用配置提供者

.NET Aspire Azure 队列存储集成支持 Microsoft.Extensions.Configuration。它使用 Aspire:Azure:Storage:Queues 键从配置中加载 AzureStorageQueuesSettings 和 QueueClientOptions。以下片段是一个 appsettings.json 文件的示例, 用于配置某些选项：

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

有关完整的 Azure Storage Queues 客户端集成 JSON 架构，请参阅 Aspire、Azure中的 Data.Queues/ConfigurationSchema.json。

使用内联委托

还可以传递 Action<AzureStorageQueuesSettings> configureSettings 委托函数来内联设置一些或所有选项，例如配置健康检查功能：

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

可以使用Action<IAzureClientBuilder<QueueServiceClient, QueueClientOptions>> configureClientBuilder委托作为AddAzureQueueClient方法的第二个参数来设置QueueClientOptions。例如，若要为此客户端的所有请求设置用户代理标头的第一部分：

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

Client 集成运行状况检查

默认情况下，.NET.NET Aspire 集成会为所有服务启用健康检查。有关详细信息，请参阅 .NET.NET Aspire 集成概述。

.NET Aspire Azure 队列存储集成：

在 AzureStorageQueuesSettings.DisableHealthChecksfalse 时添加运行状况检查，这会尝试连接到 Azure 队列存储。
与 /health HTTP 终结点集成，该终结点要求所有已注册的健康检查必须通过，以便应用被视为已准备好接受流量。

可观测性和遥测

.NET .NET Aspire 集成会自动设置日志记录、跟踪和指标配置，这些配置有时称为 可观测性的支柱。有关集成可观测性和遥测的详细信息，请参阅 .NET.NET Aspire 集成概述。根据支持服务，某些集成可能仅支持其中一些功能。例如，某些集成支持日志记录和跟踪，但不支持指标。也可以使用配置部分中介绍的技术禁用遥测功能。

伐木

.NET Aspire Azure 队列存储集成使用以下日志类别：

Azure.Core
Azure.Identity

追踪

.NET Aspire Azure 队列存储集成使用 OpenTelemetry发出以下跟踪活动：

Azure.Storage.Queues.QueueClient

指标

由于 Azure SDK 的限制，.NET AspireAzure 队列存储集成目前不默认支持指标。

通过