Getting started

Install the Microsoft.Azure.CosmosRepository package, register it with DI, and create your first item.

The quickest way to get started using the IEvangelist.Azure.CosmosRepository package is to call the AddCosmosRepository extension method on IServiceCollection. This single call registers everything the SDK needs and exposes the IRepository<TItem> interface to your application.

Install the package

dotnet add package IEvangelist.Azure.CosmosRepository

For ASP.NET Core integrations (health checks, change-feed hosted services) also install:

dotnet add package IEvangelist.Azure.CosmosRepository.AspNetCore

Quick start

1. Create an Azure Cosmos DB SQL resource.

2. Obtain the resource connection string from the Keys blade. Use the connection string (compound key + endpoint URL), not the raw key.

3. Register the repository:

   using Microsoft.Azure.CosmosRepository;
   
   var builder = WebApplication.CreateBuilder(args);
   
   builder.Services.AddCosmosRepository();

   The optional setupAction lets you configure the RepositoryOptions object directly:

   builder.Services.AddCosmosRepository(options =>
   {
       options.CosmosConnectionString = "<connection string>";
       options.ContainerId = "data-store";
       options.DatabaseId = "samples";
   });

4. Define an item type. Models must inherit from Item (or another base such as EtagItem, TimeStampedItem, TimeToLiveItem, or FullItem):

   using Microsoft.Azure.CosmosRepository;
   
   public class Person : Item
   {
       public string FirstName { get; set; } = null!;
       public string LastName { get; set; } = null!;
   }

5. Inject IRepository<TItem>:

   public class Consumer
   {
       readonly IRepository<Person> _repository;
   
       public Consumer(IRepository<Person> repository) =>
           _repository = repository;
   
       public Task<Person> CreateAsync(Person person) =>
           _repository.CreateAsync(person).AsTask();
   }

6. Perform CRUD operations on _repository. Done.

Configuration

When OptimizeBandwidth is true (the default), the SDK reduces networking and CPU load by not sending the resource back over the network or serializing it on the client for create / update / patch / delete. See Enable content response on write.

There is much debate over how to structure databases and containers. Many developers with relational background prefer a container per item type; others lean on Cosmos’s flexibility. By default, ContainerPerItemType is false and all items live in the same container. When set to true, each distinct subclass of Item gets its own container named after the class (or the [Container] attribute name).

Well-known configuration keys

The library is wired to the .NET configuration system. The following keys map onto RepositoryOptions instances. Double underscores work for environment variables; colons work for appsettings.json.

Example appsettings.json

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft": "Warning",
      "Microsoft.Hosting.Lifetime": "Information"
    }
  },
  "AllowedHosts": "*",
  "RepositoryOptions": {
    "CosmosConnectionString": "<Your-CosmosDB-ConnectionString>",
    "AccountEndpoint": "<Your-CosmosDB-URI>",
    "DatabaseId": "<Your-CosmosDB-DatabaseName>",
    "ContainerId": "<Your-CosmosDB-ContainerName>",
    "OptimizeBandwidth": true,
    "ContainerPerItemType": true,
    "AllowBulkExecution": true,
    "SerializationOptions": {
      "IgnoreNullValues": true,
      "PropertyNamingPolicy": "CamelCase"
    }
  }
}

For more, see the JSON configuration provider docs.

Example appsettings.json for Azure Functions

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft": "Warning",
      "Microsoft.Hosting.Lifetime": "Information"
    }
  },
  "AllowedHosts": "*",
  "Values": {
    "RepositoryOptions:CosmosConnectionString": "<Your-CosmosDB-ConnectionString>",
    "RepositoryOptions:AccountEndpoint": "<Your-CosmosDB-URI>",
    "RepositoryOptions:DatabaseId": "<Your-CosmosDB-DatabaseName>",
    "RepositoryOptions:ContainerId": "<Your-CosmosDB-ContainerName>",
    "RepositoryOptions:OptimizeBandwidth": true,
    "RepositoryOptions:ContainerPerItemType": true,
    "RepositoryOptions:AllowBulkExecution": true,
    "RepositoryOptions:SerializationOptions:IgnoreNullValues": true,
    "RepositoryOptions:SerializationOptions:PropertyNamingPolicy": "CamelCase"
  }
}

Where to next?

• Authentication — connection strings vs. Microsoft Entra identities.
• Partitioning — choose the right partitioning strategy.
• Container configuration — fluent and attribute-based container setup.