Migrating to Brighter V10 with MS SQL

This content originally appeared on DEV Community and was authored by Rafael Andrade

In previous articles, I covered Brighter integration with MS SQL Server and Brighter V10 RC1. This guide focuses on migrating to Brighter V10, emphasizing MS SQL Server configuration changes and breaking updates.

Requirement

• .NET 8 or superior
• A .NET project with these NuGet packages
  • Paramore.Brighter.MessagingGateway.MsSql: Enables MS SQL Server integration.
  • Paramore.Brighter.ServiceActivator.Extensions.DependencyInjection: Enable register Brighter with Microsoft DI.
  • Paramore.Brighter.ServiceActivator.Extensions.Hosting: Hosts Brighter as a background service.
  • Serilog.AspNetCore: For structured logging (optional but recommended).

Brighter Recap

Before continuing about SQL Server configuration, let’s recap what we already know about Brighter.

Request (Command/Event)

Define messages using IRequest:

public class Greeting() : Event(Guid.NewGuid())
{
    public string Name { get; set; } = string.Empty;
}

• Commands: Single-recipient operations (e.g., SendEmail).
• Events: Broadcast notifications (e.g., OrderShipped).

Message Mapper (Optional)

Translates between Brighter messages and your app objects, for async workflow mappers now require IAmAMessageMapperAsync

Request Handler

Processes incoming messages:

public class GreetingHandler(ILogger<GreetingHandler> logger) : RequestHandler<Greeting>
{
    public override Greeting Handle(Greeting command)
    {
        logger.LogInformation("Hello {Name}", command.Name);
        return base.Handle(command);
    }
}

Configuring Brighter with SQL Server

1. Creating Queue table

Brighter won’t create the queue table, for this you can use this script

IF NOT (EXISTS (SELECT * FROM INFORMATION_SCHEMA.TABLES WHERE TABLE_SCHEMA = 'dbo' AND  TABLE_NAME = 'QueueData'))
BEGIN
    CREATE TABLE [dbo].[QueueData](
        [Id] [bigint] IDENTITY(1,1) NOT NULL,
        [Topic] [nvarchar](255) NOT NULL,
        [MessageType] [nvarchar](1024) NOT NULL,
        [Payload] [nvarchar](max) NOT NULL,
        CONSTRAINT [PK_QueueData] PRIMARY KEY CLUSTERED ([Id] ASC)WITH (PAD_INDEX = OFF, STATISTICS_NORECOMPUTE = OFF, IGNORE_DUP_KEY = OFF, ALLOW_ROW_LOCKS = ON, ALLOW_PAGE_LOCKS = ON) ON [PRIMARY]
     ) ON [PRIMARY] TEXTIMAGE_ON [PRIMARY]

     CREATE NONCLUSTERED INDEX [IX_Topic] ON [dbo].[QueueData]([Topic] ASC) WITH (PAD_INDEX = OFF, STATISTICS_NORECOMPUTE = OFF, SORT_IN_TEMPDB = OFF, DROP_EXISTING = OFF, ONLINE = OFF, ALLOW_ROW_LOCKS = ON, ALLOW_PAGE_LOCKS = ON) ON [PRIMARY]
END;

2. Connection Setup

Define SQL Server connection details:

var config = new RelationalDatabaseConfiguration("<connection-string>", queueStoreTable: "QueueData");

3. SQL Subscription

Subscribe to a topic:

 .AddServiceActivator(opt =>
 {
     opt.Subscriptions =
     [
         new MsSqlSubscription<Greeting>(
             subscriptionName: new SubscriptionName("greeting.subscription"),
             channelName: new ChannelName("greeting.topic"),
             makeChannels: OnMissingChannel.Create,
             messagePumpType: MessagePumpType.Reactor,
             timeOut:  TimeSpan.FromSeconds(10)
           ),
     ];

     opt.DefaultChannelFactory = new ChannelFactory(new MsSqlMessageConsumerFactory(config));
})

4. SQL Producer Configuration

Publish events to a topic:

.UseExternalBus(opt =>
{
    opt.ProducerRegistry = new MsSqlProducerRegistryFactory(config, [
        new Publication<Greeting>
        {
            Topic = new RoutingKey("greeting.topic"),
            MakeChannels = OnMissingChannel.Create
        }]).Create();
})

Breaking Changes in Brighter V10

Brighter V10 introduces updates to SQL integration, Below are the key breaking changes:

Message Mapper Overhaul

Default JSON Serialization :

In V9, message mappers were mandatory. In V10, JSON serialization is built-in unless custom logic is required, also you can change the default Brighter serialization.

Subscription

We had 2 main changes on subscription.

Explicit Message Pump Types

The first one is before we had a field called runAsync or isAsync it was a boolean, to make everything clear we change it to messagePumpType and it’s the MessagePumpType(Reactor, Proactor, Unknown).

Property Renaming

On the AddServiceActivator where rename the ChannelFactory property to DefaultChannelFactory

Publication

Use ExternalBusConfiguration to configure producers and outbox patterns:

// V10
.UseExternalBus(opt => { ... })

// V9
.UseExternalBus(new RmqProducerRegistryFactory(...))

Conclusion

Brighter V10 simplifies SQL Server integration while introducing breaking changes to improve clarity and flexibility. Key updates include built-in serialization, explicit message pump types, and streamlined configuration APIs. For full implementation details, refer to the GitHub sample repository.

This content originally appeared on DEV Community and was authored by Rafael Andrade