Loading of IoC Container Module¶

Method Load() designed to register app components and must not contain any other logic due to the fact it is posed in inconsistent state. To register components into Load() an instance of the IContainerBuilder interface is passed.

Common structure of IoC-container module may look like this:

public class MyAppContainerModule : IContainerModule
{
    public void Load(IContainerBuilder builder)
    {
        // Registering components...
    }
}

Configuration IoC Container on Startup¶

To configure the IoC container in an ASP.NET Core application you need to create an instance of the IServiceProvider interface and return one from the ConfigureServices() method. For features that require substantial setup there are Add[Component] extension methods on IServiceCollection. User defined modules are added by the AddContainerModule() extension method. The BuildProvider() extension method builds and returns an instance of the IServiceProvider interface.

 public class Startup
 {
     public IServiceProvider ConfigureServices(IServiceCollection services)
     {
         services.AddContainerModule(new MyAppContainerModule());

         return services.BuildProvider();
     }

     // ...
 }

Register Types¶

Component instances registered with method RegisterType() created by reflection and class constructor with the most number of parameters retrievable from container.

// Способ 1
builder.RegisterType<MyComponent>().As<IMyService>();

// Способ 2
builder.RegisterType(typeof(MyComponent)).As(typeof(IMyService));

Register Generic Types¶

If component presented as generic-type to register one should use method RegisterGeneric(). As in case of regular types, instances of generic-components created by reflection and class constructor with the most number of parameters retrievable from container.

 public interface IRepository<T> { /* ... */ }

 public class MyRepository<T> : IRepository<T> { /* ... */ }

 // ...

 builder.RegisterGeneric(typeof(MyRepository<>)).As(typeof(IRepository<>));

Register Instances¶

In some cases you may want to register an instance component created beforehand. For example, if creation of the component requires a lot of resources or is a technically complicated task. To register such components one should use method RegisterInstance().

builder.RegisterInstance(new MyComponent()).As<IMyService>();

Register Factory Functions¶

Component may be registered by a factory function or lambda-expression. This way suits well when creation of component instance should be accompanied by preliminary calculations or is impossible to be created by class constructor. Such components should be registered via method RegisterFactory().

builder.RegisterFactory(r => new MyComponent()).As<IMyService>();

Input parameter r represents context of IoC-container, which can be used to get all dependencies required to create component. This approach is the most fitting rather than obtaining dependencies via closure because this ensures a unified way of managing the life cycle of all dependencies.

builder.RegisterFactory(r => new A(r.Resolve<B>()));

Resolving Direct Dependency¶

In most cases a direct dependency is defined between components. Next example component A depends on component B. In the very moment when app requests component A, first IoC-container creates component B then pass newly created component into constructor of component A. If component B depends on other components they will be created beforehand.

 public class A
 {
     private readonly B _b;

     public A(B b)
     {
         _b = b;
     }

     public void SomeMethod()
     {
         _b.DoSomething();
     }
 }

Resolving Enumeration of Dependencies¶

Dependencies of an enumerable type provide multiple implementations of the same service (interface). Next example component A is dependant on all components of type B. All components of type B will be created and passed to component A via constructor as an instance of IEnumerable<T>.

 public class A
 {
     private readonly IEnumerable<B> _list;

     public A(IEnumerable<B> list)
     {
         _list = list;
     }

     public void SomeMethod()
     {
         foreach (var b in _list)
         {
             b.DoSomething();
         }
     }
 }

Resolving with Delayed Instantiation¶

A lazy dependency is not instantiated until its first use. This appears where the dependency is infrequently used, or expensive to construct. To take advantage of this, use a Lazy<T> in the constructor. Next example shows component A depends on component B but gets that dependency via lazy initialization while requesting a property Lazy<T>.Value for the first time.

 public class A
 {
     private readonly Lazy<B> _b;

     public A(Lazy<B> b)
     {
         _b = b;
     }

     public void SomeMethod()
     {
         _b.Value.DoSomething();
     }
 }

Resolving Factory Functions¶

Using an auto-generated factory is applicable in case if it is required to create more than one instance of dependency or decision to create dependency can be done in runtime. Next example shows that component A depends on component B however it gets this dependency right before its usage.

 public class A
 {
     private readonly Func<B> _b;

     public A(Func<B> b)
     {
         _b = b;
     }

     public void SomeMethod()
     {
         var b = _b();

         b.DoSomething();
     }
 }

