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.Path

Gets or sets the queue's location.

[Visual Basic]
Overridable Public Property Path As String
[C#]
public string Path {virtual get; virtual set;}
[C++]
public: __property virtual String* get_Path();
public: __property virtual void set_Path(String*);
[JScript]
public function get Path() : String;
public function set Path(String);

Property Value

The location of the queue that is referenced by the MessageQueue.

Exceptions

Exception Type Condition
ArgumentException The path was set to an invalid value. The syntax may be invalid.
MessageQueueException The attempt to get or set the path generated an internal error on the message queue component. The error is specified by the given status message. The path syntax may not be valid.

Remarks

The syntax for the Path property 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$

Use "." for the local computer.

You can also use the FormatName or Label of a Message Queuing application 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 to define the queue Path. If you are working offline and use the syntax in the Queue Type table above instead of the format name, the application will throw an exception. This is caused when the primary domain controller is unavailable 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. Setting a new path closes the message queue and releases all handles.

Example [Visual Basic]

The following example sets the Path to a public MessageQueue based on the type of information passed in. Then a message is sent to the queue.

If the queue is defined by its FormatName or Label, the correct text is prepended to generate the Path. Otherwise, the Path is defined as MachineName\ QueueName, which is the standard format for a public queue. Because the local computer is assumed, the MachineName is ".".

This procedure assumes you have a public queue on the local computer named "myQueue". It assumes there is a queue with the label "My Queue". Then it assumes there is a queue with the specified format name.

[Visual Basic]

Private Sub SendMessageToPublicQueue()
    'Set the paths based on Label, QueueName and FormatName.
    SetPublicPath("Label", "My Queue")
    SetPublicPath("QueueName", "myQueue")
    'The format name will be non-zero.
    SetPublicPath("FormatName", "{00000000-0000-0000-0000-000000000000}")
End Sub

Private Sub SetPublicPath(ByVal pathType As String, ByVal queueStr As String)
    'Used to hold the Path.
    Dim queuePath As String
    'Define and instantiate a MessageQueue.
    Dim messageQueue1 As MessageQueue
    messageQueue1 = New MessageQueue

    'Build the Path based on the information passed in.
    Select Case pathType
        Case "FormatName"
queuePath = "FormatName:Public=" + queueStr
        Case "Label"
queuePath = "Label:" + queueStr
        Case "QueueName"
queuePath = ".\" + queueString
    End Select

    'Set the path and send a message.
    messageQueue1.Path = queuePath
    messageQueue1.Send("Sending message to myQueue.")
End Sub

See Also

MessageQueue Class | MessageQueue Members | System.Messaging Namespace | MachineName | QueueName | FormatName | Label | MessageQueue | Create | Delete | Close