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

發行項
08/15/2024

適用於： MongoDB

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

適用於 MongoDB 的 API 參考文件 | MongoDB 套件 (NuGet) 套件/Microsoft.Azure.Cosmos) | Azure Developer CLI

必要條件

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

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

設定

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

重要

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

在專案的根目錄中開啟終端。
使用 azd auth login 以向 Azure Developer CLI 進行驗證。依照工具指定的步驟，使用您慣用的 Azure 認證向 CLI 進行驗證。
```
azd auth login
```
使用 azd init 來初始化專案。
```
azd init --template cosmos-db-mongodb-dotnet-quickstart
```
注意

本快速入門使用 azure-samples/cosmos-db-mongodb-dotnet-quickstart 範本 GitHub 存放庫。如果尚未複製此專案，Azure Developer CLI 會自動將其複製至您的機器上。
在初始化期間，請設定唯一的環境名稱。

提示

環境名稱也將是目標資源群組名稱。在這個快速入門中，請考慮使用 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 以讀取 Azure Developer CLI 先前設定的連接字串。

// 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

共用方式為