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.

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

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.

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:

1. If the domain name is included, it tries to bind to the Active Directory Domain Services group object using this domain name.

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

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