CosmosDB utilities may be added to your project by referencing the MvcControlsToolkit.Business.DocumentDB package. They are completely indpendent from the remainder of the toolkit, so they may be used also in projects that do not use the Mvc Controls Toolkit.

CosmosDB utilities offer a CosmosDB/DocumentDB based implementation of ICRUDRepository, and further helper methods to build LinQ queries for CosmosDB/DocumentDB.

A good tutoria on CosmosDB utilities may be found in this issue of the DNCMagazine.

The utilities package is based on two classes, DefaultDocumentDBConnection that represents a connection with a CosmosDB/DocumentDB database, and the repository class DocumentDBCRUDRepository that contains the ICRUDRepository implementation and the LinQ helper methods.

Typically, you should inherit your repository class from DocumentDBCRUDRepository. Both your inherited repositories and the DefaultDocumentDBConnection are then created in the dependency injection section of your Asp.net Core project.

Below the advantages of using MvcControlsToolkit.Business.DocumentDB utilities:

1. They offer an implementation of ICRUDRepository whose high level methods "boost" your project development, and allow an easy connection of CosmosDB/DocumentDB with the Mvc Controls Toolkit standard controllers and tag helpers.
2. They offer an easy way to split your project into a business layer and a presentation layer. The business layer contains data models with all their CosmosDB/DocumentDB specific data annotations that declare how to serialize/deserialize them. The presentation layer, instead, operates on DTOs/ViewModels that contain just some of the information defined in the data models. DTOs/ViewModels are database agnostic and do not depend on how data are stored (with CosmosDB or with another kind of database). Data are moved from the data models to the DTOs/ViewModels and vice-versa thanks to the the MvcControlsToolkit.Business.DocumentDB projection utilities. The developer may define all details of the projection operations with simple and short LinQ expressions. Most of properties mappings are inferred automatically with a same-name convention that supports both property flattening and unflattening.
3. MvcControlsToolkit.Business.DocumentDB overcomes some CosmosDB/DocumentDB limitations on the allowed selection operations (select operations are not allowed in nested collections) by splitting the projection on a DTO/ViewModel into a query projection and an in-memory projection. The query projection creates a CosmosDB/DocumentDB query that extracts from the database just the information needed by the DTO/ViewModel, while the in-memory projection takes care of properly projecting the retrieved data into the DTOs/ViewModels. The above operation is completely automatic and fast, since it is based on a compilation performed at program start of the projection operations defined by the developer.
4. MvcControlsToolkit.Business.DocumentDB overcomes the impossibility for CosmosDB/DocumentDB of performing partial updates of an existing documents. Namely, for efficiency reasons CosmosDB/DocumentDB allows just the complete replacement of a document with a different definition, and it doesn't allow the modification of just some document properties. MvcControlsToolkit.Business.DocumentDB utilities performs partial updates by automatically retrieving the document to modify and projecting all modifications contained in a DTO/ViewModel on it. Also nested collections are updated coherently with the modifications contained in DTO/ViewModels trees.
5. All updates performed by the repository class are executed in parallel by calling the async SaveChanges method for a better performance. If some operation fails a DocumentsUpdateException<M> is thrown that contains all exceptions thrown by the failed operations and infos on both all failed and succeeded operations. All failed operations may be retried by passing this exception to the Task RetryChanges(DocumentsUpdateException<M> exception) method.
6. MvcControlsToolkit.Business.DocumentDB offers shorthands for common operations.