.NET Aspire Azure 數據表整合

發行項
12/13/2024

Azure Table Storage 是用來儲存結構化 NoSQL 數據的服務。 .NET Aspire Azure 數據表整合可讓您連線到現有的 Azure Table 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 應用程式中管理套件相依性。

新增 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 會指派給具有 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("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...

重要

相較於磁碟區，數據系結掛接的功能有限，可提供更佳的效能、可移植性和安全性，使其更適合生產環境。不過，bind 掛載允許直接存取和修改主機系統上的檔案，非常適合用於需要即時變更的情境，例如開發和測試。

數據系結掛接依賴主計算機的文件系統，在容器重新啟動時保存 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 Table Storage 資源

在應用程式的主機專案中，請在由 Azure Table Storage返回的 AddTables 實例上呼叫 IResourceBuilder<IAzureStorageResource>，以鏈結和註冊 AddAzureStorage 整合。下列範例示範如何新增名為 Azure Table Storage 的 storage 資源，以及名為 tables的數據表資源：

var builder = DistributedApplication.CreateBuilder(args);

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

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

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

上述程式代碼：

新增名為 Azure的 storage 儲存資源。
將名為 tables 的數據表記憶體資源新增至記憶體資源。
將 storage 資源新增至 ExampleProject，並等候它準備好再啟動專案。

主機整合健康檢查

Azure 記憶體裝載整合會自動新增記憶體資源的健全狀況檢查。只有在以模擬器身分執行時才會新增它。此時會確認 Azurite 容器正在執行，並確保可以建立連線。裝載整合依賴 📦 AspNetCore.HealthChecks。AzureStorage.Blobs NuGet 套件。

Client 整合

若要開始使用 .NET AspireAzure 資料表 client 整合，請在 📦使用的專案中安裝 client NuGet 套件，也就是用於 Azure 資料表的應用程式專案 client。 Azure 數據表 client 整合會註冊可用來與 TableServiceClient互動的 Azure Table Storage 實例。

.NET CLI
PackageReference

dotnet add package Aspire.Azure.Data.Tables

<PackageReference Include="Aspire.Azure.Data.Tables"
                  Version="*" />

新增 Azure Table Storageclient

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

builder.AddAzureTableClient("tables");

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

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

配置

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

使用組態提供者

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

{
  "Aspire": {
    "Azure": {
      "Data": {
        "Tables": {
          "ServiceUri": "YOUR_URI",
          "DisableHealthChecks": true,
          "DisableTracing": false,
          "ClientOptions": {
            "EnableTenantDiscovery": true
          }
        }
      }
    }
  }
}

如需完整的 Azure 資料表 client 整合 JSON 架構，請參閱 Aspire。Azure。Data.Tables/ConfigurationSchema。json。

使用內聯委派

您也可以傳遞 Action<AzureDataTablesSettings> configureSettings 委派來設定一些或所有內嵌的選項，例如設定 ServiceUri：

builder.AddAzureTableClient(
    "tables",
    settings => settings.DisableHealthChecks = true);

您也可以使用 TableClientOptions 委派來設定 Action<IAzureClientBuilder<TableServiceClient, TableClientOptions>> configureClientBuilder，這是 AddAzureTableClient 方法的第二個參數。例如，若要設定 TableServiceClient 標識碼來識別 client：

builder.AddAzureTableClient(
    "tables",
    configureClientBuilder: clientBuilder =>
        clientBuilder.ConfigureOptions(
            options => options.EnableTenantDiscovery = true));

Client 整合健康檢查

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

.NET Aspire Azure 資料表的整合

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

可檢視性和遙測

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

伐木

.NET Aspire Azure 資料表整合會使用下列記錄類別：

Azure.Core
Azure.Identity

追蹤

.NET Aspire Azure 資料表整合會使用 OpenTelemetry發出下列追蹤活動：

Azure.Data.Tables.TableServiceClient

指標

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

共用方式為