Rebus.Correlate 4.0.0

dotnet add package Rebus.Correlate --version 4.0.0
NuGet\Install-Package Rebus.Correlate -Version 4.0.0
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Rebus.Correlate" Version="4.0.0" />
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add Rebus.Correlate --version 4.0.0
#r "nuget: Rebus.Correlate, 4.0.0"
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install Rebus.Correlate as a Cake Addin
#addin nuget:?package=Rebus.Correlate&version=4.0.0

// Install Rebus.Correlate as a Cake Tool
#tool nuget:?package=Rebus.Correlate&version=4.0.0

Rebus integration of Correlate to correlate message flow via any supported Rebus transport.

Correlation ID flow

The Correlate library provides an ambient correlation context scope, that makes it easy to track a Correlation ID passing through microservices.

This library provides pipeline steps for Rebus for incoming and outgoing messages, and takes precedence over Rebus' own FlowCorrelationIdStep.

Outgoing messages

When an ambient correlation context is present, the Correlation ID associated with this context is attached to the outgoing message. When no ambient correlation context is active, a new Correlation ID is generated instead using the ICorrelationIdFactory.

If a CorrelationID header is already present, no action is performed.

Incoming messages

For each new incoming message a new ambient correlation context is created. If the incoming message contains a Correlation ID header, this id is associated with the correlation context. If no Correlation ID header is present, a new Correlation ID is generated instead using the ICorrelationIdFactory.

Usage

Configure Rebus to use Correlate.

Using built-in configuration extensions

Use Rebus' built-in configuration extensions to enable Correlate.

ILoggerFactory loggerFactory = new LoggerFactory();
loggerFactory.AddConsole();

Configure.With(....)
    .Options(o => o.EnableCorrelate(loggerFactory))
    .(...)

Using a IServiceProvider

Alternatively, use IServiceProvider to configure Rebus with Correlate.

Add package dependencies:

services
    .AddLogging(logging => logging.AddConsole())
    .AddCorrelate()
    .AddRebus((configure, serviceProvider) => configure
        .Options(o => o.EnableCorrelate(serviceProvider))
        .(...)
    );

Using a custom DI adapter

For example, provided the Correlate dependencies are registered with Autofac:

var builder = new ContainerBuilder();
... // Register Correlate dependencies.
var container = builder.Build();
var scope = container.BeginLifetimeScope(); // Dispose on app shutdown.

Configure.With(....)
    .Options(o => o.EnableCorrelate(new DependencyResolverAdapter(scope.ResolveOptional)))
    .(...)

Send/publish message in an ambient correlation context scope

This example illustrates how messages that are sent/published, inherit the Correlation ID from the ambient correlation context.

public class MyService
{
    private IAsyncCorrelationManager _asyncCorrelationManager;
    private IBus _bus;

    public MyService(IAsyncCorrelationManager asyncCorrelationManager, IBus bus)
    {
        _asyncCorrelationManager = asyncCorrelationManager;
        _bus = bus;
    }

    public async Task DoWork()
    {
        // Without ambient correlation context, the message is still published 
        // with a Correlation ID, but it is generated specifically for this message.
        await _bus.Publish(new DoWorkCalledEvent());

        // Perform work in new correlation context.
        await _asyncCorrelationManager.CorrelateAsync(async () =>
        {
            // This command will be sent with the Correlation ID from
            // the ambient correlation context.
            await _bus.Send(new DoSomethingElseCommand());

            // Do other work in ambient correlation context,
            // like call other microservice (using Correlate support)
            // ...

            // This event will be published with the same Correlation ID.
            await _bus.Publish(new WorkFinishedEvent());
        });
    }
}

Note: when using Correlate integration for ASP.NET Core, each request is already scoped to a correlation context, and so there is no need to wrap the send/publish of messages with IAsyncCorrelationManager/ICorrelationManager.

Handle message in an ambient correlation context scope

With Correlate enabled, any incoming message is handled in its own ambient correlation context automatically. If you wish to access the Correlation ID, inject the ICorrelationContextAccessor into your handler.

public class MyHandler : IHandleMessages<MyMessage>
{
    private ICorrelationContextAccessor _correlationContextAccessor;

    public MyHandler(ICorrelationContextAccessor correlationContextAccessor)
    {
        _correlationContextAccessor = correlationContextAccessor;
    }

    public Task Handle(MyMessage message)
    {
        string correlationId = _correlationContextAccessor.CorrelationContext.CorrelationId; 
    }
}

Do not keep a reference to the CorrelationContext, always use the ICorrelationContextAccessor to get the current context.

More info

  • Correlate documentation for further integration with ASP.NET Core, IHttpClientFactory and for other extensions/libraries.
  • Release notes

Contributions

Please check out the contribution guidelines.

Product Compatible and additional computed target framework versions.
.NET net5.0 was computed.  net5.0-windows was computed.  net6.0 is compatible.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 was computed.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 is compatible.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed. 
.NET Core netcoreapp2.0 was computed.  netcoreapp2.1 was computed.  netcoreapp2.2 was computed.  netcoreapp3.0 was computed.  netcoreapp3.1 was computed. 
.NET Standard netstandard2.0 is compatible.  netstandard2.1 was computed. 
.NET Framework net461 was computed.  net462 was computed.  net463 was computed.  net47 was computed.  net471 was computed.  net472 was computed.  net48 was computed.  net481 was computed. 
MonoAndroid monoandroid was computed. 
MonoMac monomac was computed. 
MonoTouch monotouch was computed. 
Tizen tizen40 was computed.  tizen60 was computed. 
Xamarin.iOS xamarinios was computed. 
Xamarin.Mac xamarinmac was computed. 
Xamarin.TVOS xamarintvos was computed. 
Xamarin.WatchOS xamarinwatchos was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last updated
4.0.0 225 11/25/2023
3.0.0 1,568 9/8/2022
2.0.0 28,385 12/5/2020
1.1.0 19,291 7/28/2019
1.0.0 583 7/3/2019