Guia de Migração: Atualizando do Brighter V9 para V10

No meu artigo anterior, discuti o Brighter V10 e seus novos recursos. Este artigo complementar foca no caminho essencial de migração do V9 para V10, destacando as mudanças significativas e fornecendo exemplos de código atualizados.

Registro de Injeção de Dependência

Uma das primeiras e mais significativas mudanças que você encontrará é a forma como o Brighter é registrado no contêiner de DI do Microsoft. O método AddServiceActivator foi removido, substituído por métodos mais específicos para consumidores e produtores.

Configuração de Consumidores e Produtores de Mensagens

No V9, você normalmente usava AddServiceActivator para consumidores. No V10, este registro agora é explicitamente dividido em AddConsumers e AddProducers, dando a você um controle mais granular.

Observe também que opt.ChannelFactory foi renomeado para opt.DefaultChannelFactory.

V9

services
    .AddServiceActivator(opt => 
    {
        opt.Subscriptions = [...];
        opt.ChannelFactory = new ChannelFactory(...);
    })
    .UseExternalBus(...)

V10

services
    .AddConsumers(opt => 
    {
        opt.Subscriptions = [...];
        opt.DefaultChannelFactory = new ChannelFactory(...);
    })
    .AddProducers(opt =>
    {
        opt.ProducerRegistry = ....
    });

Configuração de Inbox e Outbox

Anteriormente, você configurava o Inbox e o Outbox encadeando métodos como UseInMemoryInbox() após AddServiceActivator. No V10, esta configuração foi movida diretamente para as opções do AddConsumers (para o Inbox) e AddProducers (para o Outbox).

Ao configurar um Outbox no V10, você também precisa agora configurar explicitamente o ConnectionProvider e o TransactionProvider.

V9:

services
    .AddServiceActivator(opt => 
    {
        opt.Subscriptions = [...];
        opt.ChannelFactory = new ChannelFactory(...);
    })
    .UseInMemoryInbox()
    .UseInMemoryOutbox()
    .UseExternalBus(...)

V10:

services
    .AddConsumers(opt => 
    {
        opt.Subscriptions = [...];
        opt.InboxConfiguration = new InboxConfiguration(...);
        opt.DefaultChannelFactory = new ChannelFactory(...);
    })
    .AddProducers(opt =>
    {
        opt.ProducerRegistry = ....;
        opt.Outbox = ...;
        opt.ConnectionProvider = typeof(...);
        opt.TransactionProvider = typeof(...);
    });

LifeTime dos Componentes

Com o V10, é fortemente recomendado registrar seus Message Mappers, Transformers e Request Handlers como Scoped ou Transient.

Isso ocorre porque esses componentes agora frequentemente incluem uma propriedade RequestContext. Esta propriedade é atualizada pelo framework em tempo de execução (antes que os métodos sejam chamados), e usar um tempo de vida Singleton pode levar a problemas de concorrência e dados desatualizados.

Interface do Message Mapper

A interface IAmAMessageMapper tem duas mudanças significativas importantes.

1. Assinatura do MapToMessage: O método agora inclui um parâmetro Publication: MapToMessage(Greeting request, Publication publication). Isso é necessário para suportar a nova funcionalidade de mapper padrão.
2. Propriedade RequestContext: A interface agora requer uma propriedade public IRequestContext? Context { get; set; }. Isso permite que o framework ou o solicitante passem contexto e dados adicionais em tempo de execução.

V9

public class GreetingMapper : IAmAMessageMapper<Greeting>
{
    public Message MapToMessage(Greeting request)
    {
        var header = new MessageHeader();
        header.Id = request.Id;
        header.TimeStamp = DateTime.UtcNow;
        header.Topic = "greeting.topic";
        header.MessageType = MessageType.MT_EVENT;

        var body = new MessageBody(JsonSerializer.Serialize(request));
        return new Message(header, body);
    }

    public Greeting MapToRequest(Message message)
    {
        return JsonSerializer.Deserialize<Greeting>(message.Body.Bytes)!;
    }
}

V10

public class GreetingMapper : IAmAMessageMapper<Greeting>
{
    public IRequestContext? Context { get; set; }

    public Message MapToMessage(Greeting request, Publication publication)
    {
        var header = new MessageHeader();
        header.Id = request.Id;
        header.TimeStamp = DateTime.UtcNow;
        header.Topic = "greeting.topic";
        header.MessageType = MessageType.MT_EVENT;

        var body = new MessageBody(JsonSerializer.Serialize(request));
        return new Message(header, body);
    }

    public Greeting MapToRequest(Message message)
    {
        return JsonSerializer.Deserialize<Greeting>(message.Body.Bytes)!;
    }
}

Mappers Assíncronos

Uma mudança sutil, mas importante: Se você está usando RequestHandlerAsync (para handlers assíncronos), agora você deve implementar a interface correspondente IAmAMessageMapperAsync em vez da interface síncrona IAmAMessageMapper.

Mudanças Significativas no Outbox

Se você está usando o Outbox do Brighter V10, especialmente com um banco de dados relacional (como PostgreSQL, MySQL ou Microsoft SQL Server), existem várias mudanças de schema significativas.

Você precisa adicionar as seguintes colunas às suas tabelas Inbox/Outbox para suportar contexto e rastreamento aprimorados:

• Source: VARCHAR(255)
• DataSchema: VARCHAR(255)
• Subject: VARCHAR(255)
• TraceParent: VARCHAR(255)
• TraceState: VARCHAR(255)
• Baggage: TEXT (ou VARCHAR(MAX) no SQL Server)

Mudanças na Coluna MessageId

O tipo da coluna MessageId foi atualizado em várias implementações.

• PostgreSQL: O tipo do MessageId deve ser alterado de UUID para VARCHAR(255).

Mudanças Opcionais (Recomendadas): Para melhor desempenho e uso de tipos nativos, você pode fazer as seguintes alterações específicas de plataforma:

• MySQL: Alterar MessageId de CHAR(36) para VARCHAR(255).
• Microsoft SQL Server: Alterar MessageId de UNIQUEIDENTIFIER para VARCHAR(255).

Estratégia de Migração e Melhores Práticas

Ao migrar do V9 para V10, considere esta abordagem:

1. Comece pelo Registro: Atualize primeiro sua configuração de DI, pois isso afeta tudo o mais
2. Configure Inbox/Outbox: Mova sua configuração de inbox/outbox para os blocos de registro apropriados
3. Atualize os Mappers: Refatore todos os mappers de mensagens para implementar os novos requisitos da interface
4. Revise os Tempos de Vida: Audite todos os componentes relacionados ao Brighter e certifique-se de que estão registrados como Scoped ou Transient
5. Teste Exaustivamente: Dê atenção especial ao gerenciamento de transações e operações assíncronas

Conclusão

Migrar para o Brighter V10 envolve várias mudanças importantes, principalmente focadas em um registro de DI mais claro, configuração explícita de Inbox/Outbox e mapeamento de mensagens aprimorado com contexto de requisição. Ao atualizar seu registro de serviços e implementações de mappers como mostrado acima, você pode fazer a transição suave de sua aplicação para a nova versão.