Message Correlation

Component: NServiceBus
NuGet Package NServiceBus (8-pre)
This page targets a pre-release version and is subject to change prior to the final release.

Correlation is needed in order to find existing saga instances based on data in the incoming message. For example, an OrderId property of a CompleteOrder message can be used to find the existing saga instance for that order.

To declare this, use the ConfigureHowToFindSaga method and use the Mapper to specify which saga property each message maps to.

All correlated properties must have a non-null value when the saga instance is persisted.

Changing the value of correlated properties for existing instances is not supported.

protected override void ConfigureHowToFindSaga(SagaPropertyMapper<MySagaData> mapper)
{
    mapper.ConfigureMapping<MyMessage>(message => message.SomeId)
        .ToSaga(sagaData => sagaData.SomeId);
}

When an instance of MyMessage arrives, NServiceBus asks the saga persistence infrastructure to find an object of the type MySagaData that has a property SomeId whose value is the same as the SomeId property of the message. If found, the saga instance will be loaded and the Handle method for the MyMessage message will be invoked. Should the saga instance not be found, the saga is not started and the saga not found handlers will be invoked.

Starting from NServiceBus version 7.4, it is also possible to use the inverse API to map the saga. The benefit of this approach is that the fluent API allows mapping multiple messages in one operation. Using this API, it is also possible to add a map to the header values in the mix.

protected override void ConfigureHowToFindSaga(SagaPropertyMapper<MySagaData> mapper)
{
    mapper.MapSaga(saga => saga.SomeId)
        .ToMessage<MyFirstMessage>(msg => msg.SomeId)
        .ToMessage<MySecondMessage>(msg => msg.SomeOtherId)
        .ToMessageHeader<MyThirdMessage>("SomeHeaderKey");
}

Message property expression

If correlating on more than one saga property is necessary, or matched properties are of different types, use a custom saga finder.

It is possible to specify the mapping to the message using expressions if the correlation information is split between multiple fields.

protected override void ConfigureHowToFindSaga(SagaPropertyMapper<MySagaData> mapper)
{
    mapper.ConfigureMapping<MyMessage>(message => $"{message.Part1}_{message.Part2}")
        .ToSaga(sagaData => sagaData.SomeId);
}

Message header correlation

Sagas can be correlated to messages using a message header instead of a message property.

protected override void ConfigureHowToFindSaga(SagaPropertyMapper<MySagaData> mapper)
{
    mapper.ConfigureHeaderMapping<MyMessage>("HeaderName")
        .ToSaga(saga => saga.SomeId);
}
An exception is thrown if an incoming message does not contain a header with the configured key, or the value cannot be converted into the saga correlation property type.

Auto-correlation

A common usage of sagas is to have them send out a request message to get some work done and receive a response message back when the work is complete. To make this easier NServiceBus will automatically correlate those response messages back to the correct saga instance.

If it's not clear if the message can be auto-correlated, it's better to provide the mappings. In cases where the message will be auto-correlated, the mappings will be ignored.
A caveat of this feature is that it currently doesn't support auto-correlation between sagas. If the request is handled by another saga, relevant message properties must be added and mapped to the requesting saga using the syntax described above.

Custom saga finder

Full control over how a message is correlated can be achieved by creating a custom saga finder.

Uniqueness

NServiceBus will make sure that all properties used for correlation are unique across all instances of the given saga type. How this is enforced is up to each persister but will most likely translate to a unique key constraint in the database.

Mapping a single message to multiple saga instances is not supported. This can be simulated by using a message handler that looks up all saga instance affected and send a separate message targeting each of those instances using the regular correlation described above.

Related Articles

  • Saga concurrency
    NServiceBus ensures consistency between saga state and messaging.

Last modified