.NET Aspire Cosmos DB Entity Framework Core 統合

[アーティクル]
01/09/2025

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

ホスティング統合

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

AzureCosmosDBResource: 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 が公開されます。つまり、他の Cosmos DB リソースを追加する前に、AzureCosmosDBResource を追加する必要があります。

重要

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

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

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

切り替え AzureAzure Cosmos DB 上腕二頭筋。

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

param keyVaultName string

resource keyVault 'Microsoft.KeyVault/vaults@2023-07-01' existing = {
  name: keyVaultName
}

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'
  }
  kind: 'GlobalDocumentDB'
  tags: {
    'aspire-resource-name': 'cosmos'
  }
}

resource connectionString 'Microsoft.KeyVault/vaults/secrets@2023-07-01' = {
  name: 'connectionString'
  properties: {
    value: 'AccountEndpoint=${cosmos.properties.documentEndpoint};AccountKey=${cosmos.listKeys().primaryMasterKey}'
  }
  parent: keyVault
}

上記の Bicep は、次の既定値で AzureAzure Cosmos DB アカウントをプロビジョニングするモジュールです。

kind: アカウントの種類 Cosmos DB。既定値は GlobalDocumentDBです。
consistencyPolicy: Cosmos DB アカウントの整合性ポリシー。既定値は Sessionです。
locations: Cosmos DB アカウントの場所。既定値はリソースグループの場所です。

Cosmos DB アカウントに加えて、Azure Key Vault リソースもプロビジョニングされます。これは、Cosmos DB アカウントの接続文字列を安全に格納するために使用されます。生成された Bicep は開始点であり、特定の要件を満たすようにカスタマイズできます。

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

すべての .NET AspireAzure リソースは、AzureProvisioningResource 型のサブクラスです。この型では、ConfigureInfrastructure<T>(IResourceBuilder<T>, Action<AzureResourceInfrastructure>) API を使用して Azure リソースを構成する fluent 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に割り当てられます。
- ExampleKey のキーと Example valueの値を持つタグが Cosmos DB アカウントに追加されます。

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

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

接続する既存の AzureAzure Cosmos DB アカウントがある場合があります。新しい AzureAzure Cosmos DB リソースを表す代わりに、接続文字列をアプリホストに追加できます。既存の AzureAzure Cosmos DB アカウントに接続を追加するには、AddConnectionString メソッドを呼び出します。

var builder = DistributedApplication.CreateBuilder(args);

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

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

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

手記

接続文字列は、データベース接続、メッセージブローカー、エンドポイント URI、その他のサービスなど、さまざまな接続情報を表すために使用されます。 .NET .NET Aspire 命名法では、"接続文字列" という用語は、あらゆる種類の接続情報を表すために使用されます。

接続文字列は、アプリホストの構成 (通常は ConnectionStrings セクションのユーザーシークレット) で構成されます。アプリホストは、この接続文字列を環境変数としてすべての依存リソースに挿入します。次に例を示します。

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

