MessageQueue::Path Property
Gets or sets the queue's path. Setting the Path causes the MessageQueue to point to a new queue.
Assembly: System.Messaging (in System.Messaging.dll)
public: [SettingsBindableAttribute(true)] [BrowsableAttribute(false)] [TypeConverterAttribute("System.Diagnostics.Design.StringValueConverter, System.Design, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a")] [MessagingDescriptionAttribute("MQ_Path")] property String^ Path { String^ get(); void set(String^ value); }
Property Value
Type: System::String^The queue that is referenced by the MessageQueue. The default depends on which MessageQueue constructor you use; it is either null or is specified by the constructor's path parameter.
| Exception | Condition |
|---|---|
| ArgumentException | The path is not valid, possibly because the syntax is not valid. |
The syntax for the Path property depends on the type of queue it points to, as shown in the following table.
Queue type | Syntax |
|---|---|
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$ |
Use "." to represent the local computer.
The MachineName, Path, and QueueName properties are related. Changing the MachineName property causes the Path property to change. It is built from the new MachineName and the QueueName. Changing the Path (for example, to use the format name syntax) resets the MachineName and QueueName properties to refer to the new queue.
Alternatively, you can use the FormatName or Label to describe the queue path, as shown in the following table.
Reference | Syntax | Example |
|---|---|---|
Format name | FormatName: [ format name ] | FormatName:Public= 5A5F7535-AE9A-41d4-935C-845C2AFF7112 |
Label | Label: [ label ] | Label: TheLabel |
If you use the label syntax for the Path property when you send the message, an exception will be thrown if the Label is not unique.
To work offline, you must use the format name syntax, rather than the friendly name syntax in the first table. Otherwise, an exception is thrown because the primary domain controller (on which Active Directory resides) is not available to resolve the path to the format name.
Setting a new path closes the message queue and releases all handles.
The following table shows whether this property is available in various Workgroup modes.
Workgroup mode | Available |
|---|---|
Local computer | Yes |
Local computer and direct format name | Yes |
Remote computer | Yes |
Remote computer and direct format name | Yes |
Note |
|---|
In workgroup mode you can only use private queues. You specify the path using the private queue syntax MachineName\Private$\QueueName. |
The following code example creates new MessageQueue objects using various path name syntax types. In each case, it sends a message to the queue whose path is defined in the constructor.
#using <system.dll> #using <system.messaging.dll> using namespace System; using namespace System::Messaging; ref class MyNewQueue { public: // References public queues. void SendPublic() { MessageQueue^ myQueue = gcnew MessageQueue( ".\\myQueue" ); myQueue->Send( "Public queue by path name." ); return; } // References private queues. void SendPrivate() { MessageQueue^ myQueue = gcnew MessageQueue( ".\\Private$\\myQueue" ); myQueue->Send( "Private queue by path name." ); return; } // References queues by label. void SendByLabel() { MessageQueue^ myQueue = gcnew MessageQueue( "Label:TheLabel" ); myQueue->Send( "Queue by label." ); return; } // References queues by format name. void SendByFormatName() { MessageQueue^ myQueue = gcnew MessageQueue( "FormatName:Public=5A5F7535-AE9A-41d4 -935C-845C2AFF7112" ); myQueue->Send( "Queue by format name." ); return; } // References computer journal queues. void MonitorComputerJournal() { MessageQueue^ computerJournal = gcnew MessageQueue( ".\\Journal$" ); while ( true ) { Message^ journalMessage = computerJournal->Receive(); // Process the journal message. } } // References queue journal queues. void MonitorQueueJournal() { MessageQueue^ queueJournal = gcnew MessageQueue( ".\\myQueue\\Journal$" ); while ( true ) { Message^ journalMessage = queueJournal->Receive(); // Process the journal message. } } // References dead-letter queues. void MonitorDeadLetter() { MessageQueue^ deadLetter = gcnew MessageQueue( ".\\DeadLetter$" ); while ( true ) { Message^ deadMessage = deadLetter->Receive(); // Process the dead-letter message. } } // References transactional dead-letter queues. void MonitorTransactionalDeadLetter() { MessageQueue^ TxDeadLetter = gcnew MessageQueue( ".\\XactDeadLetter$" ); while ( true ) { Message^ txDeadLetter = TxDeadLetter->Receive(); // Process the transactional dead-letter message. } } }; //************************************************* // Provides an entry point into the application. // // This example demonstrates several ways to set // a queue's path. //************************************************* int main() { // Create a new instance of the class. MyNewQueue^ myNewQueue = gcnew MyNewQueue; myNewQueue->SendPublic(); myNewQueue->SendPrivate(); myNewQueue->SendByLabel(); myNewQueue->SendByFormatName(); myNewQueue->MonitorComputerJournal(); myNewQueue->MonitorQueueJournal(); myNewQueue->MonitorDeadLetter(); myNewQueue->MonitorTransactionalDeadLetter(); return 0; }
Available since 1.1
