MessageQueue Constructors

Definition

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

Applies to

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

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

Applies to

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

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

Applies to

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.

Applies to

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

Applies to

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.

Applies to