クイックスタート: .NET 用 MongoDB ドライバーで Azure Cosmos DB for MongoDB 仮想コアを使用する

2025-06-11
適用対象: ✅ MongoDB (vCore)

このクイックスタートでは、.NET を使用して基本的な Azure Cosmos DB for MongoDB 仮想コアアプリケーションをデプロイします。 Azure Cosmos DB for MongoDB 仮想コアはスキーマレスデータストアであり、アプリケーションは MongoDB ライブラリを使用して非構造化ドキュメントをクラウドに格納できます。 .NET を使用して、Azure Cosmos DB リソース内でドキュメントを作成し、基本的なタスクを実行する方法について説明します。

ライブラリのソースコード | パッケージ (NuGet) | Azure Developer CLI

前提条件

Azure 開発者コマンドラインインターフェース
Docker Desktop

Azure サブスクリプション
- Azure サブスクリプションをお持ちでない場合は、開始する前に無料アカウントを作成してください。

.NET SDK 9.0

プロジェクトを初期化する

Azure Developer CLI (azd) を使用して、Azure Cosmos DB for MongoDB 仮想コアクラスターを作成し、コンテナー化されたサンプルアプリケーションをデプロイします。サンプルアプリケーションでは、クライアントライブラリを使って、サンプルデータの管理、作成、読み取り、クエリを実行します。

空のディレクトリでターミナルを開きます。
まだ認証されていない場合は、azd auth loginを使用して Azure Developer CLI に対して認証します。ツールによって指示された手順に従って、任意の Azure 資格情報を使って CLI に対して認証します。
```
azd auth login
```
azd init を使用してプロジェクトを初期化します。
```
azd init --template cosmos-db-mongodb-vcore-dotnet-quickstart
```
初期化中に、一意の環境名を構成します。
azd upを使用してクラスターをデプロイします。 Bicep テンプレートは、サンプル Web アプリケーションもデプロイします。
```
azd up
```
このプロビジョニングプロセス中に、サブスクリプション、目的の場所、ターゲットリソースグループを選択します。プロビジョニングプロセスが完了するまで待ちます。このプロセスには 5 分ほどかかる可能性があります。

Azure リソースのプロビジョニングが完了すると、実行中の Web アプリケーションへの URL が出力に含まれます。

Deploying services (azd deploy)

  (✓) Done: Deploying service web
- Endpoint: <https://[container-app-sub-___domain].azurecontainerapps.io>

SUCCESS: Your application was provisioned and deployed to Azure in 5 minutes 0 seconds.

コンソールで URL を使って、ブラウザーで Web アプリケーションに移動します。実行中のアプリの出力を確認します。

実行中のサンプルダッシュボード Web アプリケーションのスクリーンショット。

クライアントライブラリをインストールする

クライアントライブラリは、NuGet を介して MongoDB.Driver パッケージとして入手できます。 Microsoft Entra 認証の場合は、Azure SDK for .NET の Azure.Identity パッケージを使用します。

ターミナルを開き、/src/web フォルダーに移動します。
```
cd ./src/web
```
MongoDB.Driver パッケージがまだインストールされていない場合は、dotnet add package を使ってインストールします。
```
dotnet add package MongoDB.Driver
```
まだインストールされていない場合は、 Azure.Identity パッケージをインストールします。
```
dotnet add package Azure.Identity
```
src/api/Microsoft.Learn.AzureCosmosDBMongoDBQuickstart.Api.csproj ファイルを開いて確認し、両方のパッケージエントリが存在することを検証します。

ライブラリをインポートする

次の名前空間をアプリケーションコードにインポートします。

	パッケージ	情報源
`Azure.Core`	`Azure.Identity`	Azure SDK for .NET
`Azure.Identity`	`Azure.Identity`	Azure SDK for .NET
`MongoDB.Driver`	`MongoDB.Driver`	.NET 用の公式 MongoDB ドライバー
`MongoDB.Driver.Authentication.Oidc`	`MongoDB.Driver`	.NET 用の公式 MongoDB ドライバー

using Azure.Core;
using Azure.Identity;

using MongoDB.Driver;
using MongoDB.Driver.Authentication.Oidc;

オブジェクトモデル

名前	説明
`MongoClient`	MongoDB への接続に使用される型。
`Database`	クラスター上のデータベースを表します。
`Collection`	クラスター上のデータベース内のコレクションを表します。

テンプレートのサンプルコードは、cosmicworks という名前のデータベースと products という名前のコンテナーを使います。 products コレクションには、名前、カテゴリ、一意の識別子、数量などの詳細が各製品ごとに含まれています。コレクションは、/category プロパティをシャードキーとして使用します。

クライアントを認証する

Azure Cosmos DB for MongoDB 仮想コアの Microsoft Entra 認証では既知の TokenCredential 型を使用できますが、カスタムトークンハンドラーを実装する必要があります。このサンプル実装を使用して、多くの ID の種類の標準的な Microsoft Entra 認証をサポートする MongoClient を作成できます。

まず、インターフェイスを実装する別のファイルに新しいクラス IOidcCallback 作成します。

using Azure.Core;
using MongoDB.Driver.Authentication.Oidc;

