.NET Aspire Azure Cosmos DB 統合

2025-07-09

含まれているもの: ホスティング統合 —および— Client 統合

Azure Cosmos DB は、最新のアプリ開発のためのフルマネージドの NoSQL データベースサービスです。 .NET Aspire Azure Cosmos DB 統合を使用すると、既存の Cosmos DB インスタンスに接続したり、.NET エミュレーターを使用して Azure Cosmos DB から新しいインスタンスを作成したりできます。

Entity Framework Core統合をお探しの場合は、「.NET AspireCosmos DBEntity Framework Core統合」を参照してください。

ホスティング統合

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

AzureCosmosDBResource: AzureAzure Cosmos DB リソースを表します。
AzureCosmosDBContainerResource: AzureAzure Cosmos DB コンテナーリソースを表します。
AzureCosmosDBDatabaseResource: AzureAzure Cosmos DB データベースリソースを表します。
AzureCosmosDBEmulatorResource: AzureAzure Cosmos DB エミュレーターリソースを表します。

これらの型と API にアクセスして表現するには、📦Aspire.Hosting.Azure.CosmosDB NuGet パッケージをアプリホストプロジェクトに追加してください。

.NET コマンドラインインターフェース (CLI)
パッケージリファレンス

dotnet add package Aspire.Hosting.Azure.CosmosDB

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

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

リソース AzureAzure Cosmos DB 追加する

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

var builder = DistributedApplication.CreateBuilder(args);

var cosmos = builder.AddAzureCosmosDB("cosmos-db");

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

アプリホストに AzureCosmosDBResource を追加すると、データベースとコンテナーを追加するための他の便利な API が公開されます。つまり、他の AzureCosmosDBResource リソースを追加する前に、Cosmos DB を追加する必要があります。

大事な

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

プロビジョニングによって生成されたBicep

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

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

resource cosmos 'Microsoft.DocumentDB/databaseAccounts@2024-08-15' = {
  name: take('cosmos-${uniqueString(resourceGroup().id)}', 44)
  ___location: ___location
  properties: {
    locations: [
      {
        locationName: ___location
        failoverPriority: 0
      }
    ]
    consistencyPolicy: {
      defaultConsistencyLevel: 'Session'
    }
    databaseAccountOfferType: 'Standard'
    disableLocalAuth: true
  }
  kind: 'GlobalDocumentDB'
  tags: {
    'aspire-resource-name': 'cosmos'
  }
}

output connectionString string = cosmos.properties.documentEndpoint

output name string = cosmos.name

上記の Bicep は、 AzureAzure Cosmos DB アカウントリソースをプロビジョニングするモジュールです。さらに、ロールの割り当ては、別のモジュールで Azure リソースに対して作成されます。

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

param cosmos_outputs_name string

param principalId string

resource cosmos 'Microsoft.DocumentDB/databaseAccounts@2024-08-15' existing = {
  name: cosmos_outputs_name
}

resource cosmos_roleDefinition 'Microsoft.DocumentDB/databaseAccounts/sqlRoleDefinitions@2024-08-15' existing = {
  name: '00000000-0000-0000-0000-000000000002'
  parent: cosmos
}

resource cosmos_roleAssignment 'Microsoft.DocumentDB/databaseAccounts/sqlRoleAssignments@2024-08-15' = {
  name: guid(principalId, cosmos_roleDefinition.id, cosmos.id)
  properties: {
    principalId: principalId
    roleDefinitionId: cosmos_roleDefinition.id
    scope: cosmos.id
  }
  parent: cosmos
}

生成された Bicep は開始点であり、C# のプロビジョニングインフラストラクチャへの変更の影響を受ける。 Bicep ファイルのカスタマイズは直接上書きされるため、C# プロビジョニング API を通じて変更を加えて、生成されたファイルに反映されるようにします。

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

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

builder.AddAzureCosmosDB("cosmos-db")
    .ConfigureInfrastructure(infra =>
    {
        var cosmosDbAccount = infra.GetProvisionableResources()
                                   .OfType<CosmosDBAccount>()
                                   .Single();

        cosmosDbAccount.Kind = CosmosDBAccountKind.MongoDB;
        cosmosDbAccount.ConsistencyPolicy = new()
        {
            DefaultConsistencyLevel = DefaultConsistencyLevel.Strong,
        };
        cosmosDbAccount.Tags.Add("ExampleKey", "Example value");
    });

