NServiceBus Host Profiles

Component: NServiceBus Host
NuGet Package: NServiceBus.Host (5.x)
Target Version: NServiceBus 5.x
Standard support for version 5.x of NServiceBus has expired. For more information see our Support Policy.
For endpoints using NServiceBus version 7 and above, it is no longer recommended to use the NServiceBus Host. Use alternative approaches such as Generic Host, NServiceBus Windows Service or NServiceBus Docker Container instead. With NServiceBus version 8, the NServiceBus Host is no longer supported. Refer to the the host upgrade guide for further details and alternatives.

There are many configuration options for endpoints using the NServiceBus host. The endpoint configuration specifies levels of logging, subscription, saga storage, and more.

Profiles enable tailoring endpoints configuration for different environments without recompiling code.

There are two categories of profile:

  • Environment profiles can be used to avoid common configuration errors when manually moving a system between different environments, e.g., from development to production.
  • Feature profiles allow turning NServiceBus features, such as performance counters, on and off with no code changes.

Default profiles

By default, NServiceBus comes with a set of predefined environments and feature profiles. It's also possible to create custom profiles or customize the default profiles; to learn more about those options, refer to the NServiceBus host profiles customization article.

Environment profiles

There are three built-in environment profiles that adjust the host behavior to the environment in which the endpoint is running. These profiles can be used to switch between different environments during development, testing, and deployment.

Lite profile

Suitable for running on a development machine, for example, inside Visual Studio.

  • InMemory persistence is used for storing information like sagas, subscriptions, timeouts, etc. This is a convenient option for development, but should not be used in production.
  • The Lite profile by default turns on the TimeoutManager.
  • Installers are always invoked when running the Lite profile.
  • Logging is output to the console.

Integration profile

Suitable for running the endpoint in integration and QA environments.

  • Installers are invoked to make deployment easy to automate.
  • Logging is output to the console by default.

Production profile

The default if no explicit profile is defined. This profile configures the endpoint for production use.

  • Installers are not invoked since the endpoint is often installed as a Windows Service and does not run with elevated privileges. Installers run only when installing the host or when the code runs inside Visual Studio in Debug mode.
  • All configured storage is durable and suitable for scale out.
  • Logging is output to a log file in the runtime directory.
  • Performance counters are installed by default.

Feature profiles

  • Master makes the endpoint a "master node endpoint". This means that it runs the gateway for multi-site interaction, the timeout manager, and the distributor. It also starts a worker that enlists with the distributor. It cannot be combined with the Worker or Distributor profiles.
  • Worker makes the current endpoint enlist as a worker with its distributor running on the master node. It cannot be combined with the Master or Distributor profiles.
  • Distributor starts the endpoint as a distributor only. This means that the endpoint does no work and only distributes the load among its enlisted workers. It cannot be combined with the Master and Worker profiles.
  • PerformanceCounters turns on the NServiceBus performance counters. Performance counters are enabled by default when running the Production profile.

Specifying which profiles to run

If the host is run without specifying a profile, NServiceBus defaults to the Production profile.

To activate a specific profile, pass the full name of the profile in the command line when starting the host. Type names are case-insensitive. Profiles can be combined by separating them with white space.

For example, to run the endpoint with the Integration and PerformanceCounters profiles:

.\NServiceBus.Host.exe nservicebus.integration nservicebus.performancecounters

When installing the host as a Windows Service, the profiles used during installation are saved, and they are used every time the host starts. In order to install the host with the Production and PerformanceCounters profiles:

.\NServiceBus.Host.exe /install nservicebus.production nservicebus.performancecounters


The built-in profiles, by default use the console, and rolling file appends, logging information at the Info threshold.

The rolling file logs are written to the logfile in the same directory as the executable. The file grows to a maximum size of 1MB; then a new file is created. A maximum of ten files is kept, then the oldest file is erased. If not otherwise specified, the logging threshold is set to the Warn level. To configure the logging threshold, see changing logging levels.

For changes to the configuration to have an effect, the process must be restarted.

Refer to the logging configuration article to learn about customizing logging configuration.


In NServiceBus version 5 and above, persistence must be explicitly configured.

The built-in profiles use the following default persistence settings:

TimeoutIn-MemoryAs configuredAs configured
SubscriptionIn-MemoryAs configuredAs configured
SagaIn-MemoryAs configuredAs configured
GatewayIn-MemoryAs configuredAs configured

In the Lite profile, NServiceBus Host will always use the in-memory persistence. In the Integration and Production profiles, the host verifies if a specific persistence mechanism is provided, e.g., in the endpoint configuration. If not specified otherwise, then RavenDB persistence will be used by default.

Last modified