.NET Aspire MongoDB データベース統合

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

MongoDB は、高パフォーマンス、高可用性、および簡単なスケーラビリティを提供する NoSQL データベースです。統合により、既存のインスタンス ( Atlasを含む) に接続したり、コンテナーイメージを使用してから新しいインスタンスを作成したりできます

ホスティング統合

MongoDB server ホスティング統合は、server を MongoDBServerResource 型として、データベースを MongoDBDatabaseResource 型としてモデル化します。これらの型と API にアクセスするには、アプリホストプロジェクトに 📦AspireのホスティングMongoDB NuGet パッケージを追加します。

.NET CLI
PackageReference

dotnet add package Aspire.Hosting.MongoDB

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

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

MongoDB server リソースおよびデータベースリソースを追加する

アプリホストプロジェクトで、AddMongoDB を呼び出して、MongoDBserver リソースビルダーを追加して返します。返されたリソースビルダーに対する呼び出しを連結して AddDatabaseを行い、MongoDB データベースリソースを追加します。

var builder = DistributedApplication.CreateBuilder(args);

var mongo = builder.AddMongoDB("mongo")
                   .WithLifetime(ContainerLifetime.Persistent);

var mongodb = mongo.AddDatabase("mongodb");

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

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

手記

MongoDB コンテナーの起動に時間がかかる可能性があるため、不要な再起動を避けるために、永続的な の有効期間を使用することをお勧めします。詳細については、「コンテナーリソースの有効期間」を参照してください。

.NET .NET Aspire 前の例で示したように、docker.io/library/mongo イメージでコンテナーイメージをアプリホストに追加すると、ローカルコンピューターに新しい MongoDB インスタンスが作成されます。データベースの追加には、MongoDBserver リソースビルダー (mongo 変数) への参照が使用されます。データベースには mongodb という名前が付けられ、ExampleProjectに追加されます。 MongoDB server リソースには、既定の資格情報が含まれています。

MONGO_INITDB_ROOT_USERNAME: adminの値です。
MONGO_INITDB_ROOT_PASSWORD: CreateDefaultPasswordParameter メソッドを使用して生成されたランダム password。

アプリホストを実行すると、パスワードはアプリホストのシークレットストアに格納されます。次のように、Parameters セクションに追加されます。

{
  "Parameters:mongo-password": "<THE_GENERATED_PASSWORD>"
}

パラメーターの名前は mongo-passwordですが、実際にはリソース名を -password サフィックスで書式設定するだけです。詳細については、の「開発におけるアプリシークレットの安全な保管」およびの「を使用したリソースの追加」を参照してください。

WithReference メソッドは、mongodb という名前の ExampleProject で接続を構成し、WaitFor は、mongodb リソースの準備ができるまで依存サービスを開始しないようにアプリホストに指示します。

アドバイス

既存の MongoDBserverに接続する場合は、代わりに AddConnectionString 呼び出します。詳細については、「既存のリソースを参照する」を参照してください。

MongoDB server リソースをデータボリュームで追加する

MongoDB server リソースにデータボリュームを追加するには、MongoDBserver リソースで WithDataVolume メソッドを呼び出します。

var builder = DistributedApplication.CreateBuilder(args);

var mongo = builder.AddMongoDB("mongo")
                   .WithDataVolume();

var mongodb = mongo.AddDatabase("mongodb");

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

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

データボリュームは、コンテナーのライフサイクル外に MongoDBserver データを保持するために使用されます。データボリュームは、MongoDBserver コンテナー内の /data/db パスにマウントされ、name パラメーターが指定されていない場合は、名前がランダムに生成されます。データボリュームの詳細と、マウントのバインド優先される理由の詳細については、「ドキュメント: ボリューム」を参照してください。

警告

パスワードはデータボリュームに格納されます。データボリュームを使用していて、パスワードが変更された場合は、ボリュームを削除するまで機能しません。

MongoDB server リソースをデータバインドマウントで追加する

MongoDB server リソースにデータバインドマウントを追加するには、WithDataBindMount メソッドを呼び出します。

var builder = DistributedApplication.CreateBuilder(args);

var mongo = builder.AddMongoDB("mongo")
                   .WithDataBindMount(@"C:\MongoDB\Data");

var mongodb = mongo.AddDatabase("mongodb");

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

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

大事な

データバインドマウント、パフォーマンス、移植性、およびセキュリティが向上し、運用環境に適したボリュームと比較して機能が制限されています。ただし、バインドマウントを使用すると、ホストシステム上のファイルに直接アクセスして変更できるため、リアルタイムの変更が必要な開発とテストに最適です。

データバインドマウントは、ホストマシンのファイルシステムに依存して、コンテナーの再起動間に MongoDBserver データを保持します。データバインドマウントは、MongoDBserver コンテナー内のホストコンピューター上の Windows 上の C:\MongoDB\Data (または Unixで /MongoDB/Data) パスにマウントされます。データバインドマウントの詳細については、「Docker ドキュメント: バインドマウント」を参照してください。

