Get started with Azure Cosmos DB for Table using .NET


This article shows you how to connect to Azure Cosmos DB for Table using the .NET SDK. Once connected, you can perform operations on tables and items.

Package (NuGet) | Samples | API reference | Library source code | Give Feedback |


Set up your project

Create the .NET console application

Create a new .NET application by using the dotnet new command with the console template.

dotnet new console

Import the Azure.Data.Tables NuGet package using the dotnet add package command.

dotnet add package Azure.Data.Tables

Build the project with the dotnet build command.

dotnet build

Connect to Azure Cosmos DB for Table

To connect to the API for Table of Azure Cosmos DB, create an instance of the TableServiceClient class. This class is the starting point to perform all operations against tables. There are two primary ways to connect to an API for Table account using the TableServiceClient class:

Connect with a connection string

The most common constructor for TableServiceClient has a single parameter:

Parameter Example value Description
connectionString COSMOS_CONNECTION_STRING environment variable Connection string to the API for Table account

Retrieve your account connection string

  1. Use the az cosmosdb list command to retrieve the name of the first Azure Cosmos DB account in your resource group and store it in the accountName shell variable.

    # Retrieve most recently created account name
        az cosmosdb list \
            --resource-group $resourceGroupName \
            --query "[0].name" \
            --output tsv
  2. Find the PRIMARY CONNECTION STRING from the list of connection strings for the account with the az-cosmosdb-keys-list command.

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

To use the PRIMARY CONNECTION STRING value within your .NET code, persist it to a new environment variable on the local machine running the application.


Create TableServiceClient with connection string

Create a new instance of the TableServiceClient class with the COSMOS_CONNECTION_STRING environment variable as the only parameter.

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

Build your application

As you build your application, your code will primarily interact with four types of resources:

  • The API for Table account, which is the unique top-level namespace for your Azure Cosmos DB data.

  • Tables, which contain a set of individual items in your account.

  • Items, which represent an individual item in your table.

The following diagram shows the relationship between these resources.

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

Hierarchical diagram showing an Azure Cosmos DB account at the top. The account has two child table nodes. One of the table nodes includes two child items.

Each type of resource is represented by one or more associated .NET classes or interfaces. Here's a list of the most common types:

Class Description
TableServiceClient This client class provides a client-side logical representation for the Azure Cosmos DB service. The client object is used to configure and execute requests against the service.
TableClient This client class is a reference to a table that may, or may not, exist in the service yet. The table is validated server-side when you attempt to access it or perform an operation against it.
ITableEntity This interface is the base interface for any items that are created in the table or queried from the table. This interface includes all required properties for items in the API for Table.
TableEntity This class is a generic implementation of the ITableEntity interface as a dictionary of key-value pairs.

The following guides show you how to use each of these classes to build your application.

Guide Description
Create a table Create tables
Create an item Create items
Read an item Read items

See also

Next steps

Now that you've connected to an API for Table account, use the next guide to create and manage tables.