Initializes a new instance of the MessageQueue class that references the Message Queuing application resource specified by the path parameter.
[Visual Basic] Overloads Public Sub New( _ ByVal path As String _ ) [C#] public MessageQueue( string path ); [C++] public: MessageQueue( String* path ); [JScript] public function MessageQueue( path : String );
Exception Type | Condition |
---|---|
ArgumentException | The Path property syntax in invalid. The path may not have been set. |
MessageQueueException | The FormatName property is invalid. |
MessageQueueException | The application attempted to access a queue defined by its Path property while offline. |
The MessageQueue constructor instantiates a new instance of a MessageQueue class. The constructor does not create a new Message Queuing backend object, so the queue to which you link the MessageQueue must already exist in the Message Queuing application. To create a new queue in Message Queuing, use Create.
Use this overload when the Message Queuing queue's path or format name are known and you wish to tie the MessageQueue to this backend resource. This overload of the constructor does not set the queue for exclusive access by the first application to reference the queue. If you want such access, either set the DenySharedReceive property to true or use the constructor that passes this restriction as a parameter.
The syntax for the path parameter depends on the type of queue it references. The following table shows the syntax you should use for a queue of a specified type.
Queue Type | Syntax |
---|---|
Public Queue | MachineName\QueueName |
Private Queue | MachineName\Private$\QueueName |
Journal Queue | MachineName\QueueName\Journal$ |
Machine Journal Queue | MachineName\Journal$ |
Machine Deadletter Queue | MachineName\Deadletter$ |
Machine Transactional Deadletter Queue | MachineName\XactDeadletter$ |
You can also use the FormatName or Label of a Message Queuing object to describe the queue path. The following table shows the proper syntax for each type of reference.
Reference | Syntax |
---|---|
Format Name | FormatName:[format name] |
Label | Label:[label] |
If you will be using the queue to work offline, you must use the format name, not the path name for the constructor. If you are working offline, using the path name will throw an exception because the primary domain controller won't be available to resolve the Path into the FormatName.
If you hard-code the path into your application, deleting and then creating a queue with the same name will not be seen as the same queue, because the queue Id which generates part of the FormatName will have changed.
You can specify the queue's label in the syntax of its path. Use the format Label:[label] in the Path.
When you create an instance of MessageQueue, the following read/write properties are set to initial values, based on the properties of the Message Queuing queue object at the specified path.
Property | Initial Value |
---|---|
Authenticate | The value of the Message Queuing queue object's authenticated setting. |
BasePriority | The value of the Message Queuing queue object's base priority setting. |
Category | The value of the Message Queuing queue object's type ID setting. |
DefaultPropertiesToSend | The values set by the default constructor of the DefaultPropertiesToSend class. |
EncryptionRequired | true, if the Message Queuing object's privacy level setting is "Body"; otherwise, false. |
Formatter | ?? XmlQueueMessageFormatter |
Label | The value of the Message Queuing queue object's label setting. |
MachineName | The value of the Message Queuing queue object's computer name setting. |
MaximumJournalSize | The value of the Message Queuing queue object's journal storage limit setting. |
MaximumQueueSize | The value of the Message Queuing queue object's message storage limit setting. |
MessageReadPropertyFilter | The values set by the default constructor of the MessagePropertyFilter class. All filter values are set to true. |
Path | The values of the Message Queuing queue object's path setting. |
QueueName | The values of the Message Queuing queue object's queue name setting. |
DenySharedReceive | false |
UseJournalQueue | true, if the Message Queuing object's journal setting is enabled; otherwise, false. |
You can change the value for any of these properties through a separate call to the property.
The following example creates a new MessageQueue object and sends a message to the queue. The Path is set when the MessageQueue is created.
This example assumes that a QueueName (such as "myQueue") and a body (say, a text string) are passed into the procedure. It also assumes there is a Message Queuing computer named myComputer.
[Visual Basic]
Private Sub SendMessage(ByVal queueName As String, ByVal body As Object) 'Define the queue path. Dim queuePath As String 'Set the queue path to an existing queue, such as myComputer\myQueue. queuePath = "myComputer\" + queueName 'Define a new MessageQueue object. Dim mq As MessageQueue 'Initialize the MessageQueue object using the constructor. mq = New MessageQueue(queuePath) 'Send a message to the queue. mq.Send(body) End Sub
MessageQueue Class | MessageQueue Members | System.Messaging Namespace | MessageQueue Constructor Overload List | FormatName | Label | Path | Create