通过 .NET 使用适用于表的 Azure Cosmos DB 入门

适用对象:

本文介绍如何使用 .NET SDK 连接到 Azure Cosmos DB for Table。 连接后,可以对表和项目执行操作。

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

先决条件

设置项目

创建 .NET 控制台应用程序

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

dotnet new console

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

dotnet add package Azure.Data.Tables

使用 dotnet build 命令生成项目。

dotnet build

连接到 Azure Cosmos DB for Table

若要连接到 Azure Cosmos DB 的 API for Table,请创建 TableServiceClient 类的实例。 此类是对表执行所有操作的起点。 有两种主要方法可以使用 TableServiceClient 类连接到 API for Table 帐户:

使用连接字符串连接

TableServiceClient 最常见的构造函数只有一个参数:

参数 示例值 说明
connectionString COSMOS_CONNECTION_STRING 环境变量 API for Table 帐户的连接字符串

检索帐户连接字符串

  1. 使用 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
    )
    
  2. 使用 az-cosmosdb-keys-list 命令,从帐户的连接字符串列表中查找主连接字符串。

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

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

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

使用连接字符串创建 TableServiceClient

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

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

生成应用程序

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

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

  • 表格,其中包含你的帐户中的一组单独的项。

  • 项目,它表示表中的单个项。

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

Azure Cosmos DB 层次结构示意图,其中包括帐户、表和项。

顶部是显示 Azure Cosmos DB 帐户的层次结构示意图。 该帐户有两个子级表节点。 其中一个表节点包括两个子项。

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

说明
TableServiceClient 此客户端类为 Azure Cosmos DB 服务提供客户端逻辑表示。 此客户端对象用于对服务进行配置和执行请求。
TableClient 此客户端类是对服务中可能存在或不存在的表的引用。 当尝试访问表或对其执行操作时,在服务器端验证该表。
ITableEntity 此接口是在表中创建或从表中查询的任何项的基接口。 此接口包括 API for Table 中项的所有必需属性。
TableEntity 此类是作为键值对字典的 ITableEntity 接口的通用实现。

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

指南 说明
创建表 创建表
创建项 创建项
读取项 读取项

请参阅

后续步骤

现在,你已连接到 API for Table 帐户,请使用下一指南来创建和管理表。