Laqus.Mensageria 1.0.6

Laqus Mensageria .NET

Este projeto é uma Lib em .NET para facilitar a construção e integração de aplicações distribuidas utilizando .NET, ela traz facilidade em escolher tipos de HostedServices, Brokers e configurações adicionais das mensagens, filas, exchanges e tópicos.

Documentação

1. Quick Starts
   • Adicionando a lib ao projeto
   • Configurando via AppSettings
   • Injetando a lib ao builder
   • Criando um Consumer
   • Criando um Producer
2. HostedService Types
3. Broker Types
4. Configuracoes Adicionais
   • Consumer Attributes
   • Message Attributes
5. Integrando Aplicações
6. Erros Comuns

Quick Starts

Adicionando a lib ao projeto

Execute o comando:

  dotnet add package Laqus.Mensageria

Configurando via AppSettings

Para o uso básico, pode-se passar as configurações todas via AppSettings.json, criando uma seção chamada LaqusMensageria, por exemplo:

"LaqusMensageria": {
    "HostedServiceType": "MassTransit",
    "BrokerType": "RabbitMQ",
    "ConnectionURI": "amqp://<username>:<password>@<host>:<port>",
    "Region": "",
    "AccessKey": "",
    "SecretKey": ""
}

Injetando a lib ao builder

Após isso é só adicionar a lib no builder, passando a Configuration:

builder.Services.AddLaqusMensageria(builder.Configuration);

Com isso já teremos um HostedService executando utilizando como base o MassTransit para conexão e configuração, utilizando o RabbitMQ como Broker e passando a Url, User e Password para realizar a conexão.

Criando um Consumer

Para criar um Consumer, basta implementar a classe abstrata LaqusConsumer<TMessage> da lib, onde TMessage é a classe da mensagem que será consumida, por exemplo:

public class ExemploConsumer : LaqusConsumer<Exemplo>
{
    public override Task Consume(Exemplo mensagem)
    {
        throw new NotImplementedException();
    }
}

Criando um Producer

Producer é quem irá enviar as mensagens, para isso a lib disponibiliza dois meios de envio, o Send() que envia uma mensagem diretamente para uma fila específica e o Publish() que envia a mensagem para um tópico/exchange, onde todos que estão "escutando" irá receber uma mensagem. Exemplo de um Producer:

public class ExemploProducer : ILaqusProducer
{
    private readonly IBaseProducer _laqusProducer;

    public ExemploProducer(IBaseProducer laqusProducer)
    {
        this._laqusProducer = laqusProducer;
    }

    public async Task SendExemplo(Exemplo exemplo)
    {
        var queue = new Uri("queue:NomeDaFila");
        await this._laqusProducer.Send(queue, exemplo);
    }

    public async Task PublishExemplo(Exemplo exemplo)
    {
        await this._laqusProducer.Publish(exemplo);
    }
}

Caso não queira que implementar a interface ILaqusProducer, você pode adicionar o seu Producer diretamente como Scoped, por exemplo:

builder.Services.AddScoped<ExemploProducer>();

HostedService Types:

• MassTransit
• NativeDriver (Em Breve)

Broker Types:

• RabbitMQ
• SQS
• Kafka (Em Breve)

Configuracoes Adicionais:

Consumer Attributes

As configurações podem ser adicionadas como Attributes ao Consumer, podendo alterar o nome das filas, a quantidade de retry, concorrencia, tópico, entre outras:

• QueueName: Altera o nome da fila;
• MessageRetry: Altera a quantidade de tentativas e o tempo entre elas;
• ConcurrencyLimit: Altera o limite de mensagens simultâneas a serem consumidas;
• TopicName: Altera o nome do tópico.

Exemplo de utilização no Consumer:

[QueueName("NomeDaFila")]
[TopicName("SubscribingToTopic")]
[ConcurrencyLimit(limit: 2)]
[MessageRetry(maxRetry: 3, timeInSeconds: 5)]
public class ExemploConsumer : LaqusConsumer<Exemplo>
{
    public override Task Consume(Exemplo mensagem)
    {
        throw new NotImplementedException();
    }
}

Message Attributes

Caso esteja utilizando o MassTransit e está planejando comunicar determinada mensagem (classe) com outras aplicações, deve-se utilizar o Attribute LaqusUn para definir um "nome" da mensagem que realizara o bind e será consumida, caso não utilize esse Attribute, o MassTransit coloca o padrão urn:message:<namespace>:<className>, sendo assim as duas (ou mais) aplicações deveria ter o mesmo namespace da mensagem (classe) que for ser consumida.
Exemplo de utilização LaqusUrn:

[LaqusUrn("Exemplo")]
public class Exemplo
{
    public string Nome { get; init; } = String.Empty;
    public string Descricao { get; init; } = String.Empty;
    public int Inteiro { get; init; }
    public bool Booleano { get; init; }
    public Guid CorrelationId { get; set; }
}

Com isso o MessageType será laqus:Exemplo.

Caso você não queira utilizar o prefixo laqus no Urn da mensagem é só passar false no segundo parâmetro do atributo LaqusUrn, por exemplo:

[LaqusUrn("Exemplo", useLaqusPrefix: false)]
public class Exemplo
{
    public string Nome { get; init; } = String.Empty;
    public string Descricao { get; init; } = String.Empty;
    public int Inteiro { get; init; }
    public bool Booleano { get; init; }
    public Guid CorrelationId { get; set; }
}

Com isso o MessageType será Exemplo.

Caso você precise utilizar o prefixo padrão do MassTransit, existe um outro parametro useMassTransitPrefix, e também precisa passar false no parâmetro useLaqusPrefix, por exemplo:

[LaqusUrn("Exemplo", useLaqusPrefix: false, useMassTransitPrefix: true)]
public class Exemplo
{
    public string Nome { get; init; } = String.Empty;
    public string Descricao { get; init; } = String.Empty;
    public int Inteiro { get; init; }
    public bool Booleano { get; init; }
    public Guid CorrelationId { get; set; }
}

Com isso o MessageType será urn:message:Exemplo.

Integrando com aplicacoes:

Case esteja utilizando MassTransit como HostedService e queira se integrar com outras aplicações sem ter que montar o envelope da mensage da forma como o MassTransit espera, existe a opção de usar raw JSON serializer, como diz na documentação. Para que essa configuração seja aplicada em nossa lib basta passar ela na configuração dessa forma:

builder.Services.AddLaqusMensageria(
    builder.Configuration,
    config => 
    {
        config.UseRawJsonSerializer = true;
    }
);

OBS: infelizmente só é possível habilitar ou desabilitar no broker e não por consumer.

Erros Comuns:

Mensagem nao chega ao Consumer:

• Mensagem indo para fila Skipped:
  • Geralmente ocorre quando o messageType não bate com o que é esperado na mensagem, veja a seção de Message Attributes;
• Mensagem indo para fila Error:
  • Verifique qual o erro informado, se for referente ao "envelope", certifique-se de que está mandando o messageType e o message no objeto, ou use raw json serializer como especificado em Integrando Aplicações;
• Mensagem não sendo consumida:
  • Geralmente quando não é nenhum dos casos acima, caso os consumers estiverem em um projeto a parte, verifique se no momento do build a dll do projeto dos consumers está sendo gerada junto na mesma pasta que a do Program (startup do projeto), caso não esteja, procure uma forma de forçar gerar a dll junto, ou uma maneira simples de resolver é colocar na Program algum código referenciando o consumer, por exemplo:

    var consumer = typeof(ExemploConsumer);
    Console.WriteLine(consumer.FullName);