IEvangelist.Azure.CosmosRepository 2.1.2

Azure Cosmos DB Repository .NET SDK

This package wraps the NuGet: Microsoft.Azure.Cosmos package, exposing a simple dependency-injection enabled IRepository<T> interface.

The repository is responsible for all of the create, read, update, and delete (CRUD) operations on objects where T : Item. The Item type adds several properties, one which is a globally unique identifier defined as:

[JsonProperty("id")]
public string Id { get; set; } = Guid.NewGuid().ToString();

Additionally, a type property exists which indicates the subclass name (this is used for filtering implicitly on your behalf):

[JsonProperty("type")]
public string Type { get; set; }

Finally, a partition key property is used internally to manage partitioning on your behalf. This can optionally be overridden on an item per item basis.

📣 Azure Cosmos DB - Official Blog

Getting started

1. Create an Azure Cosmos DB SQL resource.

2. Obtain the resource connection string from the Keys blade, be sure to get a connection string and not the key - these are different. The connection string is a compound key and endpoint URL.

3. Call AddCosmosRepository:

   public void ConfigureServices(IServiceCollection services)
   {
       services.AddCosmosRepository();
   }
   

   The optional setupAction allows consumers to manually configure the RepositoryOptions object:

   public void ConfigureServices(IServiceCollection services)
   {
       services.AddCosmosRepository(
           options =>
           {
               options.CosmosConnectionString = "< connection string >";
               options.ContainerId = "data-store";
               options.DatabaseId = "samples";
           });
   }
   

4. Define your object graph, objects must inherit Item, for example:

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

5. Ask for an instance of IRepository<TItem>, in this case the TItem is Person:

   using Microsoft.Azure.CosmosRepository;
   
   public class Consumer
   {
       readonly IRepository<Person> _repository;
   
       public Consumer(IRepository<Person> repository) =>
           _repository = repository;
   
       // Use the repo...
   }
   

6. Perform any of the operations on the _repository instance, create Person records, update them, read them, or delete.

7. Enjoy!

Configuration

When OptimizeBandwidth is true (its default value), the repository SDK reduces networking and CPU load by not sending the resource back over the network and serializing it to the client. This is specific to writes, such as create, update, and delete. For more information, see Optimizing bandwidth in the Azure Cosmos DB .NET SDK.

There is much debate with how to structure your database and corresponding containers. Many developers with relational database design experience might prefer to have a single container per item type, while others understand that Azure Cosmos DB will handle things correctly regardless. By default, the ContainerPerItemType option is false and all items are persisted into the same container. However, when it is true, each distinct subclass of Item gets its own container named by the class itself.

Example appsettings.json

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

Samples

Visit the Microsoft.Azure.CosmosRepository.Samples directory for samples on how to use the library with:

• Azure Functions
• Services
• Controllers (web apps)