你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。
快速入门：适用于 .NET 的 Azure Cosmos DB for MongoDB 与 MongoDB 驱动程序
适用于： 
MongoDB
开始使用 MongoDB 在 Azure Cosmos DB 资源中创建数据库、集合和文档。 请按照以下步骤安装程序包并试用基本任务的示例代码。
注意
示例代码片段在 GitHub 上作为 .NET 项目提供。
API for MongoDB 参考文档 | MongoDB 包 (NuGet)
先决条件
- 具有活动订阅的 Azure 帐户。 免费创建帐户。
- .NET 6.0
- Azure 命令行接口 (CLI) 或 Azure PowerShell
先决条件检查
- 在终端或命令窗口中，运行
dotnet --list-sdks以检查 .NET 6.x 是否是可用版本之一。 - 运行
az --version(Azure CLI) 或Get-Module -ListAvailable AzureRM(Azure PowerShell)，检查是否安装了适当的 Azure 命令行工具。
设置
本部分引导你创建 Azure Cosmos DB 帐户并设置使用 MongoDB NuGet 包的项目。
创建 Azure Cosmos DB 帐户
本快速入门将使用 API for MongoDB 创建单个 Azure Cosmos DB 帐户。
为 accountName、resourceGroupName 和 location 创建 shell 变量。
# Variable for resource group name resourceGroupName="msdocs-cosmos-quickstart-rg" location="westus" # Variable for account name with a randomnly generated suffix let suffix=$RANDOM*$RANDOM accountName="msdocs-$suffix"如果尚未登录，请使用
az login命令登录到 Azure CLI。使用
az group create命令在订阅中创建新的资源组。az group create \ --name $resourceGroupName \ --location $location使用
az cosmosdb create命令创建具有默认设置的新 Azure Cosmos DB for MongoDB 帐户。az cosmosdb create \ --resource-group $resourceGroupName \ --name $accountName \ --locations regionName=$location --kind MongoDB
获取 MongoDB 连接字符串
使用
az cosmosdb keys list命令，从帐户的连接字符串列表中查找 API for MongoDB 连接字符串。az cosmosdb keys list --type connection-strings \ --resource-group $resourceGroupName \ --name $accountName请记下“主密钥”值。 稍后将使用这些凭据。
新建 .NET 应用
使用首选终端在空文件夹中创建新的 .NET 应用程序。 使用 dotnet new console 创建新的控制台应用。
dotnet new console -o <app-name>
安装 NuGet 包
将 MongoDB.Driver NuGet 包添加到新的 .NET 项目。 使用 dotnet add package 命令指定 NuGet 包的名称。
dotnet add package MongoDb.Driver
配置环境变量
若要在代码中使用“连接字符串”值，请在运行应用程序的本地环境中设置此值。 若要设置环境变量，请使用首选终端运行以下命令：
$env:COSMOS_CONNECTION_STRING = "<cosmos-connection-string>"
对象模型
在开始构建应用程序之前，我们先来了解 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 NoSQL 帐户时，可以删除相应的资源组。
使用 az group delete 命令删除资源组。
az group delete --name $resourceGroupName
