MSMQ Connector User Guide

The Microsoft Message Queuing (MSMQ) connector uses a typical client-server architecture with two tiers, the connector or client running in Mule, and the Anypoint Gateway running on the server side. The latter exposes an HTTP Web API for sending or receiving messages from MSMQ.

The following is a high-level diagram of the solution architecture:

The Anypoint Gateway leverages the following technologies/frameworks:

The MSMQ connector supports two primary use cases:

In the POST scenario, Mule uses the connector to send a raw representation of the Mule Message in the current flow to MSMQ using HTTP to the Anypoint Gateway. The message is sent as an HTTP POST. The payload of the HTTP request is serialized payload of the Mule message (binary or text). The Web API runs on the Anypoint Gateway and forwards the message to a queue using MSMQ.

The following messages show the structure of the HTTP POST request.

In the GET scenario, Mule uses the connector to receive one or more messages from MSMQ. This is done as an HTTP GET to the Anypoint Gateway. The Web API runs in the gateway and returns the available messages in a MSMQ queue. The messages are returned in a single HTTP response using a MIME multipart/mixed content type.

The following messages illustrates the structure of the HTTP GET requests.

To enable Exactly-Once and In-Order (EOIO) support, you must select the flow containing MSMQ connector in Anypoint Studio and set the default operation Processing Strategy to synchronous. Otherwise, the connector processes messages as they are received in the ESB and ignores the original order in the queue.

The setting appears in the XML as:

The Anypoint Gateway authenticates the direct caller, which is the connector running in the Mule ESB, and optionally the user on behalf of the connector.

The user executing the call on behalf of the connector is authenticated through two custom HTTP headers, mule-impersonate-username and mule-impersonate-password.

When using user authentication, the queue in MSMQ must also be marked to require authentication. These two headers represent the Windows credentials of an existing user in the Active Directory forest where the Anypoint Gateway service is running, or a local account on the machine hosting the service. When these HTTP headers are included in an HTTP Request, the Anypoint Gateway service authenticates and impersonates this user before queuing/dequeuing a message from MSMQ. This provides the ability to configure the correct access control list permissions on the queue using Windows credentials.

The following HTTP request example illustrates how to pass these two headers from the connector to the Gateway:

Note: The connector and the gateway use SSL to protect all HTTP communications.

To use queue permissions, mark the queue to require authentication. In addition, the connector must send the Mule-Impersonate-Username and Mule-Impersonate-Password headers in the HTTP request message to impersonate the cell; otherwise the account impersonating the host is used (the user impersonating the Windows service or the application pool if the gateway is hosted in IIS).

Note: A Windows user must have logged in for at least the first time before using authenticated queues. When a user logs in for the first time, Windows creates a user’s profile, which must exist for the user to use authenticated queues.

The following table shows the permissions required for sending or receiving a message from a queue:

In both cases, Peek Message is only used for testing the connection. This permission can be removed if testing the connection is not required.

Note: When MSMQ is installed in a machine not joined to a Windows Domain, it works in Workgroup Mode. In this mode, authenticated queues are not supported and therefore the queue permissions can not be used either.

The Anypoint Gateway service does not use an MSMQ formatter unless it is specified by the connector. Therefore, a message sent in the HTTP request paylaod is stored in raw form in the body of the MSMQ message. However, this behavior can be overridden be setting a Message Formatter in the connector. A single formatter is supported out of the box: ActiveXMessageFormatter.

The following example illustrates how to set the formatter in an MSMQ connector:

When a message formatter is set on the connector, an additional HTTP header Mule-Msmq-Formatter is sent to the Anypoint Gateway. The gateway uses the formatter to serialize and deserialize the message when it enqueues or dequeues from MSMQ.

For the ActiveXMessageFormatter, the gateway also uses the Content-Type set by the connector in the HTTP request message:

The MSMQ connector supports private and public queues. Private queues are queues that are not published in Active Directory and are displayed only on the local computer that contains them.

The following schemes are supported:

Public queues are queues that are published in Active Directory.

Public format names contain the string PUBLIC= followed by the identifier assigned to the queue when it was created. This identifier is the GUID listed for the queue object in the Active Directory.

The following is the general format used to reference a public queue and its associated queue journal:

The connector also supports private queues hosted in a failover cluster or also known as an MSMQ cluster. The queues are private to the cluster and referenced with the following format:

ClusterName\private$\QueueName

The connector allows passing or receiving properties to and from the MSMQ message. Those properties are set in the current Mule Message and passed to the Anypoint Gateway as custom HTTP headers. The following message illustrates how the connector creates a new MSMQ message with a value "CustomLabel" for the label property:

The following table summarizes all supported properties on the receive operation, and the mapping of the HTTP headers.

The following table summarizes all supported properties on the send operation, and the mapping with the HTTP headers.

The following example shows how the "set-payload" component sets the label for an MSMQ message.

The Anypoint Gateway service leverages the built-in .NET tracing system. The basic premise is simple, tracing messages are sent through switches to listeners, which are lied to a specific storage medium. The listeners for the trace source used by the connector are available in the configuration file:

The previous example configures three listeners for the output console, for files, and for Event Tracing for Window (ETW). The trace source for the connector Mule.Msmq is configured to output the traces to the console and ETW only.

The Anypoint Gateway is configured by default to log everything, which is the Verbose level. Other possible levels are:

You can configure the levels at switch level in the configuration file:

ETW is a very efficient built-in publish and subscribe mechanism for doing event tracing at the kernel level. There is little overhead in using this feature compared to other traditional tracing solutions that rely on I/O for storing the traces in persistence storage such as files or databases. As a built-in mechanism in Windows, many of the operating systems services and components use this feature as well. For that reason, not only can you troubleshoot the application but also many of the OS components involved in the same execution.

In ETW, there are applications publishing events in queues (or providers) and other applications consuming events from those queues in real-time through ETW sessions. When an event is published in a provider, it goes nowhere unless there is a session collecting events on that queue. (The events are not persisted).

The tracing system in .NET includes a trace listener for ETW, EventProviderTraceListener, which you can configure with a session identifier, which ETW uses to collect traces:

In the example, the session is associated with this identifier: {47EA5BF3-802B-4351-9EED-7A96485323AC}

The MSMQ connector is integrated with the Mule ESB logging infrastructure for logging errors and relevant information for the user.

The following table lists common errors that can occur while using the MSMQ connector:

Requirements:

This sample receives incoming requests via HTTP connector, and sends the request via MSMQ connector (Send operation) to the remote MSMQ queue. It then receives a MSMQ message from your server (Streaming Receive operation) and logs the result.