Simple RavenDB Persistence Usage

In RavenDB 3.5, the client implementation of distributed transactions contains a bug that could cause an endpoint to lose data under rare conditions. If RavenDB is configured to enlist in distributed transactions with RavenDB 3.5, read DTC not supported for RavenDB Persistence.

Using RavenDB version 5 and higher in a cluster configuration with multiple nodes is only supported from version 7 or higher of the NServiceBus.RavenDB persistence package. For more information, read cluster configuration with multiple nodes.

Code walk-through

This sample shows a simple Client + Server scenario.

Client sends a StartOrder message to Server.
Server starts an OrderSaga.
OrderSaga requests a timeout with a CompleteOrder data.
When the CompleteOrder timeout fires the OrderSaga publishes a OrderCompleted event.
The Server then publishes a message that the client subscribes to.
Client handles OrderCompleted event.

Raven Config

In the RavenDB studio, create a database named RavenSimpleSample. RavenDB does not create the database automatically.
Configure the endpoint to use RavenDB persistence. The URL in the Urls collection may need to be changed to match the database host/port in use.

Copy code|Copy usings|Edit

var endpointConfiguration = new EndpointConfiguration("Samples.RavenDB.Server");
using var documentStore = new DocumentStore
{
    Urls = ["http://localhost:8080"],
    Database = "RavenSimpleSample",
};

documentStore.Initialize();

var persistence = endpointConfiguration.UsePersistence<RavenDBPersistence>();
persistence.SetDefaultDocumentStore(documentStore);

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.

Order Saga Data

Copy code|Copy usings|Edit

public class OrderSagaData :
    ContainSagaData
{
    public Guid OrderId { get; set; }
    public string OrderDescription { get; set; }
}

Order Saga

Copy code|Copy usings|Edit

public class OrderSaga :
    Saga<OrderSagaData>,
    IAmStartedByMessages<StartOrder>,
    IHandleTimeouts<CompleteOrder>
{
    static ILog log = LogManager.GetLogger<OrderSaga>();

    protected override void ConfigureHowToFindSaga(SagaPropertyMapper<OrderSagaData> mapper)
    {
        mapper.MapSaga(sagaData => sagaData.OrderId)
            .ToMessage<StartOrder>(message => message.OrderId);
    }

    public Task Handle(StartOrder message, IMessageHandlerContext context)
    {
        var orderDescription = $"The saga for order {message.OrderId}";
        Data.OrderDescription = orderDescription;
        log.Info($"Received StartOrder message {Data.OrderId}. Starting Saga");

        var shipOrder = new ShipOrder
        {
            OrderId = message.OrderId
        };

        log.Info("Order will complete in 5 seconds");
        var timeoutData = new CompleteOrder
        {
            OrderDescription = orderDescription
        };

        return Task.WhenAll(
            context.SendLocal(shipOrder),
            RequestTimeout(context, TimeSpan.FromSeconds(5), timeoutData)
        );
    }

    public Task Timeout(CompleteOrder state, IMessageHandlerContext context)
    {
        log.Info($"Saga with OrderId {Data.OrderId} completed");
        var orderCompleted = new OrderCompleted
        {
            OrderId = Data.OrderId
        };
        MarkAsComplete();
        return context.Publish(orderCompleted);
    }
}

Handler Using RavenDB Session

The handler access's the same RavenDB ISession via ISessionProvider.

Copy code|Copy usings|Edit

public class ShipOrderHandler :
    IHandleMessages<ShipOrder>
{
    public Task Handle(ShipOrder message, IMessageHandlerContext context)
    {
        var session = context.SynchronizedStorageSession.RavenSession();
        var orderShipped = new OrderShipped
        {
            OrderId = message.OrderId,
            ShippingDate = DateTime.UtcNow,
        };
        return session.StoreAsync(orderShipped, context.CancellationToken);
    }
}

The Data in RavenDB

The data in RavenDB is stored in three different collections.

By default, this sample uses the Learning Transport, which has built-in support for timeouts and subscriptions. To see the data for timeouts and subscriptions, it's necessary to change the sample to a different transport that does not have these native features such as MSMQ.

The Saga Data

IContainSagaData.Id maps to the native RavenDB document Id.
IContainSagaData.Originator and IContainSagaData.OriginalMessageId map to simple properties.
Custom properties on the SagaData, in this case OrderDescription and OrderId, are also mapped to simple properties.

{
    "IdentityDocId": "OrderSagaData/OrderId/33e54adb-10fe-ac05-abdd-a656e8f995b3",
    "Data": {
        "$type": "OrderSagaData, Server",
        "OrderId": "683e7b20-527a-475d-847c-79ef6b0f40a1",
        "OrderDescription": "The saga for order 683e7b20-527a-475d-847c-79ef6b0f40a1",
        "Id": "9bf646a0-25b1-4a79-afe3-adf600965476",
        "Originator": "Samples.RavenDB.Client",
        "OriginalMessageId": "06cdd874-de9b-40bb-8b90-adf600965448"
    },
    "@metadata": {
        "@collection": "SagaDataContainers",
        "Raven-Clr-Type": "NServiceBus.Persistence.RavenDB.SagaDataContainer, NServiceBus.RavenDB",
        "NServiceBus-Persistence-RavenDB-SagaDataContainer-SchemaVersion": "1.0.0"
    }
}

The Handler Stored data

{
    "OrderId": "683e7b20-527a-475d-847c-79ef6b0f40a1",
    "ShippingDate": "2021-12-06T09:07:20.1902988Z",
    "@metadata": {
        "@collection": "OrderShippeds",
        "Raven-Clr-Type": "OrderShipped, Server"
    }
}

Code walk-through

Raven Config

Order Saga Data

Order Saga

Handler Using RavenDB Session

The Data in RavenDB

The Saga Data

The Handler Stored data

Related Articles

In this article