Correlation is the process of finding 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 is loaded and the Handle
method for the MyMessage
message is invoked. Should the saga instance not be found, the saga is not started and the saga not found handlers are 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);
}
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 automatically correlates those response messages back to the correct saga instance.
Custom saga finder
Full control over how a message is correlated can be achieved by creating a custom saga finder.
Uniqueness
NServiceBus makes 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.