Error handling

NServiceBus has exception catching and handling logic of its own which surrounds all calls to user code. When an exception bubbles through to the NServiceBus infrastructure, it rolls back the transaction on a transactional endpoint, causing the message to be returned to the queue, and any messages that the user code tried to send or publish to be undone as well.

Configure your error queue

When a message fails NServiceBus automatically retries the message. On repeated failure NServiceBus forwards that message to a designated error queue.

Error queue can be configured in several ways.

Using Code

You can configure the target error queue at configuration time.

BusConfiguration busConfiguration = new BusConfiguration();
busConfiguration.SendFailedMessagesTo("targetErrorQueue");

Using a IConfigurationProvider

class ProvideConfiguration : IProvideConfiguration<MessageForwardingInCaseOfFaultConfig>
{
    public MessageForwardingInCaseOfFaultConfig GetConfiguration()
    {
        return new MessageForwardingInCaseOfFaultConfig
        {
            ErrorQueue = "error"
        };
    }
}
class ProvideConfiguration : IProvideConfiguration<MessageForwardingInCaseOfFaultConfig>
{
    public MessageForwardingInCaseOfFaultConfig GetConfiguration()
    {
        return new MessageForwardingInCaseOfFaultConfig
        {
            ErrorQueue = "error"
        };
    }
}

Using a ConfigurationSource

public class ConfigurationSource : IConfigurationSource
{
    public T GetConfiguration<T>() where T : class, new()
    {
        if (typeof(T) == typeof(MessageForwardingInCaseOfFaultConfig))
        {
            MessageForwardingInCaseOfFaultConfig errorConfig = new MessageForwardingInCaseOfFaultConfig
            {
                ErrorQueue = "error"
            };

            return errorConfig as T;
        }

        // To in app.config for other sections not defined in this method, otherwise return null.
        return ConfigurationManager.GetSection(typeof(T).Name) as T;
    }
}
public class ConfigurationSource : IConfigurationSource
{
    public T GetConfiguration<T>() where T : class, new()
    {
        if (typeof(T) == typeof(MessageForwardingInCaseOfFaultConfig))
        {
            MessageForwardingInCaseOfFaultConfig errorConfig = new MessageForwardingInCaseOfFaultConfig
            {
                ErrorQueue = "error"
            };

            return errorConfig as T;
        }

        // To in app.config for other sections not defined in this method, otherwise return null.
        return ConfigurationManager.GetSection(typeof(T).Name) as T;
    }
}

Then at configuration time:

Configure configure = Configure.With();
configure.CustomConfigurationSource(new ConfigurationSource());
busConfiguration.CustomConfigurationSource(new ConfigurationSource());
busConfiguration.CustomConfigurationSource(new ConfigurationSource());

Using App.Config

<configuration>
  <configSections>
    <section name="MessageForwardingInCaseOfFaultConfig" 
             type="NServiceBus.Config.MessageForwardingInCaseOfFaultConfig, NServiceBus.Core" />
  </configSections>
  <MessageForwardingInCaseOfFaultConfig ErrorQueue="error@adminMachine"/>
</configuration>
<configuration>
  <configSections>
    <section name="MessageForwardingInCaseOfFaultConfig" 
             type="NServiceBus.Config.MessageForwardingInCaseOfFaultConfig, NServiceBus.Core" />
  </configSections>
  <MessageForwardingInCaseOfFaultConfig ErrorQueue="error@adminMachine"/>
</configuration>
In NServiceBus Version 3.x the ErrorQueue settings can be set both via the new MessageForwardingInCaseOfFaultConfig section and the old MsmqTransportConfig section.

For more details on MsmqTransportConfig read this article.

Monitor your error queue

Administrators should monitor that error queue so that they can see when problems occur. The message in the error queue contains the source queue and machine so that the administrator can see what's wrong with that node and possibly correct the problem, for example, bringing up a database that went down.

Monitoring and handling of failed messages with ServicePulse provides access to full exception details (including stack-trace, and through ServiceInsight it also enables advanced debugging with all message context. It also provides a "retry" option to send the message back to the endpoint for re-processing. For more details, see Introduction to Failed Messages Monitoring in ServicePulse.

If either ServicePulse or ServiceInsight is not available in your environment you can perform this operation using the native management tools of your selected transport of by code or powershell:

ReturnToSourceQueue.exe

The MSMQ command line tool ReturnToSourceQueue has been deprecated and moved to ParticularLabs/MsmqReturnToSourceQueue.

Samples

  • Automatic Retries
    With SLR, the message causing the exception is instantly retried via a retries queue instead of an error queue.
  • Fault Tolerance
    See how NServiceBus messaging can get past all sorts of failure scenarios.
  • Notifications
    Illustrates using the notifications API

Related Articles


Last modified 2015-11-10 11:50:35Z