MongoDB server リソースを初期化データのバインドマウントで追加する

初期化フォルダーのデータバインドマウントを MongoDBserver リソースに追加するには、WithInitBindMount メソッドを呼び出します。

var builder = DistributedApplication.CreateBuilder(args);

var mongo = builder.AddMongoDB("mongo")
                   .WithInitBindMount(@"C:\MongoDB\Init");

var mongodb = mongo.AddDatabase("mongodb");

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

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

初期化データバインドマウントは、データを使用して MongoDBserver を初期化するために使用されます。初期化データバインドマウントは、MongoDBserver コンテナー内のホストコンピューター上の Windows 上の C:\MongoDB\Init (または Unix上の /MongoDB/Init) パスにマウントされ、MongoDBserver コンテナー内の /docker-entrypoint-initdb.d パスにマップされます。 MongoDB、このフォルダーにあるスクリプトを実行します。これは、データベースにデータを読み込む場合に便利です。

MongoDB server リソースをパラメーター付きで追加する

コンテナーイメージで使用されるパスワードを明示的に指定する場合は、これらの資格情報をパラメーターとして指定できます。次の代替例を考えてみましょう。

var builder = DistributedApplication.CreateBuilder(args);

var username = builder.AddParameter("username");
var password = builder.AddParameter("password", secret: true);

var mongo = builder.AddMongoDB("mongo", username, password);
var mongodb = mongo.AddDatabase("mongodb");

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

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

パラメーターの指定の詳細については、「外部パラメーターの」を参照してください。

MongoDB Express リソースを追加しなさい

MongoDB Express は、Web ベースの MongoDB 管理ユーザーインターフェイスです。 docker.io/library/mongo-express コンテナーイメージに対応する MongoDB Express リソースを追加するには、MongoDBserver リソースで WithMongoExpress メソッドを呼び出します。

var builder = DistributedApplication.CreateBuilder(args);

var mongo = builder.AddMongoDB("mongo")
                   .WithMongoExpress();

var mongodb = mongo.AddDatabase("mongodb");

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

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

ヒント

MongoExpressContainerResource のホストポートを構成するには、WithHostPort API への呼び出しをチェーンし、目的のポート番号を指定します。

上記のコードは、MongoDBserver リソースに接続するように構成された MongoDB Express リソースを追加します。既定の資格情報は次のとおりです。

ME_CONFIG_MONGODB_SERVER: 親 MongoDBServerResourceに割り当てられた名前。この場合、mongoになります。
ME_CONFIG_BASICAUTH: falseの値です。
ME_CONFIG_MONGODB_PORT: 親 MongoDBServerResourceのプライマリエンドポイントのターゲットポートから割り当てられます。
ME_CONFIG_MONGODB_ADMINUSERNAME: 親 MongoDBServerResourceで構成されたのと同じユーザー名。
ME_CONFIG_MONGODB_ADMINPASSWORD: 親 MongoDBServerResourceで構成されたパスワードと同じです。

さらに、WithMongoExpress API は、MongoDB Express コンテナーリソースの構成に使用する Action<IResourceBuilder<MongoExpressContainerResource>> 型の省略可能な configureContainer パラメーターを公開します。

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

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

ホスティング統合は、AspNetCore.HealthChecks 📦に依存し、NuGet パッケージであるMongoDbに関連しています。

Client 統合

.NET Aspire MongoDB client 統合を開始するには、📦Aspireをインストールします。MongoDB.ドライバー NuGet パッケージは、clientを使用するプロジェクト、つまり、MongoDBclientを使用するアプリケーションのプロジェクトです。 MongoDB client 統合により、MongoDBserver リソースとの対話に使用できる IMongoClient インスタンスが登録されます。アプリホストがデータベースリソース MongoDB 追加した場合、IMongoDatabase インスタンスも登録されます。

.NET CLI
PackageReference

dotnet add package Aspire.MongoDB.Driver

<PackageReference Include="Aspire.MongoDB.Driver"
                  Version="*" />

MongoDB client の追加

client-consuming プロジェクトの Program.cs ファイルで、AddMongoDBClient 拡張メソッドを任意の IHostApplicationBuilder に対して呼び出し、依存性注入コンテナーを介して使用するための IMongoClient を登録します。このメソッドは、接続名パラメーターを受け取ります。

builder.AddMongoDBClient(connectionName: "mongodb");

ヒント

connectionName パラメーターは、アプリホストプロジェクトに MongoDBserver リソース (または指定されている場合はデータベースリソース) を追加するときに使用される名前と一致する必要があります。つまり、AddDatabase を呼び出してmongodb の名前を指定した場合、その同じ名前をAddMongoDBClientを呼び出すときにも使用する必要があります。詳細については、「MongoDBserver リソースとデータベースリソースを追加する」を参照してください。

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

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

