Mapping endpoint instances with a shared file

Component: NServiceBus
NuGet Package NServiceBus (6.x)

The sample demonstrates how to use a file to describe the mapping between logical endpoints and their physical instances (deployments of given logical endpoint to a concrete VM).


Make sure MSMQ is installed and configured as described in the MSMQ Transport - MSMQ Configuration section.

Running the project

  1. Start the solution
  2. The text Press <enter> to send a message should be displayed in the Client's console window.
  3. Hit enter several times to send some messages.

Verifying that the sample works correctly

  1. The Sales.1 and Sales.2 consoles display information about accepted orders in round-robin fashion.
  2. The Shipping endpoint displays information that orders were shipped.
  3. The Billing endpoint displays information that orders were billed.

Code walk-through

This sample contains four projects.

Instance Mapping File

Shared between all endpoints.

  <endpoint name="Samples.InstanceMappingFile.Sales">
    <!-- Scaled-out endpoint -->
    <instance queue="Samples.InstanceMappingFile.Sales-1"/>
    <instance queue="Samples.InstanceMappingFile.Sales-2"/>
  <!--Multiple endpoints hosted on same machine-->
  <endpoint name="Samples.InstanceMappingFile.Billing">
    <instance machine="localhost"/>
  <endpoint name="Samples.InstanceMappingFile.Shipping">
    <instance machine="localhost"/>


The Client application submits the orders for processing by the back-end systems by sending a PlaceOrder command. The client, as well as all other endpoints, uses the file based instance mapping:

var transport = endpointConfiguration.UseTransport<MsmqTransport>();
var routing = transport.Routing();
var routingTable = routing.InstanceMappingFile();


The Sales application accepts clients' orders and publishes the OrderAccepted event.

In real-world scenarios NServiceBus endpoints are scaled out by deploying multiple physical instances of a single logical endpoint to multiple machines. For simplicity, in this sample the scale out is simulated by having two separate projects, Sales and Sales2.

Shipping and Billing

Shipping and Billing applications subscribe to OrderAccepted event in order to execute their business logic.

Shared project

The shared project contains definitions for messages.

Real-world scenario

For the sake of simplicity, in this sample all the endpoints run on a single machine. In real world is is usually best to run each instance on a separate virtual machine. In such case the instance mapping file would contain machine attributes mapping instances to their machines' host names instead of queue attributes used to run more than one instance on a single box.

Last modified