microservice.toolkit.messagemediator 0.11.1

Message mediator

The library is a work in progress. It is not yet considered production-ready.

An interface to define how cloud microservices interact each other across multi instances, using request-response pattern.

How to install

Package Manager

Install-Package microservice.toolkit.messagemediator -Version 0.11.1

.NET CLI

dotnet add package microservice.toolkit.messagemediator --version 0.11.1

Package Reference

<PackageReference Include="microservice.toolkit.messagemediator" Version="0.11.1" />

Introduction

In Microservice Toolkit, a microservice has a name (or pattern) and returns with the following structure:

{
    "error": 12,
    "payload": {
        ...
    }
}

Where:

• Error is the core of the error, it has value when an error occurs during service execution.
• Payload is the output of the service, it has value when the execution goes well.

Only one of the fields can have a value: if "error" has a value, "payload" doesn't have it, and vice versa.

Implementations

Microservice Toolkit provides message mediator (IMessageMediator) implementations which can exchange messages in a single instance environment and in a multi instances environment using a message broker like RabbitMQ, Azure Service Bus or NATS.

Single instance environment:

Multi instances environment:

Every implementation of message mediator requires a "service factory" which link service name (pattern) to its instance.

Local

<a name="local"></a> To use in a single instance environment, in a desktop application, or to testing.

No external dependencies needed.

No external service will be query/use.

RabbitMQ

<a name="rabbitmq"></a> RabbitMQ is an open-source and lightweight message broker which supports multiple messaging protocols. It can be deployed in distributed and federated configurations to meet high-scale, high-availability requirements. In addition, it's the most widely deployed message broker, used worldwide at small startups and large enterprises.

To start building RabbitMQ-based microservices, first install the required packages:

Install-Package RabbitMQ.Client -Version 6.2.2

Or:

<PackageReference Include="RabbitMQ.Client" Version="6.2.2" />

Azure Service Bus

<a name="servicebus"></a> To start building Azure Service Bus-based microservices, first install the required packages:

Install-Package Microsoft.Azure.ServiceBus -Version 5.1.3

Or:

<PackageReference Include="Microsoft.Azure.ServiceBus" Version="5.1.3"/>

NATS

<a name="nats"></a> To start building NATS-based microservices, first install the required packages:

Install-Package NATS.Client -Version 1.0.2

Or:

<PackageReference Include="NATS.Clients" Version="1.0.2"/>

How to use

Service implementation

To implement a service, extend the abstract class "Service<TRequest, TPayload>", where:

• "TRequest" is the service input (or request)
• "TPayload" is the service output (or response payload)

Example code:

[Microservice("/user/exists")]
public class UserExists : Service<UserExistsRequest, UserExistsResponse>
{
    public async override Task<ServiceResponse<UserExistsResponse>> Run(UserExistsRequest request)
    {
        return this.SuccessfulResponse(new UserExistsResponse
        {
            Exists = "Alice" == request.Username
        });
    }
}

Services registration

To register services, service factory and mediator into IoC (using Microsoft Dependency Injection), add to program startup ("services" is an instance of IServiceCollection):

using microservice.toolkit.messagemediator.extension;

[...]

// Registers all the microservices in the same assembly of "UserExists" class.
// Registers all the microservices as Singleton.
// Registers the service factory as Singleton.
var myAssembly = Assembly.GetAssembly(typeof(UserExists));
services.AddServiceContext(myAssembly);

[...]

// Registers message mediator 
services.AddSingleton<IMessageMediator, LocalMessageMediator>();

Service call

To call a service using a mediator:

private readonly IMessageMediator mediator;

[...]

public MyClass(IMessageMediator mediator){
    this.mediator = mediator;
}

[...]

// to explicit only payload type:
var response = await mediator.Send<int>(typeof(SquarePow), 2));
// or, to explicit request and payload type:
var response = await mediator.Send<int, int>(typeof(SquarePow), 2));