IMongoClient は、MongoDBserver リソースとの対話に使用されます。アプリホストプロジェクトにまだ認識されていないデータベースを作成するために使用できます。アプリホストで MongoDB データベースリソースを定義する場合は、代わりに依存関係挿入コンテナーが IMongoDatabase インスタンスを提供することを要求できます。依存関係の挿入の詳細については、.NET 依存関係の挿入を参照してください。

キー付き MongoDBclient を追加する

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

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

大事な

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

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

public class ExampleService(
    [FromKeyedServices("mainDb")] IMongoDatabase mainDatabase,
    [FromKeyedServices("loggingDb")] IMongoDatabase loggingDatabase)
{
    // Use databases...
}

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

構成

.NET Aspire MongoDB データベース統合には、プロジェクトの要件と規則を満たす複数の構成アプローチとオプションが用意されています。

接続文字列を使用する

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

builder.AddMongoDBClient("mongo");

接続文字列は、ConnectionStrings 構成セクションから取得されます。次の MongoDB 例 JSON 構成について考えてみましょう。

{
  "ConnectionStrings": {
    "mongo": "mongodb://server:port/test",
  }
}

または、次の MongoDB Atlas の構成例 JSON 考えてみます。

{
  "ConnectionStrings": {
    "mongo": "mongodb+srv://username:password@server.mongodb.net/",
  }
}

この接続文字列の書式を設定する方法の詳細については、「MongoDB: ConnectionString のドキュメント」を参照してください。

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

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

{
  "Aspire": {
    "MongoDB": {
      "Driver": {
        "ConnectionString": "mongodb://server:port/test",
        "DisableHealthChecks": false,
        "HealthCheckTimeout": 10000,
        "DisableTracing": false
      },
    }
  }

インライン構成を使用する

Action<MongoDBSettings> デリゲートを渡して、一部またはすべてのオプションをインラインで設定することもできます。

builder.AddMongoDBClient("mongodb",
    static settings => settings.ConnectionString = "mongodb://server:port/test");

構成オプション

対応する既定値を使用して構成可能なオプションを次に示します。

名前	説明
`ConnectionString`	接続する MongoDB データベースデータベースの接続文字列。
`DisableHealthChecks`	データベースの正常性チェックが無効かどうかを示すブール値。
`HealthCheckTimeout`	`int?` はミリ秒単位で MongoDB の正常性チェックのタイムアウトを示す値。
`DisableTracing`	OpenTelemetry トレースが無効かどうかを示すブール値。

健康診断

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

既定では、.NET AspireMongoDBclient 統合によって次のシナリオが処理されます。

有効にすると、一定時間内に MongoDB データベースへの接続とコマンドの実行を確認する正常性確認を追加します。
/health HTTP エンドポイントと統合します。このエンドポイントは、アプリがトラフィックを受け入れる準備ができていると見なされるために、登録されているすべての正常性チェックに合格する必要があります

可観測性とテレメトリ

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

伐採

.NET Aspire MongoDB データベース統合では、標準の .NET ログが使用され、次のカテゴリのログエントリが表示されます。

MongoDB[.*]: MongoDB 名前空間からのすべてのログエントリ。

トレーシング

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

MongoDB.Driver.Core.Extensions.DiagnosticSources

メトリック

.NET Aspire MongoDB データベース統合では、現在、OpenTelemetry メトリックは公開されていません。

次の方法で共有

.NET Aspire MongoDB データベース統合

ホスティング統合

MongoDB server リソースおよびデータベースリソースを追加する

MongoDB server リソースをデータボリュームで追加する

MongoDB server リソースをデータバインドマウントで追加する

MongoDB server リソースを初期化データのバインドマウントで追加する

MongoDB server リソースをパラメーター付きで追加する

MongoDB Express リソースを追加しなさい

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

Client 統合

MongoDB client の追加

キー付き MongoDBclient を追加する

構成

接続文字列を使用する

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

インライン構成を使用する

構成オプション

健康診断

可観測性とテレメトリ

伐採

トレーシング

メトリック

関連項目

その他のリソース

次の方法で共有

.NET Aspire MongoDB データベース統合

ホスティング統合

MongoDB server リソースおよびデータベースリソースを追加する

MongoDB server リソースをデータ ボリュームで追加する

MongoDB server リソースをデータバインドマウントで追加する

MongoDB server リソースを初期化データのバインドマウントで追加する

MongoDB server リソースをパラメーター付きで追加する

MongoDB Express リソースを追加しなさい

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

Client 統合

MongoDB client の追加

キー付き MongoDBclient を追加する

構成

接続文字列を使用する

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

インライン構成を使用する

構成オプション

健康診断

可観測性とテレメトリ

伐採

トレーシング

メトリック

関連項目

その他のリソース

MongoDB server リソースをデータボリュームで追加する