Migration Guide v4

Version 4.0 is a major release with large architectural improvements. This guide details the breaking changes and provides a clear path for upgrading your projects from v3.x.

The key changes are:

DI Abstraction: The library is now DI-agnostic, requiring new, container-specific extension packages.
Advanced Event Mediation: Event handling has been redesigned with a new [HandlerPriority] attribute and concurrency controls.
API and Naming Refinements: Several interfaces and properties have been renamed for clarity.

Step 1: Update NuGet Package References

The package structure has been completely refactored. You must update your .csproj files to reference the new extension packages.

Before (v3.x):

<PackageReference Include="LiteBus" Version="3.x.x" />
<PackageReference Include="LiteBus.Commands" Version="3.x.x" />
<PackageReference Include="LiteBus.Queries" Version="3.x.x" />
<PackageReference Include="LiteBus.Events" Version="3.x.x" />

After (v4.0) - For Microsoft DI:

<PackageReference Include="LiteBus.Commands.Extensions.Microsoft.DependencyInjection" Version="4.0.0" />
<PackageReference Include="LiteBus.Queries.Extensions.Microsoft.DependencyInjection" Version="4.0.0" />
<PackageReference Include="LiteBus.Events.Extensions.Microsoft.DependencyInjection" Version="4.0.0" />

After (v4.0) - For Autofac:

<PackageReference Include="LiteBus.Commands.Extensions.Autofac" Version="4.0.0" />
<PackageReference Include="LiteBus.Queries.Extensions.Autofac" Version="4.0.0" />
<PackageReference Include="LiteBus.Events.Extensions.Autofac" Version="4.0.0" />

Step 2: Update DI Registration

The AddLiteBus registration process is now simpler, as module extensions automatically include the core MessageModule.

Before (v3.x):

services.AddLiteBus(builder =>
{
    // MessageModule had to be registered explicitly first
    registry.AddMessageModule(module => ...);
    registry.AddCommandModule(module => ...);
});

After (v4.0):

services.AddLiteBus(builder =>
{
    // The MessageModule is now added automatically by other LiteBus.
    registry.AddCommandModule(module =>
    {
        module.RegisterFromAssembly(typeof(Program).Assembly);
    });
});

Step 3: Replace `[HandlerOrder]` with `[HandlerPriority]`

The [HandlerOrder] attribute has been removed. You must replace all occurrences with [HandlerPriority]. The behavior is identical: lower numbers execute first.

Before (v3.x):

[HandlerOrder(1)]
public class MyPreHandler : ICommandPreHandler<MyCommand> { ... }

After (v4.0):

using LiteBus.Messaging.Abstractions;

[HandlerPriority(1)]
public class MyPreHandler : ICommandPreHandler<MyCommand> { ... }

The Order property on IHandlerDescriptor has also been renamed to Priority.

Step 4: Update `EventMediationSettings`

The structure of EventMediationSettings has been completely redesigned to support the new concurrency features.

Before (v3.x):

var settings = new EventMediationSettings
{
    Filters = { Tags = new[] { "Tag1" } }
};

After (v4.0): The Filters property is now Routing, and a new Execution property has been added.

var settings = new EventMediationSettings
{
    // Filters are now under the 'Routing' property
    Routing = new EventRoutingSettings
    {
        Tags = new[] { "Tag1" },
        HandlerPredicate = descriptor => ... // Predicate now covers both publish overloads
    },
    // New property to control concurrency
    Execution = new EventExecutionSettings
    {
        PriorityGroupsConcurrencyMode = ConcurrencyMode.Sequential,
        HandlersWithinSamePriorityConcurrencyMode = ConcurrencyMode.Parallel
    }
};

Step 5: Update `ExecutionContext.Items` Key Type

The key for the Items dictionary on CommandMediationSettings, QueryMediationSettings, and IExecutionContext has been changed from object to string for better performance and type safety.

Before (v3.x):

AmbientExecutionContext.Current.Items[typeof(MyKey)] = "my-value";

After (v4.0):

AmbientExecutionContext.Current.Items["MyKey"] = "my-value";

Step 6: Update Custom Mediation Strategies (Advanced)

If you have implemented a custom IMessageMediationStrategy, the IMessageDependencies interface has been renamed for clarity.

Handlers is now MainHandlers.
IndirectHandlers is now IndirectMainHandlers.

Before (v3.x):

var handler = messageDependencies.Handlers.Single().Handler.Value;

After (v4.0):

var handler = messageDependencies.MainHandlers.Single().Handler.Value;

Migration Guide v4

Step 1: Update NuGet Package References

Step 2: Update DI Registration

Step 3: Replace `[HandlerOrder]` with `[HandlerPriority]`

Step 4: Update `EventMediationSettings`

Step 5: Update `ExecutionContext.Items` Key Type

Step 6: Update Custom Mediation Strategies (Advanced)

Next

On this page