你当前正在访问 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