MessageQueue.Path Property

Gets or sets the queue's path. Setting the Path causes the MessageQueue to point to a new queue.

[Visual Basic]
Public Property Path As String
[C#]
public string Path {get; set;}
[C++]
public: __property String* get_Path();
public: __property void set_Path(String*);
[JScript]
public function get Path() : String;
public function set Path(String);

Property Value

The queue that is referenced by the MessageQueue. The default depends on which MessageQueue constructor you use; it is either a null reference (Nothing in Visual Basic) or is specified by the constructor's path parameter.

Exceptions

Remarks

The syntax for the Path property depends on the type of queue it points to.

Use "." to represent the local computer.

Note   The MachineName, Path, and QueueName properties are related. Changing the MachineName property causes the Path property to change. It is built from the new MachineName and the QueueName. Changing the Path (for example, to use the format name syntax) resets the MachineName and QueueName properties to refer to the new queue.

Alternatively, you can use the FormatName or Label to describe the queue path.

If you use the label syntax for the Path property when you send the message, an exception will be thrown if the Label is not unique.

To work offline, you must use the format name syntax, rather than the friendly name syntax in the first table. 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.

Setting a new path closes the message queue and releases all handles.

The following table shows whether this property is available in various Workgroup modes.

Example

[Visual Basic, C#, C++] The following 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.

[Visual Basic] 
Imports System
Imports 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 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 'Main


        ' References public queues.
        Public Sub SendPublic()

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

            Return

        End Sub 'SendPublic


        ' References private queues.
        Public Sub SendPrivate()

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

            Return

        End Sub 'SendPrivate


        ' References queues by label.
        Public Sub SendByLabel()

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

            Return

        End Sub 'SendByLabel


        ' 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 'SendByFormatName


        ' 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 'MonitorComputerJournal


        ' 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 'MonitorQueueJournal


        ' 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 'MonitorDeadLetter


        ' 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 'MonitorTransactionalDeadLetter

    End Class 'MyNewQueue 
End Namespace 'MyProject

[C#] 
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.
            }
        }

    }
}

[C++] 
#using <mscorlib.dll>
#using <system.dll>
#using <system.messaging.dll>

using namespace System;
using namespace System::Messaging;

__gc class MyNewQueue 
{
    // References public queues.
public:
    void SendPublic() 
    {
        MessageQueue* myQueue = new MessageQueue(S".\\myQueue");
        myQueue->Send(S"Public queue by path name.");

        return;
    }

    // References private queues.
public:
    void SendPrivate() 
    {
        MessageQueue* myQueue = new MessageQueue(S".\\Private$\\myQueue");
        myQueue->Send(S"Private queue by path name.");

        return;
    }

    // References queues by label.
public:
    void SendByLabel() 
    {
        MessageQueue* myQueue = new MessageQueue(S"Label:TheLabel");
        myQueue->Send(S"Queue by label.");

        return;
    }

    // References queues by format name.
public:
    void SendByFormatName() 
    {
        MessageQueue* myQueue = new MessageQueue(S"FormatName:Public=5A5F7535-AE9A-41d4 -935C-845C2AFF7112");
        myQueue->Send(S"Queue by format name.");

        return;
    }

    // References computer journal queues.
public:
    void MonitorComputerJournal() 
    {
        MessageQueue* computerJournal = new MessageQueue(S".\\Journal$");
        while(true) 
        {
            Message* journalMessage = computerJournal->Receive();
            // Process the journal message.
        }
    }

    // References queue journal queues.
public:
    void MonitorQueueJournal() 
    {
        MessageQueue* queueJournal = new MessageQueue(S".\\myQueue\\Journal$");
        while(true) 
        {
            Message* journalMessage = queueJournal->Receive();
            // Process the journal message.
        }
    }

    // References dead-letter queues.
public:
    void MonitorDeadLetter() 
    {
        MessageQueue* deadLetter = new MessageQueue(S".\\DeadLetter$");
        while(true) 
        {
            Message* deadMessage = deadLetter->Receive();
            // Process the dead-letter message.
        }
    }

    // References transactional dead-letter queues.
public:
    void MonitorTransactionalDeadLetter() 
    {
        MessageQueue* TxDeadLetter = new MessageQueue(S".\\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 = new MyNewQueue();

    myNewQueue->SendPublic();
    myNewQueue->SendPrivate();
    myNewQueue->SendByLabel();
    myNewQueue->SendByFormatName();
    myNewQueue->MonitorComputerJournal();
    myNewQueue->MonitorQueueJournal();
    myNewQueue->MonitorDeadLetter();
    myNewQueue->MonitorTransactionalDeadLetter();

    return 0;
}

[JScript] No example is available for JScript. To view a Visual Basic, C#, or C++ example, click the Language Filter button in the upper-left corner of the page.

Requirements

Platforms: Windows 98, Windows NT 4.0, Windows Millennium Edition, Windows 2000, Windows XP Home Edition, Windows XP Professional, Windows Server 2003 family

.NET Framework Security: 

• Full trust for the immediate caller. This member cannot be used by partially trusted code. For more information, see Using Libraries From Partially Trusted Code

See Also

MessageQueue Class | MessageQueue Members | System.Messaging Namespace | QueueName | MachineName | FormatName | Label | MessageQueue | Create | Delete | Close | Exists