internal sealed class AzureIdentityTokenHandler(
    TokenCredential credential,
    string tenantId
) : IOidcCallback
{
    private readonly string[] scopes = ["https://ossrdbms-aad.database.windows.net/.default"];

    public OidcAccessToken GetOidcAccessToken(OidcCallbackParameters parameters, CancellationToken cancellationToken)
    {
        AccessToken token = credential.GetToken(
            new TokenRequestContext(scopes, tenantId: tenantId),
            cancellationToken
        );

        return new OidcAccessToken(token.Token, token.ExpiresOn - DateTimeOffset.UtcNow);
    }

    public async Task<OidcAccessToken> GetOidcAccessTokenAsync(OidcCallbackParameters parameters, CancellationToken cancellationToken)
    {
        AccessToken token = await credential.GetTokenAsync(
            new TokenRequestContext(scopes, parentRequestId: null, tenantId: tenantId),
            cancellationToken
        );

        return new OidcAccessToken(token.Token, token.ExpiresOn - DateTimeOffset.UtcNow);
    }
}

DefaultAzureCredential型の新しいインスタンスとテナント ID を渡すカスタムハンドラークラスの新しいインスタンスを作成します。
```
DefaultAzureCredential credential = new();

string tenantId = "<microsoft-entra-tenant-id>";

AzureIdentityTokenHandler tokenHandler = new(credential, tenantId);
```
最近デプロイした Azure Cosmos DB for MongoDB 仮想コアインスタンスのエンドポイントとスキームを使用して、 MongoUrl のインスタンスを構築します。
```
string clusterName = "<azure-cosmos-db-mongodb-vcore-cluster-name>";

MongoUrl url = MongoUrl.Create($"mongodb+srv://{clusterName}.global.mongocluster.cosmos.azure.com/");
```

Azure Cosmos DB for MongoDB 仮想コアの既知のベストプラクティス構成オプションとカスタム IOidcCallback実装を使用して、MongoClient インスタンスを構成します。

MongoClientSettings settings = MongoClientSettings.FromUrl(url);

settings.UseTls = true;
settings.RetryWrites = false;
settings.MaxConnectionIdleTime = TimeSpan.FromMinutes(2);
settings.Credential = MongoCredential.CreateOidcCredential(tokenHandler);
settings.Freeze();

MongoClient client = new(settings);

データベースの取得

このサンプルは、IMongoDatabase クラスの GetDatabase メソッドを使用して MongoClient インターフェイスのインスタンスを作成します。

IMongoDatabase database = client.GetDatabase("<database-name>");

コレクションを取得する

このサンプルは、IMongoCollection<> インターフェイスの GetCollection<> ジェネリックメソッドを使用してジェネリック IMongoDatabase インターフェイスのインスタンスを作成します。ジェネリックインターフェイスとジェネリックメソッドはどちらも、別のクラスに定義されている Product という名前の型を使用します。

IMongoCollection<Product> collection = database.GetCollection<Product>("<collection-name>");

public record Product(
    string id,
    string category,
    string name,
    int quantity,
    decimal price,
    bool clearance
);

ドキュメントの作成

ジェネリック collection.ReplaceOneAsync<> 型パラメーターを指定した Product を使用して、コレクション内にドキュメントを作成します。このメソッドは、コレクションに既に存在する場合、ドキュメントを効果的に置き換えます。

Product document = new(
    id: "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
    category: "gear-surf-surfboards",
    name: "Yamba Surfboard",
    quantity: 12,
    price: 850.00m,
    clearance: false
);

await collection.ReplaceOneAsync<Product>(
    doc => doc.id == document.id,
    document,
    new ReplaceOptions { IsUpsert = true }
);

ドキュメントを読み取る

ドキュメントの一意識別子 (id) の両方を使用して、読み取り操作を実行します。特定のドキュメントを効率的に取得するには、ジェネリック Product 型パラメーターと共にcollection.FindAsync<>を使用します。

Product? document = await collection.Find(
    doc => doc.id == "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb"
).SingleOrDefaultAsync();

ドキュメントにクエリを実行する

collection.AsQueryable()と言語統合クエリ (LINQ) を使用して、コンテナー内の複数のドキュメントに対してクエリを実行します。このクエリは、指定されたカテゴリ (シャードキー) 内のすべてのドキュメントを検索します。

List<Product> documents = await collection.Find(
    filter: doc => doc.category == "gear-surf-surfboards"
).ToListAsync();

foreach (Product document in documents)
{
    // Do something with each document
}

ドキュメントの削除

ドキュメントを削除するには、そのドキュメントの一意識別子のフィルターを送信します。 collection.DeleteOneAsync<>を使用して、コレクションからドキュメントを非同期的に削除します。

await collection.DeleteOneAsync(
    doc => doc.id == "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb"
);

データを調査する

Azure Cosmos DB の Visual Studio Code 拡張機能を使用して、MongoDB 仮想コアデータを探索します。次のようなコアデータベース操作を実行できます。ただし、これらに限定されません:

スクラップブックまたはクエリエディターを使用したクエリの実行
ドキュメントの変更、更新、作成、および削除
他のソースからのデータの一括インポート
データベースとコレクションの管理

詳細については、「 Visual Studio Code 拡張機能を使用して Azure Cosmos DB for MongoDB 仮想コアデータを探索する方法」を参照してください。

リソースをクリーンアップする

サンプルアプリケーションまたはリソースが不要になったら、対応するデプロイとすべてのリソースを削除します。

azd down --force