通过 .NET 使用 Azure Cosmos DB for MongoDB 入门

项目
04/10/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 包添加到控制台项目。使用 dotnet add package 命令指定 NuGet 包的名称。
```
dotnet add package MongoDB.Driver
```
要运行应用，请使用终端导航到应用程序目录并运行该应用程序。
```
dotnet run
```

使用 MongoDB 原生驱动程序连接到 Azure Cosmos DB for MongoDB

若要使用 MongoDB 本机驱动程序连接到 Azure Cosmos DB，请创建 MongoClient 类的实例。此类是针对 MongoDb 数据库执行所有操作的起点。 MongoClient 最常见的构造函数接受连接字符串，可按照以下步骤来检索它：

获取资源名称

为 resourceGroupName 创建 shell 变量。

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

使用 az cosmosdb list 命令检索资源组中第一个 Azure Cosmos DB 帐户的名称，并将其存储在 accountName shell 变量中。

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

为 RESOURCE_GROUP_NAME 创建 shell 变量。

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

使用 Get-AzCosmosDBAccountKey cmdlet 检索资源组中第一个 Azure Cosmos DB 帐户的名称，并将其存储在 accountName shell 变量中。

# 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

请记下“主密钥”值。稍后将使用这些凭据。

使用 Get-AzCosmosDBAccountKey cmdlet，从帐户的密钥和连接字符串列表中查找“连接字符串”。

$parameters = @{
    ResourceGroupName = $RESOURCE_GROUP_NAME
    Name = $ACCOUNT_NAME
    Type = "ConnectionStrings"
}    
Get-AzCosmosDBAccountKey @parameters |
    Select-Object -Property "Primary MongoDB 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("MONGO_CONNECTION"));

var settings = client.Settings;

Console.WriteLine(settings.Server.Host);

将 MongoDB 客户端类与 Azure Cosmos DB for API for MongoDB 配合使用

在开始构建应用程序之前，我们先来了解 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 中创建数据库