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)

public:
MessageQueue(
	String^ path
)

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

Authenticate

false

BasePriority

0

Category

Empty

DefaultPropertiesToSend

The values set by the default constructor of the DefaultPropertiesToSend class.

EncryptionRequired

true, if the Message Queuing queue's privacy level setting is "Body"; otherwise, false.

Formatter

XmlMessageFormatter

Label

Empty

MachineName

The value of the Message Queuing queue's computer name property.

MaximumJournalSize

InfiniteQueueSize

MaximumQueueSize

InfiniteQueueSize

MessageReadPropertyFilter

The values set by the default constructor of the MessagePropertyFilter class.

Path

Empty, if not set by the constructor.

QueueName

Empty, if not set by the constructor.

DenySharedReceive

false

UseJournalQueue

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.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;
}

.NET Framework
Available since 1.1
Return to top
Show: