Get started with Azure Cosmos DB for Table using .NET

APPLIES TO: Table

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 |

Prerequisites

• An Azure account with an active subscription. Create an account for free.
• Azure Cosmos DB for Table account. Create a API for Table account.
• .NET 6.0 or later
• Azure Command-Line Interface (CLI) or Azure PowerShell

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 API for Table connection string

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

Azure CLI

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
   accountName=$(
       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"
   

PowerShell

1. Use the Get-AzCosmosDBAccount cmdlet to retrieve the name of the first Azure Cosmos DB account in your resource group and store it in the ACCOUNT_NAME shell variable.

   # Retrieve most recently created account name
   $parameters = @{
       ResourceGroupName = $RESOURCE_GROUP_NAME
   }
   $ACCOUNT_NAME = (
       Get-AzCosmosDBAccount @parameters |
           Select-Object -Property Name -First 1
   ).Name
   

2. Find the PRIMARY CONNECTION STRING from the list of connection strings for the account with the 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    
   

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.

Windows

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

Linux / macOS

export COSMOS_CONNECTION_STRING="<cosmos-account-PRIMARY-CONNECTION-STRING>"

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.

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

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

Next steps

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

Create a table in Azure Cosmos DB for Table using .NET