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

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

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

ホスティング統合

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

.NET CLI
PackageReference

dotnet add package Aspire.Hosting.MongoDB

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

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

MongoDB サーバーリソースとデータベースリソースを追加する

アプリホストプロジェクトで、AddMongoDB を呼び出して、MongoDB サーバーリソースビルダーを追加して返します。返されたリソースビルダーに対する呼び出しを連結して 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 インスタンスが作成されます。データベースの追加には、MongoDB サーバーリソースビルダー (mongo 変数) への参照が使用されます。データベースには mongodb という名前が付けられ、ExampleProjectに追加されます。 MongoDB サーバーリソースには、既定の資格情報が含まれています。

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

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

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

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

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

アドバイス

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

データボリュームを持つ MongoDB サーバーリソースを追加する

MongoDB サーバーリソースにデータボリュームを追加するには、MongoDB サーバーリソースで 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...

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

警告

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

データバインドマウントを使用してMongoDBサーバーリソースを追加する

MongoDB サーバーリソースにデータバインドマウントを追加するには、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...

大事な

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

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

初期化データのバインドマウントを使用してMongoDBのサーバーリソースを追加する

初期化フォルダーのデータバインドマウントを MongoDB サーバーリソースに追加するには、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...

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

パラメーター付きのMongoDBサーバーリソースを追加する

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

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 リソースを追加するには、MongoDB サーバーリソースで 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 への呼び出しをチェーンし、目的のポート番号を指定します。

上記のコードは、MongoDB サーバーリソースに接続するように構成された 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 は、configureContainer Express コンテナーリソースの構成に使用する Action<IResourceBuilder<MongoExpressContainerResource>> 型の省略可能な MongoDB パラメーターを公開します。

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

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

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

Client 統合

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

.NET CLI
PackageReference

dotnet add package Aspire.MongoDB.Driver

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

クライアント MongoDB 追加する

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

builder.AddMongoDBClient(connectionName: "mongodb");

アドバイス

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

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

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

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

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

接続名が異なる複数の 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がサポートされます。 MongoDBSettings キーを使用して、構成から Aspire:MongoDB:Driver を読み込みます。次のスニペットは、いくつかのオプションを構成する 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 AspireMongoDB クライアント統合は次のシナリオを処理します。

有効にすると、一定時間内に 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 サーバーリソースとデータベースリソースを追加する

データボリュームを持つ MongoDB サーバーリソースを追加する

データバインドマウントを使用してMongoDBサーバーリソースを追加する

初期化データのバインドマウントを使用してMongoDBのサーバーリソースを追加する

パラメーター付きのMongoDBサーバーリソースを追加する

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

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

Client 統合

クライアント MongoDB 追加する

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

構成

接続文字列を使用する

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

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

構成オプション

健康診断

可観測性とテレメトリ

伐採

トレーシング

メトリック

関連項目

その他のリソース

次の方法で共有

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

ホスティング統合

MongoDB サーバー リソースとデータベース リソースを追加する

データボリュームを持つ MongoDB サーバーリソースを追加する

データバインドマウントを使用してMongoDBサーバーリソースを追加する

初期化データのバインドマウントを使用してMongoDBのサーバーリソースを追加する

パラメーター付きのMongoDBサーバーリソースを追加する

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

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

Client 統合

クライアント MongoDB 追加する

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

構成

接続文字列を使用する

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

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

構成オプション

健康診断

可観測性とテレメトリ

伐採

トレーシング

メトリック

関連項目

その他のリソース

MongoDB サーバーリソースとデータベースリソースを追加する