Get started with Azure Cosmos DB for Table using .NET

Article
09/14/2024

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.

Prerequisites

An Azure account with an active subscription. Create a trial subscription.
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

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
)

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"

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

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
Linux / macOS

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

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.

Diagram of the Azure Cosmos DB hierarchy including accounts, tables, and 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

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