使用 .NET 进行 NoSQL 的 Azure Cosmos DB 入门

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

Package （NuGet） | API 参考 | Library 源代码 | 提供反馈

先决条件

• 具有活动订阅的Azure帐户。 创建试用版订阅。
• Azure Cosmos DB for NoSQL 帐户。 为 NoSQL 帐户创建 API。
• .NET 6.0 或更高版本
• Azure Command-Line接口（CLI）或Azure PowerShell

设置您的项目

使用带有 dotnet new 模板的 命令创建新的.NET应用程序。

dotnet new console

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

dotnet add package Microsoft.Azure.Cosmos

此外，请添加Newtonsoft.Json NuGet 包，这是 Microsoft.Azure.Cosmos 包所必需的。

dotnet add package Newtonsoft.Json

使用 dotnet build 命令构建项目。

dotnet build

连接到 Azure Cosmos DB 用于 NoSQL

若要连接到 Azure Cosmos DB 的 NoSQL API，请创建 CosmosClient 类的实例。 此类是针对数据库执行所有操作的起点。

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

导入Azure.Identity

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

使用 命令导入 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();

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

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

生成应用程序

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

• NoSQL 帐户的 API，它是 Azure Cosmos DB 数据的唯一顶级命名空间。

• 数据库，它用于组织帐户中的容器。

• 容器，它包含数据库中的一组单个项。

• 项，它表示容器中的 JSON 文档。

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

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

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

以下指南演示如何使用这些类来构建应用程序。

另请参阅

• Package （NuGet）
• API 参考
• 代码库源代码
• Give Feedback

后续步骤