上記のコード:

ConfigureInfrastructure API への呼び出しを連結します。
- infra パラメーターは、AzureResourceInfrastructure 型のインスタンスです。
- プロビジョニング可能なリソースは、GetProvisionableResources() メソッドを呼び出すことによって取得されます。
- 1つの CosmosDBAccount が取得されました。
- CosmosDBAccount.ConsistencyPolicy は、DefaultConsistencyLevel.Strongに割り当てられます。
- Cosmos DB のキーと ExampleKeyの値を持つタグが Example value アカウントに追加されます。

Azure Azure Cosmos DB リソースをカスタマイズするには、さらに多くの構成オプションを使用できます。詳細については、Azure.Provisioning.CosmosDBを参照してください。詳細については、「プロビジョニングのカスタマイズ」を参照してください。

既存の AzureAzure Cosmos DB アカウントに接続する

接続する既存の AzureAzure Cosmos DB アカウントがある場合があります。呼び出しをチェーンして、AzureCosmosDBResource が既存のリソースであることを注釈付けることができます。

var builder = DistributedApplication.CreateBuilder(args);

var existingCosmosName = builder.AddParameter("existingCosmosName");
var existingCosmosResourceGroup = builder.AddParameter("existingCosmosResourceGroup");

var cosmos = builder.AddAzureCosmosDB("cosmos-db")
                    .AsExisting(existingCosmosName, existingCosmosResourceGroup);

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

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

大事な

RunAsExisting、PublishAsExisting、またはAsExistingメソッドを呼び出して、Azure サブスクリプションに既に存在するリソースを操作する場合は、特定の構成値をアプリホストに追加して、.NET Aspireが見つけられるようにする必要があります。必要な構成値には、 SubscriptionId、 AllowResourceGroupCreation、 ResourceGroup、 Location が含まれます。設定しない場合は、 .NET.NET Aspire ダッシュボードに "構成がありません" エラーが表示されます。設定方法の詳細については、「構成」を参照してください。

Azure Azure Cosmos DB リソースを既存のリソースとして扱う方法の詳細については、「既存の Azure リソースを使用する」を参照してください。

手記

または、AzureAzure Cosmos DB リソースを表す代わりに、接続文字列をアプリホストに追加することもできます。このアプローチは弱く型指定されており、ロールの割り当てやインフラストラクチャのカスタマイズでは機能しません。詳細については、「Azureを使用して既存のリソースを追加する」を参照してください。

データベースリソースとコンテナーリソース AzureAzure Cosmos DB 追加する

.NET Aspire は、 Azure Cosmos DB リソース間の親子関係をモデル化します。たとえば、 AzureAzure Cosmos DB アカウント (AzureCosmosDBResource) は複数のデータベース (AzureCosmosDBDatabaseResource) を持つ場合があり、各データベースには複数のコンテナー (AzureCosmosDBContainerResource) を含めることができます。データベースまたはコンテナーリソースを追加する場合は、親リソースに対して追加します。

Azure Azure Cosmos DB データベースリソースを追加するには、AddCosmosDatabase インスタンスで IResourceBuilder<AzureCosmosDBResource> メソッドを呼び出します。

var builder = DistributedApplication.CreateBuilder(args);

var cosmos = builder.AddAzureCosmosDB("cosmos-db");
var db = cosmos.AddCosmosDatabase("db");

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

AddCosmosDatabaseを呼び出すと、db という名前のデータベースが Cosmos DB リソースに追加され、新しく作成されたデータベースリソースが返されます。データベースは、先ほど追加した Cosmos DB によって表される AzureCosmosDBResource アカウントに作成されます。データベースは、コレクションとユーザーの論理コンテナーです。

Azure Azure Cosmos DB コンテナーは、データが格納される場所です。コンテナーを作成するときに、パーティションキーを指定する必要があります。

Azure Azure Cosmos DB コンテナーリソースを追加するには、AddContainer インスタンスで IResourceBuilder<AzureCosmosDBDatabaseResource> メソッドを呼び出します。

var builder = DistributedApplication.CreateBuilder(args);

