MessageQueue Constructor (String)
Initializes a new instance of the MessageQueue class that references the Message Queuing queue at the specified path.
Namespace: System.Messaging
Assembly: System.Messaging (in System.Messaging.dll)
Parameters
- path
- Type: System.String
The location of the queue referenced by this MessageQueue.
| Exception | Condition |
|---|---|
| ArgumentException | The Path property is not valid, possibly because it has not been set. |
Use this overload when you want to tie the new MessageQueue instance to a particular Message Queuing queue, for which you know the path, format name, or label. If you want to grant exclusive access to the first application that references the queue, you must set the DenySharedReceive property to true or use the constructor that passes a read-access restriction parameter.
The MessageQueue constructor instantiates a new instance of the MessageQueue class; it does not create a new Message Queuing queue. To create a new queue in Message Queuing, use Create(String).
The syntax of the path parameter depends on the type of queue it references, 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$ |
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 FormatName:DIRECT=SPX: NetworkNumber; HostNumber\QueueName FormatName:DIRECT=TCP: IPAddress\QueueName FormatName:DIRECT=OS: MachineName\QueueName |
Label | Label: [ label ] | Label: TheLabel |
To work offline, you must use the format name syntax, not the path name syntax for the constructor. Otherwise, an exception is thrown because the primary domain controller is not available to resolve the path to the format name.
The following table shows initial property values for an instance of MessageQueue. These values are based on the properties of the Message Queuing queue with the path specified by the path parameter.
Property | Initial value |
|---|---|
false | |
0 | |
The values set by the default constructor of the DefaultPropertiesToSend class. | |
true, if the Message Queuing queue's privacy level setting is "Body"; otherwise, false. | |
The value of the Message Queuing queue's computer name property. | |
The values set by the default constructor of the MessagePropertyFilter class. | |
Empty, if not set by the constructor. | |
Empty, if not set by the constructor. | |
false | |
true, if the Message Queuing object's journal setting is enabled; otherwise, false. |
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; using System.Messaging; namespace MyProject { /// <summary> /// Provides a container class for the example. /// </summary> public class MyNewQueue { //************************************************** // Provides an entry point into the application. // // This example demonstrates several ways to set // a queue's path. //************************************************** public static void Main() { // Create a new instance of the class. MyNewQueue myNewQueue = new MyNewQueue(); myNewQueue.SendPublic(); myNewQueue.SendPrivate(); myNewQueue.SendByLabel(); myNewQueue.SendByFormatName(); myNewQueue.MonitorComputerJournal(); myNewQueue.MonitorQueueJournal(); myNewQueue.MonitorDeadLetter(); myNewQueue.MonitorTransactionalDeadLetter(); return; } // References public queues. public void SendPublic() { MessageQueue myQueue = new MessageQueue(".\\myQueue"); myQueue.Send("Public queue by path name."); return; } // References private queues. public void SendPrivate() { MessageQueue myQueue = new MessageQueue(".\\Private$\\myQueue"); myQueue.Send("Private queue by path name."); return; } // References queues by label. public void SendByLabel() { MessageQueue myQueue = new MessageQueue("Label:TheLabel"); myQueue.Send("Queue by label."); return; } // References queues by format name. public void SendByFormatName() { MessageQueue myQueue = new MessageQueue("FormatName:Public=5A5F7535-AE9A-41d4" + "-935C-845C2AFF7112"); myQueue.Send("Queue by format name."); return; } // References computer journal queues. public void MonitorComputerJournal() { MessageQueue computerJournal = new MessageQueue(".\\Journal$"); while(true) { Message journalMessage = computerJournal.Receive(); // Process the journal message. } } // References queue journal queues. public void MonitorQueueJournal() { MessageQueue queueJournal = new MessageQueue(".\\myQueue\\Journal$"); while(true) { Message journalMessage = queueJournal.Receive(); // Process the journal message. } } // References dead-letter queues. public void MonitorDeadLetter() { MessageQueue deadLetter = new MessageQueue(".\\DeadLetter$"); while(true) { Message deadMessage = deadLetter.Receive(); // Process the dead-letter message. } } // References transactional dead-letter queues. public void MonitorTransactionalDeadLetter() { MessageQueue TxDeadLetter = new MessageQueue(".\\XactDeadLetter$"); while(true) { Message txDeadLetter = TxDeadLetter.Receive(); // Process the transactional dead-letter message. } } } }
- Full trust for the immediate caller. This member cannot be used by partially trusted code. For more information, see Using Libraries from Partially Trusted Code.
Windows 8, Windows Server 2012, Windows 7, Windows Vista SP2, Windows Server 2008 (Server Core Role not supported), Windows Server 2008 R2 (Server Core Role supported with SP1 or later; Itanium not supported)
The .NET Framework does not support all versions of every platform. For a list of the supported versions, see .NET Framework System Requirements.