你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

快速入门：适用于 .NET 的 Azure Cosmos DB for MongoDB 与 MongoDB 驱动程序

项目
03/29/2024

适用对象： MongoDB

开始使用 MongoDB 在 Azure Cosmos DB 资源中创建数据库、集合和文档。请按照以下步骤，使用 Azure Developer CLI 将最小解决方案部署到环境。

有关适用于 MongoDB 的 API 的参考文档 | MongoDB 包 (NuGet) packages/Microsoft.Azure.Cosmos) | Azure Developer CLI

先决条件

具有活动订阅的 Azure 帐户。免费创建帐户。
GitHub 帐户

具有活动订阅的 Azure 帐户。免费创建帐户。
Azure 开发人员 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
```
在初始化期间，配置唯一的环境名称。

提示

环境名称也将用作目标资源组名称。对于本快速入门，请考虑使用 msdocs-cosmos-db-。
使用 azd up 部署 Azure Cosmos DB 帐户。 Bicep 模板还部署示例 Web 应用程序。
```
azd up
```
在预配过程中，选择订阅和所需位置。等待预配过程完成。此过程可能需要大约 5 分钟。

预配 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# class 或 record 类型，其中包含要序列化为 JSON 的所有成员。在此示例中，C# 记录具有唯一标识符、分区键的 category 字段以及额外的 name、quantity 和 sale 字段。

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