Outbox with RavenDB persistence

Target Version: NServiceBus 5.x
Standard support for version 5.x of NServiceBus has expired. For more information see our Support Policy.
RavenDB's implementation of distributed transactions contains a bug that could cause an endpoint, in certain (rare) conditions, to lose data. If RavenDB is configured to enlist in distributed transactions, read DTC not supported for RavenDB Persistence.
Using RavenDB version 4 and higher in a cluster configuration with multiple nodes is not supported. For more information, read cluster configuration with multiple nodes not supported.

The Outbox feature requires persistence in order to store messages and enable deduplication.

Extra collections created by the RavenDB Outbox persistence

To keep track of duplicate messages, the RavenDB implementation of Outbox creates a special collection of documents called OutboxRecord.

Deduplication record lifespan

The RavenDB implementation by default keeps deduplication records for 7 days and runs the purge every 1 minute.

These default settings can be changed by specifying new defaults in the settings dictionary:


The maximum value allowed for both properties is int.MaxValue * 2 milliseconds, which is between 49 and 50 days.

The cleanup task can be disabled by specifying a value of Timeout.InfiniteTimeSpan for SetFrequencyToRunDeduplicationDataCleanup. This can be useful when an endpoint is scaled out and instances are competing to run the cleanup task.

Regardless of the setting for SetFrequencyToRunDeduplicationDataCleanup, the cleanup process will always execute once a minute after the endpoint starts up. After that, the cleanup will run (or not run) according to the value of this property.
When running in multi-tenant mode, cleanup must be handled maually since NServiceBus does not know what databases are in use.
It is advised to run the cleanup task on only one NServiceBus endpoint instance per RavenDB database and disable the cleanup task on all other NServiceBus endpoint instances for the most efficient cleanup execution.

Effect on RavenDB DocumentStore

When the Outbox is enabled, the default transport transaction level will be set so that the endpoint does not utilize distributed transactions. As a result of this, the RavenDB persistence will alter the RavenDB DocumentStore so that it also does not enlist in distributed transactions.

Although this will automatically occur when the endpoint initializes, it's still recommended to set disable RavenDB enlistment in DTC transactions in order to be explicit:

documentStore.EnlistInDistributedTransactions = false;

When the RavenDB Outbox is enabled none of the following properties, on the RavenDB DocumentStore, should be set. They are only used by RavenDB's DTC implementation:

  • ResourceManagerId
  • TransactionRecoveryStorage

Related Articles

  • Outbox
    Reliable messaging without distributed transactions.

Last modified