Particular/NServiceBus 4.0.0 on GitHub

Compatibility and Upgrades

Prerequisite: NServiceBus V4.0 requires RavenDB 2.0.0.2261 or later

NServiceBus V4.0 requires the latest RavenDB v2.x to be installed on the same machine.

You can manually validate the currently installed version of RavenDB by connecting to the RavenDB instance (http://localhost:8080) and examining the bottom status bar where the server and client build numbers are noted. Build numbers prior to 2000 indicate a RavenDB version earlier than 2.x.
If there is no existing and active installation of RavenDB v2.x on the machine, the NServiceBus installer automatically installs RavenDB v2.x.
If the NServiceBus V4.0 installer finds a RavenDB version prior to 2.x on the target machine, it installs a new instance of RavenDB v2.x with no impact on the existing instance.

NServiceBus V4.0 is not compatible with NServiceBus V2.6 (or earlier)

As you can see, a large number of features were added to NServiceBus. As a result, NServiceBus V4.0 is not compatible with NServiceBus V2.6. Furthermore, only messages marked as events (IEvent or DefiningEventsAs()) will be auto-subscribed.

PowerShell cmdlets - breaking changes

NServiceBus.Host no longer supports /installinfrastructure. Use PowerShell cmdlets instead.
PowerShell cmdlets have been renamed so that they do not clash with any existing cmdlets. See details below.

Autosubscriptions

Only messages marked as events (IEvent or DefiningEventsAs()) will be auto-subscribed.

Default transaction isolation level

The default transaction isolation level is now ReadCommitted. To revert to Serializable, use this code:

Configure.Transactions.Advanced(settings => 
   settings.IsolationLevel(IsolationLevel.Serializable));

Working with Error and Audit queues

The Management Service (installed with NServiceBus V4.0) consumes the messages from the defined MSMQ Error and Audit queues. While the Management Service is running, you can view the the Error messages by viewing the Error.log queue, and auditing data can be viewed using ServiceInsight. You can manage the Management Service (named "Particular.Management") like any other Windows Service (see MSDN article on how to "Start, stop, pause, resume, or restart a service").

Callback behaviour when scaling out

When using a broker based transport endpoints will use a unique input per machine by default unless running the NServiceBus Host in As_aServer or As_aPublisher. This ensures callbacks work as expected when scaling out. If you are not using callbacks use Configure.ScaleOut(s=>s.UseSingleBrokerQueue()); to use the same central queue.

Namespace changes to Types and Interfaces

INeedInitialization: Prior to NServicebus 4.0, The interface INeedInitialization was defined in NServiceBus.Config. In NServicebus 4.0, it is defined at the higher namespace level, i.e NServiceBus. If you receive the following compiler error, please remove the using reference to NServiceBus.Config and resolve using NServiceBus: error CS0104:

'INeedInitialization' is an ambiguous reference between 'NServiceBus.INeedInitialization' and 'NServiceBus.Config.INeedInitialization'

NServiceBus.WebService: Exposing an endpoint as a WebService using NServiceBus.Webservice<YourMessage, YourEnum> has been deprecated in 4.0. Use the WcfService option instead. For example:

YourWcfService : WcfService<YourMessage, YourEnum>

SecondLevelRetries: The type SecondLevelRetries (used in the NServiceBus.Management.Retries namespace to configure the retry and the timeout policy) has been moved to the NServiceBus.Features namespace. While version 3.3.x had a separate policy for managing second level retries and timeouts, this has been merged into the new RetryPolicy in NServiceBus 4.0 and it is capable of achieving both functions.

TransactionalTransport: The type TransactionalTransport, which used to be defined in the namespace NServiceBus.Unicast.Transport.Transactional has been renamed to TransportReceiver and moved to the namespace NServiceBus.Unicast.Transport. If you receive the following compiler error, resolve using the new namespace specified above.

error CS0246: The type or namespace name 'TransactionalTransport' could not be found (are you missing a using directive or an assembly reference?)

New Transports Support and Configuration

These new transport samples were added to the NServiceBus samples, illustrating how to configure the new transports:

Messaging.ActiveMQ
Messaging.RabbitMQ
Messaging.SqlServer
Messaging.MSMQ

New configuration APIs simplify the transports configuration and make it consistent across all transports. In your config file, specify a connection string, like this:

<connectionStrings>
<!-- MSMQ -->
<add name="NServiceBus/Transport" connectionString="deadLetter=true;
   journal=true;useTransactionalQueues=true;
   cacheSendConnection=true"/>
<!-- ActiveMQ -->
<add name="NServiceBus/Transport" 
   connectionString="ServerUrl=activemq:tcp://localhost:61616"/>
<!-- RabbitMQ-->
<add name="NServiceBus/Transport" 
   connectionString="host=localhost"/>
<!-- SqlServer -->
<add name="NServiceBus/Transport" 
   connectionString="Data Source=.\SQLEXPRESS;Initial Catalog=nservicebus;
   Integrated Security=True"
/>
</connectionStrings>

You then have two options to specify the transport:
Specify it as part of the IConfigureThisEndpoint class declaration, e.g.:

public class  EndpointConfig : IConfigureThisEndpoint, AsA_Server, 
       UsingTransport<RabbitMQ>

Or specify it in the IWantCustomInitialization.Init method,

public class EndpointConfig : IConfigureThisEndpoint, AsA_Server, 
IWantCustomInitialization
{
   public void Init(){
      Configure.With().DefaultBuilder()
         .UseTransport<RabbitMQ>()
   }
}

New NuGet packages for the new transports

These NuGet packages are also available:

Example of how to install the NServiceBus.ActiveMQ package

PM> Install-Package NServiceBus.ActiveMQ

New Transport DLLs

Add a reference to the new transport DLLs (in the Binaries directory):

NServiceBus.Transports.RabbitMQ.dll
NServiceBus.Transports.SQlServer.dll
NServiceBus.Transports.ActiveMQ.dll

MSMQ is currently in NServiceBus.Core.dll and does not require any additional reference. NuGet adds the reference automatically.

Configuration Changes

XmlMessageSerializer now supports not wrapping messages in a element for single messages. This makes interoperability with other systems easier.
To turn on this feature:

.XmlSerializer( dontWrapSingleMessages: true )

The MsmqTransportConfig section has been deprecated in favour of TransportConfig section, like this:

<section name="TransportConfig" 
   type="NServiceBus.Config.TransportConfig, NServiceBus.Core"/>
<TransportConfig MaximumConcurrencyLevel="10" MaxRetries="3" 
   MaximumMessageThroughputPerSecond="10"/>

INeedToInstallSomething: The INeedToInstallSomething interface is now resolved via the container.

NHibernate Configuration

NHibernate settings have been simplified, as follows:

<appSettings><
!-- dialect is the only required NHibernate property -->
<add key="NServiceBus/Persistence/NHibernate/dialect"
   value="NHibernate.Dialect.MsSql2008Dialect"/>
<!-- other optional settings examples -->
<add key="NServiceBus/Persistence/NHibernate/connection.provider" 
   value="NHibernate.Connection.DriverConnectionProvider"/>
<add key="NServiceBus/Persistence/NHibernate/connection.driver_class"
   value="NHibernate.Driver.Sql2008ClientDriver"
/>

<!-- For more settings: 
see http://www.nhforge.org/doc/nh/en/#configuration-hibernatejdbc 
and http://www.nhforge.org/doc/nh/en/#configuration-optional 
-->
</appSettings><
connectionStrings>
<!-- Default connection string for all Nhibernate/Sql persisters -->
<add name="NServiceBus/Persistence" 
   connectionString="Data Source=.\SQLEXPRESS;Initial Catalog=nservicebus;
   Integrated Security=True"/>
<!-- Optional overrides per persister -->
<add name="NServiceBus/Persistence/NHibernate/Timeout" 
   connectionString="Data Source=.\SQLEXPRESS;Initial Catalog=timeout;
   Integrated Security=True"/>
<add name="NServiceBus/Persistence/NHibernate/Saga" 
   connectionString="Data Source=.\SQLEXPRESS;Initial Catalog=sagas;
   Integrated Security=True"/>
<add name="NServiceBus/Persistence/NHibernate/Subscription"
   connectionString="Data Source=.\SQLEXPRESS;Initial Catalog=subscription;
   Integrated Security=True"/>
<add name="NServiceBus/Persistence/NHibernate/Gateway" 
   connectionString="Data Source=.\SQLEXPRESS;Initial Catalog=gateway;
Integrated Security=True"/>
<add name="NServiceBus/Persistence/NHibernate/Distributor"
connectionString="Data Source=.\SQLEXPRESS;Initial Catalog=distributor;
Integrated Security=True"/>
</connectionStrings>

Performance Counters

New throughput performance counters and updated performance counters are available:

NServiceBus license installed per machine

Licenses can now be installed in HKLM, allowing you to install one license per server instead of installing a license per endpoint or per Windows account.

LicenseInstaller.exe C:\License.xml

Powershell cmdlet Updates

NServiceBus PowerShell cmdlets have moved to NServiceBus.PowerShell.dll. To import it, run this:

PM> Import-Module .\NServiceBus.PowerShell.dll

NServiceBus Powershell cmdlets have been renamed so they do not clash with any existing cmdlets:

Installs a NServiceBus license file.
Install-NServiceBusLicense
Displays all messages in a queue.
Get-NServiceBusMSMQMessage
Displays the NServiceBus installed version.
Get-NServiceBusVersion
Installs DTC on the machine.
Install-NServiceBusDTC
Installs RavenDB on the machine.
Install-NServiceBusRavenDB
Installs NServiceBus performance counters on the machine.
Install-NServiceBusPerformanceCounters
Installs MSMQ on the machine.
Install-NServiceBusMSMQ
Validates if DTC is installed and running on the machine.
Test-NServiceBusDTCInstallation
Ensures RavenDB is on the machine.
Test-NServiceBusRavenDBInstallation
Validates that NServiceBus performance counters are correctly installed on the machine.
Test-NServiceBusPerformanceCountersInstallation
Validates MSMQ is correctly installed on the machine.
Test-NServiceBusMSMQInstallation
Adds the required configuration section to the config file.
Add-NServiceBusMessageForwardingInCaseOfFaultConfig
Shows the default error and audit queues.
Get-NServiceBusLocalMachineSettings
Allows specifying the default error and audit queues.
Set-NServiceBusLocalMachineSettings
NServiceBus.Host no longer supports /installinfrastructure. Use PowerShell cmdlets instead.

New Endpoint Configuration API

Sample usage:

Configure.Endpoint.AsSendOnly()
   .Advanced(settings => settings.DisableDurableMessages());
Configure.Transactions.Enable() 
   .Advanced(settings => settings.IsolationLevel(IsolationLevel.Serializable)
   .DefaultTimeout(TimeSpan.FromSeconds(40)) 
   .DisableDistributedTransactions());

Embedded RavenDB

RavenDB is not ilmerged anymore. It is embedded instead, using https://github.com/Fody/Costura#readme.
The embedding enables client updates (but may require binding redirects). It also allows passing your own DocumentStore, thereby providing full configuration flexibility.
Audit and Error Queue Defaults
Server defaults for audit and error queues can now be specified in the registry (see new PowerShell cmdlet Get/Set-NServiceBusLocalMachineSettings, above).

Unattended Installation

The NServiceBus installer can be executed in quiet, unattended mode by running the following command:

Particular.NServiceBus-4.0.x.exe /q /l install.log

This will run the installer in quiet mode and create a log file called install.log.
Note that the name of the installer file may differ from the above example, and that running the installer in quiet mode still opens a browser window to the Particular Software website when the installation is completed.

Known Issues

ActiveMQ requires enabling the Scheduler.
You can do this by setting the schedulerSupport="true" attribute to the configuration in activemq.xml:

<broker xmlns="http://activemq.apache.org/schema/core" brokerName="localhost" 
dataDirectory="${activemq.data}" schedulerSupport="true">

ActiveMQ Client connection fails when hostname includes a hyphen
See https://issues.apache.org/jira/browse/AMQNET-399.

NMS Client for ActiveMQ

The release contains a custom build of Apache.NMS.ActiveMQ.1.5.6 client. This custom build fixes the following issues:

The custom build will be removed as soon as the official NMS client is updated with the above fixes.

Installing RavenDB v2.x on a machine that already has RavenDB v1.x

When installing NServiceBus V4.x on a machine where an instance of RavenDB v1.x exists (default listening on port 8080), the installer will identify the existing RavenDB instance and try to capture the next available port (8081, 8082, etc.) instead of the default 8080 port. Once an available port is found, the installer installs RavenDB v2.x instance as a new Windows service, side-by-side with the existing RavenDB v1.x installation.

By the end of the installation there will be two RavenDB services running side by side on the machine:

RavenDB
RavenDB v2

To uninstall RavenDB v2, follow these steps:

Open a command line and navigate to this directory:
%Program Files%\NServiceBus.Persistence.V4
Execute this command:
Raven.Server.exe –uninstall –service-name=RavenDB-v2

Note that uninstalling NServiceBus (via the installer or through Control Panel > Programs) does not uninstall any RavenDB installations.

###Transport samples do not work with Visual Studio 2010

All the new transports introduced with NServiceBus 4.0 do not work with Visual Studio 2010. The supplied samples currently work only with Visual Studio 2012.

Windows Azure

Updated to the version 2.0 of the storage client.
NHibernate is no longer needed when using NServiceBus on Windows Azure (details).

RabbitMQ

Has improved support for high performance polymorphic pub/sub (details).
Thanks to Fawad Halim and Jeff Sogolov from ADP!

NHibernate

Sagas are now mapped using the table per concrete class strategy to avoid join tables when using base classes for sagas. This improves performance when reading/writing sagas to the database (details).

SQL Server Transport

NOTE: Due to schema changes from NServiceBus V4.0 Beta, to use SQL Server Transport with NServiceBus V4.0, delete any tables created with NServiceBus V4.0 Beta.

No longer using the deprecated timestamp column type (details).
Machine name is no longer used in the address for broker based transports. This fixes and issue when scaled out subscribers would receive duplicate messages (details).
Uses the ROWLOCK hint to make sure that no table locks are used (details).
Fixed a critical bug in the sql transport where a exception from a message handler would cause the message to be retried indefinitely (details).
The video store sample has been improved with better naming and also displays how to use our InMemory support for domain events (details).
Profiles are now working correctly when endpoints are installed as windows services (details).
Impersonation support renamed to better reflect the actual use case for it (details).
Improved the API for reacting to profiles being enabled (details).
Switching between persistence technologies is now easier (details).
ISagaStartedBy is now obsolete. To start sagas, use IAmStartedByMessages instead (details).

Installing NServiceBus on Windows Server 2012

When installing NServiceBus v4 on Windows Server 2012, MSMQ must be installed manullay prior to NServiceBus installation. See MSDN article "Installing and Managing Message Queuing" for more details.