通过 .NET 开始使用适用于NoSQL 的Azure Cosmos DB

项目
08/27/2024

适用范围： NoSQL

本文介绍如何使用 .NET SDK 连接到 Azure Cosmos DB for NoSQL。连接后，可对数据库、容器和项执行操作。

包 (NuGet) | 示例 | API 参考 | 库源代码 | 反馈

先决条件

具有活动订阅的 Azure 帐户。创建试用版订阅。
Azure Cosmos DB for NoSQL 帐户。创建 API for NoSQL 帐户。
.NET 6.0 或更高版本
Azure 命令行接口 (CLI) 或 Azure PowerShell

设置项目

创建 .NET 控制台应用程序

通过将 dotnet new 命令与控制台模板一起使用，创建一个新的 .NET 应用程序。

dotnet new console

使用 dotnet add package 命令导入 Microsoft.Azure.Cosmos NuGet 包。

dotnet add package Microsoft.Azure.Cosmos

使用 dotnet build 命令生成项目。

dotnet build

连接到 Azure Cosmos DB for NoSQL

若要连接到 Azure Cosmos DB 的 API for NoSQL，请创建 CosmosClient 类的实例。此类是针对数据库执行所有操作的起点。可以通过三种核心方式使用 CosmosClient 类连接到 API for NoSQL 帐户：

使用 API for NoSQL 终结点和读/写密钥进行连接
使用 API for NoSQL 连接字符串进行连接
使用 Microsoft Entra ID 进行连接

使用终结点和密钥连接

CosmosClient 的最常见构造函数有两个参数：

参数	示例值	说明
`accountEndpoint`	`COSMOS_ENDPOINT` 环境变量	用于所有请求的 API for NoSQL 终结点
`authKeyOrResourceToken`	`COSMOS_KEY` 环境变量	身份验证时要使用的帐户密钥或资源令牌

检索帐户终结点和密钥

为 resourceGroupName 创建 shell 变量。

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

使用 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
)

使用 az cosmosdb show 命令获取帐户的 API for NoSQL 终结点 URI。

az cosmosdb show \
    --resource-group $resourceGroupName \
    --name $accountName \
    --query "documentEndpoint"

使用 az-cosmosdb-keys-list 命令从帐户的密钥列表中查找主密钥。

az cosmosdb keys list \
    --resource-group $resourceGroupName \
    --name $accountName \
    --type "keys" \
    --query "primaryMasterKey"

记录 URI 和主密钥值。稍后将使用这些凭据。

为 RESOURCE_GROUP_NAME 创建 shell 变量。

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

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

# Retrieve most recently created account name
$parameters = @{
    ResourceGroupName = $RESOURCE_GROUP_NAME
}
$ACCOUNT_NAME = (
    Get-AzCosmosDBAccount @parameters |
        Select-Object -Property Name -First 1
).Name

使用 Get-AzCosmosDBAccount cmdlet 获取帐户的 API for NoSQL 终结点 URI。

$parameters = @{
    ResourceGroupName = $RESOURCE_GROUP_NAME
    Name = $ACCOUNT_NAME
}
Get-AzCosmosDBAccount @parameters |
    Select-Object -Property "DocumentEndpoint"

使用 Get-AzCosmosDBAccountKey cmdlet 从帐户的密钥列表中查找主密钥。

$parameters = @{
    ResourceGroupName = $RESOURCE_GROUP_NAME
    Name = $ACCOUNT_NAME
    Type = "Keys"
}    
Get-AzCosmosDBAccountKey @parameters |
    Select-Object -Property "PrimaryMasterKey"

记录 URI 和主密钥值。稍后将使用这些凭据。

若要在 .NET 代码中使用“URI”和“主密钥”值，请将其保存到运行应用程序的本地计算机上的新环境变量。

Windows
Linux/macOS

$env:COSMOS_ENDPOINT = "<cosmos-account-URI>"
$env:COSMOS_KEY = "<cosmos-account-PRIMARY-KEY>"

export COSMOS_ENDPOINT="<cosmos-account-URI>"
export COSMOS_KEY="<cosmos-account-PRIMARY-KEY>"

使用帐户终结点和密钥创建 CosmosClient

使用 COSMOS_ENDPOINT 和 COSMOS_KEY 环境变量作为参数，创建 CosmosClient 类的新实例。

// New instance of CosmosClient class using an endpoint and key string
using CosmosClient client = new(
    accountEndpoint: Environment.GetEnvironmentVariable("COSMOS_ENDPOINT")!,
    authKeyOrResourceToken: Environment.GetEnvironmentVariable("COSMOS_KEY")!
);

使用连接字符串连接

CosmosClient 的另一个构造函数仅包含一个参数：

参数	示例值	说明
`accountEndpoint`	`COSMOS_ENDPOINT` 环境变量	用于所有请求的 API for NoSQL 终结点
`connectionString`	`COSMOS_CONNECTION_STRING` 环境变量	API for NoSQL 帐户的连接字符串

检索帐户连接字符串

使用 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
)

使用 az-cosmosdb-keys-list 命令，从帐户的连接字符串列表中查找主连接字符串。

az cosmosdb keys list \
    --resource-group $resourceGroupName \
    --name $accountName \
    --type "connection-strings" \
    --query "connectionStrings[?description == \`Primary SQL Connection String\`] | [0].connectionString"

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

# Retrieve most recently created account name
$parameters = @{
    ResourceGroupName = $RESOURCE_GROUP_NAME
}
$ACCOUNT_NAME = (
    Get-AzCosmosDBAccount @parameters |
        Select-Object -Property Name -First 1
).Name

