MessageQueue Constructors

Definition

Namespace:

System.Messaging

Assembly:

System.Messaging.dll

Initializes a new instance of the MessageQueue class.

Overloads

MessageQueue()	Initializes a new instance of the MessageQueue class. After the parameterless constructor initializes the new instance, you must set the instance's Path property before you can use the instance.
MessageQueue(String)	Initializes a new instance of the MessageQueue class that references the Message Queuing queue at the specified path.
MessageQueue(String, Boolean)	Initializes a new instance of the MessageQueue class that references the Message Queuing queue at the specified path and with the specified read-access restriction.
MessageQueue(String, QueueAccessMode)	Initializes a new instance of the MessageQueue class.
MessageQueue(String, Boolean, Boolean)	Initializes a new instance of the MessageQueue class.
MessageQueue(String, Boolean, Boolean, QueueAccessMode)	Initializes a new instance of the MessageQueue class.

MessageQueue()

Initializes a new instance of the MessageQueue class. After the parameterless constructor initializes the new instance, you must set the instance's Path property before you can use the instance.

public:
 MessageQueue();

public MessageQueue ();

Public Sub New ()

Examples

The following code example creates a new MessageQueue.

// Connect to a queue on the local computer. You must set the queue's
// Path property before you can use the queue.
MessageQueue queue = new MessageQueue();
queue.Path = ".\\exampleQueue";

Remarks

Use this overload to create a new instance of the MessageQueue class that is not immediately tied to a queue on the Message Queuing server. Before using this instance, you must connect it to an existing Message Queuing queue by setting the Path property. Alternatively, you can set the MessageQueue reference to the Create(String) method's return value, thereby creating a new Message Queuing queue.

The MessageQueue constructor instantiates a new instance of the MessageQueue class; it does not create a new Message Queuing queue.

The following table shows initial property values for an instance of MessageQueue.

Property	Initial value
DefaultPropertiesToSend	The values set by the parameterless constructor of the DefaultPropertiesToSend class.
Formatter	XmlMessageFormatter
MessageReadPropertyFilter	The values set by the parameterless constructor of the MessagePropertyFilter class. All the filter values are set to true.
DenySharedReceive	false

See also

• Path
• QueueName
• FormatName
• Label

MessageQueue(String)

Initializes a new instance of the MessageQueue class that references the Message Queuing queue at the specified path.

public:
 MessageQueue(System::String ^ path);

public MessageQueue (string path);

new System.Messaging.MessageQueue : string -> System.Messaging.MessageQueue

Public Sub New (path As String)

Parameters

path

String

The location of the queue referenced by this MessageQueue.

Exceptions

ArgumentException

The Path property is not valid, possibly because it has not been set.

Examples

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

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

Imports System.Messaging

Public Class MyNewQueue


        
        ' Provides an entry point into the application.
        '		 
        ' This example demonstrates several ways to set
        ' a queue's path.
        

        Public Shared Sub Main()

            ' Create a new instance of the class.
            Dim myNewQueue As New MyNewQueue()

            myNewQueue.SendPublic()
            myNewQueue.SendPrivate()
            myNewQueue.SendByLabel()
            myNewQueue.SendByFormatName()
            myNewQueue.MonitorComputerJournal()
            myNewQueue.MonitorQueueJournal()
            myNewQueue.MonitorDeadLetter()
            myNewQueue.MonitorTransactionalDeadLetter()

            Return

        End Sub


        ' References public queues.
        Public Sub SendPublic()

            Dim myQueue As New MessageQueue(".\myQueue")
            myQueue.Send("Public queue by path name.")

            Return

        End Sub


        ' References private queues.
        Public Sub SendPrivate()

            Dim myQueue As New MessageQueue(".\Private$\myQueue")
            myQueue.Send("Private queue by path name.")

            Return

        End Sub


        ' References queues by label.
        Public Sub SendByLabel()

            Dim myQueue As New MessageQueue("Label:TheLabel")
            myQueue.Send("Queue by label.")

            Return

        End Sub


        ' References queues by format name.
        Public Sub SendByFormatName()

            Dim myQueue As New _
                MessageQueue("FormatName:Public=" + _
                    "5A5F7535-AE9A-41d4-935C-845C2AFF7112")
            myQueue.Send("Queue by format name.")

            Return

        End Sub


        ' References computer journal queues.
        Public Sub MonitorComputerJournal()

            Dim computerJournal As New MessageQueue(".\Journal$")

            While True

                Dim journalMessage As Message = _
                    computerJournal.Receive()

                ' Process the journal message.

            End While

            Return
        End Sub


        ' References queue journal queues.
        Public Sub MonitorQueueJournal()

            Dim queueJournal As New _
                            MessageQueue(".\myQueue\Journal$")

            While True

                Dim journalMessage As Message = _
                    queueJournal.Receive()

                ' Process the journal message.

            End While

            Return
        End Sub


        ' References dead-letter queues.
        Public Sub MonitorDeadLetter()
            Dim deadLetter As New MessageQueue(".\DeadLetter$")

            While True

                Dim deadMessage As Message = deadLetter.Receive()

                ' Process the dead-letter message.

            End While

            Return

        End Sub


        ' References transactional dead-letter queues.
        Public Sub MonitorTransactionalDeadLetter()

            Dim TxDeadLetter As New MessageQueue(".\XactDeadLetter$")

            While True

                Dim txDeadLetterMessage As Message = _
                    TxDeadLetter.Receive()

                ' Process the transactional dead-letter message.

            End While

            Return

        End Sub