依存リソースは、GetConnectionString メソッドを呼び出し、接続名をパラメーターとして渡すことによって、挿入された接続文字列にアクセスできます(この場合 "cosmos-db"。 GetConnectionString API は、IConfiguration.GetSection("ConnectionStrings")[name]の短縮形です。

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

Azure Azure Cosmos DB データベースリソースを追加するには、IResourceBuilder<AzureCosmosDBResource> の呼び出しを AddDatabase API にチェーンします。

var builder = DistributedApplication.CreateBuilder(args);

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

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

AddDatabaseを呼び出すと、dbという名前のデータベースを持つ Cosmos DB リソースが構成されます。データベースは、先ほど追加した AzureCosmosDBResource によって表される Cosmos DB アカウントに作成されます。データベースは、コレクションとユーザーの論理コンテナーです。詳細については、の「データベース、コンテナー、項目」を参照してください。

手記

AddDatabase API を使用してデータベースを AzureAzure Cosmos DB リソースに追加する場合、エミュレーターを実行している場合、データベースはエミュレーターで実際には作成されません。この API は、プロビジョニングインフラストラクチャによって生成された Bicep にデータベースを含めます。

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

Cosmos DB エミュレータコンテナを設定する

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

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

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

エンドポイント	コンテナーポート	ホストポート
`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...

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

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

永続性を持つCosmos DBエミュレーターコンテナーを構成する

永続的な有効期間で Cosmos DB エミュレーターコンテナーを構成するには、Cosmos DB エミュレーターコンテナーリソースで WithLifetime メソッドを呼び出し、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 エミュレーターリソースにデータボリュームを追加するには、AzureAzure Cosmos DB エミュレーターリソースで WithDataVolume メソッドを呼び出します。

var builder = DistributedApplication.CreateBuilder(args);

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

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

データボリュームは、コンテナーのライフサイクル外に Cosmos DB エミュレーターデータを保持するために使用されます。データボリュームは、Cosmos DB エミュレーターコンテナーの /tmp/cosmos/appdata パスにマウントされ、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...

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

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

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

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

Client 統合

.NET Aspire Microsoft Entity Framework CoreCosmos DB 統合を開始するには、📦Aspireをインストールします。Microsoft.EntityFrameworkCore.Cosmos NuGet パッケージは、clientを使用するプロジェクト、つまり、Microsoft Entity Framework CoreCosmos DBclientを使用するアプリケーションのプロジェクトです。

.NET CLI
パッケージリファレンス

dotnet add package Aspire.Microsoft.EntityFrameworkCore.Cosmos

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

コンテキスト Cosmos DB を追加する

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

builder.AddCosmosDbContext<MyDbContext>("cosmosdb");

アドバイス

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

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

public class ExampleService(MyDbContext context)
{
    // Use context...
}

でを使用する方法の詳細については、noSQL SDK for ののの例を参照してください。

構成

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

接続文字列を使用する

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

builder.AddCosmosDbContext<MyDbContext>("CosmosConnection");

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

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

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

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

.NET Aspire Microsoft Entity Framework CoreCosmos DB 統合では、Microsoft.Extensions.Configurationがサポートされています。 appsettings.jsonなどの構成ファイルから EntityFrameworkCoreCosmosSettings を読み込みます。一部のオプションを構成する _appsettings.json の例:

{
  "Aspire": {
    "Microsoft": {
      "EntityFrameworkCore": {
        "Cosmos": {
          "DisableTracing": true
        }
      }
    }
  }
}

完全な Cosmos DBclient 統合 JSON スキーマについては、Aspireを参照してください。Microsoft.EntityFrameworkCore.Cosmos/ConfigurationSchema。json.

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

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

builder.AddCosmosDbContext<MyDbContext>(
    "cosmosdb",
    settings => settings.DisableTracing = true);

Client 統合ヘルスチェック

既定では、.NET.NET Aspire 統合により、すべてのサービスの正常性チェックが有効になります。詳細については、.NET.NET Aspire 統合の概要を参照してください。

Microsoft の .NET AspireEntity Framework CoreCosmos DB 統合は現在、正常性チェックを実装していませんが、将来のリリースでは変更される可能性があります。

可観測性とテレメトリ

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

伐採

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

Azure-Cosmos-Operation-Request-Diagnostics
Microsoft.EntityFrameworkCore.ChangeTracking
Microsoft.EntityFrameworkCore.Database.Command
Microsoft.EntityFrameworkCore.Infrastructure
Microsoft.EntityFrameworkCore.Query

トレーシング

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

Azure.Cosmos.Operation
OpenTelemetry.Instrumentation.EntityFrameworkCore

メトリック

.NET Aspire Microsoft Entity Framework CoreCosmos DB 統合では、現在、次のメトリックがサポートされています。

Microsoft.EntityFrameworkCore
- ec_Microsoft_EntityFrameworkCore_active_db_contexts
- ec_Microsoft_EntityFrameworkCore_total_queries
- ec_Microsoft_EntityFrameworkCore_queries_per_second
- ec_Microsoft_EntityFrameworkCore_total_save_changes
- ec_Microsoft_EntityFrameworkCore_save_changes_per_second
- ec_Microsoft_EntityFrameworkCore_compiled_query_cache_hit_rate
- ec_Microsoft_Entity_total_execution_strategy_operation_failures
- ec_Microsoft_E_execution_strategy_operation_failures_per_second
- ec_Microsoft_EntityFramew_total_optimistic_concurrency_failures
- ec_Microsoft_EntityF_optimistic_concurrency_failures_per_second

次の方法で共有

.NET Aspire Cosmos DB Entity Framework Core 統合

ホスティング統合

リソース AzureAzure Cosmos DB 追加する

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

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

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

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

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

Cosmos DB エミュレータコンテナを設定する

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

永続性を持つCosmos DBエミュレーターコンテナーを構成する

Cosmos DBエミュレーターコンテナーをデータボリュームと共に構成する

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

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

Client 統合

コンテキスト Cosmos DB を追加する

構成

接続文字列を使用する

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

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

Client 統合ヘルスチェック

可観測性とテレメトリ

伐採

トレーシング

メトリック

関連情報をご覧ください

その他のリソース

次の方法で共有

.NET Aspire Cosmos DB Entity Framework Core 統合

ホスティング統合

リソース AzureAzure Cosmos DB 追加する

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

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

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

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

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

Cosmos DB エミュレータコンテナを設定する

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

永続性を持つCosmos DBエミュレーターコンテナーを構成する

Cosmos DBエミュレーターコンテナーをデータボリュームと共に構成する

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

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

Client 統合

コンテキスト Cosmos DB を追加する

構成

接続文字列を使用する

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

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

Client 統合ヘルスチェック

可観測性とテレメトリ

伐採

トレーシング

メトリック

関連情報をご覧ください

その他のリソース

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

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

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

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

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

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