你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

适用于 .NET 的 Azure 表客户端库 - 版本 12.8.1

  • 项目

Azure 表存储是一项服务，用于在云中存储大量结构化 NoSQL 数据，提供具有无架构设计的密钥/属性存储。

Azure Cosmos DB 为需要以下高级功能的 Azure 表存储编写的应用程序提供表 API：

  • 统包式全局分发。
  • 全球范围内专用的吞吐量。
  • 99% 的情况下低至个位数的毫秒级延迟。
  • 保证高可用性。
  • 自动编制辅助索引。

Azure 表客户端库可以无缝面向 Azure 表存储或 Azure Cosmos DB 表服务终结点，无需更改代码。

源代码 | 包 (NuGet) | API 参考文档 | 样品 | 更改日志

入门

安装包

使用 NuGet 安装适用于 .NET 的 Azure 表客户端库：

dotnet add package Azure.Data.Tables

先决条件

  • 一个 Azure 订阅。
  • 指定了 Azure 表 API 的现有 Azure 存储帐户或 Azure Cosmos DB 数据库。

如果需要创建其中任一项，可以使用 Azure CLI。

创建存储帐户

在美国西部区域的订阅MySubscription的资源组MyResourceGroup中创建存储帐户mystorageaccount。

az storage account create -n mystorageaccount -g MyResourceGroup -l westus --subscription MySubscription

创建 Cosmos DB

在订阅MySubscription的资源组MyResourceGroup中创建 Cosmos DB 帐户MyCosmosDBDatabaseAccount，并在帐户中创建名为 MyTableName 的表。

az cosmosdb create --name MyCosmosDBDatabaseAccount --capabilities EnableTable --resource-group MyResourceGroup --subscription MySubscription

az cosmosdb table create --name MyTableName --resource-group MyResourceGroup --account-name MyCosmosDBDatabaseAccount

对客户端进行身份验证

在我们的示例中，详细了解身份验证 选项 (包括连接字符串、共享密钥、共享密钥签名和 TokenCredentials) 。

关键概念

  • TableServiceClient - 提供在表服务级别进行交互的方法（例如创建、列出和删除表）的客户端
  • TableClient - 提供在表实体级别进行交互的方法（例如在表中创建、查询和删除实体）的客户端。
  • Table - 表将数据存储为实体集合。
  • Entity - 实体类似于行。 一个实体具有一个主键和一组属性。 属性是名称值对，类似于列。

表服务的常见用途包括：

  • 存储 TB 量级的结构化数据，能够为 Web 规模应用程序提供服务
  • 存储不需要复杂联接、外键或存储过程且可进行规范化以便快速访问的数据集
  • 使用聚集索引快速查询数据
  • 使用 OData 协议和 LINQ 筛选器表达式访问数据

线程安全

我们保证所有客户端实例方法都是线程安全的，并且相互独立， (准则) 。 这可确保重用客户端实例的建议始终是安全的，即使跨线程也是如此。

其他概念

客户端选项 | 访问响应 | 长时间运行的操作 | 处理失败 | 诊断 | 嘲笑 | 客户端生存期

示例

创建表服务客户端

首先，我们需要构造 TableServiceClient。

// Construct a new "TableServiceClient using a TableSharedKeyCredential.

var serviceClient = new TableServiceClient(
    new Uri(storageUri),
    new TableSharedKeyCredential(accountName, storageAccountKey));

创建 Azure 表

接下来，我们可以创建新表。

// Create a new table. The TableItem class stores properties of the created table.
TableItem table = serviceClient.CreateTableIfNotExists(tableName);
Console.WriteLine($"The created table's name is {table.Name}.");

获取 Azure 表

现有 Azure 表集可以是使用 OData 筛选器的查询。

// Use the <see cref="TableServiceClient"> to query the service. Passing in OData filter strings is optional.

Pageable<TableItem> queryTableResults = serviceClient.Query(filter: $"TableName eq '{tableName}'");

Console.WriteLine("The following are the names of the tables in the query results:");

// Iterate the <see cref="Pageable"> in order to access queried tables.

foreach (TableItem table in queryTableResults)
{
    Console.WriteLine(table.Name);
}

删除 Azure 表

可以从服务中删除单个表。

// Deletes the table made previously.
serviceClient.DeleteTable(tableName);

创建表客户端

若要与表实体交互，必须先构造 TableClient。

// Construct a new <see cref="TableClient" /> using a <see cref="TableSharedKeyCredential" />.
var tableClient = new TableClient(
    new Uri(storageUri),
    tableName,
    new TableSharedKeyCredential(accountName, storageAccountKey));

// Create the table in the service.
tableClient.Create();

添加表实体

让我们定义一个新的 TableEntity ，以便我们可以将其添加到表中。

// Make a dictionary entity by defining a <see cref="TableEntity">.
var tableEntity = new TableEntity(partitionKey, rowKey)
{
    { "Product", "Marker Set" },
    { "Price", 5.00 },
    { "Quantity", 21 }
};

Console.WriteLine($"{tableEntity.RowKey}: {tableEntity["Product"]} costs ${tableEntity.GetDouble("Price")}.");

使用 现在， TableClient 我们可以将新实体添加到表中。

// Add the newly created entity.
tableClient.AddEntity(tableEntity);

查询表实体

若要检查现有表实体集，可以使用 OData 筛选器查询表。

Pageable<TableEntity> queryResultsFilter = tableClient.Query<TableEntity>(filter: $"PartitionKey eq '{partitionKey}'");

// Iterate the <see cref="Pageable"> to access all queried entities.
foreach (TableEntity qEntity in queryResultsFilter)
{
    Console.WriteLine($"{qEntity.GetString("Product")}: {qEntity.GetDouble("Price")}");
}

Console.WriteLine($"The query returned {queryResultsFilter.Count()} entities.");

如果你更喜欢 LINQ 样式查询表达式，我们也可以使用该语法查询表。 若要演示此语法，需要一个强类型模型，如下所示：

// Define a strongly typed entity by implementing the ITableEntity interface.
public class OfficeSupplyEntity : ITableEntity
{
    public string Product { get; set; }
    public double Price { get; set; }
    public int Quantity { get; set; }
    public string PartitionKey { get; set; }
    public string RowKey { get; set; }
    public DateTimeOffset? Timestamp { get; set; }
    public ETag ETag { get; set; }
}

鉴于此模型类定义，下面是编写查询的方式：

double priceCutOff = 6.00;
Pageable<OfficeSupplyEntity> queryResultsLINQ = tableClient.Query<OfficeSupplyEntity>(ent => ent.Price >= priceCutOff);

删除表实体

如果不再需要新的表实体，则可以将其删除。

// Delete the entity given the partition and row key.
tableClient.DeleteEntity(partitionKey, rowKey);

疑难解答

使用 Azure 表库时，将使用为 REST API 请求返回的相同 HTTP 状态代码报告服务返回的错误。

例如，如果尝试创建已存在的表，则会返回一个 409 错误，指示“冲突”。

// Construct a new TableClient using a connection string.

var client = new TableClient(
    connectionString,
    tableName);

// Create the table if it doesn't already exist.

client.CreateIfNotExists();

// Now attempt to create the same table unconditionally.

try
{
    client.Create();
}
catch (RequestFailedException ex) when (ex.Status == (int)HttpStatusCode.Conflict)
{
    Console.WriteLine(ex.ToString());
}

设置控制台日志记录

查看日志的最简单方法是启用控制台日志记录。 若要创建将消息输出到控制台的 Azure SDK 日志侦听器，请使用 AzureEventSourceListener.CreateConsoleLogger 方法。

// Setup a listener to monitor logged events.
using AzureEventSourceListener listener = AzureEventSourceListener.CreateConsoleLogger();

若要详细了解其他日志记录机制，请参阅 此处。

后续步骤

表 示例入门。

已知问题

可 在此处找到与 Cosmos DB 表终结点相关的当前已知问题列表。

贡献

本项目欢迎贡献和建议。 大多数贡献要求你同意贡献者许可协议 (CLA)，并声明你有权（并且确实有权）授予我们使用你的贡献的权利。 有关详细信息，请访问 cla.microsoft.com。

此项目采用了 Microsoft 开放源代码行为准则。 有关详细信息，请参阅行为准则常见问题解答，或如果有任何其他问题或意见，请与 联系。

曝光数