Overview
The Neuron MSMQ adapter will read messages from and write messages to Microsoft Message Queue.
Requirements
This adapter requires a Microsoft Message Queuing server which is included with Windows.
For transactional messaging, MSMQ 4.0 is recommended. Additionally, the Microsoft Distributed Transaction Coordinator (MSDTC) service must be configured and running when reading from and writing to remote transactional queues.
Adapter Modes
The adapter supports the following modes of operation.
Mode |
Description |
Subscribe |
Write a message from Neuron to MSMQ. |
Publish |
Retrieve a message from MSMQ and publish it to Neuron. |
Subscribe Mode
When the adapter receives a message from Neuron, the bytes of the body of the message are sent to MSMQ.
Transactional Messaging
When the transactional property is set, the message is published to MSMQ in a transaction. This also requires that the queue be a transactional queue. If the transactional property is set and the queue is not a transactional queue, then the adapter will not be able to submit the message to the queue and the message may be lost.
If the queue is a remote queue, then the Microsoft Distributed Transaction Coordinator service must be configured and running.
Publish Mode
The adapter will poll the specified queue and when a message is read, the body of the MSMQ message is published to Neuron as an ESBMessage.
Any message received from Neuron will be discarded when the adapter is in publish mode.
Transactional Messaging
When the transactional property is set, then the message is read from the queue in a transaction. This also requires that the queue be a transaction queue. If the transactional property is set and the queue is not a transactional queue, then the adapter will not be able to retrieve messages from the queue. Remote transactional reads are only supported on MSMQ 4.0 which is shipped with Windows 2008, Vista and later operating systems. A remote transactional read is one where the queue is not on the same machine as the Neuron ESB server. Additionally, remote transactional reads require that the Microsoft Distributed Transaction Coordinator service be configured and running.
Adapter Properties
Property Name |
Description |
Queue Path |
Sets the direct format name of the queue. |
Transactional |
If set, the message will be written to or read from the queue in a transaction. |
Use ActiveXMessageFormatter |
If set, the message will be serialized to and deserialized from the queue using the ActiveXMessageFormatter. The default formatter is the BinaryMessageFormatter. This formatter is compatible with message queuing COM components. |
Publish Topic |
Publish mode only. Sets the topic to publish the message to. |
Recoverable |
Subscribe mode only. By default, MSMQ stores some messages in memory for increased performance, and a message may be sent and received from a queue without ever having been written to disk. One can control this behavior, forcing MSMQ to store a message to disk, by specifying that a message should be recoverable. |
Example queue paths:
· .\private$\myqueue
· FormatName:Direct=OS:myqueueserver\private$\myqueue
When specifying the publish topic, ensure that the configured party for the adapter endpoint has a publish subscription to the topic.
Adapter Metadata
Subscribe Mode
When the Neuron adapter endpoint has the include metadata option set, then the adapter will look for the following properties in the ESBMessage received from Neuron. The adapter metadata must be specified in the custom properties of the message header. Any other custom properties in the ESBMessage that are not listed below will not be preserved in the MSMQ message.
The names of the properties are case sensitive.
All of the adapter metadata properties are optional even when the include metadata option is set.
Property Name |
Description |
msmq_out.AcknowledgeType |
Sets the type of acknowledgment message to be returned to the sending application. |
msmq_out.AttachSenderId |
Sets the attached sender ID. |
msmq_out.AuthenticationProviderName |
Sets the name of the cryptographic provider used to generate the digital signature of the message. |
msmq_out.AuthenticationProviderType |
Sets the type of cryptographic provider used to generate the digital signature of the message. |
msmq_out.BodyType |
Set the type of data that the message body contains. |
msmq_out.ConnectorType |
Sets a value indicating that message properties typically set by MSMQ were set by the sending application. |
msmq_out.CorrelationId |
Sets the message identifier used by acknowledgment, report and response messages to reference the original message. |
msmq_out.Label |
Sets an application-defined Unicode string that describes the message. |
msmq_out.Priority |
Sets the message priority, which determines where in the queue the message is placed. |
msmq_out.Recoverable |
Sets a value indicating whether the message is guaranteed to be delivered in the event of a computer failure or network problem. |
msmq_out.TimeToBeReceived |
Sets the maximum amount of time for the message to be received from the destination queue. The value of this property is a 64-bit signed integer value which represents the number of 100-nanosecond intervals that have elapsed since 12:00:00 midnight, January 1, 0001. See the MSDN documentation for DateTime.Ticks. |
msmq_out.TimeToReachQueue |
Sets the maximum amount of time for the message to reach the queue. The value of this property is a 64-bit signed integer value which represents the number of 100-nanosecond intervals that have elapsed since 12:00:00 midnight, January 1, 0001. See the MSDN documentation for DateTime.Ticks |
msmq_out.UseAuthenication |
Sets a value indicating whether the message must be authenticated before being sent. |
msmq_out.UseDeadLetterQueue |
Sets a value indicating that if the message cannot be delivered it should be sent to a dead-letter queue. |
msmq_out.UseEncryption |
Sets a value indicating whether to make the message private. |
msmq_out.UseJournalQueue |
Sets a value indicating a copy of the message should be kept in a machine journal on the originating computer. |
msmq_out.UseTracing |
Sets a value indicating whether to trace the message as it moves toward its destination queue. |
Publish Mode
When the Neuron adapter endpoint has the include metadata option set, the following properties will be added to the Neuron ESBMessage as custom properties in the message header.
Property Name |
Description |
msmq_in.AcknowledgeType |
The type of acknowledgement message to be returned to the sending application. |
msmq_in.Acknowledgement |
The classification of the acknowledgment that the message represents. |
msmq_in.ArrivedTime |
The time the message arrived in the destination queue. |
msmq_in.AttachSenderId |
The attached sender ID. |
msmq_in.Authenticated |
Indicates if the message was authenticated. |
msmq_in.AuthenticationProviderName |
The name of the cryptographic provider used to generate the digital signature of the message. |
msmq_in.AuthenticationProviderType |
The type of cryptographic provider used to generate the digital signature of the message. |
msmq_in.BodyType |
The type of data that the message body contains. |
msmq_in.ConnectorType |
A value indicating that some message properties typically set by MSMQ were set by the sending application. |
msmq_in.CorrelationId |
The message identifier used by acknowledgment, report, and response messages to reference the original message. |
msmq_in.Id |
The message ID. |
msmq_in.IsFirstInTransaction |
A value indicating whether the message was the first message sent in a transaction. |
msmq_in.IsLastInTransaction |
A value indicating whether the message was the last messages sent in a transaction. |
msmq_in.Label |
The application-defined Unicode string that describes the message. |
msmq_in.LookupId |
The messages lookup ID. |
msmq_in.MessageType |
The message type: Normal, Acknowledgment, or Report |
msmq_in.Priority |
The message priority, which determines where in the queue the message is placed. |
msmq_in.Recoverable |
A value indicating whether the message is guaranteed to be delivered in the event of a computer failure or network problem. |
msmq_in.SentTime |
The date and time on the sending computer that the message was sent by the source queue manager. |
msmq_in.SourceMachine |
The computer from which the machine originated. |
msmq_in.TimeToBeReceived |
The maximum amount of time for the message to be received from the destination queue. The value of this property is a 64-bit signed integer value which represents the number of 100-nanosecond intervals that have elapsed since 12:00:00 midnight, January 1, 0001. See the MSDN documentation for DateTime.Ticks |
msmq_in.TimeToReachQueue |
The maximum amount of time for the message to reach the queue. The value of this property is a 64-bit signed integer value which represents the number of 100-nanosecond intervals that have elapsed since 12:00:00 midnight, January 1, 0001. See the MSDN documentation for DateTime.Ticks |
msmq_in.TransactionId |
The identifier for the transaction of which the message was a part. |
msmq_in.UseAuthentication |
A value indicating whether the message was authenticated before being sent. |
msmq_in.UseDeadLetterQueue |
a value indicating that if the message cannot be delivered it should be sent to a dead-letter queue. |
msmq_in.UseEncryption |
A value indicating whether to make the message private. |
msmq_in.UseJournalQueue |
A value indicating a copy of the message should be kept in a machine journal on the originating computer. |
msmq_in.UseTracing |
A value indicating whether to trace a message as it moves toward its destination. |
Message Format
Subscribe Mode
The bytes of the body of the ESBMessage will be the body of the MSMQ message.
Publish Mode
The contents of the MSMQ message will become the body of the ESBMessage.