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 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
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"
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.
$env: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
Next steps
Now that you've connected to an API for Table account, use the next guide to create and manage tables.