End Class

Remarks

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 parameterless 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 parameterless 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.

See also

• FormatName
• Label
• QueueName
• Path

MessageQueue(String, Boolean)

Initializes a new instance of the MessageQueue class that references the Message Queuing queue at the specified path and with the specified read-access restriction.

public:
 MessageQueue(System::String ^ path, bool sharedModeDenyReceive);

public MessageQueue (string path, bool sharedModeDenyReceive);

new System.Messaging.MessageQueue : string * bool -> System.Messaging.MessageQueue

Public Sub New (path As String, sharedModeDenyReceive As Boolean)

Parameters

path

String

The location of the queue referenced by this MessageQueue, which can be "." for the local computer.

sharedModeDenyReceive

Boolean

true to grant exclusive read access to the first application that accesses the queue; otherwise, false.

Exceptions

ArgumentException

The Path property is not valid, possibly because it has not been set.

Examples

The following code example creates a new MessageQueue with exclusive access, sets its path, and sends a message to the queue.

#using <system.dll>
#using <system.messaging.dll>

using namespace System;
using namespace System::Messaging;
ref class MyNewQueue
{
public:

   // Requests exlusive read access to the queue. If
   // access is granted, receives a message from the 
   // queue.
   void GetExclusiveAccess()
   {
      try
      {
         
         // Request exclusive read access to the queue.
         MessageQueue^ myQueue = gcnew MessageQueue( ".\\myQueue",true );
         
         // Receive a message. This is where SharingViolation 
         // exceptions would be thrown.
         Message^ myMessage = myQueue->Receive();
      }
      catch ( MessageQueueException^ e ) 
      {
         
         // Handle request for denial of exclusive read access.
         if ( e->MessageQueueErrorCode == MessageQueueErrorCode::SharingViolation )
         {
            Console::WriteLine( "Denied exclusive read access" );
         }

         
         // Handle other sources of a MessageQueueException.
      }

      
      // Handle other exceptions as necessary.
      return;
   }

};


// Provides an entry point into the application.
// This example connects to a message queue, and
// requests exclusive read access to the queue.
int main()
{
   
   // Create a new instance of the class.
   MyNewQueue^ myNewQueue = gcnew MyNewQueue;
   
   // Output the count of Lowest priority messages.
   myNewQueue->GetExclusiveAccess();
   return 0;
}

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 connects to a message queue, and
        // requests exclusive read access to the queue.
        //**************************************************

        public static void Main()
        {
            // Create a new instance of the class.
            MyNewQueue myNewQueue = new MyNewQueue();

            // Output the count of Lowest priority messages.
            GetExclusiveAccess();
                        
            return;
        }

        //**************************************************
        // Requests exlusive read access to the queue. If
        // access is granted, receives a message from the
        // queue.
        //**************************************************
        
        public static void GetExclusiveAccess()
        {
            try
            {
                // Request exclusive read access to the queue.
                MessageQueue myQueue = new
                    MessageQueue(".\\myQueue", true);

                // Receive a message. This is where SharingViolation
                // exceptions would be thrown.
                Message myMessage = myQueue.Receive();
            }
            
            catch (MessageQueueException e)
            {
                // Handle request for denial of exclusive read access.
                if (e.MessageQueueErrorCode ==
                    MessageQueueErrorCode.SharingViolation)
                {
                    Console.WriteLine("Denied exclusive read access");
                }

                // Handle other sources of a MessageQueueException.
            }

            // Handle other exceptions as necessary.

            return;
        }
    }
}

Imports System.Messaging

