快速入門：適用於 .NET 的 Azure Cosmos DB for MongoDB 與 MongoDB 驅動程式

發行項
03/28/2024

適用於： MongoDB

開始使用 MongoDB，以在您的 Azure Cosmos DB 資源內建立資料庫、集合和文件。請依照以下步驟，使用 Azure Developer CLI 將基本解決方案部署到您的環境。

適用於 MongoDB 的 API 參考檔 | MongoDB 套件（NuGet）套件/Microsoft.Azure.Cosmos） | Azure 開發人員 CLI

必要條件

具有有效訂用帳戶的 Azure 帳戶。免費建立帳戶。
GitHub 帳戶

具有有效訂用帳戶的 Azure 帳戶。免費建立帳戶。
Azure Developer CLI
Docker Desktop

設定

將這個專案的開發容器部署到您的環境。然後，使用 Azure 開發人員 CLI （azd）建立適用於 MongoDB 的 Azure Cosmos DB 帳戶，並部署容器化範例應用程式。應用程式範例使用用戶端程式庫管理、建立、讀取和查詢樣本資料。

重要

GitHub 帳戶的免費權利包括儲存體和核心時數。如需詳細資訊，請參閱 GitHub 帳戶包含的儲存體和核心時數。

在專案的根目錄中開啟終端。
使用 azd auth login 以向 Azure Developer CLI 進行驗證。依照工具指定的步驟，使用您慣用的 Azure 認證向 CLI 進行驗證。
```
azd auth login
```
使用 azd init 來初始化專案。
```
azd init
```
在初始化期間，請設定唯一的環境名稱。

提示

環境名稱也將是目標資源群組名稱。在這個快速入門中，請考慮使用 msdocs-cosmos-db-。
使用 azd up部署 Azure Cosmos DB 帳戶。 Bicep 範本也會部署範例 Web 應用程式。
```
azd up
```
在佈建流程期間，請選取您的訂用帳戶和所需位置。等候佈建程序完成。此流程「大約需要五分鐘」的時間。

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 應用程式。觀察執行中應用程式的輸出。

安裝用戶端程式庫

用戶端程式庫可透過 NuGet 以 Microsoft.Azure.Cosmos 套件形式提供。

開啟終端機，然後導覽至 /src/web 資料夾。
```
cd ./src/web
```
如果尚未安裝，則請使用 dotnet add package 來安裝 MongoDb.Driver 套件。
```
dotnet add package MongoDb.Driver
```
也請安裝 Azure.Identity 套件 (如果尚未安裝)。
```
dotnet add package Azure.Identity
```

物件模型

在開始建置應用程式之前，讓我們看一下 Azure Cosmos DB 中的資源階層。 Azure Cosmos DB 具有用來建立和存取資源的特定物件模型。 Azure Cosmos DB 會在由帳戶、資料戶、集合和文件所組成的階層中建立資源。

Azure Cosmos DB 階層的圖表，包括帳戶、資料庫、集合和檔。

您將使用下列 MongoDB 類別與這些資源互動：

MongoClient - 此類別提供 Azure Cosmos DB 上 API for MongoDB 層的用戶端邏輯表示法。用戶端物件會用於設定及執行針對服務的要求。
MongoDatabase - 此類別是服務中可能存在或不存在的資料庫參考。當您嘗試存取資料庫或對其執行作業時，資料庫為已驗證的伺服器端。
Collection - 此類別為集合參考，可能尚未存在於伺服器中。當您嘗試使用集合時，集合為已驗證的伺服器端。

本文示範的範例程式碼建立名為 adventureworks 的資料庫，其中包含名為 products 的集合。 products 集合的設計目的是要包含產品詳細資料，例如名稱、類別、數量和銷售指標。每個產品也都包含唯一識別碼。

驗證用戶端

從專案目錄開啟 Program.cs 檔案。在編輯器中，為 MongoDB.Driver 新增 using 指示詞。

using MongoDB.Driver;

使用建構函式定義 MongoClient 類別的新執行個體，並且定義 Environment.GetEnvironmentVariable 以讀取您先前設定的連接字串。

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

建立資料庫

如果資料庫尚未存在，請使用 MongoClient.GetDatabase 方法建立新的資料庫。這個方法會傳回現有或新建立資料庫的參考。

// Database reference with creation if it does not already exist
var db = client.GetDatabase("adventure");

建立集合

MongoDatabase.GetCollection 會建立新的集合 (如果尚不存在)，並傳回集合的參考。

// Container reference with creation if it does not alredy exist
var _products = db.GetCollection<Product>("products");

建立項目

要在集合中建立新的項目，最簡單的方式就是建立一個 C# 類別或記錄類型，其中包含您想要序列化為 JSON 的所有成員。在此範例中，C# 記錄具有唯一識別碼、資料分割索引鍵的類別欄位，以及額外的名稱、數量和銷售欄位。

public record Product(
    string Id,
    string Category,
    string Name,
    int Quantity,
    bool Sale
);

藉由呼叫 IMongoCollection<TDocument>.InsertOne 並使用 Product 記錄，在集合中建立項目。

// Create new object and upsert (create or replace) to container
_products.InsertOne(new Product(
    Guid.NewGuid().ToString(),
    "gear-surf-surfboards",
    "Yamba Surfboard", 
    12, 
    false
));

取得項目

在 Azure Cosmos DB 中，您可以使用 Linq 撰寫查詢，藉以擷取項目。在 SDK 中，請呼叫 IMongoCollection.FindAsync<> 並傳入 C# 運算式，以篩選結果。

// Read a single item from container
var product = (await _products.FindAsync(p => p.Name.Contains("Yamba"))).FirstOrDefault();
Console.WriteLine("Single product:");
Console.WriteLine(product.Name);

查詢項目

插入項目之後，您可以將集合視為 IQueryable，執行查詢以取得所有符合特定篩選的項目。此範例會使用運算式依類別篩選產品。在呼叫 AsQueryable 之後，呼叫 MongoQueryable.Where 以擷取一組篩選的項目。

// Read multiple items from container
_products.InsertOne(new Product(
    Guid.NewGuid().ToString(),
    "gear-surf-surfboards",
    "Sand Surfboard",
    4,
    false
));

var products = _products.AsQueryable().Where(p => p.Category == "gear-surf-surfboards");

Console.WriteLine("Multiple products:");
foreach (var prod in products)
{
    Console.WriteLine(prod.Name);
}

執行程式碼

此應用程式會建立 Azure Cosmos DB MongoDB API 資料庫和集合。然後，此範例會建立項目，然後重新讀取完全相同的項目。最後，此範例會建立第二個項目，然後執行應傳回多個項目的查詢。在每個步驟中，範例會將中繼資料輸出至主控台，包含其執行的步驟。

若要執行應用程式，請使用終端機瀏覽至應用程式目錄並執行應用程式。

dotnet run

此命令的輸出應類似此範例：

Single product name: 
Yamba Surfboard
Multiple products:
Yamba Surfboard
Sand Surfboard

清除資源

當您不再需要 Azure Cosmos DB for MongoDB 帳戶時，可以刪除對應的資源群組。

使用 az group delete 命令以刪除資源群組。

az group delete --name $resourceGroupName

使用 Remove-AzResourceGroup Cmdlet 以刪除資源群組。

$parameters = @{
    Name = $RESOURCE_GROUP_NAME
}
Remove-AzResourceGroup @parameters