The MSMQ transport in NServiceBus is a distributed transport in which the MSMQ process runs on each machine, storing messages locally before being forwarded to other machines. In this model, each
endpoint connects to the local MSMQ process and both the queue name and the host name must be specified when addressing a different endpoint.
Because the MSMQ queues are not accessible from outside the machine they are hosted in, NServiceBus endpoints using the MSMQ transport are not able to use the competing consumers pattern to scale out with a single shared queue.
Sender-side distribution can be used to overcome this limitation.
Mapping the logical destination to the physical address containing the queue and host names is the responsibility of physical routing.
The preferred way of configuring the physical routing is via an instance mapping file.
When using instance mapping:
- The settings have no effect on audit and error queues.
- publishing: The publisher publishes messages only to endpoint instances that have subscribed to the events, ignoring the settings in the mapping file (the address of the subscriber that was provided in the subscription messgae is used).
- subscribing: Subscription messages are sent to all publisher instances listed in the instance mapping file.
The instance mapping file is a simple XML file that must be located either on a local hard drive or a network drive. When using MSMQ as the transport, NServiceBus automatically looks for an
instance-mapping. file in
instance-mapping.xmlfile may not be located in
AppDomain.BaseDirectory. In this case specify the path using the
<endpoints> <endpoint name="Sales"> <instance machine="VM-1"/> </endpoint> <endpoint name="Shipping"> <instance machine="VM-2"/> </endpoint> <endpoint name="Billing"> <instance machine="VM-3"/> </endpoint> </endpoints>
The mapping file is processed before the endpoint starts up and then re-processed at regular intervals so that changes in the document are reflected in the behavior of NServiceBus automatically. If the document is not present in its configured location when endpoint starts up, NServiceBus does not search again for the file at runtime. If the file is deleted when the endpoint is already running, it will continue to run normally with the last successfully-read routes.
There are many different options to consider when deploying routing configuration.
- Many endpoints can be configured to use one centralized mapping file on a network drive accessible by all, creating a single file that describes how messages flow across an entire system. A given endpoint does not care if the file contains information for endpoints it does not need.
- The mapping file can be kept in a centralized location and replicated out to many servers on demand, allowing each endpoint to read the file from a location on the local disk.
- Each endpoint can keep its own instance mapping file containing only information for the endpoints it needs to know about, which can be deployed in the same directory as the endpoint binaries and only modified as part of a controlled deployment process.
The following default settings can be adjusted:
Specifies the interval between route data refresh attempts.
Default: 30 seconds
var transport = endpointConfiguration.UseTransport<MsmqTransport>(); var routing = transport.Routing(); var instanceMappingFile = routing.InstanceMappingFile(); var fileSettings = instanceMappingFile.FilePath(@"C:\instance-mapping.xml"); fileSettings.RefreshInterval(TimeSpan.FromSeconds(45));
Specifies the path and file name of the instance mapping file. This can be a relative or an absolute file path. Relative file paths are resolved from
var transport = endpointConfiguration.UseTransport<MsmqTransport>(); var routing = transport.Routing(); var instanceMappingFile = routing.InstanceMappingFile(); instanceMappingFile.FilePath(@"C:\instance-mapping.xml");
For compatibility reasons it can also be configured in the same way as in NServiceBus bersion 5 and older with the
UnicastBusConfig/ configuration section:
<configuration> <configSections> <section name="UnicastBusConfig" type="NServiceBus.Config.UnicastBusConfig, NServiceBus.Core"/> </configSections> <UnicastBusConfig> <MessageEndpointMappings> <add Assembly="Sales.Messages" Endpoint="Sales@VM-1" /> <add Assembly="Billing.Messages" Endpoint="Billing@VM-2" /> </MessageEndpointMappings> </UnicastBusConfig> </configuration>