NGWS SDK Documentation  

This is preliminary documentation and subject to change.
To comment on this topic, please send us email at ngwssdk@microsoft.com. Thanks!

MessageQueue.DefaultPropertiesToSend

Gets or sets the properties to be used by default when sending messages to the queue referenced by this MessageQueue.

[Visual Basic]
Overridable Public Property DefaultPropertiesToSend As _
   DefaultPropertiesToSend
[C#]
public DefaultPropertiesToSend DefaultPropertiesToSend {virtual
   get; virtual set;}
[C++]
public: __property virtual DefaultPropertiesToSend* get_DefaultPropertiesToSend();
public: __property virtual void set_DefaultPropertiesToSend(DefaultPropertiesToSend*);
[JScript]
public function get DefaultPropertiesToSend() : DefaultPropertiesToSend;
public function set DefaultPropertiesToSend(DefaultPropertiesToSend);

Property Value

A DefaultPropertiesToSend that holds the default property values used when sending messages to the queue.

Exceptions

Exception Type Condition
ArgumentException The default properties could not be set for the queue. A property may have been set to an invalid value.
MessageQueueException The attempt to get or set the default properties generated an internal error on the message queue component. The error is specified by the given status message.

Remarks

The DefaultPropertiesToSend describes the read/write property values that apply to messages sent to the queue referenced by the MessageQueue. When you create a Message object, these properties on the message will be set to their default values. Before you Send a Message object, you must explicitly override the initial values on the Message properties if you want the DefaultPropertiesToSend to apply. If you use the Send method using any object other than a Message, such as a string, the DefaultPropertiesToSend will automatically apply to the object. Only Message instances require these defaults to be explicitly overridden.

Although the properties are set using the MessageQueue object, the DefaultPropertiesToSend refers to properties on the messages that are sent to the queue, not the queue itself.

The default values for the properties are represented in the following table.

Property Value
AcknowledgeType AcknowledgeType.None
AdministrationQueue a null reference (in Visual Basic Nothing)
AppSpecific 0
AttachSenderId true
EncryptionAlgorithm EncryptionAlgorithm.RC2
Extension A zero-length array of bytes
HashAlgorithm HashAlgorithm.MD5
Label "" (empty string)
Priority MessagePriority.Normal
Recoverable false
ResponseQueue a null reference (Nothing)
TimeToBeReceived Message.InfiniteTimeout
TimeToReachQueue Message.InfiniteTimeout
TransactionStatusQueue a null reference (Nothing)
UseAuthentication false
UseDeadLetterQueue false
UseEncryption false
UseJournalQueue false
UseTracing false

Example [Visual Basic]

The following example sets different DefaultPropertiesToSend values based on whether a message passed into the procedure has high or normal MessagePriority. The properties that are set, which apply to the message to be sent to the message queue, are: Label, Priority, TimeToBeReceived, and TimeToReachQueue.

It is important to note that these properties are set through the MessageQueue, but they apply to the Message object.

This example assumes that the calling procedure passes in a MessagePriority, and that an urgent message is indicated by Highest priority. It also assumes that the calling method defines the Message that is to be sent to the queue.

[Visual Basic]

Private Sub SetDefaultPropertiesToSend(ByVal priority As MessagePriority, ByVal msg As Message)
    'Create DefaultPropertiesToSend objects
    Dim urgentMessageProperties As DefaultPropertiesToSend
    Dim normalMessageProperties As DefaultPropertiesToSend
    'Define and instantiate a new MessageQueue object
    Dim messageQueue1 As MessageQueue
    messageQueue1 = New MessageQueue

    'Set the queue path
    messageQueue1.Path = "mycomputer\myqueue"
    'Set the label for the queue (as opposed to the message labels).
    messageQueue1.Label = "My Queue"

    'Instantiate two new DefaultPropertiesToSend objects.
    urgentMessageProperties = New DefaultPropertiesToSend
    normalMessageProperties = New DefaultPropertiesToSend

    'Set the label and priority for urgent messages.
    urgentMessageProperties.Label = "Urgent Message"
    urgentMessageProperties.Priority = MessagePriority.Highest
    'Make the process wait indefinitely for a message.
    urgentMessageProperties.TimeToBeReceived = Message.Infinite
    urgentMessageProperties.TimeToReachQueue = Message.Infinite
    urgentMessageProperties.UseDeadLetterQueue = True

    'Set the label and priority for normal messages.
    normalMessageProperties.Label = "Normal Message"
    normalMessageProperties.Priority = MessagePriority.Normal
    'Make the process wait a finite amount of time for a message.
    normalMessageProperties.TimeToBeReceived = 3000
    normalMessageProperties.TimeToReachQueue = 3000
    normalMessageProperties.UseDeadLetterQueue = True
    'If the message is urgent, use the urgent DefaultPropertiesToSend
    If priority = MessagePriority.Highest Then
        messageQueue1.DefaultPropertiesToSend = urgentMessageProperties
    Else
        'Otherwise, use normal DefaultPropertiesToSend
        messageQueue1.DefaultPropertiesToSend = normalMessageProperties
    End If
    'Override default properties on the message object
    msg.Priority = messageQueue1.DefaultPropertiesToSend.Priority
    msg.Label = messageQueue1.DefaultPropertiesToSend.Label
    msg.TimeToBeReceived = messageQueue1.DefaultPropertiesToSend.TimeToBeReceived
    msg.TimeToReachQueue = messageQueue1.DefaultPropertiesToSend.TimeToReachQueue
    'Send the message that was passed in.
    messageQueue1.Send(msg)
End Sub

See Also

MessageQueue Class | MessageQueue Members | System.Messaging Namespace | Message | AcknowledgeType | EncryptionAlgorithm | HashAlgorithm | InfiniteTimeout | InfiniteTimeout