var cosmos = builder.AddAzureCosmosDB("cosmos-db");
var db = cosmos.AddCosmosDatabase("db");
var container = db.AddContainer("entries", "/id");

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

コンテナーは、先ほど追加した AzureCosmosDBDatabaseResource によって表されるデータベースに作成されます。詳細については、の「データベース、コンテナー、項目」を参照してください。

親の子リソースリレーションシップの例

Azure Cosmos DB リソース間の親子関係をより深く理解するには、次の例を検討してください。この例では、データベースとコンテナーと共にAzure Cosmos DB リソースを追加する方法を示します。

var builder = DistributedApplication.CreateBuilder(args);

var cosmos = builder.AddAzureCosmosDB("cosmos");

var customers = cosmos.AddCosmosDatabase("customers");
var profiles = customers.AddContainer("profiles", "/id");

var orders = cosmos.AddCosmosDatabase("orders");
var details = orders.AddContainer("details", "/id");
var history = orders.AddContainer("history", "/id");

builder.AddProject<Projects.Api>("api")
       .WithReference(profiles)
       .WithReference(details)
       .WithReference(history);

builder.Build().Run();

上記のコードは、AzureとAzure Cosmos DBの 2 つのデータベースを持つ cosmos という名前のcustomersorders リソースを追加します。 customers データベースには profiles という名前のコンテナーが 1 つありますが、orders データベースには details と history の 2 つのコンテナーがあります。各コンテナーのパーティションキーは /id。

次の図は、 AzureAzure Cosmos DB リソース間の親子関係を示しています。

アプリホストコードが親子関係を表す場合、クライアントは名前によってこれらのリソースにディープリンクできます。たとえば、customers データベースは、クライアントプロジェクト内の名前で参照でき、Database データベースに接続するcustomers インスタンスを登録します。名前付きコンテナーにも同じことが当てはまります。たとえば、details コンテナーはクライアントプロジェクト内の名前で参照でき、Container コンテナーに接続するdetails インスタンスを登録します。

エミュレーターリソース AzureAzure Cosmos DB 追加する

Azure Azure Cosmos DB エミュレーターリソースを追加するには、IResourceBuilder<AzureCosmosDBResource> の呼び出しを RunAsEmulator API にチェーンします。

var builder = DistributedApplication.CreateBuilder(args);

var cosmos = builder.AddAzureCosmosDB("cosmos-db")
                    .RunAsEmulator();

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

RunAsEmulatorを呼び出すと、エミュレーターを使用してローカルで実行するように Cosmos DB リソースが構成されます。この場合のエミュレーターは、AzureAzure Cosmos DB エミュレーターです。 Azure Cosmos DB Emulator は、Azure Cosmos DB アプリをテストするための無料のローカル環境を提供し、.NET AspireAzure ホスティング統合に最適です。エミュレーターはインストールされていません。代わりに、コンテナーとして .NET.NET Aspire にアクセスできます。前の例に示すように、mcr.microsoft.com/cosmosdb/emulator イメージでコンテナーをアプリホストに追加すると、アプリホストが起動したときにコンテナーが作成されて起動されます。詳細については、「コンテナーリソースのライフサイクル」を参照してください。

Cosmos DB エミュレーターコンテナーを構成する

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

エミュレーターコンテナーゲートウェイポート Cosmos DB 構成する

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

エンドポイント	コンテナーポート	ホストポート
`https`	8081	動的

リッスンしているポートは、既定では動的です。コンテナーが起動すると、ポートはホストコンピューター上のランダムなポートにマップされます。エンドポイントポートを構成するには、次の例に示すように、RunAsEmulator メソッドによって提供されるコンテナーリソースビルダーの呼び出しをチェーンします。

var builder = DistributedApplication.CreateBuilder(args);

var cosmos = builder.AddAzureCosmosDB("cosmos-db").RunAsEmulator(
                     emulator =>
                     {
                         emulator.WithGatewayPort(7777);
                     });

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

上記のコードは、ポート Cosmos DBでリッスンするように、https エミュレーターコンテナーの既存の 8081 エンドポイントを構成します。 Cosmos DB エミュレーターコンテナーのポートは、次の表に示すようにホストポートにマップされます。

