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

项目
06/02/2023

适用对象：表

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

先决条件

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

设置项目

创建 .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 帐户：

使用 API for Table 连接字符串进行连接

使用连接字符串连接

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

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

使用 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 Table 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 Table 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>"

使用连接字符串创建 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 数据的唯一顶级命名空间。
表格，其中包含你的帐户中的一组单独的项。
项目，它表示表中的单个项。

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

Diagram of the Azure Cosmos DB hierarchy including accounts, tables, and items.

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

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

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

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

请参阅

后续步骤

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

使用 .NET 在 Azure Cosmos DB for Table 中创建表