CosmosClient Class

Definition

Namespace:

Microsoft.Azure.Cosmos

Assembly:

Microsoft.Azure.Cosmos.Client.dll

Package:

Microsoft.Azure.Cosmos v3.39.0

Source:

CosmosClient.cs

Provides a client-side logical representation of the Azure Cosmos DB account. This client can be used to configure and execute requests in the Azure Cosmos DB database service.

CosmosClient is thread-safe. Its recommended to maintain a single instance of CosmosClient per lifetime of the application which enables efficient connection management and performance. Please refer to the performance guide.

public class CosmosClient : IDisposable

type CosmosClient = class
    interface IDisposable

Public Class CosmosClient
Implements IDisposable

Inheritance

Object

CosmosClient

Implements

IDisposable

Examples

This example create a CosmosClient, Database, and a Container. The CosmosClient is created with the connection string and configured to use "East US 2" region.

using Microsoft.Azure.Cosmos;

CosmosClient cosmosClient = new CosmosClient(
            "connection-string-from-portal", 
            new CosmosClientOptions()
            {
                ApplicationRegion = Regions.EastUS2,
            });

Database db = await cosmosClient.CreateDatabaseAsync("database-id");
Container container = await db.CreateContainerAsync("container-id");

// Dispose cosmosClient at application exit

This example creates a CosmosClient, Database, and a Container. The CosmosClient is created with the AccountEndpoint, AccountKey or ResourceToken and configured to use "East US 2" region.

using Microsoft.Azure.Cosmos;

CosmosClient cosmosClient = new CosmosClient(
            "account-endpoint-from-portal", 
            "account-key-from-portal", 
            new CosmosClientOptions()
            {
                ApplicationRegion = Regions.EastUS2,
            });

Database db = await cosmosClient.CreateDatabaseAsync("database-id");
Container container = await db.CreateContainerAsync("container-id");

// Dispose cosmosClient at application exit

This example creates a CosmosClient, Database, and a Container. The CosmosClient is created through builder pattern using CosmosClientBuilder.

using Microsoft.Azure.Cosmos;
using Microsoft.Azure.Cosmos.Fluent;

CosmosClient cosmosClient = new CosmosClientBuilder("connection-string-from-portal")
    .WithApplicationRegion("East US 2")
    .Build();

Database db = await cosmosClient.CreateDatabaseAsync("database-id")
Container container = await db.CreateContainerAsync("container-id");

// Dispose cosmosClient at application exit

Remarks

The returned not-initialized reference doesn't guarantee credentials or connectivity validations because creation doesn't make any network calls

Constructors

CosmosClient()	Create a new CosmosClient used for mock testing
CosmosClient(String, AzureKeyCredential, CosmosClientOptions)	Creates a new CosmosClient with the account endpoint URI string and AzureKeyCredential. AzureKeyCredential enables changing/updating master-key/ResourceToken while CosmosClient is still in use. CosmosClient is thread-safe. Its recommended to maintain a single instance of CosmosClient per lifetime of the application which enables efficient connection management and performance. Please refer to the performance guide.
CosmosClient(String, CosmosClientOptions)	Creates a new CosmosClient with the connection string. CosmosClient is thread-safe. Its recommended to maintain a single instance of CosmosClient per lifetime of the application which enables efficient connection management and performance. Please refer to the performance guide.
CosmosClient(String, String, CosmosClientOptions)	Creates a new CosmosClient with the account endpoint URI string and account key. CosmosClient is thread-safe. Its recommended to maintain a single instance of CosmosClient per lifetime of the application which enables efficient connection management and performance. Please refer to the performance guide.
CosmosClient(String, TokenCredential, CosmosClientOptions)	Creates a new CosmosClient with the account endpoint URI string and TokenCredential. CosmosClient is thread-safe. Its recommended to maintain a single instance of CosmosClient per lifetime of the application which enables efficient connection management and performance. Please refer to the performance guide.

Properties

ClientOptions	The CosmosClientOptions used initialize CosmosClient.
Endpoint	Gets the endpoint Uri for the Azure Cosmos DB service.
ResponseFactory	The response factory used to create CosmosClient response types.

Methods

