SQL Persistence Upgrade Version 1 to 2

Component: Sql Persistence

Subscription Caching configuration now required

Subscription Caching is now a required configuration option.

Ether configure a period of time cache for:

2.x NServiceBus.Persistence.Sql
var persistence = endpointConfiguration.UsePersistence<SqlPersistence>();
var subscriptions = persistence.SubscriptionSettings();
subscriptions.CacheFor(TimeSpan.FromMinutes(1));

Or explicitly disable subscription caching.

2.x NServiceBus.Persistence.Sql
var persistence = endpointConfiguration.UsePersistence<SqlPersistence>();
var subscriptions = persistence.SubscriptionSettings();
subscriptions.DisableCache();

Inheriting from SqlSaga now required

In Version 1 inheriting from NServiceBus.Saga<T> was partially supported. However this having two competing approaches that deliver the same features caused significant confusion. In Version 2 NServiceBus.Saga<T> is no longer supported and either a build error, or an runtime exception for some edge cases, will occur.

Deep nested Saga hierarchies are no longer supported

In Version 1 having deep class hierarchies from under SqlSaga<T> was supported. This scenario is no longer supported and all sagas must inherit directly from SqlSaga<T>. This change was done to bring the SQL persistence approach inline with the future approach being taken by NServiceBus.

Correlation Property

The API for definition a Correlation Property has been moved from an attribute to a property at the saga class level.

2.x NServiceBus.Persistence.Sql
public class MySaga :
    SqlSaga<MySaga.SagaData>,
    IAmStartedByMessages<MyMessage>
{
    protected override string CorrelationPropertyName => nameof(SagaData.TheId);
1.x NServiceBus.Persistence.Sql
[SqlSaga(
    correlationProperty: nameof(SagaData.TheId)
)]
public class MySaga :
    SqlSaga<MySaga.SagaData>,
    IAmStartedByMessages<MyMessage>
{

Message Mapping

The API for definition message mapping has been changed to bring it inline with the future approach being taken by NServiceBus:

  • MapMessage renamed to ConfigureMapping.
  • MessagePropertyMapper<T> renamed to IMessagePropertyMapper.
2.x NServiceBus.Persistence.Sql
protected override void ConfigureMapping(IMessagePropertyMapper mapper)
{
    mapper.ConfigureMapping<MyMessage>(_ => _.TheId);
}
1.x NServiceBus.Persistence.Sql
protected override void ConfigureMapping(MessagePropertyMapper<SagaData> mapper)
{
    mapper.MapMessage<MyMessage>(_ => _.TheId);
}

SqlSaga.ConfigureMapping made abstract

To simplify implementing a saga using SqlSaga<T> the method SqlSaga<T>.ConfigureMapping has been made abstract and now always needs to be implemented even if no message mapping is required.

SqlPersistenceSettingsAttribute move to use properties

Attribute have been moved to use properties instead of optional parameters in the constructor.

2.x NServiceBus.Persistence.Sql
[assembly: SqlPersistenceSettings(
    MsSqlServerScripts = true,
    MySqlScripts = true)]
1.x NServiceBus.Persistence.Sql
[assembly: SqlPersistenceSettings(
    msSqlServerScripts: true,
    mySqlScripts: true)]

SqlSagaAttribute made obsolete

The [SqlSagaAttribute] has been made obsolete and replaced by property overrides on the SqlSaga<T> class.

2.x NServiceBus.Persistence.Sql
public class MySaga :
    SqlSaga<MySaga.SagaData>
{
    protected override string CorrelationPropertyName => nameof(SagaData.CorrelationProperty);
    protected override string TransitionalCorrelationPropertyName => nameof(SagaData.TransitionalCorrelationProperty);
    protected override string TableSuffix => "TheCustomTableName";
1.x NServiceBus.Persistence.Sql
[SqlSaga(
    tableSuffix: "TheCustomTableName",
    transitionalCorrelationProperty: "OtherPropertyName"
)]

Explicit schema API

An explicit schema API has been added.

2.x NServiceBus.Persistence.Sql
var persistence = endpointConfiguration.UsePersistence<SqlPersistence>();
persistence.Schema("MySchema");
1.x NServiceBus.Persistence.Sql
var persistence = endpointConfiguration.UsePersistence<SqlPersistence>();
persistence.TablePrefix("MySchema.");

If characters required quoting were previously used in the table prefix, they can be removed and the following used:

2.x NServiceBus.Persistence.Sql
var persistence = endpointConfiguration.UsePersistence<SqlPersistence>();
persistence.Schema("My Schema");
1.x NServiceBus.Persistence.Sql
var persistence = endpointConfiguration.UsePersistence<SqlPersistence>();
persistence.TablePrefix("[My Schema].");
An exception will be thrown if any of ], [ or ` are detected in the tablePrefix or the schema.

Missing Indexes

Some missing indexes have been added. These indexes will be added the next time the installers are executed. No explicit SQL migration is required.

TimeoutData

  • Add missing non-unique index on Time, for query to find expired timeouts.
  • Add missing non-unique index on SagaId, used for clearing timeouts from completed sagas.

OutboxData

  • Add missing index on Dispatched (bool)
  • Add missing index on DispatchedAt (datetime)

Last modified