.NET Aspire Azure Blob Storage 整合

發行項
12/15/2024

Azure Blob Storage 是一項用於儲存大量非結構化數據的服務。 .NET Aspire Azure Blob Storage 整合可讓您連線到現有的 Azure Blob Storage 實例，或從 .NET 應用程式建立新的實例。

主機整合

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

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

若要存取這些類型和 API，以表示它們，請在 📦 專案中加入 AspireAzure.Hosting..Storage NuGet 套件。

.NET CLI
PackageReference

dotnet add package Aspire.Hosting.Azure.Storage

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

如需詳細資訊，請參閱 dotnet add package 或管理套件相依性在 .NET applications。

新增 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`	一萬	動態
`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 Blob Storage 資源

在您的應用程式主專案中，藉由將對 Azure Blob Storage的呼叫鏈結至其傳回的 AddBlobs 實例上的 IResourceBuilder<IAzureStorageResource>，來註冊 AddAzureStorage 整合。下列範例示範如何新增名為 Azure Blob Storage 的 storage 資源，以及名為 blobs的 Blob 容器：

var builder = DistributedApplication.CreateBuilder(args);

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

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

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

上述程式代碼：

新增名為 Azure的 storage 儲存資源。
將呼叫鏈結至 RunAsEmulator，以設定記憶體資源以使用模擬器在本機執行。在這種情況下，模擬器是 Azurite。
將名為 blobs 的 Blob 容器新增至記憶體資源。
將 blobs 資源新增至 ExampleProject，並等候它準備好再啟動專案。

主機整合健康檢查

Azure 儲存託管整合會自動新增儲存資源的健全狀況檢查。只有在以模擬器身份執行時才會新增它，並驗證 Azurite 容器正在運行且可以成功建立連線。主機整合依賴 📦 AspNetCore.HealthChecksAzure.Storage.Blobs NuGet 套件。

Client 整合

若要開始使用 .NET AspireAzure Blob Storageclient 整合，請在 📦消費專案中安裝 client NuGet 套件，也就是運行 Azure Blob Storageclient的應用程式專案。 Azure Blob Storage client 整合會註冊 BlobServiceClient 實例，您可以使用該實例與 Azure Blob Storage互動。

.NET CLI
PackageReference

dotnet add package Aspire.Azure.Storage.Blobs

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

新增 Azure Blob Storageclient

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

builder.AddAzureBlobClient("blobs");

接著，您可以使用依賴注入來取得 BlobServiceClient 實例。例如，若要從服務擷取 client：

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

配置

.NET Aspire Azure Blob Storage 整合提供多個選項，可根據專案的需求和慣例來設定 BlobServiceClient。

使用連接字串

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

builder.AddAzureBlobClient("blobs");

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

服務 URI

建議的方法是使用 ServiceUri，其可與 AzureStorageBlobsSettings.Credential 屬性搭配使用，以建立連線。如果未設定認證，則會使用 Azure.Identity.DefaultAzureCredential。

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

連接字串

或者，可以使用 Azure 記憶體連接字串。

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

如需詳細資訊，請參閱設定 Azure 記憶體連接字串。

使用組態提供者

.NET Aspire Azure Blob Storage 整合支援 Microsoft.Extensions.Configuration。它會使用 AzureStorageBlobsSettings 鍵從組態載入 BlobClientOptions 和 Aspire:Azure:Storage:Blobs。下列代碼段是 appsettings.json 檔案的範例，可設定一些選項：

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

如需完整的 Azure Blob Storageclient 整合 JSON 架構，請參閱 Aspire。Azure。Storage.Blobs/ConfigurationSchema。json。

使用內聯委派

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

builder.AddAzureBlobClient(
    "blobs",
    settings => settings.DisableHealthChecks = true);

您也可以透過 BlobClientOptions 方法的第二個參數 Action<IAzureClientBuilder<BlobServiceClient, BlobClientOptions>> configureClientBuilder 委派來設定 AddAzureBlobClient。例如，若要為此 client發出的所有請求設定使用者代理標頭的起始部分：

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

Client 整合健康檢查

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

.NET Aspire Azure Blob Storage 整合：

當 AzureStorageBlobsSettings.DisableHealthChecks 為 false時，新增健康情況檢查，這會嘗試連線到 Azure Blob Storage。
與 /health HTTP 端點整合，要求所有已註冊的健康檢查必須通過，才能認為應用程式已準備好接受流量。

可檢視性和遙測

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

伐木

.NET Aspire Azure Blob Storage 整合會使用下列記錄類別：

Azure.Core
Azure.Identity

追蹤

.NET Aspire Azure Blob Storage 整合會使用 OpenTelemetry產生以下追蹤活動：

Azure.Storage.Blobs.BlobContainerClient

指標

.NET Aspire Azure Blob Storage 整合目前預設不支援計量，因為 Azure SDK 的限制。

共用方式為