.NET Aspire Azure データテーブルの統合

[アーティクル]
12/12/2024

Azure Table Storage は、構造化された NoSQL データを格納するためのサービスです。 .NET Aspire Azure データテーブル統合を使用すると、既存の Azure Table Storage インスタンスに接続したり、.NET アプリケーションから新しいインスタンスを作成したりできます。

ホスティング統合

.NET .NET Aspire Azure Storage ホスティング統合は、さまざまなストレージリソースを次の種類としてモデル化します。

AzureStorageResource: Azure Storage リソースを表します。
AzureStorageEmulatorResource: Azure ストレージエミュレーターリソース (Azurite) を表します。
AzureBlobStorageResource: Azure BLOB ストレージリソースを表します。
AzureQueueStorageResource: Azure キューストレージリソースを表します。
AzureTableStorageResource: Azure テーブルストレージリソースを表します。

これらの型と API にアクセスして表現するには、、📦、Aspire、.Hosting、Azure、およびを含む NuGet パッケージ .Storage を、アプリホストプロジェクトに追加します。

.NET CLI
PackageReference

dotnet add package Aspire.Hosting.Azure.Storage

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

詳細については、「dotnet パッケージの追加」または「.NET アプリケーションでのパッケージの依存関係の管理」を参照してください。

ストレージリソース Azure 追加する

アプリホストプロジェクトで、AddAzureStorage を呼び出して、Azure Storage リソースビルダーを追加して返します。

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 を追加すると、BLOB、Queue、Table Storage のリソース Azure 追加するための他の便利な API が公開されます。つまり、他のストレージリソースを追加する前に、AzureStorageResource を追加する必要があります。

重要

AddAzureStorageを呼び出すと、暗黙的に AddAzureProvisioningが呼び出されます。これによって、アプリの起動時に Azure リソースを動的に生成するためのサポートが追加されます。アプリは、適切なサブスクリプションと場所を構成する必要があります。詳細については、「ローカルプロビジョニング: 構成」を参照してください。

生成されたプロビジョニングのBicep

Bicepを初めてする場合は、リソースを定義するためのドメイン固有の言語です。 .NET .NET Aspireでは、Bicep を手動で記述する必要はありません。代わりに、プロビジョニング API によって Bicep が生成されます。アプリを発行すると、生成された Bicep がマニフェストファイルと共に出力されます。 Azure Storage リソースを追加すると、次の Bicep が生成されます。

ストレージ Bicep Azure 切り替えます。

@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）ロールを参照してください。

役割/ID	説明
ストレージブロブデータコントリビューター `ba92f5b4-2d11-453d-a403-e96b0029c9fe`	ストレージコンテナーと BLOB の「Azure」を読み取り、書き込み、削除します。
ストレージテーブルデータ共同作成者 `0a9a7e1f-b9d0-4cc4-a60d-0319b160aaa3`	Storage のテーブルとエンティティ Azure 読み取り、書き込み、削除します。
ストレージキューデータ共同作成者 `974c5e8b-45b9-4653-ba55-5f855dd0fb88`	Azure ストレージキューおよびキューメッセージを読み取り、書き込み、削除します。

生成された Bicep は開始点であり、特定の要件を満たすようにカスタマイズできます。

プロビジョニングインフラストラクチャをカスタマイズする

すべての .NET AspireAzure リソースは、AzureProvisioningResource 型のサブクラスです。生成された Bicep は、Azure API を使用して、ConfigureInfrastructure<T>(IResourceBuilder<T>, Action<AzureResourceInfrastructure>) リソースを構成するための流暢な API を提供することにより、カスタマイズできます。たとえば、kind、sku、propertiesなどを構成できます。次の例では、Azure Storage リソースをカスタマイズする方法を示します。

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 は、PremiumZrsの Name を持つ新しい StorageSku に割り当てられます。
- ExampleKey のキーと値が Example valueのタグがストレージアカウントに追加されます。

Azure Storage リソースをカスタマイズするために使用できる構成オプションは他にも多数あります。詳細については、Azure.Provisioning.Storageを参照してください。

既存の Azure ストレージアカウントに接続する

接続する既存の Azure ストレージアカウントがある場合があります。新しい Azure Storage リソースを表す代わりに、接続文字列をアプリホストに追加できます。既存の Azure Storage アカウントに接続を追加するには、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、Queue Storage、Table Storage アプリをテストするための無料のローカル環境を提供します。これは、.NET AspireAzure ホスティング統合に最適なコンパニオンです。 Azurite はインストールされていません。代わりに、コンテナーとして .NET.NET Aspire アクセスできます。前の例に示すように、mcr.microsoft.com/azure-storage/azurite イメージでコンテナーをアプリホストに追加すると、アプリホストが起動したときにコンテナーが作成されて起動されます。詳細については、「コンテナーリソースのライフサイクルの」を参照してください。

Azurite コンテナーを構成する

コンテナーリソースで使用できるさまざまな構成があります。たとえば、コンテナーのポート、環境変数、有効期間などを構成できます。

Azurite コンテナーポートの構成

既定では、.NET.NET Aspireによって構成された Azurite コンテナーは、次のエンドポイントを公開します。

エンドポイント	コンテナーポート	ホストポート
`blob`	10,000	動的
`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 ストレージエミュレーターリソースにデータボリュームを追加するには、Azure ストレージエミュレーターリソースで WithDataVolume メソッドを呼び出します。

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 コンテナー内のアプリホストディレクトリ (IDistributedApplicationBuilder.AppHostDirectory) を基準にして、ホストコンピューター上の ../Azurite/Data パスにマウントされます。データバインドマウントの詳細については、「Docker のドキュメント: バインドマウント」を参照してください。

ストレージリソースに接続する

.NET .NET Aspire アプリホストを実行すると、Azure Storage Explorerなどの外部ツールからストレージリソースにアクセスできます。 Azurite を使用してストレージリソースがローカルで実行されている場合は、Azure Storage Explorer によって自動的に取得されます。

手記

Azure Storage Explorer は、既定のポートが使用されていると仮定して Azurite ストレージリソースを検出します。異なるポートを使用するように Azurite コンテナーを構成した場合は、適切なポートに接続するように Storage Explorer を構成する必要があります。

ストレージエクスプローラーからストレージリソース Azure 接続するには、次の手順に従います。

.NET .NET Aspire アプリホストを実行します。
Azure Storage Explorer を開きます。
エクスプローラーの ペインを表示します。
[すべてを更新] リンクを選択して、ストレージアカウントの一覧を更新します。
Emulator & Attached ノードを展開する。
ストレージアカウント ノードを展開します。
リソースの名前がプレフィックスとして含まれたストレージアカウントが表示されます。

Azure Storage Explorer を使用して、ストレージアカウントとその内容を自由に探索できます。 Azure Storage Explorer の使用方法の詳細については、「Storage Explorerを始める」をご覧ください。

リソース Azure Table Storage を追加する

アプリホストプロジェクトで、AddAzureStorageによって返された IResourceBuilder<IAzureStorageResource> インスタンスで AddTables への呼び出しを連結して、Azure Table Storage 統合を登録します。次の例では、storage という名前の Azure Table 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...

上記のコード:

storageという名前の Azure Storage リソースを追加します。
tables という名前のテーブルストレージリソースをストレージリソースに追加します。
storage リソースを ExampleProject に追加し、準備が整うのを待ってからプロジェクトを開始します。

ホスティング統合の正常性チェック

Azure Storage ホスティング統合により、ストレージリソースの正常性チェックが自動的に追加されます。エミュレーターとして実行されている場合にのみ追加され、Azurite コンテナーが実行されていることと、そのコンテナーへの接続を確立できることを確認します。ホスティング統合は、📦 AspNetCore.HealthChecks およびAzure.Storage.Blobs NuGet パッケージに依存しています。

Client 統合

.NET Aspire Azure データテーブル client 統合を開始するには、📦AspireNuGet パッケージを、Azure.Data.Tables を使用する、つまり client Data Tables Azureを使用するアプリケーションの client-consuming プロジェクトにインストールします。 Azure データテーブル client 統合により、Azure Table Storageとの対話に使用できる TableServiceClient インスタンスが登録されます。

.NET CLI
PackageReference

dotnet add package Aspire.Azure.Data.Tables

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

Azure Table Storage client の追加

Program.cs-consuming プロジェクトの 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がサポートされます。 Aspire:Azure:Data:Tables キーを使用して、構成から AzureDataTablesSettings と TableClientOptions を読み込みます。次のスニペットは、いくつかのオプションを構成する 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);

AddAzureTableClient メソッドの 2 番目のパラメーター Action<IAzureClientBuilder<TableServiceClient, TableClientOptions>> configureClientBuilder デリゲートを使用して、TableClientOptions を設定することもできます。たとえば、clientを識別する TableServiceClient ID を設定するには、次のようにします。

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 Aspire Azure データテーブル統合では、次のログカテゴリが使用されます。

Azure.Core
Azure.Identity

トレーシング

.NET Aspire Azure データテーブル統合では、OpenTelemetryを使用して次のトレースアクティビティが出力されます。

Azure.Data.Tables.TableServiceClient

メトリック

.NET Aspire Azure データテーブルの統合では現在、Azure SDK の制限により、既定ではメトリックがサポートされていません。

次の方法で共有

.NET Aspire Azure データテーブルの統合

ホスティング統合

ストレージリソース Azure 追加する

生成されたプロビジョニングのBicep

プロビジョニングインフラストラクチャをカスタマイズする

既存の Azure ストレージアカウントに接続する

ストレージエミュレーターリソース Azure 追加する

Azurite コンテナーを構成する

Azurite コンテナーポートの構成

永続的な有効期間で Azurite コンテナーを構成する

データボリュームを使用して Azurite コンテナーを構成する

データバインドマウントを使用して Azurite コンテナーを構成する

ストレージリソースに接続する

リソース Azure Table Storage を追加する

ホスティング統合の正常性チェック

Client 統合

Azure Table Storage client の追加

設定

構成プロバイダーを使用する

インラインデリゲートを使用する

Client 統合ヘルスチェック

可観測性とテレメトリ

伐採

トレーシング

メトリック

関連項目

その他のリソース

次の方法で共有

.NET Aspire Azure データ テーブルの統合

ホスティング統合

ストレージ リソース Azure 追加する

生成されたプロビジョニングのBicep

プロビジョニング インフラストラクチャをカスタマイズする

既存の Azure ストレージ アカウントに接続する

ストレージ エミュレーター リソース Azure 追加する

Azurite コンテナーを構成する

Azurite コンテナー ポートの構成

永続的な有効期間で Azurite コンテナーを構成する

データ ボリュームを使用して Azurite コンテナーを構成する

データ バインド マウントを使用して Azurite コンテナーを構成する

ストレージ リソースに接続する

リソース Azure Table Storage を追加する

ホスティング統合の正常性チェック

Client 統合

Azure Table Storage client の追加

設定

構成プロバイダーを使用する

インライン デリゲートを使用する

Client 統合ヘルスチェック

可観測性とテレメトリ

伐採

トレーシング

メトリック

関連項目

その他のリソース

.NET Aspire Azure データテーブルの統合

ストレージリソース Azure 追加する

プロビジョニングインフラストラクチャをカスタマイズする

既存の Azure ストレージアカウントに接続する

ストレージエミュレーターリソース Azure 追加する

Azurite コンテナーポートの構成

データボリュームを使用して Azurite コンテナーを構成する

データバインドマウントを使用して Azurite コンテナーを構成する

ストレージリソースに接続する

インラインデリゲートを使用する