Resolving Parameterized Factory Functions¶

Using an auto-generated factory is also applicable in case if there are strongly-typed parameters in the resolution function. Next example shows that component A depends on component B but gets this dependency right before its usage having passed to the factory function parameter values required to create component B.

 public class A
 {
     private readonly Func<int, B> _b;

     public A(Func<int, B> b)
     {
         _b = b;
     }

     public void SomeMethod()
     {
         var b = _b(42);

         b.DoSomething();
     }
 }


 public class B
 {
     public B(int v) { /* ... */ }

     public void DoSomething() { /* ... */ }
 }

If factory function has duplicate types in the input parameter list one should define its delegate.

 public class A
 {
     private readonly FactoryB _b;

     public A(FactoryB b)
     {
         _b = b;
     }

     public void SomeMethod()
     {
         var b = _b(42, 43);

         b.DoSomething();
     }
 }


 public class B
 {
     public B(int v1, int v2) { /* ... */ }

     public void DoSomething() { /* ... */ }
 }


 public delegate B FactoryB(int v1, int v2);

Getting Direct Access to IoC Container¶

In case if it is required to make a universal factory of components which type is knowable in runtime, for example as in generic-type case, or working component logic depends on configuration of IoC-container, one can obtain a direct access to container using IContainerResolver. Next example shows component A acquires access to IoC-container because component type becomes known in runtime.

 public class A
 {
     private readonly IContainerResolver _resolver;

     public A(IContainerResolver resolver)
     {
         _resolver = resolver;
     }

     public void SomeMethod<T>()
     {
         var b = _resolver.Resolve<B<T>>();

         b.DoSomething();
     }
 }


 public class B<T>
 {
     public void DoSomething() { /* ... */ }
 }

// Way 1
IMyService myService = resolver.Resolve<IMyService>();

// Way 2
object myService = resolver.Resolve(typeof(IMyService));

// Way 1

IMyService myService;

if (resolver.TryResolve<IMyService>(out myService))
{
    // ...
}

// Way 2

object myService;

if (resolver.TryResolve(typeof(IMyService), out myService))
{
    // ...
}

// Way 1

IMyService myService = resolver.ResolveOptional<IMyService>();

if (myService != null)
{
    // ...
}

// Way 2

object myService = resolver.ResolveOptional(typeof(IMyService));

if (myService != null)
{
    // ...
}

// Way 1

if (resolver.IsRegistered<IMyService>())
{
    // ...
}

// Way 2

if (resolver.IsRegistered(typeof(IMyService)))
{
    // ...
}

Defining Component Lifetime¶

IoC-container performs automatic lifetime components control thus their lifetime is defined during registration. All registered components are created each time they are received by default.

// Component will be created at each retrieving (by default)
builder.RegisterType<MyComponent>().As<IMyService>().InstancePerDependency();

// Component will be created for the time of HTTP-request execution
builder.RegisterType<MyComponent>().As<IMyService>().InstancePerLifetimeScope();

// Component will be created once for the time of the app execution
builder.RegisterType<MyComponent>().As<IMyService>().SingleInstance();

In the end of lifetime cycle IoC-container disposes component instance which makes it no longer available for further usage. This is the reason that definition of the lifetime must take into account their dependency. For example, component SingleInstance() is not able to directly be dependant on component InstancePerDependency().

If component’s lifetime is more than lifetime of the component it depends on to retrieve dependency one should use factory function. Next example shows component A depends on component B but retrieves its dependency right before usage due to the fact that the lifetime of component A is longer than lifetime of component B.

 builder.RegisterType<A>().AsSelf().SingleInstance();
 builder.RegisterType<B>().AsSelf().InstancePerDependency();

 // ...

 public class A
 {
     private readonly Func<B> _b;

     public A(Func<B> b)
     {
         _b = b;
     }

     public void SomeMethod()
     {
         var b = _b();

         b.DoSomething();
     }
 }

Components Disposing¶

App may get resources which temporary created for the time of execution. For example a connection to a database, file stream an so on. .NET model offers IDisposable interface which brings all resources to be disposed.

