MSMQ (Microsoft Message Queuing)

The MSMQ (Microsoft Message Queuing) communication point uses the MSMQ API interface to communicate with a Microsoft® Message Queuing server. It is only available on the Microsoft® Windows® platform.

The relevant MSMQ software needs to be installed on the Rhapsody server; that is, the MSMQ client if the communication point is to be operated in output mode and the MSMQ server if the communication point is to be operated in input mode. Additionally:

The appropriate queues must be set up on the MSMQ server.
The required permissions must be set to allow communication between the machine on which Rhapsody is running and the machine on which the MSMQ server is running.

The MSMQ communication point:

Supports MSMQ version 3 (Windows® XP Professional and Windows® 2003 Server) and MSMQ version 4 (Windows® Vista and Windows® 2008 Server).
Is compatible with both 32-bit and 64-bit versions of MSMQ.
Is able to talk to remote MSMQ servers, even when the MSMQ Server is running a different version of Windows® to the client (subject to the version requirements above).
Supports both transactional and non-transactional queues.
Supports queue discovery using Active Directory.
Supports Domain, Workgroup mode and cross-forest communication.

Rhapsody is not able to detect when MSMQ queues have been deleted or renamed, therefore care should be taken not to delete queues that Rhapsody is using.

Additional information can be found at the Microsoft® Message Queuing home page.

Supported Operational Modes: All

Configuration Properties

Property	Description
Receive Host Name	The name of the host machine on which the receive queue resides. The localhost can be referred to by name, using the alias `localhost`, or by a fullstop (`.`) which is the MSMQ alias. In OS mode, the server name must be a host name. In TCP mode, the server name must be an IP address.
Receive Queue Name	The name of the queue from which to receive messages.
Use Active Directory Lookups	Options: `true`, `false`; default: `true`. If set to `true`, the queue is located using Active Directory Domain Services. If set to `false`, the connection attempts to use a Direct Format Name to access the queue. In Workgroup mode or when accessing public queues across a forest boundary, this should be set to `false` as Active Directory Lookups are not possible. It should also be disabled when connecting to private queues.
MSMQ Queue Type	Options: `Public Queue - Transactional`, `Public Queue - Non-Transactional`, `Private Queue - Transactional`, `Private Queue - Non-Transactional`. The type of MSMQ queue - public or private: Public queues are published to Active Directory Domain Services and are accessible via Active Directory lookups. Private queues are not published to Active Directory services and are only accessible via direct or private format name.
Address Specification	The protocol that the MSMQ client uses to connect to the specified queue. On an MSMQ communication point in input mode, supported options are: OS and TCP. On an MSMQ communication point in output mode, supported options are: `OS`, `TCP`, `HTTP`, `HTTPS`. Please refer to the MSMQ manuals for details.
Receive Properties	The properties to read from incoming MSMQ messages and convert to Rhapsody message properties. These properties will be prefixed with `MSMQ:`.
Send Host Name	The name of the host machine on which the send queue resides. The localhost can be referred to by name, using the alias `localhost`, or by a fullstop (`.`) which is the MSMQ alias.
Send Queue Name	The name of the queue on which to send messages.
Use Active Directory Lookups	Options: `true`, `false`; default: `true`. If set to `true`, the queue is located using Active Directory Domain Services. If set to `false`, the connection attempts to use a Direct Format Name to access the queue. In Workgroup mode or when accessing public queues across a forest boundary, this should be set to `false` as Active Directory Lookups are not possible. It should also be disabled when connecting to private queues.
MSMQ Queue Type	Options: `Public Queue - Transactional`, `Public Queue - Non-Transactional`, `Private Queue - Transactional`, `Private Queue - Non-Transactional`. The type of MSMQ queue - public or private: Public queues are published to Active Directory Domain Services and are accessible via Active Directory lookups. Private queues are not published to Active Directory services and are only accessible via direct or private format name.
Address Specification	The protocol that the MSMQ client uses to connect to the specified queue. On an MSMQ communication point in input mode, supported options are: OS and TCP. On an MSMQ communication point in output mode, supported options are: `OS`, `TCP`, `HTTP`, `HTTPS`. Please refer to the MSMQ manuals for details.
Virtual Directory	The virtual directory associated with the HTTP/HTTPS direct connection. This is enabled only if the HTTP or HTTPS address specification is selected with the value defaulting to `msmq`. This must point to the path to the HTTP web site entry point under IIS.
Output Message Format	Options: Binary, ANSI, Unicode; Default: Binary. Identifies the MSMQ body type used to tag the message when it is placed on the queue. The body type will be used by the receiving application when retrieving messages. Refer to http://msdn.microsoft.com/en-us/library/windows/desktop/ms701459(v=vs.85).aspx for details on Message Body Types. Binary will set the body type to VT_ARRAY_OR_VT_UI1 (An array of bytes) String (ANSI) will set the body type to VT_LPSTR (A variable-size, NULL-terminated ANSI string) String (Unicode) will set the body type to VT_LPWSTR (A variable-size, NULL-terminated Unicode string)
Delivery Mode	Options: `Express`, `Recoverable`; default: `Express`. Sets the delivery mode for MSMQ messages. Express messages will not be recovered if the queue is restarted. Recoverable messages will be recovered if the queue is restarted, however there is a performance penalty for the queue if this mode is selected.