使用 Get-AzCosmosDBAccountKey cmdlet，从帐户的连接字符串列表中查找主连接字符串。

$parameters = @{
    ResourceGroupName = $RESOURCE_GROUP_NAME
    Name = $ACCOUNT_NAME
    Type = "ConnectionStrings"
}    
Get-AzCosmosDBAccountKey @parameters |
    Select-Object -Property "Primary SQL Connection String" -First 1

若要在 .NET 代码中使用“主连接字符串”值，请将其保存到运行应用程序的本地计算机上的新环境变量。

Windows
Linux/macOS

$env:COSMOS_CONNECTION_STRING = "<cosmos-account-PRIMARY-CONNECTION-STRING>"

export COSMOS_CONNECTION_STRING="<cosmos-account-PRIMARY-CONNECTION-STRING>"

使用连接字符串创建 CosmosClient

使用 COSMOS_CONNECTION_STRING 环境变量作为唯一参数，创建 CosmosClient 类的新实例。

// New instance of CosmosClient class using a connection string
using CosmosClient client = new(
    connectionString: Environment.GetEnvironmentVariable("COSMOS_CONNECTION_STRING")!
);

使用 Microsoft 标识平台进行连接

若要使用 Microsoft 标识平台和 Microsoft Entra ID 连接到 API for NoSQL 帐户，请使用安全主体。主体的确切类型将取决于应用程序代码的托管位置。下表可用作快速参考指南。

应用程序的运行位置	安全主体
本地计算机（开发和测试）	用户标识或服务主体
Azure	托管标识
Azure 外部的服务器或客户端	服务主体

导入 Azure.Identity

Azure.Identity NuGet 包包含所有 Azure SDK 库之间共享的核心身份验证功能。

使用 dotnet add package 命令导入 Azure.Identity NuGet 包。

dotnet add package Azure.Identity

使用 dotnet build 命令重新生成项目。

dotnet build

在代码编辑器中，添加 Azure.Core 和 Azure.Identity 命名空间的 using 指令。

using Azure.Core;
using Azure.Identity;

使用默认凭据实现创建 CosmosClient

如果在本地计算机上进行测试，或者应用程序将在 Azure 服务上运行，并直接支持托管标识，则通过创建 DefaultAzureCredential 实例来获取 OAuth 令牌。

在此示例中，我们将实例保存在类型为 TokenCredential 的变量中，因为这是一种可在 SDK 中重复使用的更通用的类型。

// Credential class for testing on a local machine or Azure services
TokenCredential credential = new DefaultAzureCredential();

使用 COSMOS_ENDPOINT 环境变量和 TokenCredential 对象作为参数，创建 CosmosClient 类的新实例。

// New instance of CosmosClient class using a connection string
using CosmosClient client = new(
    accountEndpoint: Environment.GetEnvironmentVariable("COSMOS_ENDPOINT")!,
    tokenCredential: credential
);

使用自定义凭据实现创建 CosmosClient

如果计划在 Azure 之外部署应用程序，则可以通过使用适用于 .NET 的 Azure.Identity 客户端库中的其他类来获取 OAuth 令牌。这些其他类也派生自 TokenCredential 类。

在此示例中，我们使用客户端和租户标识符以及客户端密码来创建 ClientSecretCredential 实例。

// Custom credential class for servers and clients outside of Azure
TokenCredential credential = new ClientSecretCredential(
    tenantId: Environment.GetEnvironmentVariable("AAD_TENANT_ID")!,
    clientId: Environment.GetEnvironmentVariable("AAD_CLIENT_ID")!,
    clientSecret: Environment.GetEnvironmentVariable("AAD_CLIENT_SECRET")!,
    options: new TokenCredentialOptions()
);

在 Azure Active Directory (AD) 中注册应用程序时，可以获取客户端 ID、租户 ID 和客户端密码。有关如何注册 Azure AD 应用程序的详细信息，请参阅将应用程序注册到 Microsoft 标识平台。

使用 COSMOS_ENDPOINT 环境变量和 TokenCredential 对象作为参数，创建 CosmosClient 类的新实例。

// New instance of CosmosClient class using a connection string
using CosmosClient client = new(
    accountEndpoint: Environment.GetEnvironmentVariable("COSMOS_ENDPOINT")!,
    tokenCredential: credential
);

生成应用程序

在生成应用程序时，代码主要与四种类型的资源交互：

API for NoSQL 帐户，它是 Azure Cosmos DB 数据的唯一顶级命名空间。
数据库，它用于组织帐户中的容器。
容器，它包含数据库中的一组单个项。
项，它表示容器中的 JSON 文档。

以下图示显示了这些资源之间的关系。

Azure Cosmos DB 层次结构图（包括帐户、数据库、容器和项）。

每种类型的资源由一个或多个关联的 .NET 类表示。下面列出了最常见的类：

类	说明
`CosmosClient`	此类为 Azure Cosmos DB 服务提供客户端逻辑表示。此客户端对象用于对服务进行配置和执行请求。
`Database`	此类是对服务中可能存在或可能不存在的数据库的引用。在尝试访问该数据库或对其执行操作时，会在服务器端验证该数据库。
`Container`	此类是对服务中可能不存在的容器的引用。在尝试使用该容器时，会在服务器端对其进行验证。

以下指南介绍了如何使用上述每个类来生成应用程序。

指南	说明
创建数据库	创建数据库
创建容器	创建容器
读取项	点读特定项
查询项	查询多个项

请参阅

后续步骤

现在，你已连接到 API for NoSQL 帐户，请使用下一指南创建和管理数据库。

使用 .NET 在 Azure Cosmos DB for NoSQL 中创建数据库

通过