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:

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

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" />

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

Before (v3.x):

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

After (v4.0):

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

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.

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 EventMediationRoutingSettings
    {
        Tags = new[] { "Tag1" },
        HandlerPredicate = descriptor => ... // Predicate is now more powerful
    },
    // New property to control concurrency
    Execution = new EventMediationExecutionSettings
    {
        PriorityGroupsConcurrencyMode = ConcurrencyMode.Sequential,
        HandlersWithinSamePriorityConcurrencyMode = ConcurrencyMode.Parallel
    }
};

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";

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;