In the end of component lifetime IoC-container checks whether it implements IDisposable interface and if it does then it calls method Dispose(). Afterwards the current component instance becomes unavailable for further usage.

To deny automatic disposal one should directly call method ExternallyOwned(). This may be frequently used when the component lifetime is owned by external component.

public class DisposableComponent : IDisposable { /* ... */ }

// ...

builder.RegisterType<DisposableComponent>().ExternallyOwned();

NonSerializedAttribute¶

The NonSerializedAttribute excludes a field or property from serialization. By default public fields and properties are included to serialization. Standard .NET serialization attribute NonSerializedAttribute allows to exclude specific properties from a resultant JSON. Usually it is useful to exclude properties which can be calculated from other fields.

 public class Person
 {
     public string FirstName { get; set; }

     public string LastName { get; set; }

     public DateTime Birthday { get; set; }

     [NonSerialized]
     public int Age { get; set; }
 }

SerializerVisibleAttribute¶

The SerializerVisibleAttribute includes a field or property to serialization. By default non-public fields and properties as well as properties with non-public setters (or without them) are excluded from serialization. This attribute is the opposite NonSerializedAttribute.

 public class Document
 {
     [SerializerVisible]
     public object _id { get; internal set; }

     [SerializerVisible]
     public DocumentHeader _header { get; internal set; }
 }

SerializerPropertyNameAttribute¶

The SerializerPropertyNameAttribute sets specified property name while serialization. By default, the JSON property will have the same name as the .NET property. This attribute allows the name to be customized.

 public class Person
 {
     [SerializerPropertyName("forename")]
     public string FirstName { get; set; }

     [SerializerPropertyName("surname")]
     public string LastName { get; set; }
 }

Asynchronous Handling¶

Request handlers are asynchronous by default so you can use async/await keywords.

public class MyHttpService : IHttpService
{
    public void Load(IHttpServiceBuilder builder)
    {
        builder.Get["/resource1"] = OnResource1;
        builder.Get["/resource2"] = OnResource2;
    }

    private async Task<object> OnResource1(IHttpRequest request)
    {
        // Do something asynchronously
        return await Task.FromResult<object>("Resource1");
    }

    private async Task<object> OnResource2(IHttpRequest request)
    {
        // Do something asynchronously
        return await Task.FromResult<object>("Resource2");
    }
}

Declaring Service Path¶

Usually modules combine some common functionality which are available on the same base path. So you can define a module path and each route will be subordinate to the path of the module. This saves you from having to repeat the common parts of the route patterns and also to nicely group your routes together based on their relationship.

 public class MyHttpService : IHttpService
 {
     public void Load(IHttpServiceBuilder builder)
     {
         builder.ServicePath = "/base/path/to";
         builder.Get["/resource1"] = OnResource1;
         builder.Get["/resource2"] = OnResource2;
     }

     // ...
 }

Method¶

The Method is the HTTP method that is used to access the resource. You can handle GET, POST, PUT, PATCH and DELETE methods. The IHttpServiceBuilder interface contains a definition for each of these methods.

Pattern¶

The Pattern declares the application-relative URL that the route answers to.

• Literal segment, /some, requires an exact match.
• Capture segment, /{name}, captures whatever is passed into the given segment.
• Capture optional segment, /{name?}, by adding ? at the end of the segment name the segment can be made optional.
• Capture optional/default segment, /{name?unnamed}, by adding a value after ? we can turn an optional segment into a segment with a default value.
• RegEx segment, /(?<id>[\d]{1,2}), using Named Capture Grouped Regular Expressions, you can get a little more control out of the segment pattern.
• Greedy segment, /{name*}, by adding * to the end of the segment name, the pattern will match any value from the current forward slash onward.
• Multiple captures segment, /{file}.{extension} or /{file}.ext, a segment containing a mix of captures and literals.

Pattern segments can be combined, in any order, to create a complex Pattern for a route.

Action¶

A route Action is the behavior which is invoked when a request is matched to a route. It is represented as a delegate of type Func<IHttpRequest,Task<object>> where the input argument is an information about request (IHttpRequest) and the result is a task (Task<object>) to retrieving response. The response can be any model.

Parameters and Query¶

