Getting Started

Controlling script generation

Component: Sql Persistence
Target Version: NServiceBus 7.x

SQL installation scripts are created as compile-time outputs alongside a project's binary outputs. These scripts can be promoted to a directory under source control so that differences can be tracked and analyzed.

Scripts will be created in the directory format of [CurrentProjectDebugDir]\NServiceBus.Persistence.Sql\[SqlDialect].

For example, for a project named ClassLibrary built in Debug mode, the following directories will be created.

  • ClassLibrary\bin\Debug\NServiceBus.Persistence.Sql\MsSqlServer
  • ClassLibrary\bin\Debug\NServiceBus.Persistence.Sql\MySql
  • ClassLibrary\bin\Debug\NServiceBus.Persistence.Sql\Oracle
  • ClassLibrary\bin\Debug\NServiceBus.Persistence.Sql\PostgreSql

Scripts will also be included in the list of project output files. This means that those files produced will be copied to the output directory of any project that references it.

Disabling script generation

In version 4.2 and below, script generation can be disabled by removing the NServiceBus.Persistence.Sql.MsBuild package from the project.

In version 4.3 and above, the script generation capability isn't contained in a separate package. Execution of the script generation task can be completely disabled by including the following in the project file:


SqlPersistenceSettings attribute

Scripts creation is configured via [SqlPersistenceSettings] applied to the target assembly.

To produce all scripts

[assembly: SqlPersistenceSettings(
    MsSqlServerScripts = true,
    MySqlScripts = true,
    OracleScripts = true,
    PostgreSqlScripts = true)]

To produce only MS SQL Server scripts

[assembly: SqlPersistenceSettings(MsSqlServerScripts = true)]

To produce only MySQL scripts

[assembly: SqlPersistenceSettings(MySqlScripts = true)]

To produce only Oracle scripts

[assembly: SqlPersistenceSettings(OracleScripts = true)]

To produce only PostgreSql scripts

[assembly: SqlPersistenceSettings(PostgreSqlScripts = true)]

Toggle script creation

At compile time the SQL persister validates that sagas are of the correct base type and match the required conventions. This can be problematic when mixing persisters. For example using the SQL persistence for timeouts but another persister for saga storage. As such it is possible to selectively control what SQL scripts are generated at compile time, and as a side effect avoid the convention validation of sagas.

Disable outbox script creation

[assembly: SqlPersistenceSettings(
    ProduceOutboxScripts = false)]

Disable saga script creation

[assembly: SqlPersistenceSettings(
    ProduceSagaScripts = false)]

Disable subscriptions script creation

[assembly: SqlPersistenceSettings(
    ProduceSubscriptionScripts = false)]

Disable timeout script creation

[assembly: SqlPersistenceSettings(
    ProduceTimeoutScripts = false)]


As stated above, scripts are created in the target project output directory. This directory will usually be excluded from source control. To ensure the scripts are added to source control, they can be promoted to a location outside the build directory.

Some token replacement using MSBuild variables is supported.

  • $(SolutionDir): The directory of the solution.
  • $(ProjectDir): The directory of the project

All tokens are drive + path and include the trailing backslash \.

[assembly: SqlPersistenceSettings(
    ScriptPromotionPath = "$(SolutionDir)PromotedSqlScripts")]

The path calculation is performed relative to the current project directory. So, for example, a value of PromotedSqlScripts (with no tokens) would evaluate as $(ProjectDir)PromotedSqlScripts.

Related Articles