CreateAndInitializeAsync(String, AzureKeyCredential, IReadOnlyList<ValueTuple<String,String>>, CosmosClientOptions, CancellationToken)	Creates a new CosmosClient with the account endpoint URI string and AzureKeyCredential. AzureKeyCredential enables changing/updating master-key/ResourceToken while CosmosClient is still in use. In addition to that it initializes the client with containers provided i.e The SDK warms up the caches and connections before the first call to the service is made. Use this to obtain lower latency while startup of your application. CosmosClient is thread-safe. Its recommended to maintain a single instance of CosmosClient per lifetime of the application which enables efficient connection management and performance. Please refer to the performance guide.
CreateAndInitializeAsync(String, IReadOnlyList<ValueTuple<String,String>>, CosmosClientOptions, CancellationToken)	Creates a new CosmosClient with the account endpoint URI string and TokenCredential. In addition to that it initializes the client with containers provided i.e The SDK warms up the caches and connections before the first call to the service is made. Use this to obtain lower latency while startup of your application. CosmosClient is thread-safe. Its recommended to maintain a single instance of CosmosClient per lifetime of the application which enables efficient connection management and performance. Please refer to the performance guide.
CreateAndInitializeAsync(String, String, IReadOnlyList<ValueTuple<String,String>>, CosmosClientOptions, CancellationToken)	Creates a new CosmosClient with the account endpoint URI string and TokenCredential. In addition to that it initializes the client with containers provided i.e The SDK warms up the caches and connections before the first call to the service is made. Use this to obtain lower latency while startup of your application. CosmosClient is thread-safe. Its recommended to maintain a single instance of CosmosClient per lifetime of the application which enables efficient connection management and performance. Please refer to the performance guide.
CreateAndInitializeAsync(String, TokenCredential, IReadOnlyList<ValueTuple<String,String>>, CosmosClientOptions, CancellationToken)	Creates a new CosmosClient with the account endpoint URI string and TokenCredential. In addition to that it initializes the client with containers provided i.e The SDK warms up the caches and connections before the first call to the service is made. Use this to obtain lower latency while startup of your application. CosmosClient is thread-safe. Its recommended to maintain a single instance of CosmosClient per lifetime of the application which enables efficient connection management and performance. Please refer to the performance guide.
CreateDatabaseAsync(String, Nullable<Int32>, RequestOptions, CancellationToken)	Sends a request for creating a database. A database manages users, permissions and a set of containers. Each Azure Cosmos DB Database Account is able to support multiple independent named databases, with the database being the logical container for data. Each Database consists of one or more containers, each of which in turn contain one or more documents. Since databases are an administrative resource, the Service Master Key will be required in order to access and successfully complete any action using the User APIs.
CreateDatabaseAsync(String, ThroughputProperties, RequestOptions, CancellationToken)	Sends a request for creating a database. A database manages users, permissions and a set of containers. Each Azure Cosmos DB Database Account is able to support multiple independent named databases, with the database being the logical container for data. Each Database consists of one or more containers, each of which in turn contain one or more documents. Since databases are an administrative resource, the Service Master Key will be required in order to access and successfully complete any action using the User APIs.
CreateDatabaseIfNotExistsAsync(String, Nullable<Int32>, RequestOptions, CancellationToken)	Check if a database exists, and if it doesn't, create it. Only the database id is used to verify if there is an existing database. Other database properties such as throughput are not validated and can be different then the passed properties. A database manages users, permissions and a set of containers. Each Azure Cosmos DB Database Account is able to support multiple independent named databases, with the database being the logical container for data. Each Database consists of one or more containers, each of which in turn contain one or more documents. Since databases are an administrative resource, the Service Master Key will be required in order to access and successfully complete any action using the User APIs.
CreateDatabaseIfNotExistsAsync(String, ThroughputProperties, RequestOptions, CancellationToken)	Check if a database exists, and if it doesn't, create it. Only the database id is used to verify if there is an existing database. Other database properties such as throughput are not validated and can be different then the passed properties. A database manages users, permissions and a set of containers. Each Azure Cosmos DB Database Account is able to support multiple independent named databases, with the database being the logical container for data. Each Database consists of one or more containers, each of which in turn contain one or more documents. Since databases are an administrative resource, the Service Master Key will be required in order to access and successfully complete any action using the User APIs.
CreateDatabaseStreamAsync(DatabaseProperties, Nullable<Int32>, RequestOptions, CancellationToken)	Send a request for creating a database. A database manages users, permissions and a set of containers. Each Azure Cosmos DB Database Account is able to support multiple independent named databases, with the database being the logical container for data. Each Database consists of one or more containers, each of which in turn contain one or more documents. Since databases are an administrative resource, the Service Master Key will be required in order to access and successfully complete any action using the User APIs.
Dispose()	Dispose of cosmos client
Dispose(Boolean)	Dispose of cosmos client
GetContainer(String, String)	Returns a proxy reference to a container.
GetDatabase(String)	Returns a proxy reference to a database.
GetDatabaseQueryIterator<T>(QueryDefinition, String, QueryRequestOptions)	This method creates a query for databases under an Cosmos DB Account using a SQL statement with parameterized values. It returns a FeedIterator. For more information on preparing SQL statements with parameterized values, please see QueryDefinition.
GetDatabaseQueryIterator<T>(String, String, QueryRequestOptions)	This method creates a query for databases under an Cosmos DB Account using a SQL statement. It returns a FeedIterator.
GetDatabaseQueryStreamIterator(QueryDefinition, String, QueryRequestOptions)	This method creates a query for databases under an Cosmos DB Account using a SQL statement with parameterized values. It returns a FeedIterator. For more information on preparing SQL statements with parameterized values, please see QueryDefinition.
GetDatabaseQueryStreamIterator(String, String, QueryRequestOptions)	This method creates a query for databases under an Cosmos DB Account using a SQL statement. It returns a FeedIterator.
ReadAccountAsync()	Reads the AccountProperties for the Azure Cosmos DB account.

See also

• CosmosClientBuilder
• CosmosClientOptions