To retrieve information from a URL you can use properties Parameters and Query. Both return dynamic object with information from different parts of the URL. The Parameters contains values of named segments of the path while the Query contains values of the query string.

Next example shows how to extract values from a URL which looks like on previous image.

builder.Get["/{segment1}/{segment2}/{segment3}"] = async request =>
{
    string segment1 = request.Parameters.segment1; // segment1 == "path"
    string segment2 = request.Parameters.segment2; // segment2 == "to"
    string segment3 = request.Parameters.segment3; // segment3 == "resource"

    string key1 = request.Query.key1; // key1 == "value1"
    string key2 = request.Query.key2; // key2 == "value2"

    // ...
};

Form and Content¶

Such methods as POST, PUT and PATCH can contains the body. Depending on the Content-Type header the message body can be parsed as an object. In this case the Form property returns dynamic object. For instance the request body will be considered as an object if the Content-Type equals application/json (see Media Types).

// curl -X POST -H 'Content-Type: application/json' \
// -d'{"Title":"Title1","Content":"Content1"}' \
// http://www.example.com:80/articles

builder.Post["/articles"] = async request =>
{
    string title = request.Form.Title; // title == "Title1"
    string content = request.Form.Content; // content == "Content1"

    // ...
};

If you have a strongly typed model you can deserialize it from the request body. For example if the Content-Type equals application/json the deserialization can be performed using IJsonObjectSerializer. The Content property allows you to get a Stream object representing the incoming HTTP body. Also important to note the Content can be used for a custom handling of the request body.

 public class ArticlesHttpService : IHttpService
 {
     private readonly IJsonObjectSerializer _serializer;

     public ArticlesHttpService(IJsonObjectSerializer serializer)
     {
         _serializer = serializer;
     }

     public void Load(IHttpServiceBuilder builder)
     {
         // curl -X POST -H 'Content-Type: application/json' \
         // -d'{"Title":"Title1","Content":"Content1"}' \
         // http://www.example.com:80/articles

         builder.Post["/articles"] = async request =>
         {
             var article = _serializer.Deserialize<Article>(request.Content);

             // ...
         };
     }
 }


 public class Article
 {
     public string Title { get; set; }
     public string Content { get; set; }
 }

Files¶

In more complex cases a request can contains one or few files which are available via the Files property. The Files returns an enumerable items of type IHttpRequestFile and each of them allows to get the file name and the file data stream.

 builder.Post["/albums/{id}"] = async request =>
 {
     foreach (IHttpRequestFile photo in request.Files)
     {
         // Do something
     }

     // ...
 };

Result Converters¶

The response can be any model and the final result will be determined by the ResultConverter which defines conversion rules from the source model to the IHttpResponse instance. If a module does not set the ResultConverter then the default conversion rules are used. They are represented in the DefaultHttpResultConverter class:

• IHttpResponse will be returned as is;
• null will be interpreted as HttpResponse.Ok;
• int will be interpreted as a HTTP status code;
• string will be interpreted as TextHttpResponse;
• byte[], Stream and Func<Stream> will be interpreted as StreamHttpResponse;
• Exception will be interpreted as 500 Internal Server Error with the exception message;
• other objects will be interpreted as JsonHttpResponse.

Next converter wraps a result to the JSON object with a single property Result.

 builder.ResultConverter = result =>
 {
     return (result is IHttpResponse)
         ? (IHttpResponse)result
         : new JsonHttpResponse(new { Result = result });
 };

 builder.Get["/some"] = request =>
 {
     return Task.FromResult<object>(123); // {"Result":123 }
 };

OnBefore interceptor¶

The OnBefore interceptor enables you to intercept the request before it is passed to the appropriate route handler - Action. This gives you a couple of possibilities such as modifying parts of the request or even prematurely aborting the request by returning a response that will be sent back to the caller.

builder.OnBefore = async (IHttpRequest request) =>
{
    // Do something asynchronously and return null or a result object
};

Since the interceptor will be invoked for all routes in the module, there is no need to define a pattern to match. The parameter that is passed into the interceptor is an instance of the current IHttpRequest. A return value of null means that no action is taken by the interceptor and that the request should proceed to be processed by the matching route. However, if the interceptor returns some result of its own, the route will never be processed by the route and the response will be sent back to the client.

