Tuning endpoint message processing

Component: NServiceBus | Nuget: NServiceBus (Version: 4.x)
Standard support for version 4.x of NServiceBus has expired. For more information see our Support Policy.

NServiceBus uses defaults that ensure good performance in most common cases. While this is usually the preferred mode of operation there are situations where tuning needs to be applied.

Tuning concurrency

The default concurrency limit is 1

Define a maximum concurrency setting that will make sure that no more messages than the specified value is ever being processed at the same time. Set this value to 1 to process messages sequentially. If not specified the transport will choose an optimal value.

Examples where concurrency tuning is relevant are

  • Non thread safe code that needs to run sequentially
  • Databases that might deadlock when getting too many concurrent requests


Define a maximum value for the number of messages per second that the endpoint will process at any given time. This will help avoiding the endpoint from overloading sensitive resources that it's using like web-services, databases, other endpoints etc. A concrete example could be an integration endpoint calling a web API, like api.github.com, that have restrictions on the number or requests per unit of time allowed.

By default no throughput restrictions will be enforce.


The default limits of an endpoint can be changed in both code and via app.config.

Via a IConfigurationProvider

public class ProvideConfiguration :
    public TransportConfig GetConfiguration()
        return new TransportConfig
            MaximumConcurrencyLevel = 5,
            MaximumMessageThroughputPerSecond = 10

Via app.config

By using raw xml.

  <section name="TransportConfig"
           type="NServiceBus.Config.TransportConfig, NServiceBus.Core"/>
<TransportConfig MaximumConcurrencyLevel="5"

Run time settings

Concurrency and throughput throttling to be changed and read at run time using the code below.

Optimizing at run time

var transport = unicastBus.Transport;

Reading current values at run time

var transport = unicastBus.Transport;
var messageThroughputPerSecond = transport.MaximumMessageThroughputPerSecond;
var maximumConcurrencyLevel = transport.MaximumConcurrencyLevel;

Last modified