Introduction to CosmosDB utilities
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
They offer an implementation of
ICRUDRepositorywhose 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.
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
MvcControlsToolkit.Business.DocumentDBprojection 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.
MvcControlsToolkit.Business.DocumentDBovercomes 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.
MvcControlsToolkit.Business.DocumentDBovercomes 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.DocumentDButilities 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.
All updates performed by the repository class are executed in parallel by calling the async
SaveChangesmethod 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.
MvcControlsToolkit.Business.DocumentDBoffers shorthands for common operations.