OnAfter interceptor¶

The OnAfter gets an instance of the current IHttpRequest and a result from previous stage. While an OnBefore interceptor is called before the route handler an OnAfter interceptor is called when the route has already been handled and a response has been generated. So here you can modify or replace the result.

builder.OnAfter = async (IHttpRequest request, object result) =>
{
    // Do something asynchronously and return a modified result
};

OnError interceptor¶

The OnError interceptor enables you to execute code whenever an exception occurs in any of the module routes that are being invoked. It gives you access to the current IHttpRequest and the exception that took place. So here you can handle an exception and build an error result.

builder.OnError = async (IHttpRequest request, Exception exception) =>
{
    // Do something asynchronously and return an error result
};

Global interceptors¶

The application pipelines enable you to perform tasks before and after routes are executed, and in the event of an error in any of the routes in the application. They behave the same way as the module pipelines (see the statechart above) but they are executed for all invoked routes, not just for the ones that are the module of the route that is being invoked.

To define the application level HTTP handler you need to implement the IHttpGlobalHandler interface and register the implementation in IoC Container.

Configuring Document Storage¶

1. Install MongoDB

2. Install InfinniPlatform.DocumentStorage.MongoDB package:

dotnet add package InfinniPlatform.DocumentStorage.MongoDB \
    -s https://www.myget.org/F/infinniplatform

3. Call AddMongoDocumentStorage() in ConfigureServices():

 using System;

 using InfinniPlatform.AspNetCore;

 using Microsoft.Extensions.DependencyInjection;

 public class Startup
 {
     public IServiceProvider ConfigureServices(IServiceCollection services)
     {
         services.AddMongoDocumentStorage();

         // ...

         return services.BuildProvider();
     }

     // ...
 }

Next using of the document storage differs depending on context: typed or dynamic.

Typed Context¶

When a document can be presented as a normal .NET class then better use the typed context. In this case you will have all the power static code analysis.

1. Create MyDocument.cs and define a descendant of the Document class:

 using InfinniPlatform.DocumentStorage;

 class MyDocument : Document
 {
     public string Property1 { get; set; }

     // ...
 }

2. Request the IDocumentStorageFactory instance in the constructor:

 using InfinniPlatform.DocumentStorage;

 class MyComponent
 {
     private readonly IDocumentStorage<MyDocument> _storage;

     public MyComponent(IDocumentStorageFactory factory)
     {
         _storage = factory.GetStorage<MyDocument>();
     }

     // ...
 }

3. To access to the documents use IDocumentStorage<TDocument>:

var document = new MyDocument { _id = 1, Property1 = "Hello!" };

// Create
_storage.InsertOne(document);

// Read
var document = _storage.Find(i => i._id.Equals(1)).First();

// Update
_storage.UpdateOne(u => u.Set(i => i.Property1, "Hello, World!"), i => i._id.Equals(1));

// Delete
_storage.DeleteOne(i => i._id.Equals(1));

Dynamic Context¶

When a document can not be presented as a normal .NET class because semi-structured data, you can use the dynamic context. In this case you you will have more flexibility but there is a chance to make mistake and find it only at runtime.

1. Use DynamicDocument to declare dynamic objects

2. Request the IDocumentStorageFactory instance in the constructor:

 using InfinniPlatform.DocumentStorage;

 class MyComponent
 {
     private readonly IDocumentStorage _storage;

     public MyComponent(IDocumentStorageFactory factory)
     {
         _storage = factory.GetStorage("MyDocument");
     }

     // ...
 }

3. To access to the documents use IDocumentStorage:

var document = new DynamicDocument { { "_id", 1 }, { "Property1", "Hello!" } };

// Create
_storage.InsertOne(document);

// Read
var document = _storage.Find(f => f.Eq("_id", 1)).First();

// Update
_storage.UpdateOne(u => u.Set("Property1", "Hello, World!"), f => f.Eq("_id", 1));

// Delete
_storage.DeleteOne(f => f.Eq("_id", 1));

Intercept Typed Documents¶

When a document is presented as a normal .NET class and working with it goes through the IDocumentStorage<TDocument>, to define the interceptor for this document implement the IDocumentStorageInterceptor<TDocument> interface:

class MyDocumentStorageInterceptor : DocumentStorageInterceptor<MyDocument>
{
    public override void OnAfterInsertOne(DocumentInsertOneCommand<MyDocument> command,
                                          DocumentStorageWriteResult<object> result,
                                          Exception exception)
    {
        // Handling the invocations IDocumentStorage<MyDocument>.InsertOne()...
    }

    // ...
}

After that register the interceptor in IoC-container:

builder.RegisterType<MyDocumentStorageInterceptor>()
       .As<IDocumentStorageInterceptor>()
       .SingleInstance();

Intercept Dynamic Documents¶

When a document is presented as the DynamicDocument class and working with it goes through the IDocumentStorage, to define the interceptor for this document implement the IDocumentStorageInterceptor interface:

class MyDocumentStorageInterceptor : DocumentStorageInterceptor
{
    public override void OnAfterInsertOne(DocumentInsertOneCommand command,
                                          DocumentStorageWriteResult<object> result,
                                          Exception exception)
    {
        // Handling the invocations IDocumentStorage<MyDocument>.InsertOne()...
    }

    // ...
}

After that register the interceptor in IoC-container:

builder.RegisterType<MyDocumentStorageInterceptor>()
       .As<IDocumentStorageInterceptor>()
       .SingleInstance();

Default Indexes¶

The IDocumentStorage<TDocument> interface implementation works with descendants of the Document class which defines two mandatory fields: _id and _header, respectively, the unique identifier and the system information of the document. By default the _id is Guid but it is possible to use any other type. The _header is described using DocumentHeader class.

The DocumentHeader class contains system information which is used by an implementation of the storage to organize and control access to the documents. For example, the _tenant field helps to organize multitenancy and that field is used upon each query execution as an additional filter. Thus each document contains at least two indexes:

• _id - for primary key
• _header._tenant and _header._deleted - for multitenancy

Additional Indexes¶

To define additional indexes you must create an instance of the DocumentMetadata class and set the Indexes property. Next example defines index by UserName field.

var userNameIndex = new DocumentIndex
                    {
                        Key = new Dictionary<string, DocumentIndexKeyType>
                              {
                                  { "UserName", DocumentIndexKeyType.Asc }
                              }
                    };

var userStoreMetadata = new DocumentMetadata
                        {
                            Type = "UserStore",
                            Indexes = new[] { userNameIndex }
                        };

After that you must get IDocumentStorageManager and invoke the CreateStorageAsync() method:

IDocumentStorageManager_ storageManager;

// ...

storageManager.CreateStorageAsync(userStoreMetadata);

Storage Provider¶

The IDocumentStorage<TDocument> and IDocumentStorage are used to access documents of the storage but besides data access they do additional logic. For example, providing interception mechanism and organizing multitenancy. And this logic can be a barrier to realize some system procedures such as data migration. To direct access to the storage without additional logic (interception, multitenancy and etc.), use IDocumentStorageProvider<TDocument> or IDocumentStorageProvider. To get them, use IDocumentStorageProviderFactory.

DocumentTypeAttribute¶

The DocumentTypeAttribute attribute defines the storage name of the specified document type. By default without its attribute the storage name equals an appropriate type name. It is not always reasonable especially you use existing database or other naming convention. Also this attribute eliminates possibility of accidental renaming the storage during renaming the document class name.

 [DocumentType("orders")]
 class Order : Document
 {
     // ...
 }

DocumentIgnoreAttribute¶

The DocumentIgnoreAttribute attribute forces the storage to ignore the specified property of the document class. Properties are marked with this attribute will not be stored in a database. It is most applicable for calculated properties, that is properties which values can be calculated based on values of other properties; or when data can not or should not be serialized to be stored in a database.

 class Order : Document
 {
     public double Count { get; set; }
     public double Price { get; set; }

     [DocumentIgnore]
     public double Total => Count * Price;

     // ...
 }

DocumentPropertyNameAttribute¶

The DocumentPropertyNameAttribute attribute forces the storage to use other name for the specified property of the document class. By default without its attribute field names in a database equal appropriate property names. It is not always reasonable especially you use existing database or other naming convention. Also this attribute eliminates possibility of accidental renaming the field during renaming the document property name.

 class Order : Document
 {
     [DocumentPropertyName("count")]
     public double Count { get; set; }

     [DocumentPropertyName("price")]
     public double Price { get; set; }

     // ...
 }

