microservice.toolkit.messagemediator 0.7.0

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.7.0

.NET CLI

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

Package Reference

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

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 some implementations of the message mediator interface:

• Local
• RabbitMQ
• Azure Service Bus

The implementations of message mediator can work in a single instance environment

or in a multi instances environment:

A bus can be a message broker (RabbitMQ or Azure Service bus).

Every implementation requires a "service provider" (a delegate) to link the name (pattern) to the instance of a service.

Local

<a name="local"></a> To use in a single instance environment or for 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"/>

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 payload of the response)

Example code:

[MicroService(nameof(UserExists))]
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 the services into IoC (using Microsoft Dependency Injection) and mediator, add at startup program ("services" is an instance of IServiceCollection):

using microservice.toolkit.messagemediator.extension;

[...]

// Uses assembly scan to retrieve all the "Service<,>" implementations
var microservices = Assembly.GetAssembly(typeof(UserExists)).GetServices(); 
// or 
// var microservices = typeof(UserExists).GetAssemblyServices();

// Registers all the microservices as singleton
services.AddServices(microservices);
// Or specify the life time
// services.AddServices(ServiceLifetime.Scoped, microservices);

[...]

// Registers the "service factory" 
services.AddSingleton<ServiceFactory>(serviceProvider => 
    serviceProvider.ByNameServiceFactory(microservices)
);

[...]

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

Service call

To call a service using a mediator:

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