.NET Aspire Azure 佇列儲存體整合

發行項
12/15/2024

Azure 佇列記憶體是一項服務，用於儲存大量訊息，可透過已驗證的呼叫從世界各地存取。 .NET Aspire Azure 佇列記憶體整合可讓您連線到現有的 Azure 佇列記憶體實例，或從 .NET 應用程式建立新的實例。

代管整合

.NET .NET Aspire Azure 儲存主機託管整合模型將各種儲存資源模型化為下列類型：

AzureStorageResource：代表 Azure 記憶體資源。
AzureStorageEmulatorResource：代表 Azure 記憶體模擬器資源（Azurite）。
AzureBlobStorageResource：代表 Azure Blob 記憶體資源。
AzureQueueStorageResource：代表 Azure 佇列記憶體資源。
AzureTableStorageResource：代表 Azure 資料表儲存資源。

若要存取這些型別和 API 來表示它們，請在 📦 專案中新增 AspireAzure.主機..儲存體 NuGet 套件。

.NET 命令列介面
PackageReference

dotnet add package Aspire.Hosting.Azure.Storage

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

如需詳細資訊，請參閱 dotnet add package 或管理 .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：

切換 Azure 記憶體 Bicep。

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

param principalId string

param principalType 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：記憶體帳戶的網路 ACL。預設值為 { defaultAction: 'Allow' }。

除了記憶體帳戶之外，也會布建 Blob 容器。

下列角色指派會新增到儲存體帳戶，以授予您的應用程式存取權。如需詳細資訊，請參閱內建 Azure 角色型訪問控制（Azure RBAC）角色：

角色/ 識別碼	描述
儲存體 Blob 數據貢獻者 `ba92f5b4-2d11-453d-a403-e96b0029c9fe`	讀取、寫入和刪除 Azure 儲存體容器和 Blob。
儲存表數據貢獻者 `0a9a7e1f-b9d0-4cc4-a60d-0319b160aaa3`	讀取、寫入和刪除 Azure 存储資料表和實體。
儲存佇列資料貢獻者 `974c5e8b-45b9-4653-ba55-5f855dd0fb88`	讀取、寫入和刪除 Azure 記憶體佇列和佇列訊息。

生成的 Bicep 是一個起點，可以進行自訂，以符合您的特定需求。

客製化布建基礎結構

所有 .NET AspireAzure 資源都是 AzureProvisioningResource 類型的子類別。此類型可藉由提供 Fluent API 來設定 Azure 資源，藉此自定義產生的 Bicep，方法是使用 ConfigureInfrastructure<T>(IResourceBuilder<T>, Action<AzureResourceInfrastructure>) API。例如，您可以設定 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 會指派給具有 StorageSkuName 的新 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`	10000	動態
`queue`	10001	動態
`table`	10002	動態

他們正在監聽的端口預設為動態的。當容器啟動時，埠會映射到主機上的隨機端口。若要設定端點埠，請在 RunAsEmulator 方法所提供的容器資源產生器上鏈結呼叫，如下列範例所示：

var builder = DistributedApplication.CreateBuilder(args);

var storage = builder.AddAzureStorage("storage").RunAsEmulator(
                     azurite =>
                     {
                         azurite.WithBlobPort("blob", 27000)
                                .WithQueuePort("queue", 27001)
                                .WithTablePort("table", 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/Data 路徑上，相對於 Azurite 容器中的應用程式主機目錄（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 佇列記憶體 client 整合，請安裝 📦Aspire。Azure。Storage.Queuesclient-consuming 專案中的 NuGet 套件，也就是使用 Azure 佇列記憶體的應用程式專案 client。 Azure 佇列儲存體 client 整合會註冊一個 QueueServiceClient 實例，用於與 Azure 佇列儲存體互動。

.NET 命令列介面
PackageReference

dotnet add package Aspire.Azure.Storage.Queues

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

新增佇列記憶體 Azureclient

在 Program.cs取用專案的 client 檔案中，在任何 AddAzureQueueClient 上呼叫 IHostApplicationBuilder 擴充方法，以註冊 QueueServiceClient，以透過相依性插入容器使用。方法會採用連接名稱參數。

builder.AddAzureQueueClient("queue");

然後，您可以使用依賴注入來擷取 QueueServiceClient 實例。例如，若要從服務擷取編號 client：

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

配置

.NET Aspire Azure 佇列記憶體整合提供多個選項，可根據專案的需求和慣例來設定 QueueServiceClient。

使用連線字串

從 [ConnectionStrings 組態] 區段使用連接字串時，您可以在呼叫 AddAzureQueueClient時提供連接字串的名稱：

builder.AddAzureQueueClient("queue");

然後，從 ConnectionStrings 組態區段擷取連接字串，並支援兩種連線格式：

服務 URI

建議的方法是使用 ServiceUri，其可與 AzureStorageQueuesSettings.Credential 屬性搭配使用，以建立連線。如果未設定認證，則會使用 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。它會使用 AzureStorageQueuesSettings 鍵從組態載入 QueueClientOptions 和 Aspire:Azure:Storage:Queues。下列代碼段是 appsettings.json 檔案的範例，可設定一些選項：

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

如需完整的 Azure Storage Queuesclient 整合 JSON 架構，請參閱 Aspire。Azure。Data.Queues/ConfigurationSchema。json。

使用內聯委派

您也可以傳遞 Action<AzureStorageQueuesSettings> configureSettings 委派來設定部分或所有內嵌選項，例如設定健康情況檢查：

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

您也可以使用 QueueClientOptions 委派來設定 Action<IAzureClientBuilder<QueueServiceClient, QueueClientOptions>> configureClientBuilder，這是 AddAzureQueueClient 方法的第二個參數。例如，若要設定此 client的所有請求中的用戶代理標頭的第一部分：

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

Client 整合健康情況檢查

預設，.NET.NET Aspire 整合會為所有服務啟用健康檢查。如需詳細資訊，請參閱 .NET.NET Aspire 整合概觀。

.NET Aspire Azure 佇列儲存體整合：

當 AzureStorageQueuesSettings.DisableHealthChecks 是 false時，新增健康檢查，以嘗試連線到 Azure 佇列記憶體。
與 /health HTTP 端點整合，指定所有已註冊的健康檢查都必須通過，應用程式才能被視為準備好接受流量。

可檢視性和遙測

.NET .NET Aspire 整合會自動設定記錄、追蹤和監控組態，通常稱為 可觀察性支柱。如需整合可觀察性和遙測的詳細資訊，請參閱 .NET.NET Aspire 整合概觀。視支援服務而定，某些整合可能只支援其中一些功能。例如，某些整合支援記錄和追蹤，但不支援計量。您也可以使用組態一節中呈現的技術來停用遙測功能。

伐木

.NET Aspire Azure 佇列記憶體整合會使用下列記錄類別：

Azure.Core
Azure.Identity

追蹤

.NET Aspire Azure 佇列存儲整合會使用 OpenTelemetry發出下列追蹤活動：

Azure.Storage.Queues.QueueClient

指標

.NET Aspire Azure 佇列儲存整合目前預設情況下不支援度量，這是由於 Azure SDK 的限制。

共用方式為