Specifications for Typed Documents¶

Suppose we need to organize a storage of some articles and we know each article has date, author, title, text and can be in two states: draft and published.

class Article : Document
{
    public DateTime Date { get; set; }
    public string Author { get; set; }
    public string Title { get; set; }
    public string Text { get; set; }
    public ArticleState State { get; set; }

    // ...
}

enum ArticleState
{
    Draft = 0,
    Published = 1
}

And in the most of the cases we need to fetch published articles for the specified period:

 class GetPublishedArticles : Specification<Article>
 {
     private readonly DateTime _start;
     private readonly DateTime _end;

     public GetPublishedArticles(DateTime start, DateTime end)
     {
         _start = start;
         _end = end;
     }

     public override Expression<Func<Article, bool>> Filter =>
         a => a.Date >= _start && a.Date <= _end
              && a.State == ArticleState.Published;
 }

After that it will be right to create appropriate repository of the articles:

 interface IArticleRepository
 {
     IEnumerable<Article> GetArticles(ISpecification<Article> specification);

     // ...
 }

 class ArticleRepository : IArticleRepository
 {
     private readonly IDocumentStorage<Article> _storage;

     public ArticleRepository(IDocumentStorageFactory factory)
     {
         _storage = factory.GetStorage<Article>();
     }

     public IEnumerable<Article> GetArticles(ISpecification<Article> specification)
     {
         return _storage.Find(specification.Filter).ToList();
     }

     // ...
 }

And use it to fetch articles:

IArticleRepository repository;
DateTime start, end;

// ...

ISpecification<Article> specification = new GetPublishedArticles(start, end);
IEnumerable<Article> publishedArticles = repository.GetArticles(specification);

Specifications for Dynamic Documents¶

Let’s consider the same example as above but in dynamic context. Declare specification:

 class GetPublishedArticles : Specification
 {
     private readonly DateTime _start;
     private readonly DateTime _end;

     public GetPublishedArticles(DateTime start, DateTime end)
     {
         _start = start;
         _end = end;
     }

     public override Func<IDocumentFilterBuilder, object> Filter =>
         a => a.And(a.Gte("Date", _start), a.Lte("Date", _end),
                    a.Eq("State", ArticleState.Published));
 }

Declare the repository of the articles:

 interface IArticleRepository
 {
     IEnumerable<DynamicDocument> GetArticles(ISpecification specification);

     // ...
 }

 class ArticleRepository : IArticleRepository
 {
     private readonly IDocumentStorage _storage;

     public ArticleRepository(IDocumentStorageFactory factory)
     {
         _storage = factory.GetStorage("Article");
     }

     public IEnumerable<DynamicDocument> GetArticles(ISpecification specification)
     {
         return _storage.Find(specification.Filter).ToList();
     }

     // ...
 }

And use it to fetch articles:

IArticleRepository repository;
DateTime start, end;

// ...

ISpecification specification = new GetPublishedArticles(start, end);
IEnumerable<DynamicDocument> publishedArticles = repository.GetArticles(specification);

Composing Specifications¶

The specification classes Specification<TDocument> and Specification override !, & and | operators and implement, respectively, negation, conjunction and disjunction. Thus you can compose existing specifications instead of creating new.

// Not
var notSpecification = !specification;

// And
var andSpecification = specification1 & specification2 & specification3;

// Or
var orSpecification = specification1 | specification2 | specification3;

Two Phase Commit¶

Lack of transactions is known problem and you can solve it using the Two Phase Commit, for example, in a way which is offered by MondoDB. But there is no silver bullet and if you really need ACID transactions you should use appropriate database.

Unit of Work¶

Yet another solution of transactions absence can be the Unit of Work pattern which is presented as the IUnitOfWork interface. You can accumulate changes in the memory of the web server and then commit them. Until the commit, all changes of the documents remain in the memory and nobody see them. Thus if during the changes an exception appears, the documents will not be changed. To some degree it works like transactions but if there is some functional relation between the changes, the unit of work can be unsuitable solution.

To create instance of the IUnitOfWork use the IUnitOfWorkFactory:

IUnitOfWorkFactory factory;

// ...

IUnitOfWork unitOfWork = factory.Create();

The IUnitOfWork implements the IDisposable interface so it is better to use using operator:

IUnitOfWorkFactory factory;

// ...

using (IUnitOfWork unitOfWork = factory.Create())
{
    // Inserts, updates, deletes...

    unitOfWork.Commit();
}

After all changes are applied, invoke Commit() or CommitAsync().

Now let’s consider full example of using the IUnitOfWork:

IUnitOfWorkFactory factory;

// ...

using (IUnitOfWork unitOfWork = factory.Create())
{
    unitOfWork.InsertOne(...);
    unitOfWork.InsertMany(...);

    unitOfWork.UpdateOne(...);
    unitOfWork.UpdateMany(...);

    unitOfWork.DeleteOne(...);
    unitOfWork.DeleteMany(...);

    unitOfWork.Commit();
}

Configuring Document HTTP Service¶

1. Install InfinniPlatform.DocumentStorage.HttpService package:

dotnet add package InfinniPlatform.DocumentStorage.HttpService \
    -s https://www.myget.org/F/infinniplatform/

2. Call AddDocumentStorageHttpService() in ConfigureServices():

 using System;

 using InfinniPlatform.AspNetCore;

 using Microsoft.Extensions.DependencyInjection;

 public class Startup
 {
     public IServiceProvider ConfigureServices(IServiceCollection services)
     {
         services.AddDocumentStorageHttpService();

         // ...

         return services.BuildProvider();
     }

     // ...
 }

3. Register in IoC-container the document HTTP service:

builder.RegisterDocumentHttpService<MyDocument>();

4. Run application and browse to http://localhost:5000/documents/MyDocument/

Interception of Document HTTP Service¶

The document HTTP service provides default behavior which may be a little different than what you want. In this case you can use interceptor of the document HTTP service. Implement IDocumentStorageInterceptor<TDocument> (typed context) or IDocumentStorageInterceptor (dynamic context) and register the implementation in IoC-container.

Document HTTP Service API¶

GET /documents/(string: documentType)/(string: id)¶

Returns the document of the specified type and with given identifier.

Parameters:	documentType (string) – The document type name. id (string) – The document unique identifier.
Response Headers:
	Content-Type – application/json
Status Codes:	200 OK – OK 400 Bad Request – Validation Error 500 Internal Server Error – Internal Server Error

GET /documents/(string: documentType)/¶

Returns documents of the specified type.

Parameters:	documentType (string) – The document type name.
Query Parameters:
	search (string) – Optional. The text for full text search. filter (string) – Optional. The filter query. select (string) – Optional. The select query. order (string) – Optional. The order query. count (boolean) – Optional. By default - false. The flag whether to return the number of documents. skip (int) – Optional. By default - 0. The number of documents to skip before returning the remaining elements. take (int) – Optional. By default - 10, maximum - 1000. The number of documents to return.
Response Headers:
	Content-Type – application/json
Status Codes:	200 OK – OK 400 Bad Request – Validation Error 500 Internal Server Error – Internal Server Error

POST /documents/(string: documentType)/¶

Creates or updates specified document.

Parameters:	documentType (string) – The document type name.
Form Parameters:
	body – The document and optionally the document attachments (files).
Request Headers:
	Content-Type – application/json Content-Type – multipart/form-data Content-Type – application/x-www-form-urlencoded
Response Headers:
	Content-Type – application/json
Status Codes:	200 OK – OK 400 Bad Request – Validation Error 500 Internal Server Error – Internal Server Error

DELETE /documents/(string: documentType)/(string: id)¶

Deletes the document of the specified type and with given identifier.

Parameters:	documentType (string) – The document type name. id (string) – The document unique identifier.
Response Headers:
	Content-Type – application/json
Status Codes:	200 OK – OK 400 Bad Request – Validation Error 500 Internal Server Error – Internal Server Error

DELETE /documents/(string: documentType)/¶

Deletes documents of the specified type.

Parameters:	documentType (string) – The document type name.
Query Parameters:
	filter (string) – Optional. The filter query.
Response Headers:
	Content-Type – application/json
Status Codes:	200 OK – OK 400 Bad Request – Validation Error 500 Internal Server Error – Internal Server Error

func(args)