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 in your code:
By path — the path to a queue uniquely identifies the computer and queue name for the queue in which you are interested.
By format name — a unique identifier for the queue that is generated by MSMQ when the queue is created or generated later by the application.
By label — a descriptive and potentially non-unique name for the queue that is assigned by the queue administrator when the queue is created.
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$ |
You can use "." for the local machine name, so that "YourMachine\MyQueue" is equivalent to ".\MyQueue".
The following are a few caveats about using a path to refer to your queues:
When the domain controller on a Message Queuing server receives an operation for a queue that is referenced by path, it must resolve that path and determine the format name of the queue in question. This may result in slightly slower performance than if you refer to the queue by format name directly.
If you are designing your component to be used as an XML Web service, you will get the best performance results by using the format name method of referring to queues rather than the path method.
You cannot refer to a queue by path if you want to send messages to it when the queue is disconnected. Disconnected messages must be sent using the format name.
You can retrieve the path for a queue by querying and combining the return results of two separate properties in the MessageQueue base class — the MachineName property and the QueueName property.
In code, referencing a queue by path looks like this:
MessageQueue1.Path = "YourMachine\MyQueue"
MessageQueue1.Path = @"YourMachine\MyQueue";
Note
The @".\MyQueue" syntax for C# is equivalent to using ".\\MyQueue" instead. The @ sign indicates a literal string. For more information, see string (C# Reference).
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 |
FORMATNAME:PUBLIC=QueueGUID |
Private queue |
FORMATNAME:PRIVATE=MachineGUID\QueueNumber |
Journal queue |
FORMATNAME:PUBLIC=QueueGUID;JOURNAL – or – FORMATNAME:PRIVATE=MachineGUID\QueueNumber;JOURNAL |
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:
If you intend to send messages to a disconnected queue, you must refer to the queue by format name rather than path, because the path will not be available to resolve with if the queue is offline.
Be aware that format names may become invalid when your network topography changes or when a queue is deleted and re-created.
You can retrieve a format name for a queue by querying the FormatName property in the MessageQueue class.
In code, referencing a queue by format name looks like this:
MessageQueue1.Path = _
"FORMATNAME:PUBLIC=3d3dc813-c555-4fd3-8ce0-79d5b45e0d75"
MessageQueue1.Path =
"FORMATNAME:PUBLIC=3d3dc813-c555-4fd3-8ce0-79d5b45e0d75";
Using Labels 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 if a name conflict exists when you try to connect to a specific queue using its label.
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.
In code, referencing a queue by label name looks like this:
MessageQueue1.Path = "LABEL:MyQueue"
MessageQueue1.Path = "LABEL:MyQueue";
How to: Set Queue References
How to: Set Queue References
How to: Set Queue References
See Also
Tasks
How to: Create MessageQueue Component Instances