PipelineNet

Pipeline net is a micro framework that helps you implement the pipeline and chain of responsibility patterns. With PipelineNet you can easily separate business logic and extend your application. Pipelines can be used to execute a series of middleware sequentially without expecting a return, while chains of responsibilities do the same thing but expecting a return. And you can do it all asynchronously too.

You can obtain the package from this project through nuget:

Install-Package PipelineNet

Or if you're using dotnet CLI:

dotnet add package PipelineNet

<!-- START doctoc generated TOC please keep comment here to allow auto update --> <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->

Table of Contents generated with DocToc

• Simple example
• Pipeline vs Chain of responsibility
• Middleware
• Pipelines
• Chains of responsibility
• Cancellation tokens
• Middleware resolver
  • ServiceProvider implementation
  • Unity implementation
• Migrate from PipelineNet 0.10 to 0.11
  • Changes to the Finally method
  • Changes to MiddlewareResolverResult.IsDisposable
• License

<!-- END doctoc generated TOC please keep comment here to allow auto update -->

Simple example

Just to check how easy it is to use PipelineNet, here is an example of exception handling using a chain of responsibility:

First we define some middleware:

public class OutOfMemoryExceptionHandler : IMiddleware<Exception, bool>
{
    public bool Run(Exception parameter, Func<Exception, bool> next)
    {
        if (parameter is OutOfMemoryException)
        {
            // Handle somehow
            return true;
        }

        return next(parameter);
    }
}

public class ArgumentExceptionHandler : IMiddleware<Exception, bool>
{
    public bool Run(Exception parameter, Func<Exception, bool> next)
    {
        if (parameter is ArgumentException)
        {
            // Handle somehow
            return true;
        }

        return next(parameter);
    }
}

Now we create a chain of responsibility with the middleware:

var exceptionHandlersChain = new ResponsibilityChain<Exception, bool>(new ActivatorMiddlewareResolver())
    .Chain<OutOfMemoryExceptionHandler>() // The order of middleware being chained matters
    .Chain<ArgumentExceptionHandler>();

Now your instance of ResponsibilityChain can be executed as many times as you want:

// The following line will execute only the OutOfMemoryExceptionHandler, which is the first middleware.
var result = exceptionHandlersChain.Execute(new OutOfMemoryException()); // Result will be true

// This one will execute the OutOfMemoryExceptionHandler first, and then the ArgumentExceptionHandler gets executed.
result = exceptionHandlersChain.Execute(new ArgumentExceptionHandler()); // Result will be true

// If no middleware matches returns a value, the default of the return type is returned, which in the case of 'bool' is false.
result = exceptionHandlersChain.Execute(new InvalidOperationException()); // Result will be false

You can even define a fallback that will be executed after your entire chain:

var exceptionHandlersChain = new ResponsibilityChain<Exception, bool>(new ActivatorMiddlewareResolver())
    .Chain<OutOfMemoryExceptionHandler>() // The order of middleware being chained matters
    .Chain<ArgumentExceptionHandler>()
    .Finally<ExceptionHandlerFallback>();

public class ExceptionHandlerFallback : IFinally<Exception, bool>
{
    public bool Finally(Exception parameter)
    {
        // Do something
        return true;
    }
}

Now if the same line gets executed:

var result = exceptionHandlersChain.Execute(new InvalidOperationException()); // Result will be true

The result will be true because of the type used in the Finally method.

You can also choose to throw an exception in the finally instead of returning a value:

var exceptionHandlersChain = new ResponsibilityChain<Exception, bool>(new ActivatorMiddlewareResolver())
    .Chain<OutOfMemoryExceptionHandler>()
    .Chain<ArgumentExceptionHandler>()
    .Finally<ThrowInvalidOperationException>();

public class ThrowInvalidOperationException : IFinally<Exception, bool>
{
    public bool Finally(Exception parameter)
    {
        throw new InvalidOperationException("End of the chain of responsibility reached. No middleware matches returned a value.");
    }
}

Now if the end of the chain was reached and no middleware matches returned a value, the InvalidOperationException will be thrown.

Pipeline vs Chain of responsibility

Here is the difference between those two in PipelineNet:

• Chain of responsibility:
  • Returns a value;
  • Have a fallback to execute at the end of the chain;
  • Used when you want that only one middleware to get executed based on an input, like the exception handling example;
