Azure.Data.Tables 12.8.3

Prefix Reserved
There is a newer version of this package available.
See the version list below for details.
dotnet add package Azure.Data.Tables --version 12.8.3                
NuGet\Install-Package Azure.Data.Tables -Version 12.8.3                
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Azure.Data.Tables" Version="12.8.3" />                
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add Azure.Data.Tables --version 12.8.3                
#r "nuget: Azure.Data.Tables, 12.8.3"                
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install Azure.Data.Tables as a Cake Addin
#addin nuget:?package=Azure.Data.Tables&version=12.8.3

// Install Azure.Data.Tables as a Cake Tool
#tool nuget:?package=Azure.Data.Tables&version=12.8.3                

Azure Tables client library for .NET

Azure Table storage is a service that stores large amounts of structured NoSQL data in the cloud, providing a key/attribute store with a schema-less design.

Azure Cosmos DB provides a Table API for applications that are written for Azure Table storage that need premium capabilities like:

  • Turnkey global distribution.
  • Dedicated throughput worldwide.
  • Single-digit millisecond latencies at the 99th percentile.
  • Guaranteed high availability.
  • Automatic secondary indexing.

The Azure Tables client library can seamlessly target either Azure Table storage or Azure Cosmos DB table service endpoints with no code changes.

Source code | Package (NuGet) | API reference documentation | Samples | Change Log

Getting started

Install the package

Install the Azure Tables client library for .NET with NuGet:

dotnet add package Azure.Data.Tables

Prerequisites

  • An Azure subscription.
  • An existing Azure storage account or Azure Cosmos DB database with Azure Table API specified.

If you need to create either of these, you can use the Azure CLI.

Creating a storage account

Create a storage account mystorageaccount in resource group MyResourceGroup in the subscription MySubscription in the West US region.

az storage account create -n mystorageaccount -g MyResourceGroup -l westus --subscription MySubscription
Creating a Cosmos DB

Create a Cosmos DB account MyCosmosDBDatabaseAccount in resource group MyResourceGroup in the subscription MySubscription and a table named MyTableName in the account.

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

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

Authenticate the Client

Learn more about options for authentication (including Connection Strings, Shared Key, Shared Key Signatures, and TokenCredentials) in our samples.

Key concepts

  • TableServiceClient - Client that provides methods to interact at the Table Service level such as creating, listing, and deleting tables
  • TableClient - Client that provides methods to interact at an table entity level such as creating, querying, and deleting entities within a table.
  • Table - Tables store data as collections of entities.
  • Entity - Entities are similar to rows. An entity has a primary key and a set of properties. A property is a name value pair, similar to a column.

Common uses of the Table service include:

  • Storing TBs of structured data capable of serving web scale applications
  • Storing datasets that don't require complex joins, foreign keys, or stored procedures and can be de-normalized for fast access
  • Quickly querying data using a clustered index
  • Accessing data using the OData protocol and LINQ filter expressions

Thread safety

We guarantee that all client instance methods are thread-safe and independent of each other (guideline). This ensures that the recommendation of reusing client instances is always safe, even across threads.

Additional concepts

Client options | Accessing the response | Long-running operations | Handling failures | Diagnostics | Mocking | Client lifetime

Examples

Create the Table service client

First, we need to construct a TableServiceClient.

// Construct a new "TableServiceClient using a TableSharedKeyCredential.

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

Create an Azure table

Next, we can create a new table.

// 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}.");

Get an Azure table

The set of existing Azure tables can be queries using an OData filter.

// 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);
}

Delete an Azure table

Individual tables can be deleted from the service.

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

Create the Table client

To interact with table entities, we must first construct a 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();

Add table entities

Let's define a new TableEntity so that we can add it to the table.

// 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")}.");

Using the TableClient we can now add our new entity to the table.

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

Query table entities

To inspect the set of existing table entities, we can query the table using an OData filter.

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.");

If you prefer LINQ style query expressions, we can query the table using that syntax as well. To demonstrate this syntax, you'll need a strongly typed model such as the one below:

// 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; }
}

Given this model class definition, here is how you'd write a query:

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

Delete table entities

If we no longer need our new table entity, it can be deleted.

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

Troubleshooting

When using the Azure tables library, errors returned by the service are reported using the same HTTP status codes returned for REST API requests.

For example, if you try to create a table that already exists, a 409 error is returned, indicating "Conflict".

// 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());
}

Setting up console logging

The simplest way to see the logs is to enable the console logging. To create an Azure SDK log listener that outputs messages to console use AzureEventSourceListener.CreateConsoleLogger method.

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

