MessageQueue.Path Property

 

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

Namespace:   System.Messaging
Assembly:  System.Messaging (in System.Messaging.dll)

[SettingsBindableAttribute(true)]
[BrowsableAttribute(false)]
[TypeConverterAttribute("System.Diagnostics.Design.StringValueConverter, System.Design, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a")]
[MessagingDescriptionAttribute("MQ_Path")]
public string Path { get; set; }

Property Value

Type: System.String

The queue that is referenced by the MessageQueue. The default depends on which MessageQueue constructor you use; it is either null or is specified by the constructor's path parameter.

Exception Condition
ArgumentException

The path is not valid, possibly because the syntax is not valid.

The syntax for the Path property depends on the type of queue it points to, 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$

Use "." to represent the local computer.

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, as shown in the following table.

Reference

Syntax

Example

Format name

FormatName: [ format name ]

FormatName:Public= 5A5F7535-AE9A-41d4-935C-845C2AFF7112

Label

Label: [ label ]

Label: TheLabel

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.

Workgroup mode

Available

Local computer

Yes

Local computer and direct format name

Yes

Remote computer

Yes

Remote computer and direct format name

Yes

System_CAPS_noteNote

In workgroup mode you can only use private queues. You specify the path using the private queue syntax MachineName\Private$\QueueName.

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

	}
}

.NET Framework
Available since 1.1
Return to top
Show: