For beginners to MSMQ development, the fact that there are FIVE ways of addressing an MSMQ queue is a real pitfall. Many hours will be lost trying to work out why a seemingly perfect address keeps returning errors.
To perform an operation on a queue, an application must reference the queue in one of five ways, depending on the operation that the application is performing:
- By path name—used to create the queue, to open the queue for sending, peeking at, and receiving messages, to reset the properties and security descriptor of the queue, and to delete the queue.
- By format name—used to open the queue for sending, peeking at, and receiving messages, to reset the properties and security descriptor of the queue, and to delete the queue.
- By queue handle—used to send messages to the queue, read from the queue, and create cursors for navigating through the queue (a queue handle can also be used to create a format name for the queue that can then be passed on to other processes).
- By queue alias—used to include queues that are not listed in Active Directory Domain Services (AD DS), such as a private queue or a URL-named queue, in a distribution list.
- By ADs path—used to reference queues when creating or maintaining a distribution list.
Only the first two are frequently used. I've highlighted "used to create the queue" for path name as this is a common misunderstanding - you can't create a queue using a format name.
The following require access to Active Directory when accessing remote machines
These have a basic syntax combining the machine name and queue name:
Public queues: ComputerName\QueueName
Private queues: ComputerName\Private$\QueueName
You can use a "." as a shortcut for accessing local queues on the sending machine:
Public queues: .\QueueName
Private queues: .\Private$\QueueName
If you specify a path using the path name syntax, it is translated into the associated (by querying Actice Directory) before accessing the queue.
Message Queuing uses single- and multiple-element format names to reference queues. Single-element format names include public, private, direct, distribution list, multicast address, machine, and connector format names, each with its own syntax. Multiple-element format names are a string of any number of single-element public, private, direct, and distribution list format names. Multiple-element format names are used only to send messages.
All of the following require access to Active Directory
Public Format Name Syntax
Public format names contain the string "PUBLIC=" followed by the identifier (GUID) of the queue that is generated by Message Queuing when the queue is created.
Private Format Name Syntax
Private format names contain the string "Private=" followed by the globally unique identifier (GUID) of the computer where the queue is registered and a hexadecimal number that identifies the queue.
Distribution List Format Name Syntax
Distribution list format names contain the string "DL=" followed by the distribution list identifier. The distribution list identifier (GUID) can be found in the objectGUID attribute of the distribution list group object using ADSI Edit.
Multicast Address Format Name Syntax
The following is the general form of a multicast address format name.
Multiple-Element Format Name Syntax
Multiple-element format names contain any number of single-element format names separated by commas.
Machine format name syntax
Machine format names contain the string "MACHINE=" followed by the identifier of the computer and the keyword that identifies which system queue to open. The following is the general form of the machine format names used to open a computer journal, a nontransactional dead-letter queue, and a transactional dead-letter queue:
MACHINE=ComputerGUID;JOURNAL *Computer journal.
MACHINE=ComputerGUID;DEADLETTER *Nontransactional dead-letter queue.
MACHINE=ComputerGUID;DEADXACT *Transactional dead-letter queue.
No requirement for Active Directory for the following - direct format names are essential for workgroup mode MSMQ but optional for AD-integrated MSMQ
Direct Format Name Syntax
Direct format names specify the location of the queue and the name of the queue.
The following is the general form of direct format names.
DIRECT=AddressSpecification\QueueName (For public queues)
DIRECT=AddressSpecification\PRIVATE$\QueueName (For private queues)
DIRECT=AddressSpecification\QueueName;JOURNAL (For public queue journals)
DIRECT=AddressSpecification\PRIVATE$\QueueName;JOURNAL (For private queue journals)
DIRECT=AddressSpecification\SYSTEM$;computersystemqueue (For computer journal and dead-letter queues.)
The Address Specification
The address specification of the computer can be in one of three forms. I've highlighted the portion that is the actual address specification that you need to insert in the direct format name syntax above:
- Using the IP address of the destination.
- Using the computer name of the destination.
- Using HTTP and referencing the MSMQ virtual directory of the destination web server
When sending messages over HTTP, make sure ALL the slashes in the address are leaning forward.
If you are using the MessageQueue constructor, you will need to add "FormatName:" to the beginning of the Direct Format Name string:
- FormatName:DIRECT=TCP: IPAddress\QueueName
- FormatName:DIRECT=OS: MachineName\QueueName
Confused? That's normal but with a little practice you will get the hang of things.