How to Integrate Microsoft Azure Cosmos DB API in .NET Applications

Integrate Azure Cosmos DB SDK for .NET

• Install the required NuGet package for Cosmos DB. Use the following command in your terminal or package manager console to install the package:

  ```shell
  Install-Package Microsoft.Azure.Cosmos
  ```

 

• Ensure your project is set up to use .NET Core or .NET Framework, as the SDK supports both environments.

Create the Cosmos Client

• Create an instance of the `CosmosClient` class by providing the endpoint URI and primary key you get from the Azure Portal. This client instance is used to interact with Cosmos DB.

  ```csharp
  using Microsoft.Azure.Cosmos;

  string endpointUri = "";
  string primaryKey = "";

  CosmosClient cosmosClient = new CosmosClient(endpointUri, primaryKey);
  ```

 

• Configure the client for better performance by adjusting parameters such as connection mode and request timeout if necessary.

Create a Database and Container

• Using the `CosmosClient`, create or get a reference to a database. You can specify options such as throughput if you want a dedicated throughput setting for that database.

  ```csharp
  Database database = await cosmosClient.CreateDatabaseIfNotExistsAsync("SampleDatabase");
  ```

 

• Within the database, create a container or get an existing one. This is where your items (documents) will reside. Specify a partition key to optimize performance.

  ```csharp
  Container container = await database.CreateContainerIfNotExistsAsync("SampleContainer", "/partitionKeyPath");
  ```

Perform CRUD Operations

• Insert items into the container by creating C# class objects that represent your data and using the `CreateItemAsync` method.

  ```csharp
  public class SampleItem
  {
  public string Id { get; set; }
  public string Name { get; set; }
  public string PartitionKeyPath { get; set; }
  }

  SampleItem newItem = new SampleItem { Id = "1", Name = "Sample Name", PartitionKeyPath = "SamplePartition" };
  await container.CreateItemAsync(newItem, new PartitionKey(newItem.PartitionKeyPath));
  ```

 

• Read items by querying the container using LINQ or SQL-like syntax. Make sure your queries efficiently use the partition key.

  ```csharp
  var sqlQueryText = "SELECT * FROM c WHERE c.PartitionKeyPath = @PartitionKey";
  QueryDefinition queryDefinition = new QueryDefinition(sqlQueryText).WithParameter("@PartitionKey", "SamplePartition");
  FeedIterator queryResultSetIterator = container.GetItemQueryIterator(queryDefinition);

  List items = new List();

  while (queryResultSetIterator.HasMoreResults)
  {
  FeedResponse currentResultSet = await queryResultSetIterator.ReadNextAsync();
  foreach (SampleItem item in currentResultSet)
  {
  items.Add(item);
  }
  }
  ```

Handle Exceptions and Optimize Performance

• Implement exception handling for operations using try-catch blocks to handle specific exceptions like `CosmosException` for error handling and retries.

  ```csharp
  try
  {
  ItemResponse response = await container.ReadItemAsync("1", new PartitionKey("SamplePartition"));
  SampleItem readItem = response.Resource;
  }
  catch (CosmosException ex)
  {
  Console.WriteLine($"Item read failed with status code {ex.StatusCode} and message: {ex.Message}");
  }
  ```

 

• Enable indexing and caching strategies to enhance the query performance. Adjust index policies based on query patterns to optimize storage and performance.

Best Practices and Considerations

• Use the latest SDK version to benefit from performance improvements and new features.

 

• Utilize appropriate indexing strategies and partition key choices to improve operation efficiency.

 

• Monitor the application and Cosmos DB usage to adjust throughput and indexing as needed for cost efficiency and performance optimization.