Refer to Out->In and In->Out Properties for general details on the MSMQ communication point's bidirectional, In->Out and Out->In operational modes.

MSMQ Notes

MSMQ supports public, private and system queues:
- Private queues are only accessible by setting Active Directory lookups to disabled.
- Public queues are accessible by using Active Directory lookups or directly using a Direct Format Name.
  System queues are accessible by postfixing the queue name with ;<name of system queue>. MSMQ system queues take the following format SYSTEM$;<name of system queue>.
Access to queues is controlled via normal Windows® authentication (or domain authentication for public queues). Therefore, Rhapsody must be running as a user that has permission to access the queue.
If transactions are used, the MSMQ communication point is responsible for creating and committing the transactions:
- MSMQ send operations on transactional queues must always be performed in the context of a transaction and send operations on non-transactional queues must NOT be performed in the context of a transaction, regardless of whether the queue is local or remote. The MSMQ communication point handles this automatically.
- When receiving messages, the MSMQ communication point only uses transactions if configured to do so and the queue is transactional. Transactions are not supported remote queues on MSMQ versions earlier than 4 (Vista/2008 Server). However, all MSMQ versions always support non-transactional receives on queues even if the queues themselves are transactional.
Remote reads from a transactional remote queue are only possible in versions of MSMQ 4 onwards. This is facilitated by using an external transaction manager (MSDTC). Therefore, in order to configure Rhapsody to retrieve messages from a remote transactional queue, MSDTC must be configured as an external transaction manager alongside an appropriate version of the MSMQ client. If remote reads against a transactional queue are required on a system that does not have the required MSMQ client installed, then it is possible to configure the MSMQ communication point to perform non-transactional reads against the transactional queue by disabling Active Directory lookups and selecting the appropriate non-transactional queue option. However, this is not recommended because message retrieval in the MSMQ communication point is conducted in a non-transactional manner upon a queue whose intended usage is transactional.
All transactional send operations and local transactional read operations are conducted using the MSMQ internal transaction manager. Remote transactional read operations are performed using MSDTC as an external transaction manager on versions of MSMQ that support this operation.
Remote reads in workgroup mode or across a forest boundary are strongly discouraged due to the inherent security risks associated with this approach. When using this approach, there is no mechanism to authenticate users; and MSQM mandates that read permissions are required by the ANONYMOUS user. It is recommended you always consider a push approach under these scenarios because MSMQ supports the securing of sends across forest boundaries.

See Also...