Public Class MyNewQueue


        ' Provides an entry point into the application.
        '		 
        ' This example connects to a message queue, and
        ' requests exclusive read access to the queue.
 

        Public Shared Sub Main()

            ' Create a new instance of the class.
            Dim myNewQueue As New MyNewQueue()

            ' Output the count of Lowest priority messages.
            myNewQueue.GetExclusiveAccess()

            Return

        End Sub


  
        ' Requests exlusive read access to the queue. If
        ' access is granted, receives a message from the 
        ' queue.
  

        Public Sub GetExclusiveAccess()

            Try

                ' Request exclusive read access to the queue.
                Dim myQueue As New MessageQueue(".\myQueue", True)

                ' Receive a message. This is where a SharingViolation 
                ' exception would be thrown.
                Dim myMessage As Message = myQueue.Receive()

            Catch e As MessageQueueException

                ' Handle request for denial of exclusive read access.
                If e.MessageQueueErrorCode = _
                    MessageQueueErrorCode.SharingViolation Then

                    Console.WriteLine("Denied exclusive read access.")

                End If

                ' Handle other sources of a MessageQueueException.

                ' Handle other exceptions as necessary.

            End Try

            Return

        End Sub

End Class

Remarks

Use this overload when you want to tie the new MessageQueue 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, set the sharedModeDenyReceive parameter to true. Otherwise, set sharedModeDenyReceive to false or use the constructor that has only a path parameter.

Setting sharedModeDenyReceive to true affects all objects that access the Message Queuing queue, including other applications. The effects of the parameter are not restricted to this application.

The MessageQueue constructor creates 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.

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 format name or label of a Message Queuing queue to describe the queue path.

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, rather than the friendly name syntax. 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.

If a MessageQueue opens a queue with the sharedModeDenyReceive parameter set to true, any MessageQueue that subsequently tries to read from the queue generates a MessageQueueException because of a sharing violation. A MessageQueueException is also thrown if a MessageQueue tries to access the queue in exclusive mode while another MessageQueue already has non-exclusive access to the queue.

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 parameterless 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 parameterless constructor of the MessagePropertyFilter class.
Path	Empty, if not set by the constructor.
QueueName	Empty, if not set by the constructor.
DenySharedReceive	The value of the sharedModeDenyReceive parameter.
UseJournalQueue	true, if the Message Queuing object's journal setting is enabled; otherwise, false.

See also

• FormatName
• Label
• Path
• QueueName
• DenySharedReceive

MessageQueue(String, QueueAccessMode)

Initializes a new instance of the MessageQueue class.

public:
 MessageQueue(System::String ^ path, System::Messaging::QueueAccessMode accessMode);

public MessageQueue (string path, System.Messaging.QueueAccessMode accessMode);

new System.Messaging.MessageQueue : string * System.Messaging.QueueAccessMode -> System.Messaging.MessageQueue

Public Sub New (path As String, accessMode As QueueAccessMode)

Parameters

path

String

The location of the queue referenced by this MessageQueue, which can be "." for the local computer.

accessMode

QueueAccessMode

One of the QueueAccessMode values.

MessageQueue(String, Boolean, Boolean)

Initializes a new instance of the MessageQueue class.

public:
 MessageQueue(System::String ^ path, bool sharedModeDenyReceive, bool enableCache);

public MessageQueue (string path, bool sharedModeDenyReceive, bool enableCache);

new System.Messaging.MessageQueue : string * bool * bool -> System.Messaging.MessageQueue

Public Sub New (path As String, sharedModeDenyReceive As Boolean, enableCache As Boolean)

Parameters

path

String

The location of the queue referenced by this MessageQueue, which can be "." for the local computer.

sharedModeDenyReceive

Boolean

true to grant exclusive read access to the first application that accesses the queue; otherwise, false.

enableCache

Boolean

true to create and use a connection cache; otherwise, false.

Examples

The following code example creates a new MessageQueue with exclusive read access and with connection caching enabled.

// Connect to a queue on the local computer, grant exclusive read
// access to the first application that accesses the queue, and
// enable connection caching.
MessageQueue^ queue = gcnew MessageQueue(".\\exampleQueue", true, true);

queue->Close();

// Connect to a queue on the local computer, grant exclusive read
// access to the first application that accesses the queue, and
// enable connection caching.
MessageQueue queue = new MessageQueue(".\\exampleQueue", true, true);

MessageQueue(String, Boolean, Boolean, QueueAccessMode)

Initializes a new instance of the MessageQueue class.

public:
 MessageQueue(System::String ^ path, bool sharedModeDenyReceive, bool enableCache, System::Messaging::QueueAccessMode accessMode);

public MessageQueue (string path, bool sharedModeDenyReceive, bool enableCache, System.Messaging.QueueAccessMode accessMode);

new System.Messaging.MessageQueue : string * bool * bool * System.Messaging.QueueAccessMode -> System.Messaging.MessageQueue

Public Sub New (path As String, sharedModeDenyReceive As Boolean, enableCache As Boolean, accessMode As QueueAccessMode)

Parameters

path

String

The location of the queue referenced by this MessageQueue, which can be "." for the local computer.

sharedModeDenyReceive

Boolean

true to grant exclusive read access to the first application that accesses the queue; otherwise, false.

enableCache

Boolean

true to create and use a connection cache; otherwise, false.

accessMode

QueueAccessMode

One of the QueueAccessMode values.