Skip to content

Latest commit

 

History

History
123 lines (74 loc) · 5.71 KB

index.md

File metadata and controls

123 lines (74 loc) · 5.71 KB
title summary component reviewed redirects related
NHibernate Persistence
NHibernate-based persistence for NServiceBus
NHibernate
2024-10-22
nservicebus/relational-persistence-using-nhibernate
nservicebus/nhibernate/configuration
nservicebus/nhibernate
samples/nhibernate
samples/multi-tenant/nhibernate

Uses the NHibernate ORM for persistence.

Persistence at a glance

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

Feature
Supported storage types Sagas, Outbox, Subscriptions
Transactions Local database transactions or distributed transactions when available
Concurrency control Optimistic concurrency for correctness + pessimistic concurrency for performance
Scripted deployment Not supported
Installers Table structure is created by installers.

Supported database engines

Note

SQL Server Always Encrypted feature is currently not supported by the persister when using Microsoft SQL Server

Note

When connecting to an Oracle Database, only the ODP.NET-managed driver is supported. The driver is available via the Oracle.ManagedDataAccess NuGet Package.

Warning

Although this persistence will run on the free version of the above engines, i.e. SQL Server Express and Oracle XE, it is strongly recommended to use commercial versions for any production system. It is also recommended to ensure that support agreements are in place from either Microsoft Premier Support, Oracle Support, or another third party support provider.

Usage

The next stage is to tell NServiceBus how to use NHibernate for persistence

snippet: ConfiguringNHibernate

Connection strings

Passing a connection string in the app.config file, as described in the using configuration convention section is possible.

With code

NHibernate persistence requires specifying a connection string.

The connection string might be passed using code configuration:

snippet: ConnectionStringAPI

Customizing the configuration

To customize the NHibernate Configuration object used to bootstrap the persistence mechanism, either provide a ready-made object via code or use convention-based XML configuration. The code-based approach overrides the configuration-based one when both are used.

Passing configuration in code

To specify configuration on a per-concern basis:

snippet: SpecificNHibernateConfiguration

Note

Combine both approaches to define a common configuration and override it for one specific concern.

To use a given NHibernate Configuration object for all the persistence concerns:

snippet: CommonNHibernateConfiguration

Warning

When using the per-concern API to enable the NHibernate persistence, the UseConfiguration method still applies to the common configuration, not the specific concern being enabled. The following code will set up NHibernate persistence only for Subscriptions concern but will override the default configuration for all the concerns.

snippet: CustomCommonNhibernateConfigurationWarning

Using configuration convention

NServiceBus picks up the connection setting from the app.config from connectionStrings and appSettings sections. The convention used for appSettings does not support defining settings specific for a single persistence concern. If this level of granularity is required, use a code-based approach.

Note

When using SQL 2012 or later, change the dialect to MsSql2012Dialect. Additional dialects are available in the NHibernate.Dialect namespace, NHibernate documentation.

snippet: NHibernateAppConfig

Change database schema

The database schema can be changed by defining the default_schema NHibernate property. See the previous Customizing the configuration section.

Subscription caching

The subscriptions can be cached when using NHibernate. This can improve the performance of publishing events as it is not required to request matching subscriptions from storage.

Note

Publishing is performed on stale data. This is only advised in high-volume environments where latency can be an issue.

snippet: NHibernateSubscriptionCaching

Controlling schema

In some cases, it may be necessary to take full control over creating the SQL structure used by the NHibernate persister. In these cases, the automatic creation of SQL structures on installation can be disabled as follows:

For all persistence schema updates:

snippet: DisableSchemaUpdate

For subscription schema update:

snippet: DisableSubscriptionSchemaUpdate

partial: timeout

Generating scripts for deployment

To create scripts for execution in production without using the installers, run an install in a lower environment and then export the SQL structure. This structure can then be migrated to production.