RavenDB Persistence

Project Hosting
NuGet Package NServiceBus.RavenDB (5-pre)
Target NServiceBus Version: 7.x
This page targets a pre-release version and is subject to change prior to the final release.
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.

Uses the RavenDB document database for storage.

RavenDB versions

Specific versions of RavenDB Persistence are tied to a major version of NServiceBus and also designed to work with a specific version of the RavenDB client library. When releasing a new major version of NServiceBus, the corresponding RavenDB Persistence release will use the last supported version of RavenDB, so that it is never necessary to upgrade both NServiceBus and RavenDB at the same time.

NServiceBusRavenDB PersistenceRavenDB Client
7.x5.0.x3.5
6.x4.1.x3.5
6.x4.0.x3.0
5.x3.2.x3.5
5.x3.0.x3.0
5.x2.x2.5

See the NServiceBus Packages Supported Versions to see the support details for each version of RavenDB Persistence.

Connection options for RavenDB

There are a variety of options for configuring the connection to a RavenDB Server. See RavenDB Connection Options for more details.

Shared session

NServiceBus supports sharing the same RavenDB document session between Saga persistence, Outbox persistence, and business data, so that a single transaction can be used to persist the data for all three concerns atomically.

Shared session is only applicable to Saga and Outbox storage. It can be configured via

var documentStore = new DocumentStore();
// configure documentStore here
var persistence = endpointConfiguration.UsePersistence<RavenDBPersistence>();
persistence.UseSharedAsyncSession(
    getAsyncSessionFunc: () =>
    {
        var session = documentStore.OpenAsyncSession();
        // customize session here
        return session;
    });

This optionally allows customization of the document session that is created for Saga, Outbox, and handler logic to share.

The session that is created is then made available.

When the RavenDB DocumentStore is created by the user at endpoint configuration time it's important to dispose it, by calling the Dispose() method, before shutting down the endpoint process.

Using in a Handler

public class HandlerThatUsesSession :
    IHandleMessages<MyMessage>
{
    public Task Handle(MyMessage message, IMessageHandlerContext context)
    {
        var document = new MyDocument();
        var ravenSession = context.SynchronizedStorageSession.RavenSession();
        return ravenSession.StoreAsync(document);
    }
}

Using in a Saga

Other than interacting with its own internal state, a saga should not access a database, call out to web services, or access other resources. See Accessing databases and other resources from a saga.

If the situation is special enough to warrant going against this recommendation, the following documentation will describe how to do so.

public class SagaThatUsesSession :
    Saga<SagaThatUsesSession.SagaData>,
    IHandleMessages<MyMessage>
{
    public Task Handle(MyMessage message, IMessageHandlerContext context)
    {
        var document = new MyDocument();
        var ravenSession = context.SynchronizedStorageSession.RavenSession();
        return ravenSession.StoreAsync(document);
    }

Distributed Transaction Coordinator settings

The RavenDB client requires a unique Guid to identify it to the Distributed Transaction Coordinator, and a method of storing DTC transaction recovery information in the case of process faults. By default, NServiceBus uses IsolatedStorageTransactionRecoveryStorage as its transaction recovery storage. Under certain high-load situations, this has been known to result in a TransactionAbortedException or IsolatedStorageException.

In order to set DTC settings that are safe for production use, refer to Setting RavenDB DTC settings manually.

Subscription persister and message versioning

The behavior of the RavenDB subscription persistence differs from other NServiceBus persisters in the way it handles versioning of message assemblies. It's important to understand this difference, especially when using a deployment solution that automatically increments assembly version numbers with each build.

To learn about message versioning as it relates to the RavenDB subscription persister, refer to RavenDB subscription versioning.

Viewing the data

Open a web browser and type the URL of the RavenDB server. This opens the RavenDB Studio.

Samples

Related Articles


Last modified