Mulai menggunakan Azure Cosmos DB untuk MongoDB menggunakan .NET

BERLAKU UNTUK: MongoDB

Artikel ini memperlihatkan kepada Anda cara menyambungkan ke Azure Cosmos DB untuk MongoDB menggunakan .NET Core dan paket NuGet yang relevan. Setelah terhubung, Anda dapat melakukan operasi pada database, koleksi, dan dokumen.

Catatan

Cuplikan kode contoh tersedia di GitHub sebagai proyek .NET Core.

API untuk dokumentasi | referensi MongoDB Paket MongoDB (NuGet)

Prasyarat

• Akun Azure dengan langganan aktif. Buat akun secara gratis.
• .NET 6.0
• Azure Command-Line Interface (CLI) atau Azure PowerShell
• Azure Cosmos DB untuk sumber daya MongoDB

Membuat aplikasi .NET Core baru

1. Buat aplikasi .NET Core baru di folder kosong menggunakan terminal pilihan Anda. Untuk skenario ini, Anda akan menggunakan aplikasi konsol. Gunakan perintah dotnet new untuk membuat dan memberi nama aplikasi konsol.

   dotnet new console -o app
   

2. Tambahkan paket NuGet MongoDB ke proyek konsol. Gunakan perintah dotnet add package yang menentukan nama paket NuGet.

   dotnet add package MongoDB.Driver
   

3. Untuk menjalankan aplikasi, gunakan terminal untuk menavigasi ke direktori aplikasi dan menjalankannya.

   dotnet run
   

Menyambungkan ke Azure Cosmos DB untuk MongoDB dengan driver asli MongoDB

Untuk menyambungkan ke Azure Cosmos DB dengan driver asli MongoDB, buat instans kelas MongoClient. Kelas ini adalah titik awal untuk melakukan semua operasi terhadap database MongoDb. Konstruktor paling umum untuk MongoClient menerima string koneksi, yang dapat Anda ambil menggunakan langkah-langkah berikut:

Dapatkan nama sumber daya

Azure CLI

1. Buat variabel shell untuk resourceGroupName.

   # Variable for resource group name
   resourceGroupName="msdocs-cosmos"
   

2. Gunakan perintah az cosmosdb list untuk mengambil nama akun Azure Cosmos DB pertama di grup sumber daya Anda dan simpan di variabel shell accountName.

   # Retrieve most recently created account name
   accountName=$(
       az cosmosdb list \
           --resource-group $resourceGroupName \
           --query "[0].name" \
           --output tsv
   )
   

PowerShell

1. Buat variabel shell untuk RESOURCE_GROUP_NAME.

   # Variable for resource group name
   $RESOURCE_GROUP_NAME = "msdocs-cosmos"
   

2. Gunakan cmdlet Get-AzCosmosDBAccountKey untuk mengambil nama akun Azure Cosmos DB pertama di grup sumber daya Anda dan menyimpannya di variabel shell accountName.

   # Get the name of the first Azure Cosmos DB account in your resource group
   $ACCOUNT_NAME = (Get-AzCosmosDBAccount -ResourceGroupName $RESOURCE_GROUP_NAME)[0].Name
   

Portal

Lewati langkah ini dan gunakan informasi untuk portal di langkah berikutnya.

Mengambil string koneksi Anda

Azure CLI

1. Temukan API untuk MongoDB string koneksi dari daftar string koneksi untuk akun dengan az cosmosdb keys list perintah .

   az cosmosdb keys list --type connection-strings \
       --resource-group $resourceGroupName \
       --name $accountName 
   

2. Rekam nilai KUNCI PRIMER. Anda akan menggunakan info masuk ini nanti.

PowerShell

1. Temukan STRING KONEKSI dari daftar kunci dan string koneksi untuk akun dengan cmdlet Get-AzCosmosDBAccountKey.

   $parameters = @{
       ResourceGroupName = $RESOURCE_GROUP_NAME
       Name = $ACCOUNT_NAME
       Type = "ConnectionStrings"
   }    
   Get-AzCosmosDBAccountKey @parameters |
       Select-Object -Property "Primary MongoDB Connection String"    
   

2. Rekam nilai STRING KONEKSI. Anda akan menggunakan info masuk ini nanti.

Portal

Tip

Untuk panduan ini, kami rekomendasikan untuk menggunakan nama grup sumber daya msdocs-cosmos.

1. Masuk ke portal Azure.

2. Navigasikan ke halaman akun Azure Cosmos DB for MongoDB yang sudah ada.

3. Dari halaman akun Azure Cosmos DB for MongoDB, pilih opsi menu navigasi String Koneksi.

4. Rekam nilai untuk bidang STRING KONEKSI PRIMER. Anda menggunakan nilai ini di langkah selanjutnya.

   

Mengonfigurasi variabel lingkungan

Untuk menggunakan nilai STRING KONEKSI dalam kode Anda, atur nilai ini di lingkungan lokal yang menjalankan aplikasi. Untuk mengatur variabel lingkungan, gunakan terminal pilihan Anda untuk menjalankan perintah berikut:

Windows

$env:COSMOS_CONNECTION_STRING = "<cosmos-connection-string>"

Linux / macOS

export COSMOS_CONNECTION_STRING="<cosmos-connection-string>"

.env

File .env merupakan cara standar untuk menyimpan variabel lingkungan dalam proyek. Buatlah file .env di akar proyek Anda. Tambahkan baris berikut ke file .env:

COSMOS_CONNECTION_STRING="<cosmos-connection-string>"

Membuat MongoClient dengan string koneksi

Tentukan instans baru dari kelas MongoClient menggunakan konstruktor dan variabel string koneksi yang Anda tetapkan sebelumnya.

// New instance of CosmosClient class
var client = new MongoClient(Environment.GetEnvironmentVariable("COSMOS_CONNECTION_STRING"));

var settings = client.Settings;

Console.WriteLine(settings.Server.Host);

Gunakan kelas klien MongoDB dengan Azure Cosmos DB untuk API untuk MongoDB

Sebelum Anda mulai membangun aplikasi, mari kita lihat hierarki sumber daya di Azure Cosmos DB. Azure Cosmos DB memiliki model objek tertentu yang digunakan untuk membuat dan mengakses sumber daya. Azure Cosmos DB membuat sumber daya dalam hierarki yang terdiri dari akun, database, koleksi, dan dokumen.

Diagram hierarkis memperlihatkan akun Azure Cosmos DB untuk MongoDB di bagian atas. Akun ini memiliki dua node database turunan. Salah satu node database tersebut memiliki dua node koleksi turunan. Node database lainnya memiliki satu node koleksi turunan. Satu node koleksi tersebut memiliki tiga node dokumen turunan.

Setiap jenis sumber daya diwakili oleh satu atau lebih kelas C# terkait. Berikut adalah daftar kelas yang paling umum:

Kelas	Deskripsi
MongoClient	Kelas ini menyediakan representasi logis sisi klien untuk lapisan API untuk MongoDB di Azure Cosmos DB. Klien ini digunakan untuk mengonfigurasi dan menjalankan permintaan terhadap layanan.
MongoDatabase	Kelas ini adalah referensi ke database yang mungkin sudah ada, atau mungkin belum ada dalam layanan. Database divalidasi atau dibuat di sisi server saat Anda mencoba melakukan operasi terhadapnya.
Collection	Kelas ini merupakan referensi koleksi yang mungkin juga belum ada dalam layanan. Koleksi divalidasi di sisi server saat Anda mencoba untuk menggunakannya.

Panduan berikut menunjukkan cara menggunakan masing-masing kelas ini untuk membangun aplikasi Anda dan mengelola data.

Panduan:

• Mengelola database
• Mengelola koleksi
• Mengelola dokumen
• Menggunakan kueri untuk menemukan dokumen

Lihat juga

• Paket (NuGet)
• Referensi API

Langkah berikutnya

Sekarang setelah Anda terhubung ke API untuk akun MongoDB, gunakan panduan berikutnya untuk membuat dan mengelola database.

Membuat database di Azure Cosmos DB untuk MongoDB menggunakan .NET