エンドポイント名	ポートマッピング (`container:host`)
`https`	`8081:7777`

永続的なライフタイムを持つエミュレーター Cosmos DB コンテナを構成する

永続的な有効期間で Cosmos DB エミュレーターコンテナーを構成するには、WithLifetime エミュレーターコンテナーリソースで Cosmos DB メソッドを呼び出し、ContainerLifetime.Persistent渡します。

var builder = DistributedApplication.CreateBuilder(args);

var cosmos = builder.AddAzureCosmosDB("cosmos-db").RunAsEmulator(
                     emulator =>
                     {
                         emulator.WithLifetime(ContainerLifetime.Persistent);
                     });

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

詳細については、「コンテナーリソースの有効期間」を参照してください。

データボリュームを使用してCosmos DBエミュレーターコンテナーを構成する

Azure Azure Cosmos DB エミュレーターリソースにデータボリュームを追加するには、WithDataVolumeAzure エミュレーターリソースで Azure Cosmos DB メソッドを呼び出します。

var builder = DistributedApplication.CreateBuilder(args);

var cosmos = builder.AddAzureCosmosDB("cosmos-db").RunAsEmulator(
                     emulator =>
                     {
                         emulator.WithDataVolume();
                     });

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

データボリュームは、コンテナーのライフサイクル外に Cosmos DB エミュレーターデータを保持するために使用されます。データボリュームは、/tmp/cosmos/appdata エミュレーターコンテナーの Cosmos DB パスにマウントされ、name パラメーターが指定されていない場合は、名前が生成されます。エミュレーターには、AZURE_COSMOS_EMULATOR_ENABLE_DATA_PERSISTENCE 環境変数が trueに設定されています。データボリュームの詳細と、バインドマウントよりも優先される理由の詳細については、「 Docker ドキュメント: ボリューム」を参照してください。

Cosmos DB エミュレーターコンテナーのパーティション数を構成する

Cosmos DB エミュレーターコンテナーのパーティション数を構成するには、WithPartitionCount メソッドを呼び出します。

var builder = DistributedApplication.CreateBuilder(args);

var cosmos = builder.AddAzureCosmosDB("cosmos-db").RunAsEmulator(
                     emulator =>
                     {
                         emulator.WithPartitionCount(100); // Defaults to 25
                     });

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

上記のコードでは、Cosmos DBのパーティション数を持つ 100 エミュレーターコンテナーを構成します。これは、AZURE_COSMOS_EMULATOR_PARTITION_COUNT 環境変数を設定するための短縮形です。

Linuxベースのエミュレーターを使用する (プレビュー)

Azure Azure Cosmos DB エミュレーターの次世代は完全にLinuxベースであり、Docker コンテナーとして使用できます。さまざまなプロセッサとオペレーティングシステムでの実行をサポートしています。

Cosmos DB エミュレーターのプレビューバージョンを使用するには、RunAsPreviewEmulator メソッドを呼び出します。この機能はプレビュー段階であるため、ASPIRECOSMOSDB001 試験的な診断を抑制して、プレビュー機能を明示的にオプトインする必要があります。

プレビューエミュレーターでは、Web UI を使用して Cosmos DB エミュレーターに格納されているデータを表示できる "データエクスプローラー" エンドポイントの公開もサポートしています。データエクスプローラーを有効にするには、WithDataExplorer メソッドを呼び出します。

#pragma warning disable ASPIRECOSMOSDB001

var builder = DistributedApplication.CreateBuilder(args);

var cosmos = builder.AddAzureCosmosDB("cosmos-db").RunAsPreviewEmulator(
                     emulator =>
                     {
                         emulator.WithDataExplorer();
                     });

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

上記のコードでは、実行時に使用する Linuxベースのプレビュー Cosmos DB エミュレーターコンテナーと Data Explorer エンドポイントを構成します。

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

Azure Cosmos DB ホスティング統合により、Cosmos DB リソースの正常性チェックが自動的に追加されます。正常性チェックでは、Cosmos DB が実行されていることと、その Cosmos DB への接続を確立できることを確認します。

ホスティング統合は、📦 AspNetCore.HealthChecks.CosmosDb NuGet パッケージに依存します。

Client 統合

.NET Aspire Azure Cosmos DB クライアント統合を開始するには、クライアントを使用するプロジェクト、つまり、📦 クライアントを使用するアプリケーションのプロジェクトに、Aspire NuGet パッケージをインストールします。 Cosmos DB クライアント統合では、CosmosClientとの対話に使用できる Cosmos DB インスタンスが登録されます。

.NET コマンドラインインターフェース (CLI)
パッケージリファレンス

dotnet add package Aspire.Microsoft.Azure.Cosmos

<PackageReference Include="Aspire.Microsoft.Azure.Cosmos"
                  Version="*" />

クライアント Cosmos DB 追加する

クライアントを使用するプロジェクトの Program.cs ファイルで、任意の AddAzureCosmosClient で IHostApplicationBuilder 拡張メソッドを呼び出して、依存関係挿入コンテナーを介して使用する CosmosClient を登録します。このメソッドは、接続名パラメーターを受け取ります。

builder.AddAzureCosmosClient(connectionName: "cosmos-db");

ヒント

connectionName パラメーターは、アプリホストプロジェクトに Cosmos DB リソースを追加するときに使用する名前と一致する必要があります。つまり、言い換えると、AddAzureCosmosDB を呼び出して cosmos-db という名前を指定した場合、その同じ名前を AddAzureCosmosClientを呼び出す際に使用する必要があるということです。詳細については、「リソース AzureAzure Cosmos DB 追加」を参照してください。

その後、依存関係の挿入を使用して CosmosClient インスタンスを取得できます。たとえば、サービスの例からクライアントを取得するには、次のようにします。

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

依存関係の挿入の詳細については、依存関係の挿入.NET参照してください。

キー付き Cosmos DB クライアントを追加する

接続名が異なる複数の CosmosClient インスタンスを登録する場合があります。キー付き Cosmos DB クライアントを登録するには、AddKeyedAzureCosmosClient メソッドを呼び出します。

builder.AddKeyedAzureCosmosClient(name: "mainDb");
builder.AddKeyedAzureCosmosClient(name: "loggingDb");

大事な

キー付きサービスを使用する場合、Cosmos DB リソースで、mainDb 用と loggingDb用の 2 つの名前付きデータベースが構成されている必要があります。

その後、依存関係の挿入を使用して CosmosClient インスタンスを取得できます。たとえば、サービスの例から接続を取得するには、次のようにします。

public class ExampleService(
    [FromKeyedServices("mainDb")] CosmosClient mainDbClient,
    [FromKeyedServices("loggingDb")] CosmosClient loggingDbClient)
{
    // Use clients...
}

キー付きサービスの詳細については、「 .NET 依存関係の挿入: キー付きサービス」を参照してください。

データベース AzureAzure Cosmos DB 追加する

アプリホストでは、データベースリソース (AzureCosmosDBDatabaseResource) を子リソースとして親 AzureCosmosDBResourceに追加できます。クライアントを使用するプロジェクトでは、名前によってデータベースリソースにディープリンクし、依存関係の挿入で使用する Database インスタンスを登録できます。たとえば、AddAzureCosmosDatabase インスタンスでIHostApplicationBuilderを呼び出す次のコードを考えてみます。

builder.AddAzureCosmosDatabase(connectionName: "customers");

AddAzureCosmosDatabase API は、同じデータベース接続で複数のコンテナーをアタッチするために使用できるCosmosDatabaseBuilder インスタンスを返します。すべての子コンテナーは、同じ CosmosClient とデータベース接続と CosmosClient インスタンスを共有します。この方法は、同じ CosmosClientOptions を複数のコンテナーに関連付けると便利です。

AddAzureCosmosDatabaseを呼び出した後、依存関係の挿入を使用してDatabase インスタンスを取得できます。たとえば、 MapGet 呼び出しでデリゲートからデータベースを取得するには、次のコードを検討します。

app.MapGet("/api/customers", async (Database database) =>
{
    // Query data from database...
});

キー付き AzureAzure Cosmos DB データベースを追加する

同じデータベース接続で複数のコンテナーをアタッチするために使用できるAddKeyedAzureCosmosDatabase インスタンスを返すCosmosDatabaseBuilder API もあります。異なる接続名を持つ複数のデータベースを登録できるメソッド。たとえば、AddKeyedAzureCosmosDatabase インスタンスでIHostApplicationBuilderを呼び出す次のコードを考えてみます。

