Skip to content

MSMQ Adapter

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.

ModeDescription
SubscribeWrite a message from Neuron to MSMQ.
PublishRetrieve 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 NameDescription
Queue PathSets the direct format name of the queue.
TransactionalIf set, the message will be written to or read from the queue in a transaction.
Use ActiveXMessageFormatterIf 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 TopicPublish mode only. Sets the topic to publish the message to.
RecoverableSubscribe 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 NameDescription
msmq_out.AcknowledgeTypeSets the type of acknowledgment message to be returned to the sending application.
msmq_out.AttachSenderIdSets the attached sender ID.
msmq_out.AuthenticationProviderNameSets the name of the cryptographic provider used to generate the digital signature of the message.
msmq_out.AuthenticationProviderTypeSets the type of cryptographic provider used to generate the digital signature of the message.
msmq_out.BodyTypeSet the type of data that the message body contains.
msmq_out.ConnectorTypeSets a value indicating that message properties typically set by MSMQ were set by the sending application.
msmq_out.CorrelationIdSets the message identifier used by acknowledgment, report and response messages to reference the original message.
msmq_out.LabelSets an application-defined Unicode string that describes the message.
msmq_out.PrioritySets the message priority, which determines where in the queue the message is placed.
msmq_out.RecoverableSets a value indicating whether the message is guaranteed to be delivered in the event of a computer failure or network problem.
msmq_out.TimeToBeReceivedSets 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.TimeToReachQueueSets 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.UseAuthenicationSets a value indicating whether the message must be authenticated before being sent.
msmq_out.UseDeadLetterQueueSets a value indicating that if the message cannot be delivered it should be sent to a dead-letter queue.
msmq_out.UseEncryptionSets a value indicating whether to make the message private.
msmq_out.UseJournalQueueSets a value indicating a copy of the message should be kept in a machine journal on the originating computer.
msmq_out.UseTracingSets 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 NameDescription
msmq_in.AcknowledgeTypeThe type of acknowledgement message to be returned to the sending application.
msmq_in.AcknowledgementThe classification of the acknowledgment that the message represents.
msmq_in.ArrivedTimeThe time the message arrived in the destination queue.
msmq_in.AttachSenderIdThe attached sender ID.
msmq_in.AuthenticatedIndicates if the message was authenticated.
msmq_in.AuthenticationProviderNameThe name of the cryptographic provider used to generate the digital signature of the message.
msmq_in.AuthenticationProviderTypeThe type of cryptographic provider used to generate the digital signature of the message.
msmq_in.BodyTypeThe type of data that the message body contains.
msmq_in.ConnectorTypeA value indicating that some message properties typically set by MSMQ were set by the sending application.
msmq_in.CorrelationIdThe message identifier used by acknowledgment, report, and response messages to reference the original message.
msmq_in.IdThe message ID.
msmq_in.IsFirstInTransactionA value indicating whether the message was the first message sent in a transaction.
msmq_in.IsLastInTransactionA value indicating whether the message was the last messages sent in a transaction.
msmq_in.LabelThe application-defined Unicode string that describes the message.
msmq_in.LookupIdThe messages lookup ID.
msmq_in.MessageTypeThe message type: Normal, Acknowledgment, or Report
msmq_in.PriorityThe message priority, which determines where in the queue the message is placed.
msmq_in.RecoverableA value indicating whether the message is guaranteed to be delivered in the event of a computer failure or network problem.
msmq_in.SentTimeThe date and time on the sending computer that the message was sent by the source queue manager.
msmq_in.SourceMachineThe computer from which the machine originated.
msmq_in.TimeToBeReceivedThe 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.TimeToReachQueueThe 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.TransactionIdThe identifier for the transaction of which the message was a part.
msmq_in.UseAuthenticationA value indicating whether the message was authenticated before being sent.
msmq_in.UseDeadLetterQueuea value indicating that if the message cannot be delivered it should be sent to a dead-letter queue.
msmq_in.UseEncryptionA value indicating whether to make the message private.
msmq_in.UseJournalQueueA value indicating a copy of the message should be kept in a machine journal on the originating computer.
msmq_in.UseTracingA 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.

Was this article helpful?
Dislike 0
Previous: ODBC Adapter
Next: Marketo Adapter