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!

Queue Reference Recommendations

If you create an instance of the MessageQueue component, you need to indicate what queue you want the component to communicate with. There are three ways to refer to a queue:

When you create a new queue, rather than a new instance of the MessageQueue component, you must use the path. Format name and label are assigned by the Message Queuing system after the queue is created. When you refer to an existing queue in code or from the toolbox, however, you can choose which method of referencing you want to use. Whatever method you choose is stored in the component's Path property.

Using Path to Refer to a Queue

A queue path takes the form servername\queuename. Paths to a queue are always unique. The following table lists the path information used for each type of queue:

Queue Type Syntax Used in Path
Public queue MachineName\QueueName
Private queue MachineName\Private$\QueueName
Journal queue MachineName\QueueName\Journal$
Machine journal queue MachineName\Journal$
Machine dead letter queue MachineName\Deadletter$
Machine transactional dead letter queue MachineName\XactDeadletter$

The following are a few caveats about using a path to refer to your queues:

You can retrieve the path for a queue by querying two separate properties in the MessageQueue base class—the MachineName property and the QueueName property.

Referencing a queue by Path looks like this:

[Visual Basic]
MessageQueue1.Path=”.\MyQueue”
[C#]
MessageQueue1.Path= @”.\MyQueue”;

Using Format Name to Refer to a Queue

Format names take the form of a string indicating whether a queue is public or private, followed by a generated GUID for the queue and other identifiers as necessary. The following table lists the path information used for each type of queue:

Queue Type Syntax Used in Format Name
Public queue PUBLIC=QueueGUID
Private queue PRIVATE=MachineGUID\QueueNumber
Journal queue PUBLIC=QueueGUID;JOURNAL or

PRIVATE=MachineGUID\QueueNumber;JOURNAL

Foreign queues DIRECT=AddressSpecification\QueueName

You do not assign a format name to a queue; instead, the queue manager generates this value when the queue is created. Referencing a queue by its format name is the most direct way to access a queue, because the domain controller on the server does not have to interpret the reference as it does when you refer to the queue by path.

The following are a few hints about referencing your queues by format name:

You can retrieve a format name for a queue by querying the FormatName property in the MessageQueue class.

Referencing a queue by format name looks like this:

Visual Basic]
MessageQueue1.Path=”.\MyQueue”
[C#]
MessageQueue1.Path= @”.\MyQueue”; 

Using Label to Refer to Queues

You can also refer to a queue by its label, which is a descriptive text label given to the queue by its administrator. Labels are not always unique, so you will receive an error when you try to connect to a specific queue using its label and a name conflict exists.

Labels can be useful in a situation where you know you are going to be moving a queue from one computer to another. If you refer to the queue by label only, all of your operations will continue to work successfully after the queue has been moved to its new location, provided that there are no other queues with that label on the new computer. If there are, the Send method will produce an error.

You can retrieve the label for a queue by querying the Label property in the MessageQueue class.

Referencing a queue by label name looks like this:

[Visual Basic]
MessageQueue1.Path=”.\MyQueue”
[C#]
MessageQueue1.Path= @”.\MyQueue”;

See Also

Creating, Deleting, and Administering Queues | Setting Queue References  | Creating Queues | Creating MessageQueue Components