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 Constructor (String)

Initializes a new instance of the MessageQueue class that references the Message Queuing application resource specified by the path parameter.

[Visual Basic]
Overloads Public Sub New( _
   ByVal path As String _
)
[C#]
public MessageQueue(
   string path
);
[C++]
public: MessageQueue(
   String* path
);
[JScript]
public function MessageQueue(
   path : String
);

Parameters

path
The location of the queue referenced by this MessageQueue, or "." for the local computer. For information on proper syntax for this parameter, see the Remarks section.

Exceptions

Exception Type Condition
ArgumentException The Path property syntax in invalid. The path may not have been set.
MessageQueueException The FormatName property is invalid.
MessageQueueException The application attempted to access a queue defined by its Path property while offline.

Remarks

The MessageQueue constructor instantiates a new instance of a MessageQueue class. The constructor does not create a new Message Queuing backend object, so the queue to which you link the MessageQueue must already exist in the Message Queuing application. To create a new queue in Message Queuing, use Create.

Use this overload when the Message Queuing queue's path or format name are known and you wish to tie the MessageQueue to this backend resource. This overload of the constructor does not set the queue for exclusive access by the first application to reference the queue. If you want such access, either set the DenySharedReceive property to true or use the constructor that passes this restriction as a parameter.

The syntax for the path parameter depends on the type of queue it references. The following table shows the syntax you should use for a queue of a specified type.

Queue Type Syntax
Public Queue MachineName\QueueName
Private Queue MachineName\Private$\QueueName
Journal Queue MachineName\QueueName\Journal$
Machine Journal Queue MachineName\Journal$
Machine Deadletter Queue MachineName\Deadletter$
Machine Transactional Deadletter Queue MachineName\XactDeadletter$

You can also use the FormatName or Label of a Message Queuing object to describe the queue path. The following table shows the proper syntax for each type of reference.

Reference Syntax
Format Name FormatName:[format name]
Label Label:[label]

If you will be using the queue to work offline, you must use the format name, not the path name for the constructor. If you are working offline, using the path name will throw an exception because the primary domain controller won't be available to resolve the Path into the FormatName.

If you hard-code the path into your application, deleting and then creating a queue with the same name will not be seen as the same queue, because the queue Id which generates part of the FormatName will have changed.

You can specify the queue's label in the syntax of its path. Use the format Label:[label] in the Path.

When you create an instance of MessageQueue, the following read/write properties are set to initial values, based on the properties of the Message Queuing queue object at the specified path.

Property Initial Value
Authenticate The value of the Message Queuing queue object's authenticated setting.
BasePriority The value of the Message Queuing queue object's base priority setting.
Category The value of the Message Queuing queue object's type ID setting.
DefaultPropertiesToSend The values set by the default constructor of the DefaultPropertiesToSend class.
EncryptionRequired true, if the Message Queuing object's privacy level setting is "Body"; otherwise, false.
Formatter ?? XmlQueueMessageFormatter
Label The value of the Message Queuing queue object's label setting.
MachineName The value of the Message Queuing queue object's computer name setting.
MaximumJournalSize The value of the Message Queuing queue object's journal storage limit setting.
MaximumQueueSize The value of the Message Queuing queue object's message storage limit setting.
MessageReadPropertyFilter The values set by the default constructor of the MessagePropertyFilter class. All filter values are set to true.
Path The values of the Message Queuing queue object's path setting.
QueueName The values of the Message Queuing queue object's queue name setting.
DenySharedReceive false
UseJournalQueue true, if the Message Queuing object's journal setting is enabled; otherwise, false.

You can change the value for any of these properties through a separate call to the property.

Example [Visual Basic]

The following example creates a new MessageQueue object and sends a message to the queue. The Path is set when the MessageQueue is created.

This example assumes that a QueueName (such as "myQueue") and a body (say, a text string) are passed into the procedure. It also assumes there is a Message Queuing computer named myComputer.

[Visual Basic]

Private Sub SendMessage(ByVal queueName As String, ByVal body As Object)
    'Define the queue path.
    Dim queuePath As String
    'Set the queue path to an existing queue, such as myComputer\myQueue.
    queuePath = "myComputer\" + queueName
    'Define a new MessageQueue object.
    Dim mq As MessageQueue
    'Initialize the MessageQueue object using the constructor.
    mq = New MessageQueue(queuePath)

    'Send a message to the queue.
    mq.Send(body)
End Sub

See Also

MessageQueue Class | MessageQueue Members | System.Messaging Namespace | MessageQueue Constructor Overload List | FormatName | Label | Path | Create