Initializes a new instance of the MessageQueue class that references the Message Queuing application resource specified by the path parameter, and has the specified queue access restriction.
[Visual Basic] Overloads Public Sub New( _ ByVal path As String, _ ByVal sharedModeDenyReceive As Boolean _ ) [C#] public MessageQueue( string path, bool sharedModeDenyReceive ); [C++] public: MessageQueue( String* path, bool sharedModeDenyReceive ); [JScript] public function MessageQueue( path : String, sharedModeDenyReceive : Boolean );
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 you link the MessageQueue to 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 can set the queue for exclusive access by the first application to reference the queue. If you do not want such access, either set the sharedModeDenyReceive parameter to false or use the constructor that passes in only the path 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 of 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 domain controller which owns the Active Directory 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.
If sharedModeDenyReceive is set to true, the first application to access the queue has exclusive access.
When you create an instance of MessageQueue, the folowing 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 path parameter. |
QueueName | The values of the Message Queuing queue object's queue name setting. |
DenySharedReceive | The sharedModeDenyReceive parameter. |
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. The queue requires exclusive access by setting sharedModeDenyReceive to true.
[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 with exclusive access. mq = New MessageQueue(queuePath, True) '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 | DenySharedReceive