MSMQ Transport

Transport at a glance

Configuring the endpoint

To use MSMQ as the underlying transport:

endpointConfiguration.UseTransport(new MsmqTransport());

Advantages

• MSMQ is natively available as part of the Windows operating system. In Windows servers, the MSMQ role might need to be turned on.
• MSMQ offers transactional queues which also support distributed transactions. With the transactional behavior, it is possible to get exactly-once delivery.
• MSMQ provides a store and forward mechanism. Therefore it promotes a more natural bus-style architecture. When sending messages to unavailable servers, the messages are stored locally in the outgoing queues and will be delivered automatically once the machine comes back online.

Disadvantages

• MSMQ does not offer a native publish-subscribe mechanism, therefore it requires NServiceBus persistence to be configured for storing event subscriptions. Explicit routing for publish/subscribe must also be specified.
• Many organizations don't have the same level of operational expertise with MSMQ that they do with other technologies (e.g. SQL Server), so it may require additional training. For example, as MSMQ is not a broker transport, the messages could be on different servers, and managing the storage space on each machine is important.
• As MSMQ is a store and forward transport, it requires more setup for load balancing. I.e. it requires either a sender side distribution to be configured.
• MSMQ (i.e. the System.Messaging namespace) is not available on .NET Core

MSMQ configuration

NServiceBus requires a specific MSMQ configuration to operate.

The supported configuration is to have only the base MSMQ service installed with no optional features. To enable the supported configuration, use the Install-NServiceBusMSMQ cmdlet from the NServiceBus PowerShell Module.

Alternatively, the MSMQ service can be installed manually. When installing manually do not enable the following components:

• MSMQ Active Directory Domain Services Integration
• MSMQ HTTP Support
• MSMQ Triggers
• Multicasting Support
• MSMQ DCOM Proxy

Only the Message Queue Server component should be installed. The other components may interfere with the addressing used in NServiceBus and cause messages to not be delivered, with no error messages in the NServiceBus logs.

Installation on Windows Server 2012 and higher

From Server Manager's Add Roles and Features Wizard, enable Message Queue Server. All other MSMQ options should be disabled.

The DISM command line equivalent is:

DISM.exe /Online /NoRestart /English /Enable-Feature /all /FeatureName:MSMQ-Server

Installation on Windows 10 / Windows 11

From the Control Panel, choose Programs. Then run the Windows Features Wizard by clicking Turn Windows Features On or Off. Enable Microsoft Message Queue (MSMQ) Server Core. All other MSMQ options should be disabled.

The DISM command line equivalent is:

DISM.exe /Online /NoRestart /English /Enable-Feature /all /FeatureName:MSMQ-Server

MSMQ machine name limitation

For MSMQ to function properly, the server name must be 15 characters or less. This is because of a NETBIOS limitation.

MSMQ clustering

MSMQ clustering works by having the active node running an instance of the MSMQ service and the other nodes being cold standbys. On failover, a new instance of the MSMQ service must be loaded from scratch. Otherwise, all active network connections and associated queue handles will break and need to be reconnected. Any transactional processing of messages aborts, returning the message to the queue after startup.

Downtime is proportional to the time taken for the MSMQ service to restart on another node. This is affected by how many messages are awaiting processing in current storage.

Remote queues

Remote queues are not supported for MSMQ as this conflicts with the distributed bus architectural style that is predicated on concepts of durability, autonomy and avoiding a single point of failure. For scenarios where a broker style architecture is required, use transports like SQL Server and RabbitMQ.

Error queue configuration

The transport requires all endpoints to configure the error queue address. The centralized error queue is a recommended setup for production scenarios.

See the recoverability documentation for details on how to configure the error queue address.

Public queues

Although MSMQ has the concept of both public and private queues, public queues require Active Directory as a prerequisite and are not available in a workgroup environment. Therefore, NServiceBus supports only private queues and uses the path name addressing scheme for its routing. Installing MSMQ with Active Directory may interfere with the addressing scheme when sending messages and for this reason, it is recommended not to include Active Directory when installing MSMQ.

Permissions

Any endpoint that sends a message to a target endpoint requires the Send permission to be granted for the sending user account on the target queue. For example, if an endpoint A is running as userA and is sending a message to endpoint B, then userA requires the Send permission to be granted on endpoint B's queue. When using messaging patterns like request-response or publish-subscribe, the queues for both endpoints will require Send permissions to be granted to each user account.

When an endpoint creates a queue on a machine, permissions depend on whether the server is joined to a domain or a workgroup due to Windows behavior.

Domain mode

If the machine is part of a domain, then at the time of queue creation, only the domain user that created the queue will have Send permissions granted. The Everyone user group and Anonymous user group will NOT have Send permissions. If all the endpoints which need to communicate are running under the same domain account, no further configuration is required. However, if the endpoints are run using different domain accounts, the Send permission on the receiving endpoint's input queue must be explicitly granted to the domain user account of the sending endpoint.

Workgroup mode

If the machine is connected to a workgroup, the Send permission is granted to the Everyone and Anonymous user groups by Windows. Any endpoint will be able to send messages to any other endpoint without further configuration.

Well-known group names and queue access rights

The WellKnownSidType enumeration is used to retrieve the group names.

MSMQ permissions are defined in the MessageQueueAccessRights enumeration.

An example of the warning that is logged:

WARN NServiceBus.QueuePermissions - Queue [private$\xxxx] is running with [Everyone] with AccessRights set to [GenericWrite]. Consider setting appropriate permissions, if required by the organization. For more information, consult the documentation.

See also Message Queuing Security Overview.

Distributed Transaction Coordinator

NServiceBus makes use of the Microsoft Distributed Transaction Coordinator (MSDTC) to synchronize transactions between MSMQ and the database in order to support guaranteed once delivery of messages. For this to work, MSDTC must be started and configured correctly. This can be done manually or using the NServiceBus PowerShell module.

Alternatively, there is a _non-MSDTC mode of operation available. In this mode NServiceBus uses the outbox, a message store backed by the same database as the user code, to temporarily store messages that must be sent as a result of processing an incoming message. To read more about this subject see Outbox.

If neither the MSDTC nor the outbox is configured, an exception message will appear when an MSMQ-enabled endpoint is started:

Transaction mode is set to `TransactionScope`. This depends on Microsoft Distributed Transaction Coordinator (MSDTC) which is not available. Either enable MSDTC, enable Outbox, or lower the transaction mode to `SendsAtomicWithReceive`.