Getting Started

Learning Persistence

NuGet Package: NServiceBus (8.x)

The Learning Persistence simulates saga persistence infrastructure by storing data in the local file system. All files and directories are relative to the current project directory.

The Learning Transport and Learning Persistence are not for production use. They are designed for short term learning and experimentation purposes. It should also not be used for longer-term development, i.e. the same transport and persistence used in production should be used in development and debug scenarios. Select a production transport and persistence before developing features. Do not use the learning transport or learning persistence to perform any kind of performance analysis.

Added in NServiceBus 6.3.

Some recommended use cases are:

  • Learning/Experimenting with NServiceBus features.
  • Building a spike or demo.
  • Reproducing a bug that is not related to a production transport, for example when raising a support case.

Persistence at a glance

For a description of each feature, see the persistence at a glance legend.

Storage TypesSagas only. Subscriptions/Timeouts handled natively by Learning Transport.
Concurrency controlOptimistic concurrency via file locks
Scripted deploymentNot supported
InstallersNone. The required folder structure is always created at runtime.



Storage Directory

By default all data is stored in a .sagas directory that exists at AppDomain.CurrentDomain.BaseDirectory.

To configure the storage location:

var persistence = endpointConfiguration.UsePersistence<LearningPersistence>();

Each saga will be stored a sub-directory matching the saga type name with the saga data being serialized into a .json file named based on the saga ID.

Saga concurrency

When simultaneously handling messages, conflicts may occur. See below for examples of the exceptions which are thrown. Saga concurrency explains how these conflicts are handled, and contains guidance for high-load scenarios.

Starting a saga

Example exception:

System.IO.IOException: The file 'S:\.sagas\OrderSaga\944b7efb-7146-adf1-d6ae-968f0d7757fa.json' already exists.

Updating or deleting saga data

Learning persistence uses file locks when updating or deleting saga data. The effect is similar to optimistic concurrency control with the difference that failure will occur when reading the saga data, before the handler is invoked.

Example exception:

The process cannot access the file 'S:\.sagas\OrderSaga\a71d248d-0d94-e0bf-3673-361dbd3ec026.json' because it is being used by another process.


Related Articles