• Pipeline:
  • Does not return a value;
  • Used when you want to execute various middleware over an input, like filterings over an image;

Middleware

In PipelineNet the middleware is a definition of a piece of code that will be executed inside a pipeline or a chain of responsibility.

We have four interfaces defining middleware:

• The IMiddleware<TParameter> is used exclusively for pipelines, which does not have a return value.
• The IAsyncMiddleware<TParameter> the same as above but used for asynchronous pipelines.
• The IMiddleware<TParameter, TReturn> is used exclusively for chains of responsibility, which does have a return value.
• The IAsyncMiddleware<TParameter, TReturn> the same as above but used for asynchronous chains of responsibility.

Besides the differences between those four kinds of middleware, they all have a similar structure, the definition of a method Run in which the first parameter is the parameter passed to the Pipeline/Chain of responsibility beind executed and the second one is an Action of Func to execute the next middleware in the flow. It is important to remember to invoke the next middleware by executing the Action/Func provided as the second parameter.

Pipelines

The pipeline can be found in two flavours: Pipeline<TParameter> and AsyncPipeline<TParameter>. Both have the same functionaly, aggregate and execute a series of middleware.

Here is an example of pipeline being configured with three middleware types:

var pipeline = new Pipeline<Bitmap>(new ActivatorMiddlewareResolver())
    .Add<RoudCornersMiddleware>()
    .Add<AddTransparencyMiddleware>()
    .Add<AddWatermarkMiddleware>();

From now on, the instance of pipeline can be used to perform the same operation over as many Bitmap instance as you like:

Bitmap image1 = (Bitmap) Image.FromFile("party-photo.png");
Bitmap image2 = (Bitmap) Image.FromFile("marriage-photo.png");
Bitmap image3 = (Bitmap) Image.FromFile("matrix-wallpaper.png");

pipeline.Execute(image1);
pipeline.Execute(image2);
pipeline.Execute(image3);

If you want to, you can use the asynchronous version, using asynchronous middleware. Changing the instantiation to:

var pipeline = new AsyncPipeline<Bitmap>(new ActivatorMiddlewareResolver())
    .Add<RoudCornersAsyncMiddleware>()
    .Add<AddTransparencyAsyncMiddleware>()
    .Add<AddWatermarkAsyncMiddleware>();

And the usage may be optimized:

Bitmap image1 = (Bitmap) Image.FromFile("party-photo.png");
Task task1 = pipeline.Execute(image1); // You can also simply use "await pipeline.Execute(image1);"

Bitmap image2 = (Bitmap) Image.FromFile("marriage-photo.png");
Task task2 = pipeline.Execute(image2);

Bitmap image3 = (Bitmap) Image.FromFile("matrix-wallpaper.png");
Task task3 = pipeline.Execute(image3);

Task.WaitAll(new Task[]{ task1, task2, task3 });

Chains of responsibility

The chain of responsibility also has two implementations: ResponsibilityChain<TParameter, TReturn> and AsyncResponsibilityChain<TParameter, TReturn>. Both have the same functionaly, aggregate and execute a series of middleware retrieving a return type.

One difference of chain responsibility when compared to pipeline is the fallback that can be defined with the Finally method. You can set one finally for chain of responsibility, calling the method more than once will replace the previous type used.

As we already have an example of a chain of responsibility, here is an example using the asynchronous implementation: If you want to, you can use the asynchronous version, using asynchronous middleware. Changing the instantiation to:

var exceptionHandlersChain = new AsyncResponsibilityChain<Exception, bool>(new ActivatorMiddlewareResolver())
    .Chain<OutOfMemoryAsyncExceptionHandler>() // The order of middleware being chained matters
    .Chain<ArgumentAsyncExceptionHandler>()
    .Finally<ExceptionHandlerAsyncFallback>();

public class ExceptionHandlerAsyncFallback : IAsyncFinally<Exception, bool>
{
    public Task<bool> Finally(Exception parameter)
    {
        parameter.Data.Add("MoreExtraInfo", "More information about the exception.");
        return Task.FromResult(true);
    }
}

And here is the execution:

// The following line will execute only the OutOfMemoryExceptionHandler, which is the first middleware.
bool result = await exceptionHandlersChain.Execute(new OutOfMemoryException()); // Result will be true

// This one will execute the OutOfMemoryExceptionHandler first