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

先决条件

先决条件检查

  • 在终端或命令窗口中,运行 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 帐户。

  1. 为 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"
    
  2. 如果尚未登录,请使用 az login 命令登录到 Azure CLI。

  3. 使用 az group create 命令在订阅中创建新的资源组。

    az group create \
        --name $resourceGroupName \
        --location $location
    
  4. 使用 az cosmosdb create 命令创建具有默认设置的新 Azure Cosmos DB for MongoDB 帐户。

    az cosmosdb create \
        --resource-group $resourceGroupName \
        --name $accountName \
        --locations regionName=$location
        --kind MongoDB
    

获取 MongoDB 连接字符串

  1. 使用 az cosmosdb keys list 命令,从帐户的连接字符串列表中查找 API for MongoDB 连接字符串。

    az cosmosdb keys list --type connection-strings \
        --resource-group $resourceGroupName \
        --name $accountName 
    
  2. 请记下“主密钥”值。 稍后将使用这些凭据。

新建 .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 层次结构示意图,其中包括帐户、数据库、集合和文档。

顶部是显示 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# classrecord 类型,其中包含要序列化为 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