Membangun aplikasi konsol .NET dengan Azure Cosmos DB untuk MongoDB vCore

2025-05-20
Berlaku untuk: ✅ MongoDB (vCore)

Panduan ini menunjukkan cara membuat aplikasi konsol .NET untuk menyambungkan ke kluster Azure Cosmos DB for MongoDB vCore. Anda menyiapkan lingkungan pengembangan, menggunakan Azure.Identity pustaka dari Azure SDK untuk .NET untuk mengautentikasi, dan berinteraksi dengan database untuk membuat, mengkueri, dan memperbarui dokumen.

Prasyarat

Kluster Azure Cosmos DB untuk MongoDB (vCore) yang sudah ada.

Versi terbaru Azure CLI di Azure Cloud Shell.
- Jika Anda lebih suka menjalankan perintah referensi CLI secara lokal, masuk ke Azure CLI dengan menggunakan az login perintah .

Autentikasi Microsoft Entra dikonfigurasi untuk kluster dengan identitas Anda yang diberikan peran dbOwner.
- Untuk mengaktifkan autentikasi Microsoft Entra, tinjau panduan konfigurasi.
Versi terbaru dari .NET.

Mendapatkan metadata instansi Microsoft Entra

Untuk mengambil token akses menggunakan kelas TokenCredential di Azure.Identity, Anda memerlukan pengidentifikasi unik untuk tenant Microsoft Entra. Dalam langkah prasyarat ini, gunakan Azure CLI untuk mengambil dan merekam nilainya tenantId .

Dapatkan detail langganan Azure yang sedang aktif menggunakan az account show.
```
az account show
```

Perintah menghasilkan respons JSON yang berisi berbagai bidang.

{
  "environmentName": "AzureCloud",
  "homeTenantId": "eeeeffff-4444-aaaa-5555-bbbb6666cccc",
  "id": "dddd3d3d-ee4e-ff5f-aa6a-bbbbbb7b7b7b",
  "isDefault": true,
  "managedByTenants": [],
  "name": "example-azure-subscription",
  "state": "Enabled",
  "tenantId": "eeeeffff-4444-aaaa-5555-bbbb6666cccc",
  "user": {
    "cloudShellID": true,
    "name": "kai@adventure-works.com",
    "type": "user"
  }
}

Catat nilai tenantId properti . Properti ini adalah pengidentifikasi unik untuk penyewa Microsoft Entra Anda dan terkadang disebut sebagai ID penyewa. Anda menggunakan nilai ini dalam langkah-langkah dalam bagian berikutnya.

Mengonfigurasi aplikasi konsol Anda

Selanjutnya, buat project aplikasi konsol baru dan masukkan pustaka yang diperlukan untuk mengautentikasi ke dalam kluster Anda.

Di direktori kosong, buat aplikasi konsol .NET baru.
```
dotnet new console
```
Azure.Identity Impor paket dari NuGet.
```
dotnet add package Azure.Identity
```
Selanjutnya, impor MongoDB.Driver paket.
```
dotnet add package MongoDB.Driver
```
Membangun proyek .NET
```
dotnet build
```

Menyambungkan ke kluster

Sekarang, gunakan pustaka Azure.Identity untuk mendapatkan TokenCredential yang dapat Anda gunakan untuk menghubungkan ke kluster Anda. Driver Resmi MongoDB memiliki antarmuka khusus yang harus diimplementasikan untuk mendapatkan token dari Microsoft Entra untuk digunakan saat menyambungkan ke kluster.

Dalam file Program.cs, tambahkan blok using untuk namespace Azure.Identity dan MongoDB.Driver.
```
using Azure.Identity;
using MongoDB.Driver;
```

Buat kelas baru dalam file terpisah yang mengimplementasikan semua anggota antarmuka yang MongoDB.Driver.Authentication.Oidc.IOidcCallback diperlukan.

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);
    }
}

Petunjuk / Saran

Untuk tujuan ilustrasi, kelas ini diberi nama AzureIdentityTokenHandler. Anda dapat memberi nama kelas ini apa pun yang Anda inginkan. Sisa panduan ini mengasumsikan kelas diberi nama AzureIdentityTokenHandler.

Kembali ke editor untuk file Program.cs .

Buat variabel string dengan nama kluster Anda yang ada. Kemudian, gunakan variabel tersebut untuk membuat instans MongoUrl jenis baru menggunakan MongoUrl.Create

string clusterName = "<azure-cosmos-db-mongodb-vcore-cluster-name>";

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

Konfigurasikan instans MongoSettings baru dengan memanfaatkan MongoUrl yang telah dibuat pada langkah sebelumnya dan menerapkan konfigurasi praktik terbaik standar untuk Azure Cosmos DB dengan MongoDB vCore.
```
MongoClientSettings settings = MongoClientSettings.FromUrl(url);

settings.UseTls = true;
settings.RetryWrites = false;
settings.MaxConnectionIdleTime = TimeSpan.FromMinutes(2);
```
Buat kredensial baru jenis DefaultAzureCredential.
```
DefaultAzureCredential credential = new();
```
Petunjuk / Saran