var builder = WebApplication.CreateBuilder(args);

builder.AddKeyedAzureCosmosDatabase("customers");
builder.AddKeyedAzureCosmosDatabase("orders");

var app = builder.Build();

app.MapGet("/api/customers", async (
    [FromKeyedServices("customers")] Database database) =>
{
    // Get container from database and query data
});

app.MapPost("/api/orders", async (
    [FromKeyedServices("orders")] Database database,
    [FromBody] OrderRequest order) =>
{
    // Get container from database and query data
});

app.Run();

前のコード例は、 details と customersの 2 つのデータベースを登録する方法を示しています。各名前付きデータベースを使用して、対応するコンテナーを取得してデータを照会できます。

コンテナー AzureAzure Cosmos DB 追加する

アプリホストプロジェクトに Cosmos DB リソースを追加するときに、 Azure Cosmos DB コンテナーリソースを追加することもできます。コンテナーリソースは、親 AzureCosmosDBDatabaseResourceの子リソースと見なされます。クライアントを使用するプロジェクトでは、名前によってコンテナーリソースにディープリンクし、依存関係の挿入で使用する Container インスタンスを登録できます。たとえば、AddAzureCosmosContainer インスタンスでIHostApplicationBuilderを呼び出す次のコードを考えてみます。

builder.AddAzureCosmosContainer(connectionName: "details");

その後、依存関係の挿入を使用して Container インスタンスを取得できます。たとえば、 MapGet 呼び出しでデリゲートからコンテナーを取得するには、次のコードを検討します。

app.MapGet("/api/orders/{id:guid}", async (
    Container container, 
    [FromRoute] Guid id) =>
{
    // Query data from container...
});

キー付き AzureAzure Cosmos DB コンテナーを追加する

複数のコンテナーを異なる接続名で登録できる AddKeyedAzureCosmosContainer メソッドもあります。たとえば、AddKeyedAzureCosmosContainer インスタンスでIHostApplicationBuilderを呼び出す次のコードを考えてみます。

var builder = WebApplication.CreateBuilder(args);

builder.AddKeyedAzureCosmosContainer("customers");

var app = builder.Build();

app.MapGet("/api/customers", async (
    [FromKeyedServices("customers")] Container container) =>
{
    // Query data from container...
});

app.Run();

同じデータベース接続の下に複数のコンテナーがある場合は、 AddAzureCosmosDatabase API を使用して、同じデータベース接続の下に複数のコンテナーをアタッチできます。すべての子コンテナーは、同じ CosmosClient とデータベース接続を共有します。この方法は、同じ CosmosClientOptions を複数のコンテナーに関連付けると便利です。同じデータベース接続で複数のコンテナーを登録するには、次の代替コードを検討してください。

var builder = WebApplication.CreateBuilder(args);

builder.AddAzureCosmosDatabase("customers", configureClientOptions: options =>
    {
        options.SerializerOptions = new CosmosSerializationOptions()
        {
            PropertyNamingPolicy = CosmosPropertyNamingPolicy.CamelCase
        };
    })
    .AddKeyedContainer(name: "profiles");

builder.AddAzureCosmosDatabase(connectionName: "orders")
       .AddKeyedContainer(name: "details")
       .AddKeyedContainer(name: "history");

var app = builder.Build();

app.MapGet("/api/customers", async (
    [FromKeyedServices("profiles")] Container container) =>
{
    // Query data from container
});

app.MapGet("/api/orders", async (
    [FromKeyedServices("details")] Container container,
    [FromKeyedServices("history")] Container container) =>
{
    // Query data from container
});

app.Run();

前のコード例では、2 つのデータベース ( customers と orders) をそれぞれ独自のコンテナーに登録する方法を示します。 customers データベースには profiles という名前のコンテナーが 1 つありますが、orders データベースには details と history という名前の 2 つのコンテナーがあります。各コンテナーは、それぞれのキーを使用して個別にクエリを実行できます。

設定

.NET Aspire Azure Cosmos DB 統合には、プロジェクトの要件と規則に基づいて接続を構成するための複数のオプションが用意されています。

接続文字列を使用する

ConnectionStrings 構成セクションの接続文字列を使用する場合は、AddAzureCosmosClient メソッドを呼び出すときに接続文字列の名前を指定できます。

builder.AddAzureCosmosClient("cosmos-db");

その後、接続文字列は ConnectionStrings 構成セクションから取得されます。

{
  "ConnectionStrings": {
    "cosmos-db": "AccountEndpoint=https://{account_name}.documents.azure.com:443/;AccountKey={account_key};"
  }
}

詳細については、 ConnectionString のドキュメントを参照してください。

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

.NET Aspire Azure Cosmos DB 統合では、Microsoft.Extensions.Configurationがサポートされます。 MicrosoftAzureCosmosSettings キーを使用して、構成から Aspire:Microsoft:Azure:Cosmos を読み込みます。次のスニペットは、いくつかのオプションを構成する appsettings.json ファイルの例です。

{
  "Aspire": {
    "Microsoft": {
      "Azure": {
        "Cosmos": {
          "DisableTracing": false,
        }
      }
    }
  }
}

完全なCosmos DBクライアント統合JSONスキーマについては、Aspire.Microsoft.Azure.Cosmos/ConfigurationSchema.jsonを参照してください。

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

また、Action<MicrosoftAzureCosmosSettings> configureSettings デリゲートを渡して、コードからのトレースを無効にするなど、一部またはすべてのオプションをインラインで設定することもできます。

builder.AddAzureCosmosClient(
    "cosmos-db",
    static settings => settings.DisableTracing = true);

Microsoft.Azure.Cosmos.CosmosClientOptions メソッドの省略可能な Action<CosmosClientOptions> configureClientOptions パラメーターを使用して、AddAzureCosmosClient を設定することもできます。たとえば、このクライアントによって発生するすべての要求の問題に対して、CosmosClientOptions.ApplicationName ユーザーエージェントヘッダーサフィックスを設定するには、次のようにします。

builder.AddAzureCosmosClient(
    "cosmosConnectionName",
    configureClientOptions:
        clientOptions => clientOptions.ApplicationName = "myapp");

Client 統合ヘルスチェック

現在、.NET AspireCosmos DB クライアント統合では正常性チェックは実装されていませんが、これは将来のリリースで変更される可能性があります。

可観測性とテレメトリ

統合により、ログ記録、トレース、メトリックの構成が自動的に設定されます。これは、監視の柱とも呼ばれます。統合の可観測性とテレメトリの詳細については、統合の概要参照してください。バッキングサービスによっては、一部の統合でこれらの機能の一部のみがサポートされる場合があります。たとえば、一部の統合ではログ記録とトレースがサポートされますが、メトリックはサポートされません。テレメトリ機能は、「構成」セクションに示されている手法を使用して無効にすることもできます。

伐採

.NET Aspire Azure Cosmos DB 統合では、次のログカテゴリが使用されます。

Azure-Cosmos-Operation-Request-Diagnostics

失敗した要求の Azure Cosmos DB 要求診断を取得するだけでなく、待機時間のしきい値を構成して、成功した Azure Cosmos DB 要求診断をログに記録するかを決定できます。既定値は、ポイント操作の場合は 100 ミリ秒、非ポイント操作の場合は 500 ミリ秒です。

builder.AddAzureCosmosClient(
    "cosmosConnectionName",
    configureClientOptions:
        clientOptions => {
            clientOptions.CosmosClientTelemetryOptions = new()
            {
                CosmosThresholdOptions = new()
                {
                    PointOperationLatencyThreshold = TimeSpan.FromMilliseconds(50),
                    NonPointOperationLatencyThreshold = TimeSpan.FromMilliseconds(300)
                }
            };
        });

トレース

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

Azure.Cosmos.Operation

Azure Azure Cosmos DB トレースは現在プレビュー段階であるため、トレースが確実に出力されるように試験段階のスイッチを設定する必要があります。

AppContext.SetSwitch("Azure.Experimental.EnableActivitySource", true);

詳細については、「 AzureAzure Cosmos DB SDK の可観測性: トレース属性」を参照してください。

メトリック

.NET Aspire Azure Cosmos DB 統合は現在、Azure SDK の制限により、既定ではメトリックをサポートしていません。