Queue Names
Applies To: Windows Server 2008
Queue names
The following sections describe the various ways to designate Message Queuing queues. Queues are specified using path names, format names, and queue aliases. For more information about the types of queues mentioned here, see Queues.
Path names
The path name of a queue consists of the name of the computer hosting the queue and the name of the queue separated by a slash in the form ComputerName\QueueName, except for a public queue located on the local computer where the path name is in the form .\QueueName. The names of private queues are prefixed by the string private$ separated by a slash. Thus, the path name of a private queue has the form ComputerName\private$\QueueName or .\private$\QueueName for a private queue located on the local computer.
Format names
Format names are used mostly by Message Queuing applications to perform tasks programmatically. However, they are also used in some administrative tasks (for example, in creating queue aliases and multiple-element format names), and administrators must have an understanding of format names to make correct decisions. The following sections describe most of the types of format names used in Message Queuing.
Direct format names
Direct format names are used to reference public or private queues without accessing the directory service. Message Queuing can use the information provided by direct format names to send messages directly to their destination. Thus, direct format names can be used to send and receive messages in workgroup mode, to send messages to computers on the Internet, and to send messages directly to a computer.
Note
Direct format names that specify the HTTP or HTTPS protocol cannot be used to peek at or receive messages, only to send them.
The following is the general format of direct format names. Note that public, private, and (for MSMQ 2.0 or later clients and servers) computer system queues can be accessed directly.
Direct format names contain the string DIRECT= followed by the location of the queue and its name. The location of the queue can be specified as the name (computer address), the HTTP URL (https://URL_Address/msmq or HTTPS://URL_Address/msmq), or the IP address associated with the destination computer.
When specifying the destination computer using the computer address, either the fully qualified domain name or the NetBIOS name of the computer can be used if the specified name can be resolved to an IP address. The following is the general format of direct format names for public, private, and system queues when distinguished by the computer address:
DIRECT=ComputerAddress\PublicQueueName
DIRECT=ComputerAddress\PRIVATE$\PrivateQueueName
DIRECT=ComputerAddress\SYSTEM$;SystemQueueName
The computer address can also be specified as the network address of the target computer, which includes the network protocol TCP, or as any name for the target computer that is supported natively by the underlying operating system, where OS is used to indicate that the computer's native protocol will be used. The following examples illustrate the use of these forms:
DIRECT=TCP:157.18.3.1\PublicQueueName
DIRECT=OS:pc001.microsoft.com\PublicQueueName
When specifying the destination computer with the HTTP URL associated with the computer, the queue name is preceded by the string msmq separated by a slash. For example, the following format names can be used to reference "PublicQueue" and "PrivateQueue":
DIRECT=https://URL_Address/msmq/PublicQueue
DIRECT=HTTPS://URL_Address/msmq/PublicQueue
DIRECT=HTTPS://URL_Address/msmq/private$\PrivateQueue
Note
Accessing the destination computer using an HTTP URL requires that the HTTP Support feature is installed and correctly configured on the destination computer.
Public format names
Public format names and direct format names are used to reference public queues. When a public format name is used, Message Queuing uses its internal routing algorithm to define the route to the destination queue. When a direct format name is used, the message is sent directly to the destination queue.
When Message Queuing detects a public format name, it queries the directory service to determine what computer is currently hosting the queue, what protocol the host computer uses, and any other information it needs to rout a message to the queue.
Public format names contain the string PUBLIC= followed by the identifier assigned to the queue when it was created. This identifier is the GUID listed for the queue object in Active Directory Domain Services. The following is the general format used to reference a public queue and its associated queue journal:
PUBLIC=QueueGUID
PUBLIC=QueueGUID;JOURNAL
A public format name is strictly equivalent to the identifier of the queue except that a public format name is formatted as a string rather than as binary data. The following is an example of a public format name string (note that the format name string is a null-terminated Unicode string).
PUBLIC=308FB580-1EB2-11CA-923B-08002B1075A7
Private format names
Private format names and direct format names are used to reference private queues. When a private format name is used, Message Queuing uses its internal routing algorithm to define the route to the destination queue. When a direct format name is used, the message is sent directly to the destination queue.
When Message Queuing detects a private format name, it does not refer to the directory service for information about the queue. However, it does use the directory service to look up information about the computer for routing purposes.
Private format names contain the string PRIVATE= followed by the identifier of the computer where the queue is registered and a hexadecimal number that identifies the queue. The following is the general format used to reference a private queue and its associated journal:
PRIVATE=ComputerGUID\QueueNumber
PRIVATE=ComputerGUID\QueueNumber;JOURNAL
The following is an example of a private format name string (note that the format name string is a null-terminated Unicode string).
PRIVATE=ae0c5671-f190-12ce-ae10-00dd0114290f\0000000d
Distribution list format names
Distribution list format names are used to reference distribution lists (group objects) stored in Active Directory Domain Services. The distribution list identifier is the GUID listed for the distribution list (group) object in Active Directory Domain Services.
Distribution list format names contain the string DL= followed by the distribution list identifier. This identifier is the GUID listed for the distribution list (group) object in Active Directory Domain Services.
Note
Use ADSI edit to determine the GUID for a distribution list in Active Directory Domain Services. To launch ADSI edit, click Start, click Run, type adsiedit.msc, and then press Enter.
The following is the general format used to reference a distribution list with optional inclusion of the domain name:
DL=DistributionListGUID[@DomainName]
The following is an example of a distribution list format name string (note that the format name string is a null-terminated Unicode string).
DL=ae0c5671-f190-12ce-ae10-00dd0114290f
To retrieve information about a distribution list, Message Queuing tries to resolve the DL format name to the corresponding Active Directory Domain Services object in three steps:
If the domain name is included, it tries to bind to the Active Directory Domain Services group object using this domain name.
If this attempt fails or the domain name is not specified, it allows Active Directory Domain Services to use serverless binding to find the best domain controller in the default domain.
If this also fails, it tries to query the global catalog.
A distribution list format name can be an element of a multiple-element format name. In this respect, the analogy to a queue format name is preserved.
For more information about distribution lists, see Distribution Lists.
Multiple-element format names
A multiple-element format name is formed as a concatenation of one or more public, private, direct, or distribution list format names separated by commas. Thus, different kinds of format names used in Message Queuing can be used together as elements of a multiple-element format name. The following example shows a multiple-element format name that contains a direct format name, a public format name, and a distribution list format name.
DIRECT=ComputerAddress\QueueName,PUBLIC=QueueGUID,DL=DL_GUID
Note that a multiple-element format name containing an element that points to a public queue or a distribution list cannot be used when there is no access to Active Directory Domain Services.
Multiple-element format names cannot contain the format names of read-only queues, such as queue journals, computer journals, or dead-letter queues. An error is returned if the format name of a read-only queue is included in the multiple-element format name.
For more information about multiple-element format names, see Multiple-Element Format Names.
For more information about these and other types of format names, such as machine and connector format names, refer to the Message Queuing Software Development Kit (SDK). For information about accessing the Message Queuing SDK, see Additional Resources for Administering Message Queuing.