Anda dapat menggunakan kredensial jenis TokenCredential apa pun di sini. DefaultAzureCredential adalah opsi paling tanpa gesekan untuk skenario pengembangan awal.
Buat instans baru dari kelas Anda yang mengimplementasikan IOidcCallback, dan konfigurasikan dengan ID penyewa yang Anda catat sebelumnya dalam panduan ini.
```
string tenantId = "<microsoft-entra-tenant-id>";

AzureIdentityTokenHandler tokenHandler = new(credential, tenantId);
```
Konfigurasikan kredensial untuk pengaturan Anda dengan menggunakan MongoCredential.CreateOidcCredential dan menambahkan implementasi callback handler kustom Anda.
```
settings.Credential = MongoCredential.CreateOidcCredential(tokenHandler);
```

Bekukan pengaturan lalu buat instans baru .MongoClient

settings.Freeze();

MongoClient client = new(settings);

Console.WriteLine("Client created");

Melakukan operasi umum

Terakhir, gunakan pustaka resmi untuk melakukan tugas umum dengan database, koleksi, dan dokumen. Di sini, Anda menggunakan kelas dan metode yang sama dengan yang akan Anda gunakan untuk berinteraksi dengan MongoDB atau DocumentDB untuk mengelola koleksi dan item Anda.

Wakili dokumen Anda dengan membuat tipe catatan khusus dalam berkas tersendiri.
```
public record Product(
    string id,
    string category,
    string name,
    int quantity,
    decimal price,
    bool clearance
);
```
Petunjuk / Saran

Untuk tujuan ilustrasi, struktur ini diberi nama Product. Sisa panduan ini mengasumsikan Anda telah menentukan struktur ini.
Kembali ke file Program.cs .

Dapatkan penunjuk ke basis data Anda menggunakan MongoClient.GetDatabase.

string databaseName = "<database-name>";

IMongoDatabase database = client.GetDatabase(databaseName);

Console.WriteLine("Database pointer created");

Kemudian, gunakan penunjuk database untuk mendapatkan penunjuk ke koleksi Anda menggunakan IMongoDatabase.GetCollection<>.

string collectionName = "<collection-name>";

IMongoCollection<Product> collection = database.GetCollection<Product>(collectionName);

Console.WriteLine("Collection pointer created");

Buat dan upsert dua dokumen menggunakan metode IMongoCollection<>.ReplaceOneAsync.

Product classicSurfboard = new(
    id: "bbbbbbbb-1111-2222-3333-cccccccccccc",
    category: "gear-surf-surfboards",
    name: "Kiama Classic Surfboard",
    quantity: 25,
    price: 790.00m,
    clearance: false
);

Product paddleKayak = new(
    id: "cccccccc-2222-3333-4444-dddddddddddd",
    category: "gear-paddle-kayaks",
    name: "Lastovichka Paddle Kayak",
    quantity: 10,
    price: 599.99m,
    clearance: true
);

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

Console.WriteLine($"Upserted document:\t{classicSurfboard.id}");

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

Console.WriteLine($"Upserted document:\t{paddleKayak.id}");

Baca satu dokumen dari koleksi menggunakan IMongoCollection<>.Find dan IFindFluent<,>.SingleAsync. Gunakan filter untuk menentukan dokumen tertentu yang ingin Anda temukan.

Product document = await collection.Find(
    doc => doc.id == "cccccccc-2222-3333-4444-dddddddddddd"
).SingleAsync();

Console.WriteLine($"Found document:\t{document.name}");

Lakukan kueri untuk semua dokumen yang sesuai dengan filter menggunakan metode yang sama Find. Gunakan filter untuk menentukan properti tertentu (seperti category) dan nilai tertentu (seperti gear-surf-surfboards). Hitung hasilnya menggunakan IFindFluent<,>.ToListAsync.
```
List<Product> documents = await collection.Find(
    doc => doc.category == "gear-surf-surfboards"
).ToListAsync();

foreach (Product doc in documents)
{
    Console.WriteLine($"Queried document:\t{doc}");
}
```

Hapus dokumen tertentu dari koleksi menggunakan IMongoCollection<>.DeleteOneAsync dan filter.

await collection.DeleteOneAsync(
    doc => doc.id == "bbbbbbbb-1111-2222-3333-cccccccccccc"
);

Console.WriteLine($"Deleted document");

Simpan semua file kode dalam proyek.
Menjalankan proyek menggunakan dotnet run
```
dotnet run
```

Amati output dari aplikasi yang sedang berjalan.

Client created
Database pointer created
Collection pointer created
Upserted document:      bbbbbbbb-1111-2222-3333-cccccccccccc
Upserted document:      cccccccc-2222-3333-4444-dddddddddddd
Found document: Lastovichka Paddle Kayak
Queried document:       Product { id = bbbbbbbb-1111-2222-3333-cccccccccccc, category = gear-surf-surfboards, name = Kiama Classic Surfboard, quantity = 25, price = 790.00, clearance = False }
Deleted document

Bagikan melalui

Membangun aplikasi konsol .NET dengan Azure Cosmos DB untuk MongoDB vCore

Prasyarat

Mendapatkan metadata instansi Microsoft Entra

Mengonfigurasi aplikasi konsol Anda

Menyambungkan ke kluster

Melakukan operasi umum

Konten terkait

Saran dan Komentar

Sumber Daya Tambahan: