Getting Started
Architecture
NServiceBus
Transports
Persistence
ServiceInsight
ServicePulse
ServiceControl
Monitoring
Samples

Gateway Upgrade Version 1 to 2

Component: Gateway

This is part of the NServiceBus Upgrade Guide from Version 5 to 6, which also includes the following individual upgrade guides for specific components:

Feature Details
Transports
Persistence
Hosting
Other

Extensibility

IForwardMessagesToSites, IRouteMessagesToEndpoints, and IRouteMessagesToSites have been deprecated and are no longer available as extension points in the gateway. These have been replaced by custom channel types.

Concurrency configuration

NumberOfWorkerThreads is deprecated as a parameter for channels in the endpoint config file. Use MaxConcurrency to set the maximum number of messages that should be processed at any given time by the gateway instead.

// For Gateway version 2.x
<GatewayConfig>
  <Channels>
    <Channel Address="http://hq.mycorp.com/"
             ChannelType="Http"
             MaxConcurrency="3"/>
  </Channels>
</GatewayConfig>

// For Gateway version 1.x
<GatewayConfig>
  <Channels>
    <Channel Address="http://hq.mycorp.com/"
             ChannelType="Http"
             NumberOfWorkerThreads="3"/>
  </Channels>
</GatewayConfig>

Automatic retries

In versions 2 and above, the gateway has its own retry mechanism. It will retry failed messages four times by default, increasing the delay by 60 seconds each time. The default retry policy can be replaced.

Notifications

In versions 2 and above, the gateway does not provide error notifications. When an error occurs during sending of a message to other sites, the message will be retried and possibly moved to the error queue.

Note that in version 1, when subscribing to error notifications, the notification is received in the situation described above.

Backward compatibility migration

In order to send or publish messages to a Gateway version 1.x, it is required to set the TimeToBeReceived and NonDurableMessage headers as the Gateway 1.x receiver expects these headers to be present.

The following message mutator can be temporarily deployed until all Gateway 1.x endpoints are migrated to a newer major version.

// For Gateway version 3.x
public class AddRequiredHeadersForGatewayBackwardsCompatibility : IMutateOutgoingTransportMessages
{
    public Task MutateOutgoing(MutateOutgoingTransportMessageContext context)
    {
        var headers = context.OutgoingHeaders;
        headers.Add(Headers.TimeToBeReceived, TimeSpan.MaxValue.ToString());
        headers.Add(Headers.NonDurableMessage, false.ToString());

        return Task.CompletedTask;
    }
}

// For Gateway version 2.x
public class AddRequiredHeadersForGatewayBackwardsCompatibility : IMutateOutgoingTransportMessages
{
    public Task MutateOutgoing(MutateOutgoingTransportMessageContext context)
    {
        var headers = context.OutgoingHeaders;
        headers.Add(Headers.TimeToBeReceived, TimeSpan.MaxValue.ToString());
        headers.Add(Headers.NonDurableMessage, false.ToString());

        return Task.CompletedTask;
    }
}

Related Articles