Getting Started

Mapping Endpoint Instances With a Shared File

Component: NServiceBus
NuGet Package: NServiceBus (8.x)

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


Ensure 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. Press enter several times to send some messages.

Verifying that the sample works

  1. The Sales.1 and Sales.2 consoles display information about accepted orders in a 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 routing = endpointConfiguration.UseTransport(new MsmqTransport());
var routingTable = routing.InstanceMappingFile();


The Sales application accepts client orders and publishes the OrderAccepted event.

Shipping and Billing

The Shipping and Billing applications subscribe to OrderAccepted events to execute their business logic.

Shared project

The shared project contains definitions for messages.

Real-world scenario

For the sake of simplicity, all the endpoints in this sample run on a single machine. In production, it is recommended to run each instance on a separate virtual machine. In this case, the instance mapping file would contain machine attributes mapping instances to their machines' hostnames instead of queue attributes used to run more than one instance on a single box.