開始搭配 Azure Cosmos DB for MongoDB 使用 .NET

發行項
08/15/2024

適用於： MongoDB

本文說明如何使用 .NET Core 和相關 NuGet 套件連線至 Azure Cosmos DB for MongoDB。連線之後，您即可在資料庫、集合和文件上執行作業。

注意

範例程式碼片段可在 GitHub 上作為 .NET Core 專案提供。

API for MongoDB 參考文件 | MongoDB 套件 (NuGet)

必要條件

建立新的 .NET Core 應用程式

使用您慣用的終端機，在空白資料夾中建立新的 .NET Core 應用程式。在此案例中，您將使用主控台應用程式。使用 dotnet new 命令來建立和命名主控台應用程式。
```
dotnet new console -o app
```
將 MongoDB NuGet 套件新增至主控台專案。使用指定 NuGet 套件名稱的 dotnet add package 命令。
```
dotnet add package MongoDB.Driver
```
若要執行應用程式，請使用終端機瀏覽至應用程式目錄並執行應用程式。
```
dotnet run
```

使用 MongoDB 原生驅動程式連線至 Azure Cosmos DB for MongoDB

若要使用 MongoDB 原生驅動程式連線至 Azure Cosmos DB，請建立 MongoClient 類別的執行個體。此類別是對 MongoDb 資料庫執行所有作業的起點。 MongoClient 最常見的建構函式會接受連接字串，而您可以使用下列步驟來擷取該字串：

取得資源名稱

建立 resourceGroupName 的殼層變數。

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

使用 az cosmosdb list 命令來擷取資源群組中第一個 Azure Cosmos DB 帳戶的名稱，並將其儲存在 accountName 殼層變數中。

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

建立 RESOURCE_GROUP_NAME 的殼層變數。

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

使用 Get-AzCosmosDBAccountKey Cmdlet 擷取資源群組中第一個 Azure Cosmos DB 帳戶的名稱，並將其儲存在 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

擷取連接字串

使用 az cosmosdb keys list 命令，從帳戶的連接字串清單中尋找 API for MongoDB 連接字串。

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

記錄 PRIMARY KEY 值。稍後您將使用這些認證。

使用 Cmdlet，從帳戶的金鑰和連接字串清單中尋找 CONNECTION STRINGGet-AzCosmosDBAccountKey。

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

記錄 CONNECTION STRING 值。稍後您將使用這些認證。

設定環境變數

若要在程式碼內使用 CONNECTION STRING 值，請在執行應用程式的本機環境中設定此值。若要設定環境變數，請使用您慣用的終端機來執行下列命令：

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

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

.env 檔案是將環境變數儲存在專案中的標準方式。在專案的根目錄中建立 .env 檔案。將下列幾行新增至 .env 檔案：

COSMOS_CONNECTION_STRING="<cosmos-connection-string>"

使用連接字串建立 MongoClient

使用建構函式和您先前設定的連接字串變數來定義 MongoClient 類別的新執行個體。

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

var settings = client.Settings;

Console.WriteLine(settings.Server.Host);

使用 MongoDB 用戶端類別搭配適用於 API for MongoDB 的 Azure Cosmos DB

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

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

每種資源以一或多個相關聯的 C# 類別來表示。以下是最常見類別的清單：

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

下列指南說明如何以上述每個類別來建置應用程式和管理資料。

指南：

另請參閱

下一步

既然您已連線到 API for MongoDB 帳戶，請使用下一個指南來建立和管理資料庫。

使用 .NET 在 Azure Cosmos DB for MongoDB 中建立資料庫

共用方式為