The NetMsmqBinding provides a secure and reliable queued communication for cross-machine environments.
Queuing is provided by using the MSMQ (Microsoft Message Queuing) as a transport, which enables support for disconnected operations, failure isolation, and load leveling. Each of these three is described in detail next.
A disconnected operation means that the client and the service do not have to be online at the same time.
The client can initiate the transaction and disconnect. The service can accept the assignment and begin working on it while the client is disconnected.
Load leveling is the process of managing incoming messages so that the receiving service is not completely overwhelmed by the number of incoming messages.
Failure isolation means that messages can fail without affecting the processing of other messages. If a message is received by a service and the receiving service fails, the client can continue to send messages, which will be received by the message queue. When the failed receiving application is up and running again, it will start pulling messages off of the queue. This process guarantees message reliability and system stability.
NetMsmqBinding Properties
The following table is a list of attributes, and their descriptions, that are available to be used with the NetMsmqBinding.
| Attribute | Description |
|---|---|
| closeTimeout | A time interval value, which must be greater than zero, that specifies the amount of time for a close operation to complete. The default value is 1 minute (00:01:00). |
| customDeadLetterQueue | A string value that contains a URI that specifies the location of expired messages or messages that have failed delivery. |
| deadLetterQueue | A string value that contains a URI that specifies the location of the dead letter queue. |
| Durable | A Boolean value that specifies whether a message is durable or unstable in the queue. |
| exactlyOnce | A Boolean value that specifies whether each message processed by this binding is only delivered a single time. |
| maxBufferPoolSize | Specifies the maximum buffer size for a buffer pool, which stores messages processed by the binding. This is an integer value with a default of 512*1024, or 524388. |
| maxImmediateRetries | An integer value that specifies the maximum number of retry attempts per message that is ready from the application queue. These retries are immediate. The default is 5. |
| maxReceivedMessageSize | Specifies the maximum size of a message, including headers. The number is specified in bytes with a default value of 65536. If a message is larger than the value specified, the sender receives a SOAP fault message and the receiver drops the message and creates an event in the trace log. |
| maxRetryCycles | An integer value that specifies the maximum number of retry cycles used by the poison message feature. A message becomes poisoned when it fails all delivery attempts. The default is 3. |
| Name | A unique string value that contains the configuration name of the binding. |
| openTimeout | A time interval value that specifies the amount of time a message has to complete. Value should be greater than zero. Default is 1 minute (00:01:00). |
| poisonMessageHandling | Allows the service to enable or disable poison message handling. Valid values are Disabled and EnabledIfSupported. The default is EnabledIfSupported. |
| queueTransferProtocol | A valid QueueTransferProtocol value that specifies the queued communication channel transport that this binding will use. |
| recieveTimeout | A time interval value that specifies the amount of time a receive operation has to complete. Value should be greater than zero. Default is 1 minute (00:01:00). |
| rejectAfterLastRetry | A Boolean value that specifies the action to be taken for a failed message delivery after the maximum number of retries. True signifies a negative acknowledgment is sent to the sender and the message is dropped. False signifies that the message is sent to the poison queue. The default is False. |
| retryCycleDelay | A time interval value that specifies the minimum time delay between retry cycles for failed message delivery. Value should be greater than zero. Default is 10 minutes (00:10:00). |
| sendTimeout | A time interval value that specifies the amount of time a send operation has to complete. Value should be greater than zero. Default is 1 minute (00:01:00). |
| timeToLive | A time interval value that specifies the amount of time a message is valid before it expires and is sent to the dead letter queue. Default is 1 day (1.00:00:00). |
| usingActiveDirectory | A Boolean value that specifies whether the queue addresses should be converted using AD (Active Directory). |
| useMsmqTracing | A Boolean value that specifies whether messages processed by this binding should be traced. The default value is False. |
| useSourceJournal | A Boolean value that specifies whether copies of process messages should be stored in the source journal. The default is False. |
The following example illustrates some of the properties being configured in a configuration file:
<system.serviceModel> <bindings> <netMsmqBinding> <binding name = “netmsmqbind” exactlyonce = “true” durable = “true” usemsmqtracing = “false” openTimeout = “00:00:30”> </binding> </netMsmqBinding> </bindings> </system.ServiceModel>
The same can be done through code, as illustrated here:
NetMsmqBinding nmqb = new NetMsmqBinding(); nmqb.ExactlyOnce = true; nmqb.Durable = true; nmqb.UseMsmqTracing = false; nmqb.OpenTimeout = 30000;
Notes
The dead letter queue is a queue on the queue manager of the sending application. This queue is for expired messages that have failed to be delivered. The URI that is specified by the customDeadLetterQueue property must use the net.msmq scheme.
A durable message survives a queue manager crash, whereas an unstable or volatile message does not survive. Why would you send a volatile message? Your application might require a lower latency and an occasional lost message is not a big deal. As a note, if the exactlyOnce attribute is set to True, this attribute must be True as well.
When using SOAP Reliable Messaging Protocol, MSMQ does not support Active Directory addressing.
Therefore, the QueueTransferProtocol attribute must not be set to a value of Srmp or SrmpSecure when the useActiveDirectory attribute is set to True.
A poison message is a message that has reached, or exceeded, the maximum number of delivery attempts to the awaiting application. This could happen because an application fails to successfully process a message due to errors that occur during the processing of the message. MSMQ 3.0 does not support message poisoning, so any WCF applications deployed using this binding should take this into consideration. This attribute can be disabled and enabled based on the underlying platform support as well, meaning that an application can choose to disable poison handling if the application will contain its own poison-message mechanism. You could disable poison-message handling via the configuration file, and then when the environment is upgraded to MSMQ 4.0 (which supports poison-messaging), the
configuration can simply be modified to enable to poison-messaging.
The timeToLive attribute helps to ensure that time-sensitive messages are delivered in a quick timeframe and do not expire before they are processed by the receiving application. Any message that is not consumed within the time interval specified by this attribute expires and is sent to the dead letter queue.
When using the useActiveDirectory attribute, keep in mind that MSMQ queue addresses can be in several formats, including path names and direct format names. With a path name, MSMQ can resolve the computer using Active Directory. Not so with direct format names, which in this case MSMQ will use DNS, NetBIOS, or IP to resolve the computer name. WCF will convert the URI of a message queue to a direct format name, and when this property is set to True, this allows an application to dictate that the queued transport should resolve the computer name via AD.
A source journal provides queued applications the ability to keep a copy of any outgoing messages via the outgoing queue. Basically it works like this:
- The sending application sends a message to the receiver.
- The receiver sends a message back to the sender acknowledging that the message was received by the receiver.
- When the acknowledgment is received by the sender, a copy of the original message is stored in the sender’s journal queue.
- The useSourceJournal attribute enables this functionality, but it is disabled by default. Set this attribute to True to enable this functionality.