To learn more about other logging mechanisms see here.

Next steps

Get started with our Table samples.

Known Issues

A list of currently known issues relating to Cosmos DB table endpoints can be found here.

Contributing

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit cla.microsoft.com.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.

Product Compatible and additional computed target framework versions.
.NET net5.0 was computed.  net5.0-windows was computed.  net6.0 was computed.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 was computed.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 was computed.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed. 
.NET Core netcoreapp2.0 was computed.  netcoreapp2.1 was computed.  netcoreapp2.2 was computed.  netcoreapp3.0 was computed.  netcoreapp3.1 was computed. 
.NET Standard netstandard2.0 is compatible.  netstandard2.1 was computed. 
.NET Framework net461 was computed.  net462 was computed.  net463 was computed.  net47 was computed.  net471 was computed.  net472 was computed.  net48 was computed.  net481 was computed. 
MonoAndroid monoandroid was computed. 
MonoMac monomac was computed. 
MonoTouch monotouch was computed. 
Tizen tizen40 was computed.  tizen60 was computed. 
Xamarin.iOS xamarinios was computed. 
Xamarin.Mac xamarinmac was computed. 
Xamarin.TVOS xamarintvos was computed. 
Xamarin.WatchOS xamarinwatchos was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (238)

Showing the top 5 NuGet packages that depend on Azure.Data.Tables:

Package Downloads
Microsoft.Azure.DurableTask.AzureStorage

Azure Storage provider extension for the Durable Task Framework.

Microsoft.Orleans.Clustering.AzureStorage

Microsoft Orleans clustering provider backed by Azure Table Storage

Serilog.Sinks.AzureTableStorage

Serilog event sink that writes to Azure Table Storage over HTTP.

Microsoft.Azure.Kusto.Ingest

Programmatically ingest data into Kusto

TIKSN-Framework

This is a .NET Framework enhancement framework. Main features are Versioning, Finance, Currency, Foreign Exchange, Money, Pricing strategy, Telemetry, Composite Weighted Progress, Repository and Unity of Wok pattern implementation with Entity Framework Core, Network Connectivity Service and Triggering, Settings, Windows Registry configuration source, Azure Storage Repository, MongoDB Repository, NoDB Repository, Lingual and Regional Localization, Serialization, Rest Requester, Rest Repository, Dependency Injection, Composition Root Setup base classes.

GitHub repositories (38)

Showing the top 5 popular GitHub repositories that depend on Azure.Data.Tables:

Repository Stars
bitwarden/server
Bitwarden infrastructure/backend (API, database, Docker, etc).
dotnet/orleans
Cloud Native application framework for .NET
MassTransit/MassTransit
Distributed Application Framework for .NET
Azure/azure-sdk-for-net
This repository is for active development of the Azure SDK for .NET. For consumers of the SDK we recommend visiting our public developer docs at https://learn.microsoft.com/dotnet/azure/ or our versioned developer docs at https://azure.github.io/azure-sdk-for-net.
Azure/azure-powershell
Microsoft Azure PowerShell
Version Downloads Last updated
12.9.1 1,750,625 9/17/2024
12.9.0 1,614,117 7/22/2024
12.8.3 5,912,753 2/6/2024
12.8.2 3,491,886 11/13/2023
12.8.1 2,678,282 8/16/2023
12.8.0 13,503,714 2/8/2023
12.7.1 3,301,422 11/15/2022
12.7.0 422,097 11/9/2022
12.7.0-beta.1 29,371 9/6/2022
12.6.1 6,769,544 7/7/2022
12.6.0 883,198 6/8/2022
12.6.0-beta.1 7,418 5/10/2022
12.5.0 2,869,743 3/10/2022
12.4.0 1,871,237 1/13/2022
12.3.0 4,363,255 11/9/2021
12.2.1 326,252 10/14/2021
12.2.0 1,074,349 9/8/2021
12.2.0-beta.1 10,127 8/10/2021
12.1.0 649,763 7/7/2021
12.0.1 174,316 6/10/2021
12.0.0 42,189 6/9/2021
12.0.0-beta.8 161,178 5/11/2021
12.0.0-beta.7 39,823 4/6/2021
12.0.0-beta.6 104,868 3/9/2021
3.0.0-beta.5 146,026 1/12/2021
3.0.0-beta.4 8,933 12/10/2020
3.0.0-beta.3 62,308 11/12/2020
3.0.0-beta.2 20,620 10/6/2020
3.0.0-beta.1 17,582 9/8/2020