Home

The command framework provides a simple, configurable command processing pipeline that can be added to any .NET project.

It is ideal for CQRS based systems and is designed to be invoked via a single REST endpoint.

The command pipeline is exposed as middleware, but it can easily added to specific endpoint routing using the extension methods within this library. Alternatively, you can just use the underlying framework to create your own pipeline. Check out the wiki for more information.

Installing CommandApi

You should install the CommandApi framework with NuGet:

Install-Package CommandApi

Basic Usage

To get started you just need to specify a command and its handler, register the dependencies, and add the command api endpoint.

A simple command

Commands are requests to change the state of the system. They contain the information required to make the necessary changes. They are simple POCOs that should be immutable, and must implement the ICommand interface and use the CommandNameAttribute.

The command name should be unique within the scope of the running application.

[CommandName("Api/AddUser")]
public class AddUser : ICommand
{
    public AddUser(int id, string name)
    {
        this.Id = id;
        this.Name = name;
    }

    public int Id { get; }

    public string Name { get; }
}

Its handler

Each command must have a handler. Simply implement the generic ICommandHandler<> interface.

public class AddUserHandler : ICommandHandler<AddUser>
{
    public Task HandleAsync(AddUser command, CommandMetadata metadata)
    {
        // handle the command
    }
}

Register the dependencies

In order to use the middleware, you need to register the required services. This can be done in the ConfigureServices method of your Startup.cs file:

public void ConfigureServices(IServiceCollection services)
{
    services.AddControllers();

    // register the command pipeline dependencies
    services.AddCommandBus(
        new List<Assembly>
        {
            // assemblies that contain commands that should be registered
            // ie: if all commands are in the api project...
            typeof(Startup).Assembly
        });
}

Add the route to your API

To add the command pipeline to your api, simply use the MapCommandEndpoint() extension method in the Configure method of your Startup.cs file.

This will add the "/command" route to your api. If you want to specify the route, you can use the overload as demonstrated in the example below.

app.UseEndpoints(endpoints =>
{
    // add the command endpoint
    // ----------------------------- //
    
    endpoints.MapCommandEndpoint();

    // OR

    endpoints.MapCommandEndpoint("custom/command-route");

    // ----------------------------- //

    endpoints.MapControllers();
});

Invoke the command

To invoke the pipeline, send a POST request to the endpoint you configured above. The endpoint expects a JSON body with two properties...

• command - The name specified on the CommandName attribute
• body - The JSON representation of the command itself

So, using the AddUser command above, the request body would be:

{
  "command": "Api/AddUser",
  "body": {
    "id": 1,
    "name": "Jake"
  }
}

Using your method of choice, run your API and test it...

This example uses PowerShell and the Invoke-WebRequest cmdlet

$body = @{
  command = "Api/AddUser"
  body = @{
    id = 1
    id = "Jake"
  }
} | ConvertTo-Json

Invoke-WebRequest http://localhost:5000/command -Method 'POST' -Body $body