Skip to content
Permalink
Branch: master
Find file Copy path
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
8062 lines (6670 sloc) 608 KB
<Type Name="MessageQueue" FullName="System.Messaging.MessageQueue">
<TypeSignature Language="C#" Value="public class MessageQueue : System.ComponentModel.Component, System.Collections.IEnumerable" />
<TypeSignature Language="ILAsm" Value=".class public auto ansi beforefieldinit MessageQueue extends System.ComponentModel.Component implements class System.Collections.IEnumerable" />
<TypeSignature Language="DocId" Value="T:System.Messaging.MessageQueue" />
<TypeSignature Language="VB.NET" Value="Public Class MessageQueue&#xA;Inherits Component&#xA;Implements IEnumerable" />
<TypeSignature Language="C++ CLI" Value="public ref class MessageQueue : System::ComponentModel::Component, System::Collections::IEnumerable" />
<TypeSignature Language="F#" Value="type MessageQueue = class&#xA; inherit Component&#xA; interface IEnumerable" />
<AssemblyInfo>
<AssemblyName>System.Messaging</AssemblyName>
<AssemblyVersion>1.0.5000.0</AssemblyVersion>
<AssemblyVersion>2.0.0.0</AssemblyVersion>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
</AssemblyInfo>
<Base>
<BaseTypeName>System.ComponentModel.Component</BaseTypeName>
</Base>
<Interfaces>
<Interface>
<InterfaceName>System.Collections.IEnumerable</InterfaceName>
</Interface>
</Interfaces>
<Attributes>
<Attribute FrameworkAlternate="netframework-1.1;netframework-2.0;netframework-3.0;netframework-3.5;netframework-4.0;netframework-4.5;netframework-4.5.1;netframework-4.5.2;netframework-4.6;netframework-4.6.1;netframework-4.6.2;netframework-4.7;netframework-4.7.1;netframework-4.7.2;xamarinmac-3.0;netframework-4.8">
<AttributeName>System.ComponentModel.DefaultEvent("ReceiveCompleted")</AttributeName>
</Attribute>
<Attribute FrameworkAlternate="netframework-4.0;netframework-4.5;netframework-4.5.1;netframework-4.5.2;netframework-4.6;netframework-4.6.1;netframework-4.6.2;netframework-4.7;netframework-4.7.1;netframework-4.7.2;xamarinmac-3.0;netframework-4.8">
<AttributeName>System.ComponentModel.Editor("System.Messaging.Design.QueuePathEditor", "System.Drawing.Design.UITypeEditor, System.Drawing, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a")</AttributeName>
</Attribute>
<Attribute FrameworkAlternate="netframework-1.1;netframework-2.0;netframework-3.0;netframework-3.5;netframework-4.0;netframework-4.5;netframework-4.5.1;netframework-4.5.2;netframework-4.6;netframework-4.6.1;netframework-4.6.2;netframework-4.7;netframework-4.7.1;netframework-4.7.2;xamarinmac-3.0;netframework-4.8">
<AttributeName>System.ComponentModel.InstallerType(typeof(System.Messaging.MessageQueueInstaller))</AttributeName>
</Attribute>
<Attribute FrameworkAlternate="netframework-1.1;netframework-2.0;netframework-3.0;netframework-3.5;netframework-4.0;netframework-4.5;netframework-4.5.1;netframework-4.5.2;netframework-4.6;netframework-4.6.1;netframework-4.6.2;netframework-4.7;netframework-4.7.1;netframework-4.7.2;xamarinmac-3.0;netframework-4.8">
<AttributeName>System.ComponentModel.TypeConverter(typeof(System.Messaging.Design.MessageQueueConverter))</AttributeName>
</Attribute>
<Attribute FrameworkAlternate="netframework-1.1">
<AttributeName>System.ComponentModel.Designer("Microsoft.VisualStudio.Install.MessageQueueInstallableComponentDesigner, Microsoft.VisualStudio, Version=1.0.5000.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a")</AttributeName>
</Attribute>
<Attribute FrameworkAlternate="netframework-1.1">
<AttributeName>System.ComponentModel.Editor("System.Messaging.Design.QueuePathEditor", "System.Drawing.Design.UITypeEditor, System.Drawing, Version=1.0.5000.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a")</AttributeName>
</Attribute>
<Attribute FrameworkAlternate="netframework-2.0;netframework-3.0;netframework-3.5">
<AttributeName>System.ComponentModel.Editor("System.Messaging.Design.QueuePathEditor", "System.Drawing.Design.UITypeEditor, System.Drawing, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a")</AttributeName>
</Attribute>
<Attribute FrameworkAlternate="netframework-2.0;netframework-3.0;netframework-3.5;netframework-4.0;netframework-4.5;netframework-4.5.1;netframework-4.5.2;netframework-4.6;netframework-4.6.1;netframework-4.6.2;netframework-4.7;netframework-4.7.1;netframework-4.7.2;netframework-4.8">
<AttributeName>System.Messaging.MessagingDescription("MessageQueueDesc")</AttributeName>
</Attribute>
</Attributes>
<Docs>
<summary>Provides access to a queue on a Message Queuing server.</summary>
<remarks>
<format type="text/markdown"><![CDATA[
## Remarks
The Message Queuing technology allows applications running at different times to communicate across heterogeneous networks and systems that might be temporarily offline. Applications send, receive, or peek (read without removing) messages from queues. Message Queuing is an optional component of [!INCLUDE[Win2kFamily](~/includes/win2kfamily-md.md)] and Windows NT, and must be installed separately.
The <xref:System.Messaging.MessageQueue> class is a wrapper around Message Queuing. There are multiple versions of Message Queuing, and using the <xref:System.Messaging.MessageQueue> class can result in slightly different behavior, depending on the operating system you are using. For information about specific features of each version of Message Queuing, see the topic "What's New in Message Queuing" in the Platform SDK in MSDN.
The <xref:System.Messaging.MessageQueue> class provides a reference to a Message Queuing queue. You can specify a path in the <xref:System.Messaging.MessageQueue.%23ctor%2A> constructor to connect to an existing resource, or you can create a new queue on the server. Before you can call <xref:System.Messaging.MessageQueue.Send%28System.Object%29>, <xref:System.Messaging.MessageQueue.Peek%2A>, or <xref:System.Messaging.MessageQueue.Receive%2A>, you must associate the new instance of the <xref:System.Messaging.MessageQueue> class with an existing queue. At that point, you can manipulate the queue properties such as <xref:System.Messaging.MessageQueue.Category%2A> and <xref:System.Messaging.MessageQueue.Label%2A>.
<xref:System.Messaging.MessageQueue> supports two types of message retrieval: synchronous and asynchronous. The synchronous methods, <xref:System.Messaging.MessageQueue.Peek%2A> and <xref:System.Messaging.MessageQueue.Receive%2A>, cause the process thread to wait a specified time interval for a new message to arrive in the queue. The asynchronous methods, <xref:System.Messaging.MessageQueue.BeginPeek%2A> and <xref:System.Messaging.MessageQueue.BeginReceive%2A>, allow the main application tasks to continue in a separate thread until a message arrives in the queue. These methods work by using callback objects and state objects to communicate information between threads.
When you create a new instance of the <xref:System.Messaging.MessageQueue> class, you are not creating a new Message Queuing queue. Instead, you can use the <xref:System.Messaging.MessageQueue.Create%28System.String%29>, <xref:System.Messaging.MessageQueue.Delete%28System.String%29>, and <xref:System.Messaging.MessageQueue.Purge%2A> methods to manage queues on the server.
Unlike <xref:System.Messaging.MessageQueue.Purge%2A>, <xref:System.Messaging.MessageQueue.Create%28System.String%29> and <xref:System.Messaging.MessageQueue.Delete%28System.String%29> are `static` members, so you can call them without creating a new instance of the <xref:System.Messaging.MessageQueue> class.
You can set the <xref:System.Messaging.MessageQueue> object's <xref:System.Messaging.MessageQueue.Path%2A> property with one of three names: the friendly name, the <xref:System.Messaging.MessageQueue.FormatName%2A>, or the <xref:System.Messaging.MessageQueue.Label%2A>. The friendly name, which is defined by the queue's <xref:System.Messaging.MessageQueue.MachineName%2A> and <xref:System.Messaging.MessageQueue.QueueName%2A> properties, is <xref:System.Messaging.MessageQueue.MachineName%2A>\\<xref:System.Messaging.MessageQueue.QueueName%2A> for a public queue, and <xref:System.Messaging.MessageQueue.MachineName%2A>\\`Private$`\\<xref:System.Messaging.MessageQueue.QueueName%2A> for a private queue. The <xref:System.Messaging.MessageQueue.FormatName%2A> property allows offline access to message queues. Lastly, you can use the queue's <xref:System.Messaging.MessageQueue.Label%2A> property to set the queue's <xref:System.Messaging.MessageQueue.Path%2A>.
For a list of initial property values for an instance of <xref:System.Messaging.MessageQueue>, see the <xref:System.Messaging.MessageQueue.%23ctor%2A> constructor.
## Examples
The following code example creates new <xref:System.Messaging.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.
[!code-cpp[MessageQueue.Path#1](~/samples/snippets/cpp/VS_Snippets_Remoting/MessageQueue.Path/CPP/mqpath.cpp#1)]
[!code-csharp[MessageQueue.Path#1](~/samples/snippets/csharp/VS_Snippets_Remoting/MessageQueue.Path/CS/mqpath.cs#1)]
[!code-vb[MessageQueue.Path#1](~/samples/snippets/visualbasic/VS_Snippets_Remoting/MessageQueue.Path/VB/mqpath.vb#1)]
The following code example sends a message to a queue, and receives a message from a queue, using an application-specific class called `Order`.
[!code-cpp[MessageQueue.Receive_noparms#1](~/samples/snippets/cpp/VS_Snippets_Remoting/MessageQueue.Receive_noparms/CPP/mqreceive_noparms.cpp#1)]
[!code-csharp[MessageQueue.Receive_noparms#1](~/samples/snippets/csharp/VS_Snippets_Remoting/MessageQueue.Receive_noparms/CS/mqreceive_noparms.cs#1)]
[!code-vb[MessageQueue.Receive_noparms#1](~/samples/snippets/visualbasic/VS_Snippets_Remoting/MessageQueue.Receive_noparms/VB/mqreceive_noparms.vb#1)]
]]></format>
</remarks>
<threadsafe>Only the <see cref="M:System.Messaging.MessageQueue.GetAllMessages" /> method is thread safe.</threadsafe>
<altmember cref="T:System.Messaging.Message" />
<altmember cref="T:System.Messaging.DefaultPropertiesToSend" />
<altmember cref="T:System.Messaging.MessageQueueException" />
<altmember cref="M:System.Messaging.MessageQueue.#ctor" />
<altmember cref="M:System.Messaging.MessageQueue.Peek" />
<altmember cref="M:System.Messaging.MessageQueue.Receive" />
<altmember cref="M:System.Messaging.MessageQueue.BeginPeek" />
<altmember cref="M:System.Messaging.MessageQueue.BeginReceive" />
<altmember cref="P:System.Messaging.MessageQueue.Path" />
<altmember cref="P:System.Messaging.MessageQueue.Label" />
<altmember cref="P:System.Messaging.MessageQueue.FormatName" />
<altmember cref="P:System.Messaging.MessageQueue.QueueName" />
<altmember cref="P:System.Messaging.MessageQueue.MachineName" />
</Docs>
<Members>
<MemberGroup MemberName=".ctor">
<AssemblyInfo>
<AssemblyName>System.Messaging</AssemblyName>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
</AssemblyInfo>
<Docs>
<summary>Initializes a new instance of the <see cref="T:System.Messaging.MessageQueue" /> class.</summary>
</Docs>
</MemberGroup>
<Member MemberName=".ctor">
<MemberSignature Language="C#" Value="public MessageQueue ();" />
<MemberSignature Language="ILAsm" Value=".method public hidebysig specialname rtspecialname instance void .ctor() cil managed" />
<MemberSignature Language="DocId" Value="M:System.Messaging.MessageQueue.#ctor" />
<MemberSignature Language="VB.NET" Value="Public Sub New ()" />
<MemberSignature Language="C++ CLI" Value="public:&#xA; MessageQueue();" />
<MemberType>Constructor</MemberType>
<AssemblyInfo>
<AssemblyName>System.Messaging</AssemblyName>
<AssemblyVersion>1.0.5000.0</AssemblyVersion>
<AssemblyVersion>2.0.0.0</AssemblyVersion>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
</AssemblyInfo>
<Parameters />
<Docs>
<summary>Initializes a new instance of the <see cref="T:System.Messaging.MessageQueue" /> class. After the parameterless constructor initializes the new instance, you must set the instance's <see cref="P:System.Messaging.MessageQueue.Path" /> property before you can use the instance.</summary>
<remarks>
<format type="text/markdown"><![CDATA[
## Remarks
Use this overload to create a new instance of the <xref:System.Messaging.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 <xref:System.Messaging.MessageQueue.Path%2A> property. Alternatively, you can set the <xref:System.Messaging.MessageQueue> reference to the <xref:System.Messaging.MessageQueue.Create%28System.String%29> method's return value, thereby creating a new Message Queuing queue.
The <xref:System.Messaging.MessageQueue.%23ctor%2A> constructor instantiates a new instance of the <xref:System.Messaging.MessageQueue> class; it does not create a new Message Queuing queue.
The following table shows initial property values for an instance of <xref:System.Messaging.MessageQueue>.
|Property|Initial value|
|--------------|-------------------|
|<xref:System.Messaging.MessageQueue.DefaultPropertiesToSend%2A>|The values set by the parameterless constructor of the <xref:System.Messaging.DefaultPropertiesToSend> class.|
|<xref:System.Messaging.MessageQueue.Formatter%2A>|<xref:System.Messaging.XmlMessageFormatter>|
|<xref:System.Messaging.MessageQueue.MessageReadPropertyFilter%2A>|The values set by the parameterless constructor of the <xref:System.Messaging.MessagePropertyFilter> class. All the filter values are set to `true`.|
|<xref:System.Messaging.MessageQueue.DenySharedReceive%2A>|`false`|
## Examples
The following code example creates a new <xref:System.Messaging.MessageQueue>.
[!code-csharp[MessageQueue#1](~/samples/snippets/csharp/VS_Snippets_Remoting/MessageQueue/CS/class1.cs#1)]
]]></format>
</remarks>
<altmember cref="P:System.Messaging.MessageQueue.Path" />
<altmember cref="P:System.Messaging.MessageQueue.QueueName" />
<altmember cref="P:System.Messaging.MessageQueue.FormatName" />
<altmember cref="P:System.Messaging.MessageQueue.Label" />
</Docs>
</Member>
<Member MemberName=".ctor">
<MemberSignature Language="C#" Value="public MessageQueue (string path);" />
<MemberSignature Language="ILAsm" Value=".method public hidebysig specialname rtspecialname instance void .ctor(string path) cil managed" />
<MemberSignature Language="DocId" Value="M:System.Messaging.MessageQueue.#ctor(System.String)" />
<MemberSignature Language="VB.NET" Value="Public Sub New (path As String)" />
<MemberSignature Language="C++ CLI" Value="public:&#xA; MessageQueue(System::String ^ path);" />
<MemberSignature Language="F#" Value="new System.Messaging.MessageQueue : string -&gt; System.Messaging.MessageQueue" Usage="new System.Messaging.MessageQueue path" />
<MemberType>Constructor</MemberType>
<AssemblyInfo>
<AssemblyName>System.Messaging</AssemblyName>
<AssemblyVersion>1.0.5000.0</AssemblyVersion>
<AssemblyVersion>2.0.0.0</AssemblyVersion>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
</AssemblyInfo>
<Parameters>
<Parameter Name="path" Type="System.String" />
</Parameters>
<Docs>
<param name="path">The location of the queue referenced by this <see cref="T:System.Messaging.MessageQueue" />.</param>
<summary>Initializes a new instance of the <see cref="T:System.Messaging.MessageQueue" /> class that references the Message Queuing queue at the specified path.</summary>
<remarks>
<format type="text/markdown"><![CDATA[
## Remarks
Use this overload when you want to tie the new <xref:System.Messaging.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 <xref:System.Messaging.MessageQueue.DenySharedReceive%2A> property to `true` or use the constructor that passes a read-access restriction parameter.
The <xref:System.Messaging.MessageQueue.%23ctor%2A> constructor instantiates a new instance of the <xref:System.Messaging.MessageQueue> class; it does not create a new Message Queuing queue. To create a new queue in Message Queuing, use <xref:System.Messaging.MessageQueue.Create%28System.String%29>.
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 <xref:System.Messaging.MessageQueue.FormatName%2A> or <xref:System.Messaging.MessageQueue.Label%2A> 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<br /><br /> `FormatName:DIRECT=SPX:` `NetworkNumber`; `HostNumber`\\`QueueName`<br /><br /> `FormatName:DIRECT=TCP:` `IPAddress`\\`QueueName`<br /><br /> `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 <xref:System.Messaging.MessageQueue>. These values are based on the properties of the Message Queuing queue with the path specified by the `path` parameter.
|Property|Initial value|
|--------------|-------------------|
|<xref:System.Messaging.MessageQueue.Authenticate%2A>|`false`|
|<xref:System.Messaging.MessageQueue.BasePriority%2A>|0|
|<xref:System.Messaging.MessageQueue.Category%2A>|<xref:System.Guid.Empty>|
|<xref:System.Messaging.MessageQueue.DefaultPropertiesToSend%2A>|The values set by the parameterless constructor of the <xref:System.Messaging.DefaultPropertiesToSend> class.|
|<xref:System.Messaging.MessageQueue.EncryptionRequired%2A>|`true`, if the Message Queuing queue's privacy level setting is "Body"; otherwise, `false`.|
|<xref:System.Messaging.MessageQueue.Formatter%2A>|<xref:System.Messaging.XmlMessageFormatter>|
|<xref:System.Messaging.MessageQueue.Label%2A>|<xref:System.String.Empty>|
|<xref:System.Messaging.MessageQueue.MachineName%2A>|The value of the Message Queuing queue's computer name property.|
|<xref:System.Messaging.MessageQueue.MaximumJournalSize%2A>|<xref:System.Messaging.MessageQueue.InfiniteQueueSize>|
|<xref:System.Messaging.MessageQueue.MaximumQueueSize%2A>|<xref:System.Messaging.MessageQueue.InfiniteQueueSize>|
|<xref:System.Messaging.MessageQueue.MessageReadPropertyFilter%2A>|The values set by the parameterless constructor of the <xref:System.Messaging.MessagePropertyFilter> class.|
|<xref:System.Messaging.MessageQueue.Path%2A>|<xref:System.String.Empty>, if not set by the constructor.|
|<xref:System.Messaging.MessageQueue.QueueName%2A>|<xref:System.String.Empty>, if not set by the constructor.|
|<xref:System.Messaging.MessageQueue.DenySharedReceive%2A>|`false`|
|<xref:System.Messaging.MessageQueue.UseJournalQueue%2A>|`true`, if the Message Queuing object's journal setting is enabled; otherwise, `false`.|
## Examples
The following code example creates new <xref:System.Messaging.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.
[!code-cpp[MessageQueue.Path#1](~/samples/snippets/cpp/VS_Snippets_Remoting/MessageQueue.Path/CPP/mqpath.cpp#1)]
[!code-csharp[MessageQueue.Path#1](~/samples/snippets/csharp/VS_Snippets_Remoting/MessageQueue.Path/CS/mqpath.cs#1)]
[!code-vb[MessageQueue.Path#1](~/samples/snippets/visualbasic/VS_Snippets_Remoting/MessageQueue.Path/VB/mqpath.vb#1)]
]]></format>
</remarks>
<exception cref="T:System.ArgumentException">The <see cref="P:System.Messaging.MessageQueue.Path" /> property is not valid, possibly because it has not been set.</exception>
<altmember cref="P:System.Messaging.MessageQueue.FormatName" />
<altmember cref="P:System.Messaging.MessageQueue.Label" />
<altmember cref="P:System.Messaging.MessageQueue.QueueName" />
<altmember cref="P:System.Messaging.MessageQueue.Path" />
</Docs>
</Member>
<Member MemberName=".ctor">
<MemberSignature Language="C#" Value="public MessageQueue (string path, bool sharedModeDenyReceive);" />
<MemberSignature Language="ILAsm" Value=".method public hidebysig specialname rtspecialname instance void .ctor(string path, bool sharedModeDenyReceive) cil managed" />
<MemberSignature Language="DocId" Value="M:System.Messaging.MessageQueue.#ctor(System.String,System.Boolean)" />
<MemberSignature Language="VB.NET" Value="Public Sub New (path As String, sharedModeDenyReceive As Boolean)" />
<MemberSignature Language="C++ CLI" Value="public:&#xA; MessageQueue(System::String ^ path, bool sharedModeDenyReceive);" />
<MemberSignature Language="F#" Value="new System.Messaging.MessageQueue : string * bool -&gt; System.Messaging.MessageQueue" Usage="new System.Messaging.MessageQueue (path, sharedModeDenyReceive)" />
<MemberType>Constructor</MemberType>
<AssemblyInfo>
<AssemblyName>System.Messaging</AssemblyName>
<AssemblyVersion>1.0.5000.0</AssemblyVersion>
<AssemblyVersion>2.0.0.0</AssemblyVersion>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
</AssemblyInfo>
<Parameters>
<Parameter Name="path" Type="System.String" />
<Parameter Name="sharedModeDenyReceive" Type="System.Boolean" />
</Parameters>
<Docs>
<param name="path">The location of the queue referenced by this <see cref="T:System.Messaging.MessageQueue" />, which can be "." for the local computer.</param>
<param name="sharedModeDenyReceive">
<see langword="true" /> to grant exclusive read access to the first application that accesses the queue; otherwise, <see langword="false" />.</param>
<summary>Initializes a new instance of the <see cref="T:System.Messaging.MessageQueue" /> class that references the Message Queuing queue at the specified path and with the specified read-access restriction.</summary>
<remarks>
<format type="text/markdown"><![CDATA[
## Remarks
Use this overload when you want to tie the new <xref:System.Messaging.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 <xref:System.Messaging.MessageQueue.%23ctor%2A> constructor creates a new instance of the <xref:System.Messaging.MessageQueue> class; it does not create a new Message Queuing queue. To create a new queue in Message Queuing, use <xref:System.Messaging.MessageQueue.Create%28System.String%29>.
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<br /><br /> `FormatName:DIRECT=SPX:` `NetworkNumber`; `HostNumber`\\`QueueName`<br /><br /> `FormatName:DIRECT=TCP:` `IPAddress`\\`QueueName`<br /><br /> `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 <xref:System.Messaging.MessageQueue> opens a queue with the `sharedModeDenyReceive` parameter set to `true`, any <xref:System.Messaging.MessageQueue> that subsequently tries to read from the queue generates a <xref:System.Messaging.MessageQueueException> because of a sharing violation. A <xref:System.Messaging.MessageQueueException> is also thrown if a <xref:System.Messaging.MessageQueue> tries to access the queue in exclusive mode while another <xref:System.Messaging.MessageQueue> already has non-exclusive access to the queue.
The following table shows initial property values for an instance of <xref:System.Messaging.MessageQueue>. These values are based on the properties of the Message Queuing queue, with the path specified by the `path` parameter.
|Property|Initial value|
|--------------|-------------------|
|<xref:System.Messaging.MessageQueue.Authenticate%2A>|`false`.|
|<xref:System.Messaging.MessageQueue.BasePriority%2A>|0.|
|<xref:System.Messaging.MessageQueue.Category%2A>|<xref:System.Guid.Empty>.|
|<xref:System.Messaging.MessageQueue.DefaultPropertiesToSend%2A>|The values set by the parameterless constructor of the <xref:System.Messaging.DefaultPropertiesToSend> class.|
|<xref:System.Messaging.MessageQueue.EncryptionRequired%2A>|`true`, if the Message Queuing queue's privacy level setting is "Body"; otherwise, `false`.|
|<xref:System.Messaging.MessageQueue.Formatter%2A>|<xref:System.Messaging.XmlMessageFormatter>.|
|<xref:System.Messaging.MessageQueue.Label%2A>|<xref:System.String.Empty>.|
|<xref:System.Messaging.MessageQueue.MachineName%2A>|The value of the Message Queuing queue's computer name property.|
|<xref:System.Messaging.MessageQueue.MaximumJournalSize%2A>|<xref:System.Messaging.MessageQueue.InfiniteQueueSize>.|
|<xref:System.Messaging.MessageQueue.MaximumQueueSize%2A>|<xref:System.Messaging.MessageQueue.InfiniteQueueSize>.|
|<xref:System.Messaging.MessageQueue.MessageReadPropertyFilter%2A>|The values set by the parameterless constructor of the <xref:System.Messaging.MessagePropertyFilter> class.|
|<xref:System.Messaging.MessageQueue.Path%2A>|<xref:System.String.Empty>, if not set by the constructor.|
|<xref:System.Messaging.MessageQueue.QueueName%2A>|<xref:System.String.Empty>, if not set by the constructor.|
|<xref:System.Messaging.MessageQueue.DenySharedReceive%2A>|The value of the `sharedModeDenyReceive` parameter.|
|<xref:System.Messaging.MessageQueue.UseJournalQueue%2A>|`true`, if the Message Queuing object's journal setting is enabled; otherwise, `false`.|
## Examples
The following code example creates a new <xref:System.Messaging.MessageQueue> with exclusive access, sets its path, and sends a message to the queue.
[!code-cpp[MessageQueue.ctor_PathSharedModeDenyReceive#1](~/samples/snippets/cpp/VS_Snippets_Remoting/MessageQueue.ctor_PathSharedModeDenyReceive/CPP/mqctor_denysharedreceive.cpp#1)]
[!code-csharp[MessageQueue.ctor_PathSharedModeDenyReceive#1](~/samples/snippets/csharp/VS_Snippets_Remoting/MessageQueue.ctor_PathSharedModeDenyReceive/CS/mqctor_denysharedreceive.cs#1)]
[!code-vb[MessageQueue.ctor_PathSharedModeDenyReceive#1](~/samples/snippets/visualbasic/VS_Snippets_Remoting/MessageQueue.ctor_PathSharedModeDenyReceive/VB/mqctor_denysharedreceive.vb#1)]
]]></format>
</remarks>
<exception cref="T:System.ArgumentException">The <see cref="P:System.Messaging.MessageQueue.Path" /> property is not valid, possibly because it has not been set.</exception>
<altmember cref="P:System.Messaging.MessageQueue.FormatName" />
<altmember cref="P:System.Messaging.MessageQueue.Label" />
<altmember cref="P:System.Messaging.MessageQueue.Path" />
<altmember cref="P:System.Messaging.MessageQueue.QueueName" />
<altmember cref="P:System.Messaging.MessageQueue.DenySharedReceive" />
</Docs>
</Member>
<Member MemberName=".ctor">
<MemberSignature Language="C#" Value="public MessageQueue (string path, System.Messaging.QueueAccessMode accessMode);" />
<MemberSignature Language="ILAsm" Value=".method public hidebysig specialname rtspecialname instance void .ctor(string path, valuetype System.Messaging.QueueAccessMode accessMode) cil managed" />
<MemberSignature Language="DocId" Value="M:System.Messaging.MessageQueue.#ctor(System.String,System.Messaging.QueueAccessMode)" />
<MemberSignature Language="VB.NET" Value="Public Sub New (path As String, accessMode As QueueAccessMode)" />
<MemberSignature Language="C++ CLI" Value="public:&#xA; MessageQueue(System::String ^ path, System::Messaging::QueueAccessMode accessMode);" />
<MemberSignature Language="F#" Value="new System.Messaging.MessageQueue : string * System.Messaging.QueueAccessMode -&gt; System.Messaging.MessageQueue" Usage="new System.Messaging.MessageQueue (path, accessMode)" />
<MemberType>Constructor</MemberType>
<AssemblyInfo>
<AssemblyName>System.Messaging</AssemblyName>
<AssemblyVersion>2.0.0.0</AssemblyVersion>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
</AssemblyInfo>
<Parameters>
<Parameter Name="path" Type="System.String" Index="0" FrameworkAlternate="netframework-2.0;netframework-3.0;netframework-3.5;netframework-4.0;netframework-4.5;netframework-4.5.1;netframework-4.5.2;netframework-4.6;netframework-4.6.1;netframework-4.6.2;netframework-4.7;netframework-4.7.1;netframework-4.7.2;netframework-4.8;xamarinmac-3.0" />
<Parameter Name="accessMode" Type="System.Messaging.QueueAccessMode" Index="1" FrameworkAlternate="netframework-2.0;netframework-3.0;netframework-3.5;netframework-4.0;netframework-4.5;netframework-4.5.1;netframework-4.5.2;netframework-4.6;netframework-4.6.1;netframework-4.6.2;netframework-4.7;netframework-4.7.1;netframework-4.7.2;netframework-4.8;xamarinmac-3.0" />
</Parameters>
<Docs>
<param name="path">The location of the queue referenced by this <see cref="T:System.Messaging.MessageQueue" />, which can be "." for the local computer.</param>
<param name="accessMode">One of the <see cref="T:System.Messaging.QueueAccessMode" /> values.</param>
<summary>Initializes a new instance of the <see cref="T:System.Messaging.MessageQueue" /> class.</summary>
<remarks>To be added.</remarks>
</Docs>
</Member>
<Member MemberName=".ctor">
<MemberSignature Language="C#" Value="public MessageQueue (string path, bool sharedModeDenyReceive, bool enableCache);" />
<MemberSignature Language="ILAsm" Value=".method public hidebysig specialname rtspecialname instance void .ctor(string path, bool sharedModeDenyReceive, bool enableCache) cil managed" />
<MemberSignature Language="DocId" Value="M:System.Messaging.MessageQueue.#ctor(System.String,System.Boolean,System.Boolean)" />
<MemberSignature Language="VB.NET" Value="Public Sub New (path As String, sharedModeDenyReceive As Boolean, enableCache As Boolean)" />
<MemberSignature Language="C++ CLI" Value="public:&#xA; MessageQueue(System::String ^ path, bool sharedModeDenyReceive, bool enableCache);" />
<MemberSignature Language="F#" Value="new System.Messaging.MessageQueue : string * bool * bool -&gt; System.Messaging.MessageQueue" Usage="new System.Messaging.MessageQueue (path, sharedModeDenyReceive, enableCache)" />
<MemberType>Constructor</MemberType>
<AssemblyInfo>
<AssemblyName>System.Messaging</AssemblyName>
<AssemblyVersion>2.0.0.0</AssemblyVersion>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
</AssemblyInfo>
<Parameters>
<Parameter Name="path" Type="System.String" Index="0" FrameworkAlternate="netframework-2.0;netframework-3.0;netframework-3.5;netframework-4.0;netframework-4.5;netframework-4.5.1;netframework-4.5.2;netframework-4.6;netframework-4.6.1;netframework-4.6.2;netframework-4.7;netframework-4.7.1;netframework-4.7.2;netframework-4.8" />
<Parameter Name="sharedModeDenyReceive" Type="System.Boolean" Index="1" FrameworkAlternate="netframework-2.0;netframework-3.0;netframework-3.5;netframework-4.0;netframework-4.5;netframework-4.5.1;netframework-4.5.2;netframework-4.6;netframework-4.6.1;netframework-4.6.2;netframework-4.7;netframework-4.7.1;netframework-4.7.2;netframework-4.8" />
<Parameter Name="enableCache" Type="System.Boolean" Index="2" FrameworkAlternate="netframework-2.0;netframework-3.0;netframework-3.5;netframework-4.0;netframework-4.5;netframework-4.5.1;netframework-4.5.2;netframework-4.6;netframework-4.6.1;netframework-4.6.2;netframework-4.7;netframework-4.7.1;netframework-4.7.2;netframework-4.8" />
</Parameters>
<Docs>
<param name="path">The location of the queue referenced by this <see cref="T:System.Messaging.MessageQueue" />, which can be "." for the local computer.</param>
<param name="sharedModeDenyReceive">
<see langword="true" /> to grant exclusive read access to the first application that accesses the queue; otherwise, <see langword="false" />.</param>
<param name="enableCache">
<see langword="true" /> to create and use a connection cache; otherwise, <see langword="false" />.</param>
<summary>Initializes a new instance of the <see cref="T:System.Messaging.MessageQueue" /> class.</summary>
<remarks>
<format type="text/markdown"><![CDATA[
## Examples
The following code example creates a new <xref:System.Messaging.MessageQueue> with exclusive read access and with connection caching enabled.
[!code-cpp[MessageQueue4#1](~/samples/snippets/cpp/VS_Snippets_Remoting/MessageQueue4/cpp/class1.cpp#1)]
[!code-csharp[MessageQueue4#1](~/samples/snippets/csharp/VS_Snippets_Remoting/MessageQueue4/CS/class1.cs#1)]
]]></format>
</remarks>
</Docs>
</Member>
<Member MemberName=".ctor">
<MemberSignature Language="C#" Value="public MessageQueue (string path, bool sharedModeDenyReceive, bool enableCache, System.Messaging.QueueAccessMode accessMode);" />
<MemberSignature Language="ILAsm" Value=".method public hidebysig specialname rtspecialname instance void .ctor(string path, bool sharedModeDenyReceive, bool enableCache, valuetype System.Messaging.QueueAccessMode accessMode) cil managed" />
<MemberSignature Language="DocId" Value="M:System.Messaging.MessageQueue.#ctor(System.String,System.Boolean,System.Boolean,System.Messaging.QueueAccessMode)" />
<MemberSignature Language="VB.NET" Value="Public Sub New (path As String, sharedModeDenyReceive As Boolean, enableCache As Boolean, accessMode As QueueAccessMode)" />
<MemberSignature Language="C++ CLI" Value="public:&#xA; MessageQueue(System::String ^ path, bool sharedModeDenyReceive, bool enableCache, System::Messaging::QueueAccessMode accessMode);" />
<MemberSignature Language="F#" Value="new System.Messaging.MessageQueue : string * bool * bool * System.Messaging.QueueAccessMode -&gt; System.Messaging.MessageQueue" Usage="new System.Messaging.MessageQueue (path, sharedModeDenyReceive, enableCache, accessMode)" />
<MemberType>Constructor</MemberType>
<AssemblyInfo>
<AssemblyName>System.Messaging</AssemblyName>
<AssemblyVersion>2.0.0.0</AssemblyVersion>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
</AssemblyInfo>
<Parameters>
<Parameter Name="path" Type="System.String" Index="0" FrameworkAlternate="netframework-2.0;netframework-3.0;netframework-3.5;netframework-4.0;netframework-4.5;netframework-4.5.1;netframework-4.5.2;netframework-4.6;netframework-4.6.1;netframework-4.6.2;netframework-4.7;netframework-4.7.1;netframework-4.7.2;netframework-4.8" />
<Parameter Name="sharedModeDenyReceive" Type="System.Boolean" Index="1" FrameworkAlternate="netframework-2.0;netframework-3.0;netframework-3.5;netframework-4.0;netframework-4.5;netframework-4.5.1;netframework-4.5.2;netframework-4.6;netframework-4.6.1;netframework-4.6.2;netframework-4.7;netframework-4.7.1;netframework-4.7.2;netframework-4.8" />
<Parameter Name="enableCache" Type="System.Boolean" Index="2" FrameworkAlternate="netframework-2.0;netframework-3.0;netframework-3.5;netframework-4.0;netframework-4.5;netframework-4.5.1;netframework-4.5.2;netframework-4.6;netframework-4.6.1;netframework-4.6.2;netframework-4.7;netframework-4.7.1;netframework-4.7.2;netframework-4.8" />
<Parameter Name="accessMode" Type="System.Messaging.QueueAccessMode" Index="3" FrameworkAlternate="netframework-2.0;netframework-3.0;netframework-3.5;netframework-4.0;netframework-4.5;netframework-4.5.1;netframework-4.5.2;netframework-4.6;netframework-4.6.1;netframework-4.6.2;netframework-4.7;netframework-4.7.1;netframework-4.7.2;netframework-4.8" />
</Parameters>
<Docs>
<param name="path">The location of the queue referenced by this <see cref="T:System.Messaging.MessageQueue" />, which can be "." for the local computer.</param>
<param name="sharedModeDenyReceive">
<see langword="true" /> to grant exclusive read access to the first application that accesses the queue; otherwise, <see langword="false" />.</param>
<param name="enableCache">
<see langword="true" /> to create and use a connection cache; otherwise, <see langword="false" />.</param>
<param name="accessMode">One of the <see cref="T:System.Messaging.QueueAccessMode" /> values.</param>
<summary>Initializes a new instance of the <see cref="T:System.Messaging.MessageQueue" /> class.</summary>
<remarks>To be added.</remarks>
</Docs>
</Member>
<Member MemberName="AccessMode">
<MemberSignature Language="C#" Value="public System.Messaging.QueueAccessMode AccessMode { get; }" />
<MemberSignature Language="ILAsm" Value=".property instance valuetype System.Messaging.QueueAccessMode AccessMode" />
<MemberSignature Language="DocId" Value="P:System.Messaging.MessageQueue.AccessMode" />
<MemberSignature Language="VB.NET" Value="Public ReadOnly Property AccessMode As QueueAccessMode" />
<MemberSignature Language="C++ CLI" Value="public:&#xA; property System::Messaging::QueueAccessMode AccessMode { System::Messaging::QueueAccessMode get(); };" />
<MemberSignature Language="F#" Value="member this.AccessMode : System.Messaging.QueueAccessMode" Usage="System.Messaging.MessageQueue.AccessMode" />
<MemberType>Property</MemberType>
<AssemblyInfo>
<AssemblyName>System.Messaging</AssemblyName>
<AssemblyVersion>2.0.0.0</AssemblyVersion>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
</AssemblyInfo>
<ReturnValue>
<ReturnType>System.Messaging.QueueAccessMode</ReturnType>
</ReturnValue>
<Docs>
<summary>Gets a value that indicates the access mode for the queue.</summary>
<value>One of the <see cref="T:System.Messaging.QueueAccessMode" /> values.</value>
<remarks>
<format type="text/markdown"><![CDATA[
## Remarks
The default access mode for a queue is `QueueAccessMode.SendAndReceive`, unless you specify otherwise when calling the constructor.
]]></format>
</remarks>
</Docs>
</Member>
<Member MemberName="Authenticate">
<MemberSignature Language="C#" Value="public bool Authenticate { get; set; }" />
<MemberSignature Language="ILAsm" Value=".property instance bool Authenticate" />
<MemberSignature Language="DocId" Value="P:System.Messaging.MessageQueue.Authenticate" />
<MemberSignature Language="VB.NET" Value="Public Property Authenticate As Boolean" />
<MemberSignature Language="C++ CLI" Value="public:&#xA; property bool Authenticate { bool get(); void set(bool value); };" />
<MemberSignature Language="F#" Value="member this.Authenticate : bool with get, set" Usage="System.Messaging.MessageQueue.Authenticate" />
<MemberType>Property</MemberType>
<AssemblyInfo>
<AssemblyName>System.Messaging</AssemblyName>
<AssemblyVersion>1.0.5000.0</AssemblyVersion>
<AssemblyVersion>2.0.0.0</AssemblyVersion>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
</AssemblyInfo>
<Attributes>
<Attribute FrameworkAlternate="netframework-1.1;netframework-2.0;netframework-3.0;netframework-3.5;netframework-4.0;netframework-4.5;netframework-4.5.1;netframework-4.5.2;netframework-4.6;netframework-4.6.1;netframework-4.6.2;netframework-4.7;netframework-4.7.1;netframework-4.7.2;xamarinmac-3.0;netframework-4.8">
<AttributeName>System.Messaging.MessagingDescription("MQ_Authenticate")</AttributeName>
</Attribute>
<Attribute>
<AttributeName>System.ComponentModel.DesignerSerializationVisibility(System.ComponentModel.DesignerSerializationVisibility.Hidden)</AttributeName>
</Attribute>
</Attributes>
<ReturnValue>
<ReturnType>System.Boolean</ReturnType>
</ReturnValue>
<Docs>
<summary>Gets or sets a value that indicates whether the queue accepts only authenticated messages.</summary>
<value>
<see langword="true" /> if the queue accepts only authenticated messages; otherwise, <see langword="false" />. The default is <see langword="false" />.</value>
<remarks>
<format type="text/markdown"><![CDATA[
## Remarks
Message authentication provides a way to ensure message integrity and to verify who sent the message. To request authentication, the sending application sets the message's authentication level.
When you set <xref:System.Messaging.MessageQueue.Authenticate%2A> to `true`, you are restricting access to the queue on the server, not only to this <xref:System.Messaging.MessageQueue> instance. All clients working against the same Message Queuing queue will be affected.
A queue that accepts only authenticated messages will reject a non-authenticated message. To request notification of message rejection, a sending application can set the <xref:System.Messaging.Message.AcknowledgeType%2A> property of the message. Because no other indication of message rejection exists, the sending application can lose the message unless you request that it be sent to the dead-letter queue.
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|No|
|Remote computer and direct format name|No|
## Examples
The following code example gets and sets the value of a message queue's <xref:System.Messaging.MessageQueue.Authenticate%2A> property.
[!code-csharp[MessageQueue#3](~/samples/snippets/csharp/VS_Snippets_Remoting/MessageQueue/CS/class1.cs#3)]
]]></format>
</remarks>
<exception cref="T:System.Messaging.MessageQueueException">An error occurred when accessing a Message Queuing method.</exception>
<altmember cref="P:System.Messaging.Message.UseDeadLetterQueue" />
<altmember cref="P:System.Messaging.Message.AcknowledgeType" />
</Docs>
</Member>
<Member MemberName="BasePriority">
<MemberSignature Language="C#" Value="public short BasePriority { get; set; }" />
<MemberSignature Language="ILAsm" Value=".property instance int16 BasePriority" />
<MemberSignature Language="DocId" Value="P:System.Messaging.MessageQueue.BasePriority" />
<MemberSignature Language="VB.NET" Value="Public Property BasePriority As Short" />
<MemberSignature Language="C++ CLI" Value="public:&#xA; property short BasePriority { short get(); void set(short value); };" />
<MemberSignature Language="F#" Value="member this.BasePriority : int16 with get, set" Usage="System.Messaging.MessageQueue.BasePriority" />
<MemberType>Property</MemberType>
<AssemblyInfo>
<AssemblyName>System.Messaging</AssemblyName>
<AssemblyVersion>1.0.5000.0</AssemblyVersion>
<AssemblyVersion>2.0.0.0</AssemblyVersion>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
</AssemblyInfo>
<Attributes>
<Attribute FrameworkAlternate="netframework-1.1;netframework-2.0;netframework-3.0;netframework-3.5;netframework-4.0;netframework-4.5;netframework-4.5.1;netframework-4.5.2;netframework-4.6;netframework-4.6.1;netframework-4.6.2;netframework-4.7;netframework-4.7.1;netframework-4.7.2;xamarinmac-3.0;netframework-4.8">
<AttributeName>System.Messaging.MessagingDescription("MQ_BasePriority")</AttributeName>
</Attribute>
<Attribute>
<AttributeName>System.ComponentModel.DesignerSerializationVisibility(System.ComponentModel.DesignerSerializationVisibility.Hidden)</AttributeName>
</Attribute>
</Attributes>
<ReturnValue>
<ReturnType>System.Int16</ReturnType>
</ReturnValue>
<Docs>
<summary>Gets or sets the base priority Message Queuing uses to route a public queue's messages over the network.</summary>
<value>The single base priority for all messages sent to the (public) queue. The default is zero (0).</value>
<remarks>
<format type="text/markdown"><![CDATA[
## Remarks
A message queue's base priority specifies how a message en route to that queue is treated as it travels through the network. You can set the <xref:System.Messaging.MessageQueue.BasePriority%2A> property to confer a higher or lower priority to all messages sent to the specified queue than those sent to other queues. Setting this property modifies the Message Queuing queue. Therefore, any other <xref:System.Messaging.MessageQueue> instances are affected by the change.
A message queue's <xref:System.Messaging.MessageQueue.BasePriority%2A> is not related to the <xref:System.Messaging.Message.Priority%2A> property of a message, which specifies the order in which an incoming message is placed in the queue.
<xref:System.Messaging.MessageQueue.BasePriority%2A> applies only to public queues whose paths are specified using the format name. The base priority of a private queue is always zero (0).
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|No|
|Remote computer and direct format name|No|
## Examples
The following code example gets and sets the value of a message queue's <xref:System.Messaging.MessageQueue.BasePriority%2A> property.
[!code-csharp[MessageQueue#4](~/samples/snippets/csharp/VS_Snippets_Remoting/MessageQueue/CS/class1.cs#4)]
]]></format>
</remarks>
<exception cref="T:System.ArgumentException">The base priority was set to an invalid value.</exception>
<exception cref="T:System.Messaging.MessageQueueException">An error occurred when accessing a Message Queuing method.</exception>
<altmember cref="P:System.Messaging.MessageQueue.FormatName" />
</Docs>
</Member>
<MemberGroup MemberName="BeginPeek">
<AssemblyInfo>
<AssemblyName>System.Messaging</AssemblyName>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
</AssemblyInfo>
<Docs>
<threadsafe>The method is not thread safe.</threadsafe>
<summary>Initiates an asynchronous peek operation by telling Message Queuing to begin peeking a message and notify the event handler when finished.</summary>
</Docs>
</MemberGroup>
<Member MemberName="BeginPeek">
<MemberSignature Language="C#" Value="public IAsyncResult BeginPeek ();" />
<MemberSignature Language="ILAsm" Value=".method public hidebysig instance class System.IAsyncResult BeginPeek() cil managed" />
<MemberSignature Language="DocId" Value="M:System.Messaging.MessageQueue.BeginPeek" />
<MemberSignature Language="VB.NET" Value="Public Function BeginPeek () As IAsyncResult" />
<MemberSignature Language="C++ CLI" Value="public:&#xA; IAsyncResult ^ BeginPeek();" />
<MemberSignature Language="F#" Value="member this.BeginPeek : unit -&gt; IAsyncResult" Usage="messageQueue.BeginPeek " />
<MemberType>Method</MemberType>
<AssemblyInfo>
<AssemblyName>System.Messaging</AssemblyName>
<AssemblyVersion>1.0.5000.0</AssemblyVersion>
<AssemblyVersion>2.0.0.0</AssemblyVersion>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
</AssemblyInfo>
<ReturnValue>
<ReturnType>System.IAsyncResult</ReturnType>
</ReturnValue>
<Parameters />
<Docs>
<summary>Initiates an asynchronous peek operation that has no time-out. The operation is not complete until a message becomes available in the queue.</summary>
<returns>The <see cref="T:System.IAsyncResult" /> that identifies the posted asynchronous request.</returns>
<remarks>
<format type="text/markdown"><![CDATA[
## Remarks
In asynchronous processing, you use <xref:System.Messaging.MessageQueue.BeginPeek%2A> to raise the <xref:System.Messaging.MessageQueue.PeekCompleted> event when a message becomes available in the queue.
<xref:System.Messaging.MessageQueue.PeekCompleted> is also raised if a message already exists in the queue.
To use <xref:System.Messaging.MessageQueue.BeginPeek%2A>, create an event handler that processes the results of the asynchronous operation, and associate it with your event delegate. <xref:System.Messaging.MessageQueue.BeginPeek%2A> initiates an asynchronous peek operation; the <xref:System.Messaging.MessageQueue> is notified, through the raising of the <xref:System.Messaging.MessageQueue.PeekCompleted> event, when a message arrives in the queue. The <xref:System.Messaging.MessageQueue> can then access the message by calling <xref:System.Messaging.MessageQueue.EndPeek%28System.IAsyncResult%29> or by retrieving the result using the <xref:System.Messaging.PeekCompletedEventArgs>.
The <xref:System.Messaging.MessageQueue.BeginPeek%2A> method returns immediately, but the asynchronous operation is not completed until the event handler is called.
Because <xref:System.Messaging.MessageQueue.BeginPeek%2A> is asynchronous, you can call it to peek the queue without blocking the current thread of execution. To synchronously peek the queue, use the <xref:System.Messaging.MessageQueue.Peek%2A> method.
Once an asynchronous operation completes, you can call <xref:System.Messaging.MessageQueue.BeginPeek%2A> or <xref:System.Messaging.MessageQueue.BeginReceive%2A> again in the event handler to keep receiving notifications.
The <xref:System.IAsyncResult> that <xref:System.Messaging.MessageQueue.BeginPeek%2A> returns identifies the asynchronous operation that the method started. You can use this <xref:System.IAsyncResult> throughout the lifetime of the operation, although you generally do not use it until <xref:System.Messaging.MessageQueue.EndPeek%28System.IAsyncResult%29> is called. However, if you start several asynchronous operations, you can place their <xref:System.IAsyncResult> values in an array and specify whether to wait for all operations or any operation to complete. In this case, you use the <xref:System.IAsyncResult.AsyncWaitHandle%2A> property of the <xref:System.IAsyncResult> to identify the completed operation.
If <xref:System.Messaging.MessageQueue.CanRead%2A> is `false`, the completion event is raised, but an exception will be thrown when calling <xref:System.Messaging.MessageQueue.EndPeek%28System.IAsyncResult%29>.
The following table shows whether this method is available in various Workgroup modes.
|Workgroup mode|Available|
|--------------------|---------------|
|Local computer|Yes|
|Local computer and direct format name|Yes|
|Remote computer|No|
|Remote computer and direct format name|Yes|
## Examples
The following code example creates an event handler named `MyPeekCompleted`, attaches it to the <xref:System.Messaging.MessageQueue.PeekCompleted> event handler delegate, and calls <xref:System.Messaging.MessageQueue.BeginPeek%2A> to initiate an asynchronous peek operation on the queue that is located at the path ".\myQueue". When a <xref:System.Messaging.MessageQueue.PeekCompleted> event is raised, the example peeks the message and writes its body to the screen. The example then calls <xref:System.Messaging.MessageQueue.BeginPeek%2A> again to initiate a new asynchronous peek operation.
[!code-cpp[MessageQueue.BeginPeek_noparms#1](~/samples/snippets/cpp/VS_Snippets_Remoting/MessageQueue.BeginPeek_noparms/CPP/mqbeginpeek_noparms.cpp#1)]
[!code-csharp[MessageQueue.BeginPeek_noparms#1](~/samples/snippets/csharp/VS_Snippets_Remoting/MessageQueue.BeginPeek_noparms/CS/mqbeginpeek_noparms.cs#1)]
[!code-vb[MessageQueue.BeginPeek_noparms#1](~/samples/snippets/visualbasic/VS_Snippets_Remoting/MessageQueue.BeginPeek_noparms/VB/mqbeginpeek_noparms.vb#1)]
]]></format>
</remarks>
<exception cref="T:System.Messaging.MessageQueueException">An error occurred when accessing a Message Queuing method.</exception>
<threadsafe>The method is not thread safe.</threadsafe>
<altmember cref="E:System.Messaging.MessageQueue.PeekCompleted" />
<altmember cref="M:System.Messaging.MessageQueue.BeginReceive" />
<altmember cref="M:System.Messaging.MessageQueue.Peek" />
<altmember cref="M:System.Messaging.MessageQueue.Receive" />
</Docs>
</Member>
<Member MemberName="BeginPeek">
<MemberSignature Language="C#" Value="public IAsyncResult BeginPeek (TimeSpan timeout);" />
<MemberSignature Language="ILAsm" Value=".method public hidebysig instance class System.IAsyncResult BeginPeek(valuetype System.TimeSpan timeout) cil managed" />
<MemberSignature Language="DocId" Value="M:System.Messaging.MessageQueue.BeginPeek(System.TimeSpan)" />
<MemberSignature Language="VB.NET" Value="Public Function BeginPeek (timeout As TimeSpan) As IAsyncResult" />
<MemberSignature Language="C++ CLI" Value="public:&#xA; IAsyncResult ^ BeginPeek(TimeSpan timeout);" />
<MemberSignature Language="F#" Value="member this.BeginPeek : TimeSpan -&gt; IAsyncResult" Usage="messageQueue.BeginPeek timeout" />
<MemberType>Method</MemberType>
<AssemblyInfo>
<AssemblyName>System.Messaging</AssemblyName>
<AssemblyVersion>1.0.5000.0</AssemblyVersion>
<AssemblyVersion>2.0.0.0</AssemblyVersion>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
</AssemblyInfo>
<ReturnValue>
<ReturnType>System.IAsyncResult</ReturnType>
</ReturnValue>
<Parameters>
<Parameter Name="timeout" Type="System.TimeSpan" />
</Parameters>
<Docs>
<param name="timeout">A <see cref="T:System.TimeSpan" /> that indicates the interval of time to wait for a message to become available.</param>
<summary>Initiates an asynchronous peek operation that has a specified time-out. The operation is not complete until either a message becomes available in the queue or the time-out occurs.</summary>
<returns>The <see cref="T:System.IAsyncResult" /> that identifies the posted asynchronous request.</returns>
<remarks>
<format type="text/markdown"><![CDATA[
## Remarks
In asynchronous processing, you use <xref:System.Messaging.MessageQueue.BeginPeek%2A> to raise the <xref:System.Messaging.MessageQueue.PeekCompleted> event when a message becomes available in the queue or when the specified interval of time has expired.
<xref:System.Messaging.MessageQueue.PeekCompleted> is also raised if a message already exists in the queue.
To use <xref:System.Messaging.MessageQueue.BeginPeek%2A>, create an event handler that processes the results of the asynchronous operation, and associate it with your event delegate. <xref:System.Messaging.MessageQueue.BeginPeek%2A> initiates an asynchronous peek operation; the <xref:System.Messaging.MessageQueue> is notified, through the raising of the <xref:System.Messaging.MessageQueue.PeekCompleted> event, when a message arrives in the queue. The <xref:System.Messaging.MessageQueue> can then access the message by calling <xref:System.Messaging.MessageQueue.EndPeek%28System.IAsyncResult%29> or by retrieving the result using the <xref:System.Messaging.PeekCompletedEventArgs>.
The <xref:System.Messaging.MessageQueue.BeginPeek%2A> method returns immediately, but the asynchronous operation is not completed until the event handler is called.
Because <xref:System.Messaging.MessageQueue.BeginPeek%2A> is asynchronous, you can call it to peek the queue without blocking the current thread of execution. To synchronously peek the queue, use the <xref:System.Messaging.MessageQueue.Peek%2A> method.
Once an asynchronous operation completes, you can call <xref:System.Messaging.MessageQueue.BeginPeek%2A> or <xref:System.Messaging.MessageQueue.BeginReceive%2A> again in the event handler to keep receiving notifications.
The <xref:System.IAsyncResult> that <xref:System.Messaging.MessageQueue.BeginPeek%2A> returns identifies the asynchronous operation that the method started. You can use this <xref:System.IAsyncResult> throughout the lifetime of the operation, although you generally do not use it until <xref:System.Messaging.MessageQueue.EndPeek%28System.IAsyncResult%29> is called. However, if you start several asynchronous operations, you can place their <xref:System.IAsyncResult> values in an array and specify whether to wait for all operations or any operation to complete. In this case, you use the <xref:System.IAsyncResult.AsyncWaitHandle%2A> property of the <xref:System.IAsyncResult> to identify the completed operation.
This overload specifies a time-out. If the interval specified by the `timeout` parameter expires, this component raises the <xref:System.Messaging.MessageQueue.PeekCompleted> event. Because no message exists, a subsequent call to <xref:System.Messaging.MessageQueue.EndPeek%28System.IAsyncResult%29> will throw an exception.
If <xref:System.Messaging.MessageQueue.CanRead%2A> is `false`, the completion event is raised, but an exception will be thrown when calling <xref:System.Messaging.MessageQueue.EndPeek%28System.IAsyncResult%29>.
The following table shows whether this method is available in various Workgroup modes.
|Workgroup mode|Available|
|--------------------|---------------|
|Local computer|Yes|
|Local computer and direct format name|Yes|
|Remote computer|No|
|Remote computer and direct format name|Yes|
## Examples
The following code example creates an asynchronous peek operation, using the queue path ".\myQueue". It creates an event handler, `MyPeekCompleted`, and attaches it to the <xref:System.Messaging.MessageQueue.PeekCompleted> event handler delegate. <xref:System.Messaging.MessageQueue.BeginPeek%2A> is called with a time-out of one minute, to initiate the asynchronous peek operation. When a <xref:System.Messaging.MessageQueue.PeekCompleted> event is raised or the time-out expires, the message is retrieved if one exists, and its body is written to the screen. Then <xref:System.Messaging.MessageQueue.BeginPeek%2A> is called again to initiate a new asynchronous peek operation with the same time-out.
[!code-cpp[MessageQueue.BeginPeek_timeout#1](~/samples/snippets/cpp/VS_Snippets_Remoting/MessageQueue.BeginPeek_timeout/CPP/mqbeginpeek_timeout.cpp#1)]
[!code-csharp[MessageQueue.BeginPeek_timeout#1](~/samples/snippets/csharp/VS_Snippets_Remoting/MessageQueue.BeginPeek_timeout/CS/mqbeginpeek_timeout.cs#1)]
[!code-vb[MessageQueue.BeginPeek_timeout#1](~/samples/snippets/visualbasic/VS_Snippets_Remoting/MessageQueue.BeginPeek_timeout/VB/mqbeginpeek_timeout.vb#1)]
]]></format>
</remarks>
<exception cref="T:System.ArgumentException">The value specified for the <paramref name="timeout" /> parameter is not valid.</exception>
<exception cref="T:System.Messaging.MessageQueueException">An error occurred when accessing a Message Queuing method.</exception>
<threadsafe>The method is not thread safe.</threadsafe>
<altmember cref="E:System.Messaging.MessageQueue.PeekCompleted" />
<altmember cref="M:System.Messaging.MessageQueue.BeginReceive" />
<altmember cref="M:System.Messaging.MessageQueue.Peek" />
<altmember cref="M:System.Messaging.MessageQueue.Receive" />
<altmember cref="T:System.TimeSpan" />
</Docs>
</Member>
<Member MemberName="BeginPeek">
<MemberSignature Language="C#" Value="public IAsyncResult BeginPeek (TimeSpan timeout, object stateObject);" />
<MemberSignature Language="ILAsm" Value=".method public hidebysig instance class System.IAsyncResult BeginPeek(valuetype System.TimeSpan timeout, object stateObject) cil managed" />
<MemberSignature Language="DocId" Value="M:System.Messaging.MessageQueue.BeginPeek(System.TimeSpan,System.Object)" />
<MemberSignature Language="VB.NET" Value="Public Function BeginPeek (timeout As TimeSpan, stateObject As Object) As IAsyncResult" />
<MemberSignature Language="C++ CLI" Value="public:&#xA; IAsyncResult ^ BeginPeek(TimeSpan timeout, System::Object ^ stateObject);" />
<MemberSignature Language="F#" Value="member this.BeginPeek : TimeSpan * obj -&gt; IAsyncResult" Usage="messageQueue.BeginPeek (timeout, stateObject)" />
<MemberType>Method</MemberType>
<AssemblyInfo>
<AssemblyName>System.Messaging</AssemblyName>
<AssemblyVersion>1.0.5000.0</AssemblyVersion>
<AssemblyVersion>2.0.0.0</AssemblyVersion>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
</AssemblyInfo>
<ReturnValue>
<ReturnType>System.IAsyncResult</ReturnType>
</ReturnValue>
<Parameters>
<Parameter Name="timeout" Type="System.TimeSpan" />
<Parameter Name="stateObject" Type="System.Object" />
</Parameters>
<Docs>
<param name="timeout">A <see cref="T:System.TimeSpan" /> that indicates the interval of time to wait for a message to become available.</param>
<param name="stateObject">A state object, specified by the application, that contains information associated with the asynchronous operation.</param>
<summary>Initiates an asynchronous peek operation that has a specified time-out and a specified state object, which provides associated information throughout the operation's lifetime. The operation is not complete until either a message becomes available in the queue or the time-out occurs.</summary>
<returns>The <see cref="T:System.IAsyncResult" /> that identifies the posted asynchronous request.</returns>
<remarks>
<format type="text/markdown"><![CDATA[
## Remarks
In asynchronous processing, you use <xref:System.Messaging.MessageQueue.BeginPeek%2A> to raise the <xref:System.Messaging.MessageQueue.PeekCompleted> event when a message becomes available in the queue or when the specified interval of time has expired.
<xref:System.Messaging.MessageQueue.PeekCompleted> is also raised if a message already exists in the queue.
Use this overload to associate information with the operation that will be preserved throughout the operation's lifetime. The event handler can access this information by looking at the <xref:System.IAsyncResult.AsyncState%2A> property of the <xref:System.IAsyncResult> that is associated with the operation.
To use <xref:System.Messaging.MessageQueue.BeginPeek%2A>, create an event handler that processes the results of the asynchronous operation, and associate it with your event delegate. <xref:System.Messaging.MessageQueue.BeginPeek%2A> initiates an asynchronous peek operation; the <xref:System.Messaging.MessageQueue> is notified, through the raising of the <xref:System.Messaging.MessageQueue.PeekCompleted> event, when a message arrives in the queue. The <xref:System.Messaging.MessageQueue> can then access the message by calling <xref:System.Messaging.MessageQueue.EndPeek%28System.IAsyncResult%29> or by retrieving the result using the <xref:System.Messaging.PeekCompletedEventArgs>.
The <xref:System.Messaging.MessageQueue.BeginPeek%2A> method returns immediately, but the asynchronous operation is not completed until the event handler is called.
Because <xref:System.Messaging.MessageQueue.BeginPeek%2A> is asynchronous, you can call it to peek the queue without blocking the current thread of execution. To synchronously peek the queue, use the <xref:System.Messaging.MessageQueue.Peek%2A> method.
Once an asynchronous operation completes, you can call <xref:System.Messaging.MessageQueue.BeginPeek%2A> or <xref:System.Messaging.MessageQueue.BeginReceive%2A> again in the event handler to keep receiving notifications.
<xref:System.Messaging.MessageQueue.BeginPeek%2A> returns a <xref:System.IAsyncResult> that identifies the asynchronous operation that the method started. You can use this <xref:System.IAsyncResult> throughout the lifetime of the operation, although you generally do not use it until <xref:System.Messaging.MessageQueue.EndPeek%28System.IAsyncResult%29> is called. However, if you start several asynchronous operations, you can place their <xref:System.IAsyncResult> values in an array and specify whether to wait for all operations or any operation to complete. In this case, you use the <xref:System.IAsyncResult.AsyncWaitHandle%2A> property of the <xref:System.IAsyncResult> to identify the completed operation.
This overload specifies a time-out and a state object. If the interval specified by the `timeout` parameter expires, this component raises the <xref:System.Messaging.MessageQueue.PeekCompleted> event. Because no message exists, a subsequent call to <xref:System.Messaging.MessageQueue.EndPeek%28System.IAsyncResult%29> will throw an exception.
The state object associates state information with the operation. For example, if you call <xref:System.Messaging.MessageQueue.BeginPeek%2A> multiple times to initiate multiple operations, you can identify each operation through a separate state object that you define. For an illustration of this scenario, see the Example section.
You can also use the state object to pass information across process threads. If a thread is started but the callback is on a different thread in an asynchronous scenario, the state object is marshaled and passed back along with information from the event.
If <xref:System.Messaging.MessageQueue.CanRead%2A> is `false`, the completion event is raised, but an exception will be thrown when calling <xref:System.Messaging.MessageQueue.EndPeek%28System.IAsyncResult%29>.
The following table shows whether this method is available in various Workgroup modes.
|Workgroup mode|Available|
|--------------------|---------------|
|Local computer|Yes|
|Local computer and direct format name|Yes|
|Remote computer|No|
|Remote computer and direct format name|Yes|
## Examples
The following code example creates an asynchronous peek operation, using the queue path ".\myQueue". It creates an event handler, `MyPeekCompleted`, and attaches it to the <xref:System.Messaging.MessageQueue.PeekCompleted> event handler delegate. <xref:System.Messaging.MessageQueue.BeginPeek%2A> is called, with a time-out of one minute. Each call to <xref:System.Messaging.MessageQueue.BeginPeek%2A> has a unique associated integer that identifies that particular operation. When a <xref:System.Messaging.MessageQueue.PeekCompleted> event is raised or the time-out expired, the message, if one exists, is retrieved and its body and the operation-specific integer identifier are written to the screen. Then <xref:System.Messaging.MessageQueue.BeginPeek%2A> is called again to initiate a new asynchronous peek operation with the same time-out and the associated integer of the just completed operation.
[!code-cpp[MessageQueue.BeginPeek_TimeSpanStateObject#1](~/samples/snippets/cpp/VS_Snippets_Remoting/MessageQueue.BeginPeek_TimeSpanStateObject/CPP/mqbeginpeek_timeoutstateobject.cpp#1)]
[!code-csharp[MessageQueue.BeginPeek_TimeSpanStateObject#1](~/samples/snippets/csharp/VS_Snippets_Remoting/MessageQueue.BeginPeek_TimeSpanStateObject/CS/mqbeginpeek_timeoutstateobject.cs#1)]
[!code-vb[MessageQueue.BeginPeek_TimeSpanStateObject#1](~/samples/snippets/visualbasic/VS_Snippets_Remoting/MessageQueue.BeginPeek_TimeSpanStateObject/VB/mqbeginpeek_timeoutstateobject.vb#1)]
]]></format>
</remarks>
<exception cref="T:System.ArgumentException">The value specified for the <paramref name="timeout" /> parameter is not valid.</exception>
<exception cref="T:System.Messaging.MessageQueueException">An error occurred when accessing a Message Queuing method.</exception>
<threadsafe>The method is not thread safe.</threadsafe>
<altmember cref="E:System.Messaging.MessageQueue.PeekCompleted" />
<altmember cref="M:System.Messaging.MessageQueue.BeginReceive" />
<altmember cref="M:System.Messaging.MessageQueue.Peek" />
<altmember cref="M:System.Messaging.MessageQueue.Receive" />
<altmember cref="T:System.TimeSpan" />
</Docs>
</Member>
<Member MemberName="BeginPeek">
<MemberSignature Language="C#" Value="public IAsyncResult BeginPeek (TimeSpan timeout, object stateObject, AsyncCallback callback);" />
<MemberSignature Language="ILAsm" Value=".method public hidebysig instance class System.IAsyncResult BeginPeek(valuetype System.TimeSpan timeout, object stateObject, class System.AsyncCallback callback) cil managed" />
<MemberSignature Language="DocId" Value="M:System.Messaging.MessageQueue.BeginPeek(System.TimeSpan,System.Object,System.AsyncCallback)" />
<MemberSignature Language="VB.NET" Value="Public Function BeginPeek (timeout As TimeSpan, stateObject As Object, callback As AsyncCallback) As IAsyncResult" />
<MemberSignature Language="C++ CLI" Value="public:&#xA; IAsyncResult ^ BeginPeek(TimeSpan timeout, System::Object ^ stateObject, AsyncCallback ^ callback);" />
<MemberSignature Language="F#" Value="member this.BeginPeek : TimeSpan * obj * AsyncCallback -&gt; IAsyncResult" Usage="messageQueue.BeginPeek (timeout, stateObject, callback)" />
<MemberType>Method</MemberType>
<AssemblyInfo>
<AssemblyName>System.Messaging</AssemblyName>
<AssemblyVersion>1.0.5000.0</AssemblyVersion>
<AssemblyVersion>2.0.0.0</AssemblyVersion>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
</AssemblyInfo>
<ReturnValue>
<ReturnType>System.IAsyncResult</ReturnType>
</ReturnValue>
<Parameters>
<Parameter Name="timeout" Type="System.TimeSpan" />
<Parameter Name="stateObject" Type="System.Object" />
<Parameter Name="callback" Type="System.AsyncCallback" />
</Parameters>
<Docs>
<param name="timeout">A <see cref="T:System.TimeSpan" /> that indicates the interval of time to wait for a message to become available.</param>
<param name="stateObject">A state object, specified by the application, that contains information associated with the asynchronous operation.</param>
<param name="callback">The <see cref="T:System.AsyncCallback" /> that will receive the notification of the asynchronous operation completion.</param>
<summary>Initiates an asynchronous peek operation that has a specified time-out and a specified state object, which provides associated information throughout the operation's lifetime. This overload receives notification, through a callback, of the identity of the event handler for the operation. The operation is not complete until either a message becomes available in the queue or the time-out occurs.</summary>
<returns>The <see cref="T:System.IAsyncResult" /> that identifies the posted asynchronous request.</returns>
<remarks>
<format type="text/markdown"><![CDATA[
## Remarks
When you use this overload, the callback specified in the callback parameter is invoked directly when a message becomes available in the queue or when the specified interval of time has expired; the <xref:System.Messaging.MessageQueue.PeekCompleted> event is not raised. The other overloads of <xref:System.Messaging.MessageQueue.BeginPeek%2A> rely on this component to raise the <xref:System.Messaging.MessageQueue.PeekCompleted> event.
<xref:System.Messaging.MessageQueue.PeekCompleted> is also raised if a message already exists in the queue.
The <xref:System.Messaging.MessageQueue.BeginPeek%2A> method returns immediately, but the asynchronous operation is not completed until the event handler is called.
Because <xref:System.Messaging.MessageQueue.BeginPeek%2A> is asynchronous, you can call it to peek the queue without blocking the current thread of execution. To synchronously peek the queue, use the <xref:System.Messaging.MessageQueue.Peek%2A> method.
Once an asynchronous operation completes, you can call <xref:System.Messaging.MessageQueue.BeginPeek%2A> or <xref:System.Messaging.MessageQueue.BeginReceive%2A> again in the event handler to keep receiving notifications.
<xref:System.Messaging.MessageQueue.BeginPeek%2A> returns a <xref:System.IAsyncResult> that identifies the asynchronous operation that the method started. You can use this <xref:System.IAsyncResult> throughout the lifetime of the operation, although you generally do not use it until <xref:System.Messaging.MessageQueue.EndPeek%28System.IAsyncResult%29> is called. However, if you start several asynchronous operations, you can place their <xref:System.IAsyncResult> values in an array and specify whether to wait for all operations or any operation to complete. In this case, you use the <xref:System.IAsyncResult.AsyncWaitHandle%2A> property of the <xref:System.IAsyncResult> to identify the completed operation.
The state object associates state information with the operation. For example, if you call <xref:System.Messaging.MessageQueue.BeginPeek%2A> multiple times to initiate multiple operations, you can identify each operation through a separate state object that you define.
The following table shows whether this method is available in various Workgroup modes.
|Workgroup mode|Available|
|--------------------|---------------|
|Local computer|Yes|
|Local computer and direct format name|Yes|
|Remote computer|No|
|Remote computer and direct format name|Yes|
## Examples
The following code example creates an asynchronous peek operation. The code example sends a message to a local message queue, then calls <xref:System.Messaging.MessageQueue.BeginPeek%28System.TimeSpan%2CSystem.Object%2CSystem.AsyncCallback%29>, passing in: a time-out value of ten seconds; a unique integer that identifies that particular message; and a new instance of <xref:System.AsyncCallback> that identifies the event handler, `MyPeekCompleted`. When a <xref:System.Messaging.MessageQueue.PeekCompleted> event is raised, the event handler peeks at the message and writes the message body and the integer message identifier to the screen.
[!code-cpp[MessageQueueBeginPeek#0](~/samples/snippets/cpp/VS_Snippets_Remoting/MessageQueueBeginPeek/cpp/class1.cpp#0)]
[!code-csharp[MessageQueueBeginPeek#0](~/samples/snippets/csharp/VS_Snippets_Remoting/MessageQueueBeginPeek/CS/class1.cs#0)]
]]></format>
</remarks>
<exception cref="T:System.ArgumentException">The value specified for the <paramref name="timeout" /> parameter is not valid.</exception>
<exception cref="T:System.Messaging.MessageQueueException">An error occurred when accessing a Message Queuing method.</exception>
<threadsafe>The method is not thread safe.</threadsafe>
<altmember cref="E:System.Messaging.MessageQueue.PeekCompleted" />
<altmember cref="M:System.Messaging.MessageQueue.BeginReceive" />
<altmember cref="M:System.Messaging.MessageQueue.Peek" />
<altmember cref="M:System.Messaging.MessageQueue.Receive" />
<altmember cref="T:System.AsyncCallback" />
<altmember cref="T:System.TimeSpan" />
</Docs>
</Member>
<Member MemberName="BeginPeek">
<MemberSignature Language="C#" Value="public IAsyncResult BeginPeek (TimeSpan timeout, System.Messaging.Cursor cursor, System.Messaging.PeekAction action, object state, AsyncCallback callback);" />
<MemberSignature Language="ILAsm" Value=".method public hidebysig instance class System.IAsyncResult BeginPeek(valuetype System.TimeSpan timeout, class System.Messaging.Cursor cursor, valuetype System.Messaging.PeekAction action, object state, class System.AsyncCallback callback) cil managed" />
<MemberSignature Language="DocId" Value="M:System.Messaging.MessageQueue.BeginPeek(System.TimeSpan,System.Messaging.Cursor,System.Messaging.PeekAction,System.Object,System.AsyncCallback)" />
<MemberSignature Language="C++ CLI" Value="public:&#xA; IAsyncResult ^ BeginPeek(TimeSpan timeout, System::Messaging::Cursor ^ cursor, System::Messaging::PeekAction action, System::Object ^ state, AsyncCallback ^ callback);" />
<MemberSignature Language="F#" Value="member this.BeginPeek : TimeSpan * System.Messaging.Cursor * System.Messaging.PeekAction * obj * AsyncCallback -&gt; IAsyncResult" Usage="messageQueue.BeginPeek (timeout, cursor, action, state, callback)" />
<MemberType>Method</MemberType>
<AssemblyInfo>
<AssemblyName>System.Messaging</AssemblyName>
<AssemblyVersion>2.0.0.0</AssemblyVersion>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
</AssemblyInfo>
<ReturnValue>
<ReturnType>System.IAsyncResult</ReturnType>
</ReturnValue>
<Parameters>
<Parameter Name="timeout" Type="System.TimeSpan" Index="0" FrameworkAlternate="netframework-2.0;netframework-3.0;netframework-3.5;netframework-4.0;netframework-4.5;netframework-4.5.1;netframework-4.5.2;netframework-4.6;netframework-4.6.1;netframework-4.6.2;netframework-4.7;netframework-4.7.1;netframework-4.7.2;netframework-4.8" />
<Parameter Name="cursor" Type="System.Messaging.Cursor" Index="1" FrameworkAlternate="netframework-2.0;netframework-3.0;netframework-3.5;netframework-4.0;netframework-4.5;netframework-4.5.1;netframework-4.5.2;netframework-4.6;netframework-4.6.1;netframework-4.6.2;netframework-4.7;netframework-4.7.1;netframework-4.7.2;netframework-4.8" />
<Parameter Name="action" Type="System.Messaging.PeekAction" Index="2" FrameworkAlternate="netframework-2.0;netframework-3.0;netframework-3.5;netframework-4.0;netframework-4.5;netframework-4.5.1;netframework-4.5.2;netframework-4.6;netframework-4.6.1;netframework-4.6.2;netframework-4.7;netframework-4.7.1;netframework-4.7.2;netframework-4.8" />
<Parameter Name="state" Type="System.Object" Index="3" FrameworkAlternate="netframework-2.0;netframework-3.0;netframework-3.5;netframework-4.0;netframework-4.5;netframework-4.5.1;netframework-4.5.2;netframework-4.6;netframework-4.6.1;netframework-4.6.2;netframework-4.7;netframework-4.7.1;netframework-4.7.2;netframework-4.8" />
<Parameter Name="callback" Type="System.AsyncCallback" Index="4" FrameworkAlternate="netframework-2.0;netframework-3.0;netframework-3.5;netframework-4.0;netframework-4.5;netframework-4.5.1;netframework-4.5.2;netframework-4.6;netframework-4.6.1;netframework-4.6.2;netframework-4.7;netframework-4.7.1;netframework-4.7.2;netframework-4.8" />
</Parameters>
<Docs>
<param name="timeout">A <see cref="T:System.TimeSpan" /> that indicates the interval of time to wait for a message to become available.</param>
<param name="cursor">A <see cref="T:System.Messaging.Cursor" /> that maintains a specific position in the message queue.</param>
<param name="action">One of the <see cref="T:System.Messaging.PeekAction" /> values. Indicates whether to peek at the current message in the queue, or the next message.</param>
<param name="state">A state object, specified by the application, that contains information associated with the asynchronous operation.</param>
<param name="callback">The <see cref="T:System.AsyncCallback" /> that receives the notification of the asynchronous operation completion.</param>
<summary>Initiates an asynchronous peek operation that has a specified time-out and that uses a specified cursor, a specified peek action, and a specified state object. The state object provides associated information throughout the lifetime of the operation. This overload receives notification, through a callback, of the identity of the event handler for the operation. The operation is not complete until either a message becomes available in the queue or the time-out occurs.</summary>
<returns>The <see cref="T:System.IAsyncResult" /> that identifies the posted asynchronous request.</returns>
<remarks>
<format type="text/markdown"><![CDATA[
## Remarks
When you use this overload, the callback specified in the callback parameter is invoked directly when a message becomes available in the queue or when the specified interval of time has expired. The <xref:System.Messaging.MessageQueue.PeekCompleted> event is not raised. The other overloads of <xref:System.Messaging.MessageQueue.BeginPeek%2A> rely on this component to raise the <xref:System.Messaging.MessageQueue.PeekCompleted> event.
<xref:System.Messaging.MessageQueue.PeekCompleted> is also raised if a message already exists in the queue.
The <xref:System.Messaging.MessageQueue.BeginPeek%2A> method returns immediately, but the asynchronous operation is not completed until the event handler is called.
Because <xref:System.Messaging.MessageQueue.BeginPeek%2A> is asynchronous, you can call it to peek the queue without blocking the current thread of execution. To synchronously peek the queue, use the <xref:System.Messaging.MessageQueue.Peek%2A> method.
Once an asynchronous operation completes, you can call <xref:System.Messaging.MessageQueue.BeginPeek%2A> or <xref:System.Messaging.MessageQueue.BeginReceive%2A> again in the event handler to keep receiving notifications.
<xref:System.Messaging.MessageQueue.BeginPeek%2A> returns a <xref:System.IAsyncResult> that identifies the asynchronous operation started by the method. You can use this <xref:System.IAsyncResult> throughout the lifetime of the operation, although you generally do not use it until <xref:System.Messaging.MessageQueue.EndPeek%28System.IAsyncResult%29> is called. However, if you start several asynchronous operations, you can place their <xref:System.IAsyncResult> values in an array and specify whether to wait for all operations or any operation to complete. In this case, use the <xref:System.IAsyncResult.AsyncWaitHandle%2A> property of the <xref:System.IAsyncResult> to identify the completed operation.
The state object associates state information with the operation. For example, if you call <xref:System.Messaging.MessageQueue.BeginPeek%2A> multiple times to initiate multiple operations, you can identify each operation through a separate state object that you define.
The following table shows whether this method is available in various Workgroup modes.
|Workgroup mode|Available|
|--------------------|---------------|
|Local computer|Yes|
|Local computer and direct format name|Yes|
|Remote computer|No|
|Remote computer and direct format name|Yes|
]]></format>
</remarks>
<exception cref="T:System.ArgumentOutOfRangeException">A value other than <see langword="PeekAction.Current" /> or <see langword="PeekAction.Next" /> was specified for the <paramref name="action" /> parameter.</exception>
<exception cref="T:System.ArgumentNullException">The <paramref name="cursor" /> parameter is <see langword="null" />.</exception>
<exception cref="T:System.ArgumentException">The value specified for the <paramref name="timeout" /> parameter is not valid.</exception>
<exception cref="T:System.Messaging.MessageQueueException">An error occurred when accessing a Message Queuing method.</exception>
<threadsafe>The method is not thread safe.</threadsafe>
<altmember cref="E:System.Messaging.MessageQueue.PeekCompleted" />
<altmember cref="M:System.Messaging.MessageQueue.BeginReceive" />
<altmember cref="M:System.Messaging.MessageQueue.Peek" />
<altmember cref="M:System.Messaging.MessageQueue.Receive" />
<altmember cref="T:System.AsyncCallback" />
<altmember cref="T:System.TimeSpan" />
</Docs>
</Member>
<MemberGroup MemberName="BeginReceive">
<AssemblyInfo>
<AssemblyName>System.Messaging</AssemblyName>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
</AssemblyInfo>
<Docs>
<threadsafe>The method is not thread safe.</threadsafe>
<summary>Initiates an asynchronous receive operation by telling Message Queuing to begin receiving a message and notify the event handler when finished.</summary>
</Docs>
</MemberGroup>
<Member MemberName="BeginReceive">
<MemberSignature Language="C#" Value="public IAsyncResult BeginReceive ();" />
<MemberSignature Language="ILAsm" Value=".method public hidebysig instance class System.IAsyncResult BeginReceive() cil managed" />
<MemberSignature Language="DocId" Value="M:System.Messaging.MessageQueue.BeginReceive" />
<MemberSignature Language="VB.NET" Value="Public Function BeginReceive () As IAsyncResult" />
<MemberSignature Language="C++ CLI" Value="public:&#xA; IAsyncResult ^ BeginReceive();" />
<MemberSignature Language="F#" Value="member this.BeginReceive : unit -&gt; IAsyncResult" Usage="messageQueue.BeginReceive " />
<MemberType>Method</MemberType>
<AssemblyInfo>
<AssemblyName>System.Messaging</AssemblyName>
<AssemblyVersion>1.0.5000.0</AssemblyVersion>
<AssemblyVersion>2.0.0.0</AssemblyVersion>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
</AssemblyInfo>
<ReturnValue>
<ReturnType>System.IAsyncResult</ReturnType>
</ReturnValue>
<Parameters />
<Docs>
<summary>Initiates an asynchronous receive operation that has no time-out. The operation is not complete until a message becomes available in the queue.</summary>
<returns>The <see cref="T:System.IAsyncResult" /> that identifies the posted asynchronous request.</returns>
<remarks>
<format type="text/markdown"><![CDATA[
## Remarks
In asynchronous processing, you use <xref:System.Messaging.MessageQueue.BeginReceive%2A> to raise the <xref:System.Messaging.MessageQueue.ReceiveCompleted> event when a message has been removed from the queue.
<xref:System.Messaging.MessageQueue.ReceiveCompleted> is also raised if a message already exists in the queue.
To use <xref:System.Messaging.MessageQueue.BeginReceive%2A>, create an event handler that processes the results of the asynchronous operation and associate it with your event delegate. <xref:System.Messaging.MessageQueue.BeginReceive%2A> initiates an asynchronous receive operation; the <xref:System.Messaging.MessageQueue> is notified, through the raising of the <xref:System.Messaging.MessageQueue.ReceiveCompleted> event, when a message arrives in the queue. The <xref:System.Messaging.MessageQueue> can then access the message by calling <xref:System.Messaging.MessageQueue.EndReceive%28System.IAsyncResult%29>.
The <xref:System.Messaging.MessageQueue.BeginReceive%2A> method returns immediately, but the asynchronous operation is not completed until the event handler is called.
Because <xref:System.Messaging.MessageQueue.BeginReceive%2A> is asynchronous, you can call it to receive a message from the queue without blocking the current thread of execution. To synchronously receive a message, use the <xref:System.Messaging.MessageQueue.Receive%2A> method.
Once an asynchronous operation completes, you can call <xref:System.Messaging.MessageQueue.BeginPeek%2A> or <xref:System.Messaging.MessageQueue.BeginReceive%2A> again in the event handler to keep receiving notifications.
The <xref:System.IAsyncResult> that <xref:System.Messaging.MessageQueue.BeginReceive%2A> returns identifies the asynchronous operation that the method started. You can use this <xref:System.IAsyncResult> throughout the lifetime of the operation, although you generally do not use it until <xref:System.Messaging.MessageQueue.EndReceive%28System.IAsyncResult%29> is called. However, if you start several asynchronous operations, you can place their <xref:System.IAsyncResult> values in an array and specify whether to wait for all operations or any operation to complete. In this case, you use the <xref:System.IAsyncResult.AsyncWaitHandle%2A> property of the <xref:System.IAsyncResult> to identify the completed operation.
If <xref:System.Messaging.MessageQueue.CanRead%2A> is `false`, the completion event is raised, but an exception will be thrown when calling <xref:System.Messaging.MessageQueue.EndReceive%28System.IAsyncResult%29>.
Do not use the asynchronous call <xref:System.Messaging.MessageQueue.BeginReceive%2A> with transactions. If you want to perform a transactional asynchronous operation, call <xref:System.Messaging.MessageQueue.BeginPeek%2A>, and put the transaction and the (synchronous) <xref:System.Messaging.MessageQueue.Receive%2A> method within the event handler you create for the peek operation. Your event handler might contain functionality as shown in the following C# code.
```csharp
myMessageQueue.BeginTransaction();
myMessageQueue.Receive();
myMessageQueue.CommitTransaction();
```
The following table shows whether this method is available in various Workgroup modes.
|Workgroup mode|Available|
|--------------------|---------------|
|Local computer|Yes|
|Local computer and direct format name|Yes|
|Remote computer|No|
|Remote computer and direct format name|Yes|
## Examples
The following code example chains asynchronous requests. It assumes there is a queue on the local computer called "myQueue". The `Main` function begins the asynchronous operation that is handled by the `MyReceiveCompleted` routine. `MyReceiveCompleted` processes the current message and begins a new asynchronous receive operation.
[!code-cpp[MessageQueue.BeginReceive_noparms_combined#1](~/samples/snippets/cpp/VS_Snippets_Remoting/MessageQueue.BeginReceive_noparms_combined/CPP/mqbeginreceive_noparms_mre.cpp#1)]
[!code-csharp[MessageQueue.BeginReceive_noparms_combined#1](~/samples/snippets/csharp/VS_Snippets_Remoting/MessageQueue.BeginReceive_noparms_combined/CS/mqbeginreceive_noparms_mre.cs#1)]
[!code-vb[MessageQueue.BeginReceive_noparms_combined#1](~/samples/snippets/visualbasic/VS_Snippets_Remoting/MessageQueue.BeginReceive_noparms_combined/VB/mqbeginreceive_noparms_mre.vb#1)]
The following code example queues asynchronous requests. The call to <xref:System.Messaging.MessageQueue.BeginReceive%2A> uses the <xref:System.IAsyncResult.AsyncWaitHandle%2A> in its return value. The `Main` routine waits for all asynchronous operations to be completed before exiting.
[!code-cpp[MessageQueue.BeginReceive_noparms_combined#2](~/samples/snippets/cpp/VS_Snippets_Remoting/MessageQueue.BeginReceive_noparms_combined/CPP/mqbeginreceive_noparms_wh.cpp#2)]
[!code-csharp[MessageQueue.BeginReceive_noparms_combined#2](~/samples/snippets/csharp/VS_Snippets_Remoting/MessageQueue.BeginReceive_noparms_combined/CS/mqbeginreceive_noparms_wh.cs#2)]
[!code-vb[MessageQueue.BeginReceive_noparms_combined#2](~/samples/snippets/visualbasic/VS_Snippets_Remoting/MessageQueue.BeginReceive_noparms_combined/VB/mqbeginreceive_noparms_wh.vb#2)]
]]></format>
</remarks>
<exception cref="T:System.Messaging.MessageQueueException">An error occurred when accessing a Message Queuing method.</exception>
<threadsafe>The method is not thread safe.</threadsafe>
<altmember cref="E:System.Messaging.MessageQueue.ReceiveCompleted" />
<altmember cref="M:System.Messaging.MessageQueue.BeginPeek" />
<altmember cref="M:System.Messaging.MessageQueue.Receive" />
<altmember cref="M:System.Messaging.MessageQueue.Peek" />
</Docs>
</Member>
<Member MemberName="BeginReceive">
<MemberSignature Language="C#" Value="public IAsyncResult BeginReceive (TimeSpan timeout);" />
<MemberSignature Language="ILAsm" Value=".method public hidebysig instance class System.IAsyncResult BeginReceive(valuetype System.TimeSpan timeout) cil managed" />
<MemberSignature Language="DocId" Value="M:System.Messaging.MessageQueue.BeginReceive(System.TimeSpan)" />
<MemberSignature Language="VB.NET" Value="Public Function BeginReceive (timeout As TimeSpan) As IAsyncResult" />
<MemberSignature Language="C++ CLI" Value="public:&#xA; IAsyncResult ^ BeginReceive(TimeSpan timeout);" />
<MemberSignature Language="F#" Value="member this.BeginReceive : TimeSpan -&gt; IAsyncResult" Usage="messageQueue.BeginReceive timeout" />
<MemberType>Method</MemberType>
<AssemblyInfo>
<AssemblyName>System.Messaging</AssemblyName>
<AssemblyVersion>1.0.5000.0</AssemblyVersion>
<AssemblyVersion>2.0.0.0</AssemblyVersion>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
</AssemblyInfo>
<ReturnValue>
<ReturnType>System.IAsyncResult</ReturnType>
</ReturnValue>
<Parameters>
<Parameter Name="timeout" Type="System.TimeSpan" />
</Parameters>
<Docs>
<param name="timeout">A <see cref="T:System.TimeSpan" /> that indicates the interval of time to wait for a message to become available.</param>
<summary>Initiates an asynchronous receive operation that has a specified time-out. The operation is not complete until either a message becomes available in the queue or the time-out occurs.</summary>
<returns>The <see cref="T:System.IAsyncResult" /> that identifies the posted asynchronous request.</returns>
<remarks>
<format type="text/markdown"><![CDATA[
## Remarks
In asynchronous processing, you use <xref:System.Messaging.MessageQueue.BeginReceive%2A> to raise the <xref:System.Messaging.MessageQueue.ReceiveCompleted> event when a message becomes available in the queue or when the specified interval of time has expired.
<xref:System.Messaging.MessageQueue.ReceiveCompleted> is also raised if a message already exists in the queue.
To use <xref:System.Messaging.MessageQueue.BeginReceive%2A>, create an event handler that processes the results of the asynchronous operation and associate it with your event delegate. <xref:System.Messaging.MessageQueue.BeginReceive%2A> initiates an asynchronous receive operation; the <xref:System.Messaging.MessageQueue> is notified, through the raising of the <xref:System.Messaging.MessageQueue.ReceiveCompleted> event, when a message arrives in the queue. The <xref:System.Messaging.MessageQueue> can then access the message by calling <xref:System.Messaging.MessageQueue.EndReceive%28System.IAsyncResult%29> or retrieving the result using the <xref:System.Messaging.ReceiveCompletedEventArgs>.
The <xref:System.Messaging.MessageQueue.BeginReceive%2A> method returns immediately, but the asynchronous operation is not completed until the event handler is called.
Because <xref:System.Messaging.MessageQueue.BeginReceive%2A> is asynchronous, you can call it to receive a message from the queue without blocking the current thread of execution. To synchronously receive a message, use the <xref:System.Messaging.MessageQueue.Receive%2A> method.
Once an asynchronous operation completes, you can call <xref:System.Messaging.MessageQueue.BeginPeek%2A> or <xref:System.Messaging.MessageQueue.BeginReceive%2A> again in the event handler to keep receiving notifications.
If <xref:System.Messaging.MessageQueue.CanRead%2A> is `false`, the completion event is raised, but an exception will be thrown when calling <xref:System.Messaging.MessageQueue.EndReceive%28System.IAsyncResult%29>.
The <xref:System.IAsyncResult> that <xref:System.Messaging.MessageQueue.BeginReceive%2A> returns identifies the asynchronous operation that the method started. You can use this <xref:System.IAsyncResult> throughout the lifetime of the operation, although you generally do not use it until <xref:System.Messaging.MessageQueue.EndReceive%28System.IAsyncResult%29> is called. However, if you start several asynchronous operations, you can place their <xref:System.IAsyncResult> values in an array and specify whether to wait for all operations or any operation to complete. In this case, you use the <xref:System.IAsyncResult.AsyncWaitHandle%2A> property of the <xref:System.IAsyncResult> to identify the completed operation.
This overload specifies a time-out. If the interval specified by the `timeout` parameter expires, this component raises the <xref:System.Messaging.MessageQueue.ReceiveCompleted> event. Because no message exists, a subsequent call to <xref:System.Messaging.MessageQueue.EndReceive%28System.IAsyncResult%29> will throw an exception.
Do not use the asynchronous call <xref:System.Messaging.MessageQueue.BeginReceive%2A> with transactions. If you want to perform a transactional asynchronous operation, call <xref:System.Messaging.MessageQueue.BeginPeek%2A>, and put the transaction and the (synchronous) <xref:System.Messaging.MessageQueue.Receive%2A> method within the event handler you create for the peek operation. Your event handler might contain functionality as shown in the following C# code.
```csharp
myMessageQueue.BeginTransaction();
myMessageQueue.Receive();
myMessageQueue.CommitTransaction();
```
The following table shows whether this method is available in various Workgroup modes.
|Workgroup mode|Available|
|--------------------|---------------|
|Local computer|Yes|
|Local computer and direct format name|Yes|
|Remote computer|No|
|Remote computer and direct format name|Yes|
## Examples
The following code example creates an asynchronous receive operation. The code example creates an event handler, `MyReceiveCompleted`, and attaches it to the <xref:System.Messaging.MessageQueue.ReceiveCompleted> event handler delegate. The code example sends a message to a local message queue, then calls <xref:System.Messaging.MessageQueue.BeginReceive%28System.TimeSpan%29>, passing in a time-out value of ten seconds. When a <xref:System.Messaging.MessageQueue.ReceiveCompleted> event is raised, the event handler receives the message and writes the message body to the screen.
[!code-cpp[MessageQueueBeginReceive1#0](~/samples/snippets/cpp/VS_Snippets_Remoting/MessageQueueBeginReceive1/cpp/class1.cpp#0)]
[!code-csharp[MessageQueueBeginReceive1#0](~/samples/snippets/csharp/VS_Snippets_Remoting/MessageQueueBeginReceive1/CS/class1.cs#0)]
]]></format>
</remarks>
<exception cref="T:System.ArgumentException">The value specified for the <paramref name="timeout" /> parameter is not valid, possibly because it represents a negative number.</exception>
<exception cref="T:System.Messaging.MessageQueueException">An error occurred when accessing a Message Queuing method.</exception>
<threadsafe>The method is not thread safe.</threadsafe>
<altmember cref="E:System.Messaging.MessageQueue.ReceiveCompleted" />
<altmember cref="M:System.Messaging.MessageQueue.BeginPeek" />
<altmember cref="M:System.Messaging.MessageQueue.Receive" />
<altmember cref="M:System.Messaging.MessageQueue.Peek" />
<altmember cref="T:System.TimeSpan" />
</Docs>
</Member>
<Member MemberName="BeginReceive">
<MemberSignature Language="C#" Value="public IAsyncResult BeginReceive (TimeSpan timeout, object stateObject);" />
<MemberSignature Language="ILAsm" Value=".method public hidebysig instance class System.IAsyncResult BeginReceive(valuetype System.TimeSpan timeout, object stateObject) cil managed" />
<MemberSignature Language="DocId" Value="M:System.Messaging.MessageQueue.BeginReceive(System.TimeSpan,System.Object)" />
<MemberSignature Language="VB.NET" Value="Public Function BeginReceive (timeout As TimeSpan, stateObject As Object) As IAsyncResult" />
<MemberSignature Language="C++ CLI" Value="public:&#xA; IAsyncResult ^ BeginReceive(TimeSpan timeout, System::Object ^ stateObject);" />
<MemberSignature Language="F#" Value="member this.BeginReceive : TimeSpan * obj -&gt; IAsyncResult" Usage="messageQueue.BeginReceive (timeout, stateObject)" />
<MemberType>Method</MemberType>
<AssemblyInfo>
<AssemblyName>System.Messaging</AssemblyName>
<AssemblyVersion>1.0.5000.0</AssemblyVersion>
<AssemblyVersion>2.0.0.0</AssemblyVersion>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
</AssemblyInfo>
<ReturnValue>
<ReturnType>System.IAsyncResult</ReturnType>
</ReturnValue>
<Parameters>
<Parameter Name="timeout" Type="System.TimeSpan" />
<Parameter Name="stateObject" Type="System.Object" />
</Parameters>
<Docs>
<param name="timeout">A <see cref="T:System.TimeSpan" /> that indicates the interval of time to wait for a message to become available.</param>
<param name="stateObject">A state object, specified by the application, that contains information associated with the asynchronous operation.</param>
<summary>Initiates an asynchronous receive operation that has a specified time-out and a specified state object, which provides associated information throughout the operation's lifetime. The operation is not complete until either a message becomes available in the queue or the time-out occurs.</summary>
<returns>The <see cref="T:System.IAsyncResult" /> that identifies the posted asynchronous request.</returns>
<remarks>
<format type="text/markdown"><![CDATA[
## Remarks
In asynchronous processing, you use <xref:System.Messaging.MessageQueue.BeginReceive%2A> to raise the <xref:System.Messaging.MessageQueue.ReceiveCompleted> event when a message becomes available in the queue or when the specified interval of time has expired.
<xref:System.Messaging.MessageQueue.ReceiveCompleted> is also raised if a message already exists in the queue.
Use this overload to associate information with the operation that will be preserved throughout the operation's lifetime. The event handler can detect this information by looking at the <xref:System.IAsyncResult.AsyncState%2A> property of the <xref:System.IAsyncResult> that is associated with the operation.
To use <xref:System.Messaging.MessageQueue.BeginReceive%2A>, create an event handler that processes the results of the asynchronous operation and associate it with your event delegate. <xref:System.Messaging.MessageQueue.BeginReceive%2A> initiates an asynchronous receive operation; the <xref:System.Messaging.MessageQueue> is notified, through the raising of the <xref:System.Messaging.MessageQueue.ReceiveCompleted> event, when a message arrives in the queue. The <xref:System.Messaging.MessageQueue> can then access the message by calling <xref:System.Messaging.MessageQueue.EndReceive%28System.IAsyncResult%29> or retrieving the result using the <xref:System.Messaging.ReceiveCompletedEventArgs>.
The <xref:System.Messaging.MessageQueue.BeginReceive%2A> method returns immediately, but the asynchronous operation is not completed until the event handler is called.
Because <xref:System.Messaging.MessageQueue.BeginReceive%2A> is asynchronous, you can call it to receive a message from the queue without blocking the current thread of execution. To synchronously receive a message, use the <xref:System.Messaging.MessageQueue.Receive%2A> method.
Once an asynchronous operation completes, you can call <xref:System.Messaging.MessageQueue.BeginPeek%2A> or <xref:System.Messaging.MessageQueue.BeginReceive%2A> again in the event handler to keep receiving notifications.
The <xref:System.IAsyncResult> that <xref:System.Messaging.MessageQueue.BeginReceive%2A> returns identifies the asynchronous operation that the method started. You can use this <xref:System.IAsyncResult> throughout the lifetime of the operation, although you generally do not use it until <xref:System.Messaging.MessageQueue.EndReceive%28System.IAsyncResult%29> is called. However, if you start several asynchronous operations, you can place their <xref:System.IAsyncResult> values in an array and specify whether to wait for all operations or any operation to complete. In this case, you use the <xref:System.IAsyncResult.AsyncWaitHandle%2A> property of the <xref:System.IAsyncResult> to identify the completed operation.
This overload specifies a time-out and a state object. If the interval specified by the `timeout` parameter expires, this component raises the <xref:System.Messaging.MessageQueue.ReceiveCompleted> event. Because no message exists, a subsequent call to <xref:System.Messaging.MessageQueue.EndReceive%28System.IAsyncResult%29> will throw an exception.
The state object associates state information with the operation. For example, if you call <xref:System.Messaging.MessageQueue.BeginReceive%2A> multiple times to initiate multiple operations, you can identify each operation through a separate state object that you define.
You can also use the state object to pass information across process threads. If a thread is started but the callback is on a different thread in an asynchronous scenario, the state object is marshaled and passed back along with information from the event.
Do not use the asynchronous call <xref:System.Messaging.MessageQueue.BeginReceive%2A> with transactions. If you want to perform a transactional asynchronous operation, call <xref:System.Messaging.MessageQueue.BeginPeek%2A>, and put the transaction and the (synchronous) <xref:System.Messaging.MessageQueue.Receive%2A> method within the event handler you create for the peek operation. Your event handler might contain functionality as shown in the following C# code.
```csharp
myMessageQueue.BeginTransaction();
myMessageQueue.Receive();
myMessageQueue.CommitTransaction();
```
The following table shows whether this method is available in various Workgroup modes.
|Workgroup mode|Available|
|--------------------|---------------|
|Local computer|Yes|
|Local computer and direct format name|Yes|
|Remote computer|No|
|Remote computer and direct format name|Yes|
## Examples
The following code example creates an asynchronous receive operation. The code example creates an event handler, `MyReceiveCompleted`, and attaches it to the <xref:System.Messaging.MessageQueue.ReceiveCompleted> event handler delegate. The code example sends a message to a local message queue, then calls <xref:System.Messaging.MessageQueue.BeginReceive%28System.TimeSpan%2CSystem.Object%29>, passing in a time-out value of ten seconds and a unique integer that identifies that particular message. When a <xref:System.Messaging.MessageQueue.ReceiveCompleted> event is raised, the event handler receives the message and writes the message body and the integer message identifier to the screen.
[!code-cpp[MessageQueueBeginReceive2#0](~/samples/snippets/cpp/VS_Snippets_Remoting/MessageQueueBeginReceive2/cpp/class1.cpp#0)]
[!code-csharp[MessageQueueBeginReceive2#0](~/samples/snippets/csharp/VS_Snippets_Remoting/MessageQueueBeginReceive2/CS/class1.cs#0)]
]]></format>
</remarks>
<exception cref="T:System.ArgumentException">The value specified for the <paramref name="timeout" /> parameter is not valid.</exception>
<exception cref="T:System.Messaging.MessageQueueException">An error occurred when accessing a Message Queuing method.</exception>
<threadsafe>The method is not thread safe.</threadsafe>
<altmember cref="E:System.Messaging.MessageQueue.ReceiveCompleted" />
<altmember cref="M:System.Messaging.MessageQueue.BeginPeek" />
<altmember cref="M:System.Messaging.MessageQueue.Receive" />
<altmember cref="M:System.Messaging.MessageQueue.Peek" />
<altmember cref="T:System.TimeSpan" />
</Docs>
</Member>
<Member MemberName="BeginReceive">
<MemberSignature Language="C#" Value="public IAsyncResult BeginReceive (TimeSpan timeout, object stateObject, AsyncCallback callback);" />
<MemberSignature Language="ILAsm" Value=".method public hidebysig instance class System.IAsyncResult BeginReceive(valuetype System.TimeSpan timeout, object stateObject, class System.AsyncCallback callback) cil managed" />
<MemberSignature Language="DocId" Value="M:System.Messaging.MessageQueue.BeginReceive(System.TimeSpan,System.Object,System.AsyncCallback)" />
<MemberSignature Language="VB.NET" Value="Public Function BeginReceive (timeout As TimeSpan, stateObject As Object, callback As AsyncCallback) As IAsyncResult" />
<MemberSignature Language="C++ CLI" Value="public:&#xA; IAsyncResult ^ BeginReceive(TimeSpan timeout, System::Object ^ stateObject, AsyncCallback ^ callback);" />
<MemberSignature Language="F#" Value="member this.BeginReceive : TimeSpan * obj * AsyncCallback -&gt; IAsyncResult" Usage="messageQueue.BeginReceive (timeout, stateObject, callback)" />
<MemberType>Method</MemberType>
<AssemblyInfo>
<AssemblyName>System.Messaging</AssemblyName>
<AssemblyVersion>1.0.5000.0</AssemblyVersion>
<AssemblyVersion>2.0.0.0</AssemblyVersion>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
</AssemblyInfo>
<ReturnValue>
<ReturnType>System.IAsyncResult</ReturnType>
</ReturnValue>
<Parameters>
<Parameter Name="timeout" Type="System.TimeSpan" />
<Parameter Name="stateObject" Type="System.Object" />
<Parameter Name="callback" Type="System.AsyncCallback" />
</Parameters>
<Docs>
<param name="timeout">A <see cref="T:System.TimeSpan" /> that indicates the interval of time to wait for a message to become available.</param>
<param name="stateObject">A state object, specified by the application, that contains information associated with the asynchronous operation.</param>
<param name="callback">The <see cref="T:System.AsyncCallback" /> that will receive the notification of the asynchronous operation completion.</param>
<summary>Initiates an asynchronous receive operation that has a specified time-out and a specified state object, which provides associated information throughout the operation's lifetime. This overload receives notification, through a callback, of the identity of the event handler for the operation. The operation is not complete until either a message becomes available in the queue or the time-out occurs.</summary>
<returns>The <see cref="T:System.IAsyncResult" /> that identifies the posted asynchronous request.</returns>
<remarks>
<format type="text/markdown"><![CDATA[
## Remarks
When you use this overload, the callback specified in the callback parameter is invoked directly when a message becomes available in the queue or when the specified interval of time has expired; the <xref:System.Messaging.MessageQueue.ReceiveCompleted> event is not raised. The other overloads of <xref:System.Messaging.MessageQueue.BeginReceive%2A> rely on this component to raise the <xref:System.Messaging.MessageQueue.ReceiveCompleted> event.
<xref:System.Messaging.MessageQueue.ReceiveCompleted> is also raised if a message already exists in the queue.
To use <xref:System.Messaging.MessageQueue.BeginReceive%2A>, create an event handler that processes the results of the asynchronous operation and associate it with your event delegate. <xref:System.Messaging.MessageQueue.BeginReceive%2A> initiates an asynchronous receive operation; the <xref:System.Messaging.MessageQueue> is notified, through the raising of the <xref:System.Messaging.MessageQueue.ReceiveCompleted> event, when a message arrives in the queue. The <xref:System.Messaging.MessageQueue> can then access the message by calling <xref:System.Messaging.MessageQueue.EndReceive%28System.IAsyncResult%29> or retrieving the result using the <xref:System.Messaging.ReceiveCompletedEventArgs>.
The <xref:System.Messaging.MessageQueue.BeginReceive%2A> method returns immediately, but the asynchronous operation is not completed until the event handler is called.
Because <xref:System.Messaging.MessageQueue.BeginReceive%2A> is asynchronous, you can call it to receive a message from the queue without blocking the current thread of execution. To synchronously receive a message, use the <xref:System.Messaging.MessageQueue.Receive%2A> method.
Once an asynchronous operation completes, you can call <xref:System.Messaging.MessageQueue.BeginPeek%2A> or <xref:System.Messaging.MessageQueue.BeginReceive%2A> again in the event handler to keep receiving notifications.
The <xref:System.IAsyncResult> that <xref:System.Messaging.MessageQueue.BeginReceive%2A> returns identifies the asynchronous operation that the method started. You can use this <xref:System.IAsyncResult> throughout the lifetime of the operation, although you generally do not use it until <xref:System.Messaging.MessageQueue.EndReceive%28System.IAsyncResult%29> is called. However, if you start several asynchronous operations, you can place their <xref:System.IAsyncResult> values in an array and specify whether to wait for all operations or any operation to complete. In this case, you use the <xref:System.IAsyncResult.AsyncWaitHandle%2A> property of the <xref:System.IAsyncResult> to identify the completed operation.
The state object associates state information with the operation. For example, if you call <xref:System.Messaging.MessageQueue.BeginReceive%2A> multiple times to initiate multiple operations, you can identify each operation through a separate state object that you define.
You can also use the state object to pass information across process threads. If a thread is started but the callback is on a different thread in an asynchronous scenario, the state object is marshaled and passed back along with information from the event.
Do not use the asynchronous call <xref:System.Messaging.MessageQueue.BeginReceive%2A> with transactions. If you want to perform a transactional asynchronous operation, call <xref:System.Messaging.MessageQueue.BeginPeek%2A>, and put the transaction and the (synchronous) <xref:System.Messaging.MessageQueue.Receive%2A> method within the event handler you create for the peek operation. Your event handler might contain functionality as shown in the following C# code.
```csharp
myMessageQueue.BeginTransaction();
myMessageQueue.Receive();
myMessageQueue.CommitTransaction();
```
The following table shows whether this method is available in various Workgroup modes.
|Workgroup mode|Available|
|--------------------|---------------|
|Local computer|Yes|
|Local computer and direct format name|Yes|
|Remote computer|No|
|Remote computer and direct format name|Yes|
## Examples
The following code example creates an asynchronous receive operation. The code example sends a message to a local message queue, then calls <xref:System.Messaging.MessageQueue.BeginReceive%28System.TimeSpan%2CSystem.Object%2CSystem.AsyncCallback%29>, passing in: a time-out value of ten seconds; a unique integer that identifies that particular message; and a new instance of <xref:System.AsyncCallback> that identifies the event handler, `MyReceiveCompleted`. When a <xref:System.Messaging.MessageQueue.ReceiveCompleted> event is raised, the event handler receives the message and writes the message body and the integer message identifier to the screen.
[!code-cpp[MessageQueueBeginReceive3#0](~/samples/snippets/cpp/VS_Snippets_Remoting/MessageQueueBeginReceive3/cpp/class1.cpp#0)]
[!code-csharp[MessageQueueBeginReceive3#0](~/samples/snippets/csharp/VS_Snippets_Remoting/MessageQueueBeginReceive3/CS/class1.cs#0)]
]]></format>
</remarks>
<exception cref="T:System.ArgumentException">The value specified for the <paramref name="timeout" /> parameter is not valid.</exception>
<exception cref="T:System.Messaging.MessageQueueException">An error occurred when accessing a Message Queuing method.</exception>
<threadsafe>The method is not thread safe.</threadsafe>
<altmember cref="E:System.Messaging.MessageQueue.ReceiveCompleted" />
<altmember cref="M:System.Messaging.MessageQueue.BeginPeek" />
<altmember cref="M:System.Messaging.MessageQueue.Receive" />
<altmember cref="M:System.Messaging.MessageQueue.Peek" />
<altmember cref="T:System.AsyncCallback" />
<altmember cref="T:System.TimeSpan" />
</Docs>
</Member>
<Member MemberName="BeginReceive">
<MemberSignature Language="C#" Value="public IAsyncResult BeginReceive (TimeSpan timeout, System.Messaging.Cursor cursor, object state, AsyncCallback callback);" />
<MemberSignature Language="ILAsm" Value=".method public hidebysig instance class System.IAsyncResult BeginReceive(valuetype System.TimeSpan timeout, class System.Messaging.Cursor cursor, object state, class System.AsyncCallback callback) cil managed" />
<MemberSignature Language="DocId" Value="M:System.Messaging.MessageQueue.BeginReceive(System.TimeSpan,System.Messaging.Cursor,System.Object,System.AsyncCallback)" />
<MemberSignature Language="C++ CLI" Value="public:&#xA; IAsyncResult ^ BeginReceive(TimeSpan timeout, System::Messaging::Cursor ^ cursor, System::Object ^ state, AsyncCallback ^ callback);" />
<MemberSignature Language="F#" Value="member this.BeginReceive : TimeSpan * System.Messaging.Cursor * obj * AsyncCallback -&gt; IAsyncResult" Usage="messageQueue.BeginReceive (timeout, cursor, state, callback)" />
<MemberType>Method</MemberType>
<AssemblyInfo>
<AssemblyName>System.Messaging</AssemblyName>
<AssemblyVersion>2.0.0.0</AssemblyVersion>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
</AssemblyInfo>
<ReturnValue>
<ReturnType>System.IAsyncResult</ReturnType>
</ReturnValue>
<Parameters>
<Parameter Name="timeout" Type="System.TimeSpan" Index="0" FrameworkAlternate="netframework-2.0;netframework-3.0;netframework-3.5;netframework-4.0;netframework-4.5;netframework-4.5.1;netframework-4.5.2;netframework-4.6;netframework-4.6.1;netframework-4.6.2;netframework-4.7;netframework-4.7.1;netframework-4.7.2;netframework-4.8" />
<Parameter Name="cursor" Type="System.Messaging.Cursor" Index="1" FrameworkAlternate="netframework-2.0;netframework-3.0;netframework-3.5;netframework-4.0;netframework-4.5;netframework-4.5.1;netframework-4.5.2;netframework-4.6;netframework-4.6.1;netframework-4.6.2;netframework-4.7;netframework-4.7.1;netframework-4.7.2;netframework-4.8" />
<Parameter Name="state" Type="System.Object" Index="2" FrameworkAlternate="netframework-2.0;netframework-3.0;netframework-3.5;netframework-4.0;netframework-4.5;netframework-4.5.1;netframework-4.5.2;netframework-4.6;netframework-4.6.1;netframework-4.6.2;netframework-4.7;netframework-4.7.1;netframework-4.7.2;netframework-4.8" />
<Parameter Name="callback" Type="System.AsyncCallback" Index="3" FrameworkAlternate="netframework-2.0;netframework-3.0;netframework-3.5;netframework-4.0;netframework-4.5;netframework-4.5.1;netframework-4.5.2;netframework-4.6;netframework-4.6.1;netframework-4.6.2;netframework-4.7;netframework-4.7.1;netframework-4.7.2;netframework-4.8" />
</Parameters>
<Docs>
<param name="timeout">A <see cref="T:System.TimeSpan" /> that indicates the interval of time to wait for a message to become available.</param>
<param name="cursor">A <see cref="T:System.Messaging.Cursor" /> that maintains a specific position in the message queue.</param>
<param name="state">A state object, specified by the application, that contains information associated with the asynchronous operation.</param>
<param name="callback">The <see cref="T:System.AsyncCallback" /> that receives the notification of the asynchronous operation completion.</param>
<summary>Initiates an asynchronous receive operation that has a specified time-out and uses a specified cursor and a specified state object. The state object provides associated information throughout the lifetime of the operation. This overload receives notification, through a callback, of the identity of the event handler for the operation. The operation is not complete until either a message becomes available in the queue or the time-out occurs.</summary>
<returns>The <see cref="T:System.IAsyncResult" /> that identifies the posted asynchronous request.</returns>
<remarks>
<format type="text/markdown"><![CDATA[
## Remarks
When you use this overload, the callback specified in the callback parameter is invoked directly when a message becomes available in the queue or when the specified interval of time has expired; the <xref:System.Messaging.MessageQueue.ReceiveCompleted> event is not raised. The other overloads of <xref:System.Messaging.MessageQueue.BeginReceive%2A> rely on this component to raise the <xref:System.Messaging.MessageQueue.ReceiveCompleted> event.
<xref:System.Messaging.MessageQueue.ReceiveCompleted> is also raised if a message already exists in the queue.
To use <xref:System.Messaging.MessageQueue.BeginReceive%2A>, create an event handler that processes the results of the asynchronous operation and associate it with your event delegate. <xref:System.Messaging.MessageQueue.BeginReceive%2A> initiates an asynchronous receive operation; the <xref:System.Messaging.MessageQueue> is notified, through the raising of the <xref:System.Messaging.MessageQueue.ReceiveCompleted> event, when a message arrives in the queue. The <xref:System.Messaging.MessageQueue> can then access the message by calling <xref:System.Messaging.MessageQueue.EndReceive%28System.IAsyncResult%29> or retrieving the result using the <xref:System.Messaging.ReceiveCompletedEventArgs>.
The <xref:System.Messaging.MessageQueue.BeginReceive%2A> method returns immediately, but the asynchronous operation is not completed until the event handler is called.
Because <xref:System.Messaging.MessageQueue.BeginReceive%2A> is asynchronous, you can call it to receive a message from the queue without blocking the current thread of execution. To synchronously receive a message, use the <xref:System.Messaging.MessageQueue.Receive%2A> method.
Once an asynchronous operation completes, you can call <xref:System.Messaging.MessageQueue.BeginPeek%2A> or <xref:System.Messaging.MessageQueue.BeginReceive%2A> again in the event handler to keep receiving notifications.
The <xref:System.IAsyncResult> that <xref:System.Messaging.MessageQueue.BeginReceive%2A> returns identifies the asynchronous operation that the method started. You can use this <xref:System.IAsyncResult> throughout the lifetime of the operation, although you generally do not use it until <xref:System.Messaging.MessageQueue.EndReceive%28System.IAsyncResult%29> is called. However, if you start several asynchronous operations, you can place their <xref:System.IAsyncResult> values in an array and specify whether to wait for all operations or any operation to complete. In this case, use the <xref:System.IAsyncResult.AsyncWaitHandle%2A> property of the <xref:System.IAsyncResult> to identify the completed operation.
The state object associates state information with the operation. For example, if you call <xref:System.Messaging.MessageQueue.BeginReceive%2A> multiple times to initiate multiple operations, you can identify each operation through a separate state object that you define.
You can also use the state object to pass information across process threads. If a thread is started but the callback is on a different thread in an asynchronous scenario, the state object is marshaled and passed back along with information from the event.
Do not use the asynchronous call <xref:System.Messaging.MessageQueue.BeginReceive%2A> with transactions. If you want to perform a transactional asynchronous operation, call <xref:System.Messaging.MessageQueue.BeginPeek%2A>, and put the transaction and the (synchronous) <xref:System.Messaging.MessageQueue.Receive%2A> method within the event handler you create for the peek operation. Your event handler might contain functionality as shown in the following C# code.
```csharp
myMessageQueue.BeginTransaction();
myMessageQueue.Receive();
myMessageQueue.CommitTransaction();
```
The following table shows whether this method is available in various Workgroup modes.
|Workgroup mode|Available|
|--------------------|---------------|
|Local computer|Yes|
|Local computer and direct format name|Yes|
|Remote computer|No|
|Remote computer and direct format name|Yes|
]]></format>
</remarks>
<exception cref="T:System.ArgumentNullException">The <paramref name="cursor" /> parameter is <see langword="null" />.</exception>
<exception cref="T:System.ArgumentException">The value specified for the <paramref name="timeout" /> parameter is not valid.</exception>
<exception cref="T:System.Messaging.MessageQueueException">An error occurred when accessing a Message Queuing method.</exception>
<threadsafe>The method is not thread safe.</threadsafe>
<altmember cref="T:System.Messaging.Cursor" />
<altmember cref="E:System.Messaging.MessageQueue.ReceiveCompleted" />
<altmember cref="M:System.Messaging.MessageQueue.BeginPeek" />
<altmember cref="M:System.Messaging.MessageQueue.Receive" />
<altmember cref="M:System.Messaging.MessageQueue.Peek" />
<altmember cref="T:System.AsyncCallback" />
<altmember cref="T:System.TimeSpan" />
</Docs>
</Member>
<Member MemberName="CanRead">
<MemberSignature Language="C#" Value="public bool CanRead { get; }" />
<MemberSignature Language="ILAsm" Value=".property instance bool CanRead" />
<MemberSignature Language="DocId" Value="P:System.Messaging.MessageQueue.CanRead" />
<MemberSignature Language="VB.NET" Value="Public ReadOnly Property CanRead As Boolean" />
<MemberSignature Language="C++ CLI" Value="public:&#xA; property bool CanRead { bool get(); };" />
<MemberSignature Language="F#" Value="member this.CanRead : bool" Usage="System.Messaging.MessageQueue.CanRead" />
<MemberType>Property</MemberType>
<AssemblyInfo>
<AssemblyName>System.Messaging</AssemblyName>
<AssemblyVersion>1.0.5000.0</AssemblyVersion>
<AssemblyVersion>2.0.0.0</AssemblyVersion>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
</AssemblyInfo>
<Attributes>
<Attribute FrameworkAlternate="netframework-1.1;netframework-2.0;netframework-3.0;netframework-3.5;netframework-4.0;netframework-4.5;netframework-4.5.1;netframework-4.5.2;netframework-4.6;netframework-4.6.1;netframework-4.6.2;netframework-4.7;netframework-4.7.1;netframework-4.7.2;xamarinmac-3.0;netframework-4.8">
<AttributeName>System.ComponentModel.Browsable(false)</AttributeName>
</Attribute>
<Attribute FrameworkAlternate="netframework-1.1;netframework-2.0;netframework-3.0;netframework-3.5;netframework-4.0;netframework-4.5;netframework-4.5.1;netframework-4.5.2;netframework-4.6;netframework-4.6.1;netframework-4.6.2;netframework-4.7;netframework-4.7.1;netframework-4.7.2;xamarinmac-3.0;netframework-4.8">
<AttributeName>System.Messaging.MessagingDescription("MQ_CanRead")</AttributeName>
</Attribute>
<Attribute>
<AttributeName>System.ComponentModel.DesignerSerializationVisibility(System.ComponentModel.DesignerSerializationVisibility.Hidden)</AttributeName>
</Attribute>
</Attributes>
<ReturnValue>
<ReturnType>System.Boolean</ReturnType>
</ReturnValue>
<Docs>
<summary>Gets a value that indicates whether the <see cref="T:System.Messaging.MessageQueue" /> can be read.</summary>
<value>
<see langword="true" /> if the <see cref="T:System.Messaging.MessageQueue" /> exists and the application can read from it; otherwise, <see langword="false" />.</value>
<remarks>
<format type="text/markdown"><![CDATA[
## Remarks
<xref:System.Messaging.MessageQueue.CanRead%2A> indicates whether the application is able to peek or receive messages from the queue. If <xref:System.Messaging.MessageQueue.CanRead%2A> is `true`, the <xref:System.Messaging.MessageQueue> can receive or peek messages from the queue. Otherwise, it cannot.
<xref:System.Messaging.MessageQueue.CanRead%2A> is `false` if a queue is already open with exclusive read access (or if it's open with non-exclusive access and this <xref:System.Messaging.MessageQueue> requests exclusive access), or if the application does not have sufficient rights to access it. If your application tries to read from a queue when <xref:System.Messaging.MessageQueue.CanRead%2A> is `false`, access is denied.
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|No|
|Remote computer and direct format name|Yes|
## Examples
The following code example displays the value of a message queue's <xref:System.Messaging.MessageQueue.CanRead%2A> property.
[!code-csharp[MessageQueue#5](~/samples/snippets/csharp/VS_Snippets_Remoting/MessageQueue/CS/class1.cs#5)]
]]></format>
</remarks>
<altmember cref="P:System.Messaging.MessageQueue.CanWrite" />
<altmember cref="P:System.Messaging.MessageQueue.ReadHandle" />
</Docs>
</Member>
<Member MemberName="CanWrite">
<MemberSignature Language="C#" Value="public bool CanWrite { get; }" />
<MemberSignature Language="ILAsm" Value=".property instance bool CanWrite" />
<MemberSignature Language="DocId" Value="P:System.Messaging.MessageQueue.CanWrite" />
<MemberSignature Language="VB.NET" Value="Public ReadOnly Property CanWrite As Boolean" />
<MemberSignature Language="C++ CLI" Value="public:&#xA; property bool CanWrite { bool get(); };" />
<MemberSignature Language="F#" Value="member this.CanWrite : bool" Usage="System.Messaging.MessageQueue.CanWrite" />
<MemberType>Property</MemberType>
<AssemblyInfo>
<AssemblyName>System.Messaging</AssemblyName>
<AssemblyVersion>1.0.5000.0</AssemblyVersion>
<AssemblyVersion>2.0.0.0</AssemblyVersion>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
</AssemblyInfo>
<Attributes>
<Attribute FrameworkAlternate="netframework-1.1;netframework-2.0;netframework-3.0;netframework-3.5;netframework-4.0;netframework-4.5;netframework-4.5.1;netframework-4.5.2;netframework-4.6;netframework-4.6.1;netframework-4.6.2;netframework-4.7;netframework-4.7.1;netframework-4.7.2;xamarinmac-3.0;netframework-4.8">
<AttributeName>System.ComponentModel.Browsable(false)</AttributeName>
</Attribute>
<Attribute FrameworkAlternate="netframework-1.1;netframework-2.0;netframework-3.0;netframework-3.5;netframework-4.0;netframework-4.5;netframework-4.5.1;netframework-4.5.2;netframework-4.6;netframework-4.6.1;netframework-4.6.2;netframework-4.7;netframework-4.7.1;netframework-4.7.2;xamarinmac-3.0;netframework-4.8">
<AttributeName>System.Messaging.MessagingDescription("MQ_CanWrite")</AttributeName>
</Attribute>
<Attribute>
<AttributeName>System.ComponentModel.DesignerSerializationVisibility(System.ComponentModel.DesignerSerializationVisibility.Hidden)</AttributeName>
</Attribute>
</Attributes>
<ReturnValue>
<ReturnType>System.Boolean</ReturnType>
</ReturnValue>
<Docs>
<summary>Gets a value that indicates whether the <see cref="T:System.Messaging.MessageQueue" /> can be written to.</summary>
<value>
<see langword="true" /> if the <see cref="T:System.Messaging.MessageQueue" /> exists and the application can write to it; otherwise, <see langword="false" />.</value>
<remarks>
<format type="text/markdown"><![CDATA[
## Remarks
<xref:System.Messaging.MessageQueue.CanWrite%2A> indicates whether the application is able to send messages to the queue. If <xref:System.Messaging.MessageQueue.CanWrite%2A> is `true`, the <xref:System.Messaging.MessageQueue> can send messages to the queue. Otherwise, it cannot.
<xref:System.Messaging.MessageQueue.CanWrite%2A> is `false` if a queue is already open with exclusive write access (or if it's open with non-exclusive access and this <xref:System.Messaging.MessageQueue> requests exclusive access), or if the application does not have sufficient rights to access it. If your application tries to write to a queue when <xref:System.Messaging.MessageQueue.CanWrite%2A> is `false`, access is denied.
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|No|
|Remote computer and direct format name|Yes|
## Examples
The following code example displays the value of a message queue's <xref:System.Messaging.MessageQueue.CanWrite%2A> property.
[!code-csharp[MessageQueue#6](~/samples/snippets/csharp/VS_Snippets_Remoting/MessageQueue/CS/class1.cs#6)]
]]></format>
</remarks>
<altmember cref="P:System.Messaging.MessageQueue.WriteHandle" />
<altmember cref="P:System.Messaging.MessageQueue.CanRead" />
</Docs>
</Member>
<Member MemberName="Category">
<MemberSignature Language="C#" Value="public Guid Category { get; set; }" />
<MemberSignature Language="ILAsm" Value=".property instance valuetype System.Guid Category" />
<MemberSignature Language="DocId" Value="P:System.Messaging.MessageQueue.Category" />
<MemberSignature Language="VB.NET" Value="Public Property Category As Guid" />
<MemberSignature Language="C++ CLI" Value="public:&#xA; property Guid Category { Guid get(); void set(Guid value); };" />
<MemberSignature Language="F#" Value="member this.Category : Guid with get, set" Usage="System.Messaging.MessageQueue.Category" />
<MemberType>Property</MemberType>
<AssemblyInfo>
<AssemblyName>System.Messaging</AssemblyName>
<AssemblyVersion>1.0.5000.0</AssemblyVersion>
<AssemblyVersion>2.0.0.0</AssemblyVersion>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
</AssemblyInfo>
<Attributes>
<Attribute FrameworkAlternate="netframework-1.1;netframework-2.0;netframework-3.0;netframework-3.5;netframework-4.0;netframework-4.5;netframework-4.5.1;netframework-4.5.2;netframework-4.6;netframework-4.6.1;netframework-4.6.2;netframework-4.7;netframework-4.7.1;netframework-4.7.2;xamarinmac-3.0;netframework-4.8">
<AttributeName>System.Messaging.MessagingDescription("MQ_Category")</AttributeName>
</Attribute>
<Attribute>
<AttributeName>System.ComponentModel.DesignerSerializationVisibility(System.ComponentModel.DesignerSerializationVisibility.Hidden)</AttributeName>
</Attribute>
</Attributes>
<ReturnValue>
<ReturnType>System.Guid</ReturnType>
</ReturnValue>
<Docs>
<summary>Gets or sets the queue category.</summary>
<value>A <see cref="T:System.Guid" /> that represents the queue category (Message Queuing type identifier), which allows an application to categorize its queues. The default is <see langword="Guid.empty" />.</value>
<remarks>
<format type="text/markdown"><![CDATA[
## Remarks
The queue category allows an application to categorize its queues. For example, you can place all Billing queues in one category and all Order queues in another.
The <xref:System.Messaging.MessageQueue.Category%2A> property provides access to the Message Queuing Type ID property (which is read/write), accessible through the **Queue Properties** dialog box in the Computer Management Console. You can define a new category. Although you can use <xref:System.Guid.NewGuid%2A> to create a category value that is unique across all <xref:System.Guid> values, such an action is unnecessary. The category value needs to be distinct only from other categories, not from all other <xref:System.Guid> values. For example, you can assign {00000000-0000-0000-0000-000000000001} as the <xref:System.Messaging.MessageQueue.Category%2A> for one set of queues and {00000000-0000-0000-0000-000000000002} as the <xref:System.Messaging.MessageQueue.Category%2A> for another set.
It is not necessary to set the <xref:System.Messaging.MessageQueue.Category%2A>. The value can be `null`.
Setting this property modifies the Message Queuing queue. Therefore, any other <xref:System.Messaging.MessageQueue> instances are affected by the change.
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|No|
|Remote computer and direct format name|No|
## Examples
The following code example gets and sets the value of a message queue's <xref:System.Messaging.MessageQueue.Category%2A> property.
[!code-csharp[MessageQueue#7](~/samples/snippets/csharp/VS_Snippets_Remoting/MessageQueue/CS/class1.cs#7)]
]]></format>
</remarks>
<exception cref="T:System.ArgumentException">The queue category was set to an invalid value.</exception>
<exception cref="T:System.Messaging.MessageQueueException">An error occurred when accessing a Message Queuing method.</exception>
<altmember cref="P:System.Messaging.MessageQueue.Id" />
<altmember cref="P:System.Messaging.MessageQueue.Label" />
<altmember cref="M:System.Messaging.MessageQueue.GetPublicQueues" />
</Docs>
</Member>
<Member MemberName="ClearConnectionCache">
<MemberSignature Language="C#" Value="public static void ClearConnectionCache ();" />
<MemberSignature Language="ILAsm" Value=".method public static hidebysig void ClearConnectionCache() cil managed" />
<MemberSignature Language="DocId" Value="M:System.Messaging.MessageQueue.ClearConnectionCache" />
<MemberSignature Language="VB.NET" Value="Public Shared Sub ClearConnectionCache ()" />
<MemberSignature Language="C++ CLI" Value="public:&#xA; static void ClearConnectionCache();" />
<MemberSignature Language="F#" Value="static member ClearConnectionCache : unit -&gt; unit" Usage="System.Messaging.MessageQueue.ClearConnectionCache " />
<MemberType>Method</MemberType>
<AssemblyInfo>
<AssemblyName>System.Messaging</AssemblyName>
<AssemblyVersion>1.0.5000.0</AssemblyVersion>
<AssemblyVersion>2.0.0.0</AssemblyVersion>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
</AssemblyInfo>
<ReturnValue>
<ReturnType>System.Void</ReturnType>
</ReturnValue>
<Parameters />
<Docs>
<summary>Clears the connection cache.</summary>
<remarks>
<format type="text/markdown"><![CDATA[
## Remarks
When you call <xref:System.Messaging.MessageQueue.ClearConnectionCache%2A>, the format names stored in the cache are removed and handles opened and stored in the cache are closed.
The following table shows whether this method 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|
## Examples
The following code example calls <xref:System.Messaging.MessageQueue.ClearConnectionCache%2A>.
[!code-csharp[MessageQueue#8](~/samples/snippets/csharp/VS_Snippets_Remoting/MessageQueue/CS/class1.cs#8)]
]]></format>
</remarks>
</Docs>
</Member>
<Member MemberName="Close">
<MemberSignature Language="C#" Value="public void Close ();" />
<MemberSignature Language="ILAsm" Value=".method public hidebysig instance void Close() cil managed" />
<MemberSignature Language="DocId" Value="M:System.Messaging.MessageQueue.Close" />
<MemberSignature Language="VB.NET" Value="Public Sub Close ()" />
<MemberSignature Language="C++ CLI" Value="public:&#xA; void Close();" />
<MemberSignature Language="F#" Value="member this.Close : unit -&gt; unit" Usage="messageQueue.Close " />
<MemberType>Method</MemberType>
<AssemblyInfo>
<AssemblyName>System.Messaging</AssemblyName>
<AssemblyVersion>1.0.5000.0</AssemblyVersion>
<AssemblyVersion>2.0.0.0</AssemblyVersion>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
</AssemblyInfo>
<ReturnValue>
<ReturnType>System.Void</ReturnType>
</ReturnValue>
<Parameters />
<Docs>
<summary>Frees all resources allocated by the <see cref="T:System.Messaging.MessageQueue" />.</summary>
<remarks>
<format type="text/markdown"><![CDATA[
## Remarks
<xref:System.Messaging.MessageQueue.Close%2A> frees all resources associated with a <xref:System.Messaging.MessageQueue>, including shared resources if appropriate. The system re-acquires these resources automatically if they are still available, for example when you call the <xref:System.Messaging.MessageQueue.Send%28System.Object%29> method, as in the following C# code.
```csharp
myMessageQueue.Send("Text 1.");
myMessageQueue.Close();
myMessageQueue.Send("Text 2."); //Resources are re-acquired.
```
When you call <xref:System.Messaging.MessageQueue.Close%2A>, all <xref:System.Messaging.MessageQueue> properties that directly access the Message Queuing queue are cleared out. The <xref:System.Messaging.MessageQueue.Path%2A>, <xref:System.Messaging.MessageQueue.DefaultPropertiesToSend%2A>, <xref:System.Messaging.MessageQueue.Formatter%2A>, and <xref:System.Messaging.MessageQueue.MessageReadPropertyFilter%2A> all remain as they were.
<xref:System.Messaging.MessageQueue.Close%2A> does not always free the read and write handles to a queue, because they might be shared. You can take any of the following steps to ensure that <xref:System.Messaging.MessageQueue.Close%2A> frees the read and write handles to a queue:
- Create the <xref:System.Messaging.MessageQueue> with exclusive access. To do so, call the <xref:System.Messaging.MessageQueue.%23ctor%28System.String%2CSystem.Boolean%29> or <xref:System.Messaging.MessageQueue.%23ctor%28System.String%2CSystem.Boolean%2CSystem.Boolean%29> constructor, and set the `sharedModeDenyReceive` parameter to `true`.
- Create the <xref:System.Messaging.MessageQueue> with connection caching disabled. To do so, call the <xref:System.Messaging.MessageQueue.%23ctor%28System.String%2CSystem.Boolean%2CSystem.Boolean%29> constructor and set the `enableConnectionCache` parameter to `false`.
- Disable connection caching. To do so, set the <xref:System.Messaging.MessageQueue.EnableConnectionCache%2A> property to `false`.
You should call <xref:System.Messaging.MessageQueue.Close%2A> for a queue before you delete the queue on the Message Queuing server. Otherwise, messages sent to the queue could throw exceptions or appear in the dead-letter queue.
The following table shows whether this method 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|
## Examples
The following code example closes a Message Queuing queue.
[!code-cpp[MessageQueue.Close#1](~/samples/snippets/cpp/VS_Snippets_Remoting/MessageQueue.Close/CPP/mqclose.cpp#1)]
[!code-csharp[MessageQueue.Close#1](~/samples/snippets/csharp/VS_Snippets_Remoting/MessageQueue.Close/CS/mqclose.cs#1)]
[!code-vb[MessageQueue.Close#1](~/samples/snippets/visualbasic/VS_Snippets_Remoting/MessageQueue.Close/VB/mqclose.vb#1)]
]]></format>
</remarks>
</Docs>
</Member>
<MemberGroup MemberName="Create">
<AssemblyInfo>
<AssemblyName>System.Messaging</AssemblyName>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
</AssemblyInfo>
<Docs>
<summary>Creates a new queue at the specified path on a Message Queuing server.</summary>
</Docs>
</MemberGroup>
<Member MemberName="Create">
<MemberSignature Language="C#" Value="public static System.Messaging.MessageQueue Create (string path);" />
<MemberSignature Language="ILAsm" Value=".method public static hidebysig class System.Messaging.MessageQueue Create(string path) cil managed" />
<MemberSignature Language="DocId" Value="M:System.Messaging.MessageQueue.Create(System.String)" />
<MemberSignature Language="VB.NET" Value="Public Shared Function Create (path As String) As MessageQueue" />
<MemberSignature Language="C++ CLI" Value="public:&#xA; static System::Messaging::MessageQueue ^ Create(System::String ^ path);" />
<MemberSignature Language="F#" Value="static member Create : string -&gt; System.Messaging.MessageQueue" Usage="System.Messaging.MessageQueue.Create path" />
<MemberType>Method</MemberType>
<AssemblyInfo>
<AssemblyName>System.Messaging</AssemblyName>
<AssemblyVersion>1.0.5000.0</AssemblyVersion>
<AssemblyVersion>2.0.0.0</AssemblyVersion>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
</AssemblyInfo>
<ReturnValue>
<ReturnType>System.Messaging.MessageQueue</ReturnType>
</ReturnValue>
<Parameters>
<Parameter Name="path" Type="System.String" />
</Parameters>
<Docs>
<param name="path">The path of the queue to create.</param>
<summary>Creates a non-transactional Message Queuing queue at the specified path.</summary>
<returns>A <see cref="T:System.Messaging.MessageQueue" /> that represents the new queue.</returns>
<remarks>
<format type="text/markdown"><![CDATA[
## Remarks
Use this overload to create a non-transactional Message Queuing queue.
To create a new instance of the <xref:System.Messaging.MessageQueue> class in your application and bind it to an existing queue, use the <xref:System.Messaging.MessageQueue.%23ctor%2A> constructor. To create a new queue in Message Queuing, call <xref:System.Messaging.MessageQueue.Create%28System.String%29>.
The syntax for 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`|
Use "." for the local computer. For more syntax, see the <xref:System.Messaging.MessageQueue.Path%2A> property.
The following table shows whether this method is available in various Workgroup modes.
|Workgroup mode|Available|
|--------------------|---------------|
|Local computer|Yes|
|Local computer and direct format name|Yes|
|Remote computer|No|
|Remote computer and direct format name|No|
## Examples
The following code example creates public and private queues. It sends a message to selected queues.
[!code-cpp[MessageQueue.Create_path#1](~/samples/snippets/cpp/VS_Snippets_Remoting/MessageQueue.Create_path/CPP/mqcreate.cpp#1)]
[!code-csharp[MessageQueue.Create_path#1](~/samples/snippets/csharp/VS_Snippets_Remoting/MessageQueue.Create_path/CS/mqcreate.cs#1)]
[!code-vb[MessageQueue.Create_path#1](~/samples/snippets/visualbasic/VS_Snippets_Remoting/MessageQueue.Create_path/VB/mqcreate.vb#1)]
]]></format>
</remarks>
<exception cref="T:System.ArgumentException">The <paramref name="path" /> parameter is <see langword="null" /> or is an empty string ("").</exception>
<exception cref="T:System.Messaging.MessageQueueException">A queue already exists at the specified path.
-or-
An error occurred when accessing a Message Queuing method.</exception>
<altmember cref="P:System.Messaging.MessageQueue.Path" />
<altmember cref="M:System.Messaging.MessageQueue.#ctor" />
</Docs>
</Member>
<Member MemberName="Create">
<MemberSignature Language="C#" Value="public static System.Messaging.MessageQueue Create (string path, bool transactional);" />
<MemberSignature Language="ILAsm" Value=".method public static hidebysig class System.Messaging.MessageQueue Create(string path, bool transactional) cil managed" />
<MemberSignature Language="DocId" Value="M:System.Messaging.MessageQueue.Create(System.String,System.Boolean)" />
<MemberSignature Language="VB.NET" Value="Public Shared Function Create (path As String, transactional As Boolean) As MessageQueue" />
<MemberSignature Language="C++ CLI" Value="public:&#xA; static System::Messaging::MessageQueue ^ Create(System::String ^ path, bool transactional);" />
<MemberSignature Language="F#" Value="static member Create : string * bool -&gt; System.Messaging.MessageQueue" Usage="System.Messaging.MessageQueue.Create (path, transactional)" />
<MemberType>Method</MemberType>
<AssemblyInfo>
<AssemblyName>System.Messaging</AssemblyName>
<AssemblyVersion>1.0.5000.0</AssemblyVersion>
<AssemblyVersion>2.0.0.0</AssemblyVersion>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
</AssemblyInfo>
<ReturnValue>
<ReturnType>System.Messaging.MessageQueue</ReturnType>
</ReturnValue>
<Parameters>
<Parameter Name="path" Type="System.String" />
<Parameter Name="transactional" Type="System.Boolean" />
</Parameters>
<Docs>
<param name="path">The path of the queue to create.</param>
<param name="transactional">
<see langword="true" /> to create a transactional queue; <see langword="false" /> to create a non-transactional queue.</param>
<summary>Creates a transactional or non-transactional Message Queuing queue at the specified path.</summary>
<returns>A <see cref="T:System.Messaging.MessageQueue" /> that represents the new queue.</returns>
<remarks>
<format type="text/markdown"><![CDATA[
## Remarks
You can use this overload to create a transactional queue in Message Queuing. You can create a non-transactional queue, by setting the `transactional` parameter to `false` or by calling the other overload of <xref:System.Messaging.MessageQueue.Create%28System.String%29>.
To create a new instance of the <xref:System.Messaging.MessageQueue> class in your application and bind it to an existing queue, use the <xref:System.Messaging.MessageQueue.%23ctor%2A> constructor. To create a new queue in Message Queuing, call <xref:System.Messaging.MessageQueue.Create%28System.String%29>.
The syntax for 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`|
Use "." for the local computer. For more syntax, see the <xref:System.Messaging.MessageQueue.Path%2A> property.
The following table shows whether this method is available in various Workgroup modes.
|Workgroup mode|Available|
|--------------------|---------------|
|Local computer|Yes|
|Local computer and direct format name|Yes|
|Remote computer|No|
|Remote computer and direct format name|No|
## Examples
The following code example creates public and private transactional queues. It sends a message to selected queues.
[!code-cpp[MessageQueue.Create_PathTransactional#1](~/samples/snippets/cpp/VS_Snippets_Remoting/MessageQueue.Create_PathTransactional/CPP/mqcreate_transactional.cpp#1)]
[!code-csharp[MessageQueue.Create_PathTransactional#1](~/samples/snippets/csharp/VS_Snippets_Remoting/MessageQueue.Create_PathTransactional/CS/mqcreate_transactional.cs#1)]
[!code-vb[MessageQueue.Create_PathTransactional#1](~/samples/snippets/visualbasic/VS_Snippets_Remoting/MessageQueue.Create_PathTransactional/VB/mqcreate_transactional.vb#1)]
]]></format>
</remarks>
<exception cref="T:System.ArgumentException">The <paramref name="path" /> parameter is <see langword="null" /> or is an empty string ("").</exception>
<exception cref="T:System.Messaging.MessageQueueException">A queue already exists at the specified path.
-or-
An error occurred when accessing a Message Queuing method.</exception>
<altmember cref="P:System.Messaging.MessageQueue.Path" />
<altmember cref="M:System.Messaging.MessageQueue.#ctor" />
<altmember cref="P:System.Messaging.MessageQueue.Transactional" />
</Docs>
</Member>
<Member MemberName="CreateCursor">
<MemberSignature Language="C#" Value="public System.Messaging.Cursor CreateCursor ();" />
<MemberSignature Language="ILAsm" Value=".method public hidebysig instance class System.Messaging.Cursor CreateCursor() cil managed" />
<MemberSignature Language="DocId" Value="M:System.Messaging.MessageQueue.CreateCursor" />
<MemberSignature Language="VB.NET" Value="Public Function CreateCursor () As Cursor" />
<MemberSignature Language="C++ CLI" Value="public:&#xA; System::Messaging::Cursor ^ CreateCursor();" />
<MemberSignature Language="F#" Value="member this.CreateCursor : unit -&gt; System.Messaging.Cursor" Usage="messageQueue.CreateCursor " />
<MemberType>Method</MemberType>
<AssemblyInfo>
<AssemblyName>System.Messaging</AssemblyName>
<AssemblyVersion>2.0.0.0</AssemblyVersion>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
</AssemblyInfo>
<ReturnValue>
<ReturnType>System.Messaging.Cursor</ReturnType>
</ReturnValue>
<Parameters />
<Docs>
<summary>Creates a new <see cref="T:System.Messaging.Cursor" /> for the current message queue.</summary>
<returns>A new <see cref="T:System.Messaging.Cursor" /> for the current message queue. This cursor is used to maintain a specific location in the queue when reading the queue's messages.</returns>
<remarks>To be added.</remarks>
<altmember cref="T:System.Messaging.Cursor" />
</Docs>
</Member>
<Member MemberName="CreateTime">
<MemberSignature Language="C#" Value="public DateTime CreateTime { get; }" />
<MemberSignature Language="ILAsm" Value=".property instance valuetype System.DateTime CreateTime" />
<MemberSignature Language="DocId" Value="P:System.Messaging.MessageQueue.CreateTime" />
<MemberSignature Language="VB.NET" Value="Public ReadOnly Property CreateTime As DateTime" />
<MemberSignature Language="C++ CLI" Value="public:&#xA; property DateTime CreateTime { DateTime get(); };" />
<MemberSignature Language="F#" Value="member this.CreateTime : DateTime" Usage="System.Messaging.MessageQueue.CreateTime" />
<MemberType>Property</MemberType>
<AssemblyInfo>
<AssemblyName>System.Messaging</AssemblyName>
<AssemblyVersion>1.0.5000.0</AssemblyVersion>
<AssemblyVersion>2.0.0.0</AssemblyVersion>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
</AssemblyInfo>
<Attributes>
<Attribute FrameworkAlternate="netframework-1.1;netframework-2.0;netframework-3.0;netframework-3.5;netframework-4.0;netframework-4.5;netframework-4.5.1;netframework-4.5.2;netframework-4.6;netframework-4.6.1;netframework-4.6.2;netframework-4.7;netframework-4.7.1;netframework-4.7.2;xamarinmac-3.0;netframework-4.8">
<AttributeName>System.Messaging.MessagingDescription("MQ_CreateTime")</AttributeName>
</Attribute>
<Attribute>
<AttributeName>System.ComponentModel.DesignerSerializationVisibility(System.ComponentModel.DesignerSerializationVisibility.Hidden)</AttributeName>
</Attribute>
</Attributes>
<ReturnValue>
<ReturnType>System.DateTime</ReturnType>
</ReturnValue>
<Docs>
<summary>Gets the time and date that the queue was created in Message Queuing.</summary>
<value>A <see cref="T:System.DateTime" /> that represents the date and time at which the queue was created.</value>
<remarks>
<format type="text/markdown"><![CDATA[
## Remarks
<xref:System.Messaging.MessageQueue.CreateTime%2A> refers to the queue on the Message Queuing server, not the <xref:System.Messaging.MessageQueue> instance.
If the queue exists, this property represents the time the queue was created, adjusted to the local time of the server on which the queue exists.
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|No|
|Remote computer and direct format name|No|
## Examples
The following code example displays the value of a message queue's <xref:System.Messaging.MessageQueue.CreateTime%2A> property.
[!code-csharp[MessageQueue#9](~/samples/snippets/csharp/VS_Snippets_Remoting/MessageQueue/CS/class1.cs#9)]
]]></format>
</remarks>
<exception cref="T:System.Messaging.MessageQueueException">An error occurred when accessing a Message Queuing method.</exception>
<altmember cref="P:System.Messaging.MessageQueue.LastModifyTime" />
</Docs>
</Member>
<Member MemberName="DefaultPropertiesToSend">
<MemberSignature Language="C#" Value="public System.Messaging.DefaultPropertiesToSend DefaultPropertiesToSend { get; set; }" />
<MemberSignature Language="ILAsm" Value=".property instance class System.Messaging.DefaultPropertiesToSend DefaultPropertiesToSend" />
<MemberSignature Language="DocId" Value="P:System.Messaging.MessageQueue.DefaultPropertiesToSend" />
<MemberSignature Language="VB.NET" Value="Public Property DefaultPropertiesToSend As DefaultPropertiesToSend" />
<MemberSignature Language="C++ CLI" Value="public:&#xA; property System::Messaging::DefaultPropertiesToSend ^ DefaultPropertiesToSend { System::Messaging::DefaultPropertiesToSend ^ get(); void set(System::Messaging::DefaultPropertiesToSend ^ value); };" />
<MemberSignature Language="F#" Value="member this.DefaultPropertiesToSend : System.Messaging.DefaultPropertiesToSend with get, set" Usage="System.Messaging.MessageQueue.DefaultPropertiesToSend" />
<MemberType>Property</MemberType>
<AssemblyInfo>
<AssemblyName>System.Messaging</AssemblyName>
<AssemblyVersion>1.0.5000.0</AssemblyVersion>
<AssemblyVersion>2.0.0.0</AssemblyVersion>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
</AssemblyInfo>
<Attributes>
<Attribute FrameworkAlternate="netframework-1.1;netframework-2.0;netframework-3.0;netframework-3.5;netframework-4.0;netframework-4.5;netframework-4.5.1;netframework-4.5.2;netframework-4.6;netframework-4.6.1;netframework-4.6.2;netframework-4.7;netframework-4.7.1;netframework-4.7.2;xamarinmac-3.0;netframework-4.8">
<AttributeName>System.ComponentModel.Browsable(false)</AttributeName>
</Attribute>
<Attribute FrameworkAlternate="netframework-1.1;netframework-2.0;netframework-3.0;netframework-3.5;netframework-4.0;netframework-4.5;netframework-4.5.1;netframework-4.5.2;netframework-4.6;netframework-4.6.1;netframework-4.6.2;netframework-4.7;netframework-4.7.1;netframework-4.7.2;xamarinmac-3.0;netframework-4.8">
<AttributeName>System.Messaging.MessagingDescription("MQ_DefaultPropertiesToSend")</AttributeName>
</Attribute>
<Attribute>
<AttributeName>System.ComponentModel.DesignerSerializationVisibility(System.ComponentModel.DesignerSerializationVisibility.Content)</AttributeName>
</Attribute>
</Attributes>
<ReturnValue>
<ReturnType>System.Messaging.DefaultPropertiesToSend</ReturnType>
</ReturnValue>
<Docs>
<summary>Gets or sets the message property values to be used by default when the application sends messages to the queue.</summary>
<value>A <see cref="T:System.Messaging.DefaultPropertiesToSend" /> that contains the default Message Queuing message property values used when the application sends objects other than <see cref="T:System.Messaging.Message" /> instances to the queue.</value>
<remarks>
<format type="text/markdown"><![CDATA[
## Remarks
When you send any object that is not of type <xref:System.Messaging.Message> to the queue, the <xref:System.Messaging.MessageQueue> inserts the object into a Message Queuing message. At that time, the <xref:System.Messaging.MessageQueue> applies to the message the property values you specify in the <xref:System.Messaging.MessageQueue.DefaultPropertiesToSend%2A> property. Conversely, if you send a <xref:System.Messaging.Message> to the queue, these properties are already specified for the instance itself, so <xref:System.Messaging.MessageQueue.DefaultPropertiesToSend%2A> is ignored for the <xref:System.Messaging.Message>.
Although you set the properties through the <xref:System.Messaging.MessageQueue> object, the <xref:System.Messaging.MessageQueue.DefaultPropertiesToSend%2A> refers to the properties of the messages that are sent to the queue, not the queue itself.
The default values for the properties are shown in the following table.
|Property|Default value|
|--------------|-------------------|
|<xref:System.Messaging.DefaultPropertiesToSend.AcknowledgeType%2A>|`AcknowledgeType.None`|
|<xref:System.Messaging.DefaultPropertiesToSend.AdministrationQueue%2A>|`null`|
|<xref:System.Messaging.DefaultPropertiesToSend.AppSpecific%2A>|Zero (0)|
|<xref:System.Messaging.DefaultPropertiesToSend.AttachSenderId%2A>|`true`|
|<xref:System.Messaging.DefaultPropertiesToSend.EncryptionAlgorithm%2A>|`EncryptionAlgorithm.RC2`|
|<xref:System.Messaging.DefaultPropertiesToSend.Extension%2A>|A zero-length array of bytes|
|<xref:System.Messaging.DefaultPropertiesToSend.HashAlgorithm%2A>|`HashAlgorithm.MD5`|
|<xref:System.Messaging.DefaultPropertiesToSend.Label%2A>|Empty string ("")|
|<xref:System.Messaging.DefaultPropertiesToSend.Priority%2A>|`MessagePriority.Normal`|
|<xref:System.Messaging.DefaultPropertiesToSend.Recoverable%2A>|`false`|
|<xref:System.Messaging.DefaultPropertiesToSend.ResponseQueue%2A>|`null`|
|<xref:System.Messaging.DefaultPropertiesToSend.TimeToBeReceived%2A>|`Message.InfiniteTimeout`|
|<xref:System.Messaging.DefaultPropertiesToSend.TimeToReachQueue%2A>|`Message.InfiniteTimeout`|
|<xref:System.Messaging.DefaultPropertiesToSend.TransactionStatusQueue%2A>|`null`|
|<xref:System.Messaging.DefaultPropertiesToSend.UseAuthentication%2A>|`false`|
|<xref:System.Messaging.DefaultPropertiesToSend.UseDeadLetterQueue%2A>|`false`|
|<xref:System.Messaging.DefaultPropertiesToSend.UseEncryption%2A>|`false`|
|<xref:System.Messaging.DefaultPropertiesToSend.UseJournalQueue%2A>|`false`|
|<xref:System.Messaging.DefaultPropertiesToSend.UseTracing%2A>|`false`|
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|
## Examples
The following code example uses the priority of a message to determine default properties to send for the message.
[!code-cpp[MessageQueue.DefaultPropertiesToSend#1](~/samples/snippets/cpp/VS_Snippets_Remoting/MessageQueue.DefaultPropertiesToSend/CPP/mqdefaultpropertiestosend.cpp#1)]
[!code-csharp[MessageQueue.DefaultPropertiesToSend#1](~/samples/snippets/csharp/VS_Snippets_Remoting/MessageQueue.DefaultPropertiesToSend/CS/mqdefaultpropertiestosend.cs#1)]
[!code-vb[MessageQueue.DefaultPropertiesToSend#1](~/samples/snippets/visualbasic/VS_Snippets_Remoting/MessageQueue.DefaultPropertiesToSend/VB/mqdefaultpropertiestosend.vb#1)]
]]></format>
</remarks>
<exception cref="T:System.ArgumentException">The default properties could not be set for the queue, possibly because one of the properties is not valid.</exception>
<altmember cref="T:System.Messaging.Message" />
<altmember cref="T:System.Messaging.AcknowledgeTypes" />
<altmember cref="T:System.Messaging.EncryptionAlgorithm" />
<altmember cref="T:System.Messaging.HashAlgorithm" />
<altmember cref="F:System.Messaging.Message.InfiniteTimeout" />
</Docs>
</Member>
<Member MemberName="Delete">
<MemberSignature Language="C#" Value="public static void Delete (string path);" />
<MemberSignature Language="ILAsm" Value=".method public static hidebysig void Delete(string path) cil managed" />
<MemberSignature Language="DocId" Value="M:System.Messaging.MessageQueue.Delete(System.String)" />
<MemberSignature Language="VB.NET" Value="Public Shared Sub Delete (path As String)" />
<MemberSignature Language="C++ CLI" Value="public:&#xA; static void Delete(System::String ^ path);" />
<MemberSignature Language="F#" Value="static member Delete : string -&gt; unit" Usage="System.Messaging.MessageQueue.Delete path" />
<MemberType>Method</MemberType>
<AssemblyInfo>
<AssemblyName>System.Messaging</AssemblyName>
<AssemblyVersion>1.0.5000.0</AssemblyVersion>
<AssemblyVersion>2.0.0.0</AssemblyVersion>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
</AssemblyInfo>
<ReturnValue>
<ReturnType>System.Void</ReturnType>
</ReturnValue>
<Parameters>
<Parameter Name="path" Type="System.String" />
</Parameters>
<Docs>
<param name="path">The location of the queue to be deleted.</param>
<summary>Deletes a queue on a Message Queuing server.</summary>
<remarks>
<format type="text/markdown"><![CDATA[
## Remarks
The syntax for the `path` parameter depends on the type of queue.
|Queue type|Syntax|
|----------------|------------|
|Public queue|`MachineName`\\`QueueName`|
|Private queue|`MachineName`\\`Private$`\\`QueueName`|
For more syntax, see the <xref:System.Messaging.MessageQueue.Path%2A> property.
Alternatively, you can use the <xref:System.Messaging.MessageQueue.FormatName%2A> or <xref:System.Messaging.MessageQueue.Label%2A> to describe the queue path.
|Reference|Syntax|
|---------------|------------|
|Format name|FormatName:[ *format name* ]|
|Label|Label:[ *label* ]|
The following table shows whether this method is available in various Workgroup modes.
|Workgroup mode|Available|
|--------------------|---------------|
|Local computer|Yes|
|Local computer and direct format name|Yes|
|Remote computer|No|
|Remote computer and direct format name|No|
## Examples
The following code example deletes a Message Queuing queue, if it exists.
[!code-cpp[MessageQueue.ExistsDelete#1](~/samples/snippets/cpp/VS_Snippets_Remoting/MessageQueue.ExistsDelete/CPP/mqexistsdelete.cpp#1)]
[!code-csharp[MessageQueue.ExistsDelete#1](~/samples/snippets/csharp/VS_Snippets_Remoting/MessageQueue.ExistsDelete/CS/mqexistsdelete.cs#1)]
[!code-vb[MessageQueue.ExistsDelete#1](~/samples/snippets/visualbasic/VS_Snippets_Remoting/MessageQueue.ExistsDelete/VB/mqexistsdelete.vb#1)]
]]></format>
</remarks>
<exception cref="T:System.ArgumentException">The <paramref name="path" /> parameter is <see langword="null" /> or is an empty string ("").</exception>
<exception cref="T:System.Messaging.MessageQueueException">The syntax for the <paramref name="path" /> parameter is not valid.
-or-
An error occurred when accessing a Message Queuing method.</exception>
<altmember cref="M:System.Messaging.MessageQueue.Close" />
<altmember cref="P:System.Messaging.MessageQueue.Path" />
</Docs>
</Member>
<Member MemberName="DenySharedReceive">
<MemberSignature Language="C#" Value="public bool DenySharedReceive { get; set; }" />
<MemberSignature Language="ILAsm" Value=".property instance bool DenySharedReceive" />
<MemberSignature Language="DocId" Value="P:System.Messaging.MessageQueue.DenySharedReceive" />
<MemberSignature Language="VB.NET" Value="Public Property DenySharedReceive As Boolean" />
<MemberSignature Language="C++ CLI" Value="public:&#xA; property bool DenySharedReceive { bool get(); void set(bool value); };" />
<MemberSignature Language="F#" Value="member this.DenySharedReceive : bool with get, set" Usage="System.Messaging.MessageQueue.DenySharedReceive" />
<MemberType>Property</MemberType>
<AssemblyInfo>
<AssemblyName>System.Messaging</AssemblyName>
<AssemblyVersion>1.0.5000.0</AssemblyVersion>
<AssemblyVersion>2.0.0.0</AssemblyVersion>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
</AssemblyInfo>
<Attributes>
<Attribute FrameworkAlternate="netframework-1.1;netframework-2.0;netframework-3.0;netframework-3.5;netframework-4.0;netframework-4.5;netframework-4.5.1;netframework-4.5.2;netframework-4.6;netframework-4.6.1;netframework-4.6.2;netframework-4.7;netframework-4.7.1;netframework-4.7.2;xamarinmac-3.0;netframework-4.8">
<AttributeName>System.ComponentModel.Browsable(false)</AttributeName>
</Attribute>
<Attribute FrameworkAlternate="netframework-1.1;netframework-2.0;netframework-3.0;netframework-3.5;netframework-4.0;netframework-4.5;netframework-4.5.1;netframework-4.5.2;netframework-4.6;netframework-4.6.1;netframework-4.6.2;netframework-4.7;netframework-4.7.1;netframework-4.7.2;xamarinmac-3.0;netframework-4.8">
<AttributeName>System.ComponentModel.DefaultValue(false)</AttributeName>
</Attribute>
<Attribute FrameworkAlternate="netframework-1.1;netframework-2.0;netframework-3.0;netframework-3.5;netframework-4.0;netframework-4.5;netframework-4.5.1;netframework-4.5.2;netframework-4.6;netframework-4.6.1;netframework-4.6.2;netframework-4.7;netframework-4.7.1;netframework-4.7.2;xamarinmac-3.0;netframework-4.8">
<AttributeName>System.Messaging.MessagingDescription("MQ_DenySharedReceive")</AttributeName>
</Attribute>
</Attributes>
<ReturnValue>
<ReturnType>System.Boolean</ReturnType>
</ReturnValue>
<Docs>
<summary>Gets or sets a value that indicates whether this <see cref="T:System.Messaging.MessageQueue" /> has exclusive access to receive messages from the Message Queuing queue.</summary>
<value>
<see langword="true" /> if this <see cref="T:System.Messaging.MessageQueue" /> has exclusive rights to receive messages from the queue; otherwise, <see langword="false" />. The default is <see langword="false" />.</value>
<remarks>
<format type="text/markdown"><![CDATA[
## Remarks
<xref:System.Messaging.MessageQueue.DenySharedReceive%2A> specifies the shared mode of the queue referenced by this <xref:System.Messaging.MessageQueue>. Set <xref:System.Messaging.MessageQueue.DenySharedReceive%2A> to `true` to indicate that only this <xref:System.Messaging.MessageQueue> should have access to peek or receive messages from the queue with the specified <xref:System.Messaging.MessageQueue.Path%2A>. If another <xref:System.Messaging.MessageQueue> or another application is associated with the same queue resource, that instance or application will not be able to peek or receive messages, but it can still send them.
If <xref:System.Messaging.MessageQueue.DenySharedReceive%2A> is `false`, the queue is available to multiple applications for sending, peeking, or receiving messages.
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|
## Examples
The following code example gets and sets the value of a message queue's <xref:System.Messaging.MessageQueue.DenySharedReceive%2A> property.
[!code-csharp[MessageQueue#10](~/samples/snippets/csharp/VS_Snippets_Remoting/MessageQueue/CS/class1.cs#10)]
]]></format>
</remarks>
<altmember cref="M:System.Messaging.MessageQueue.#ctor" />
<altmember cref="P:System.Messaging.MessageQueue.EnableConnectionCache" />
</Docs>
</Member>
<Member MemberName="Dispose">
<MemberSignature Language="C#" Value="protected override void Dispose (bool disposing);" />
<MemberSignature Language="ILAsm" Value=".method familyhidebysig virtual instance void Dispose(bool disposing) cil managed" />
<MemberSignature Language="DocId" Value="M:System.Messaging.MessageQueue.Dispose(System.Boolean)" />
<MemberSignature Language="VB.NET" Value="Protected Overrides Sub Dispose (disposing As Boolean)" />
<MemberSignature Language="C++ CLI" Value="protected:&#xA; override void Dispose(bool disposing);" />
<MemberSignature Language="F#" Value="override this.Dispose : bool -&gt; unit" Usage="messageQueue.Dispose disposing" />
<MemberType>Method</MemberType>
<AssemblyInfo>
<AssemblyName>System.Messaging</AssemblyName>
<AssemblyVersion>1.0.5000.0</AssemblyVersion>
<AssemblyVersion>2.0.0.0</AssemblyVersion>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
</AssemblyInfo>
<ReturnValue>
<ReturnType>System.Void</ReturnType>
</ReturnValue>
<Parameters>
<Parameter Name="disposing" Type="System.Boolean" />
</Parameters>
<Docs>
<param name="disposing">
<see langword="true" /> to release both managed and unmanaged resources; <see langword="false" /> to release only unmanaged resources.</param>
<summary>Disposes of the resources (other than memory) used by the <see cref="T:System.Messaging.MessageQueue" />.</summary>
<remarks>
<format type="text/markdown"><![CDATA[
## Remarks
Call <xref:System.Messaging.MessageQueue.Dispose%28System.Boolean%29> when you are finished using the <xref:System.Messaging.MessageQueue>. The <xref:System.Messaging.MessageQueue.Dispose%28System.Boolean%29> method leaves the <xref:System.Messaging.MessageQueue> in an unusable state. After calling <xref:System.Messaging.MessageQueue.Dispose%28System.Boolean%29>, you must release all references to the <xref:System.Messaging.MessageQueue> so the memory it was occupying can be reclaimed by garbage collection.
You should call <xref:System.Messaging.MessageQueue.Dispose%28System.Boolean%29> before you release your last reference to the <xref:System.Messaging.MessageQueue>. Otherwise, the resources the <xref:System.Messaging.MessageQueue> is using will not be freed until garbage collection calls the <xref:System.Messaging.MessageQueue> object's destructor.
]]></format>
</remarks>
<altmember cref="M:System.Messaging.MessageQueue.Close" />
</Docs>
</Member>
<Member MemberName="EnableConnectionCache">
<MemberSignature Language="C#" Value="public static bool EnableConnectionCache { get; set; }" />
<MemberSignature Language="ILAsm" Value=".property bool EnableConnectionCache" />
<MemberSignature Language="DocId" Value="P:System.Messaging.MessageQueue.EnableConnectionCache" />
<MemberSignature Language="VB.NET" Value="Public Shared Property EnableConnectionCache As Boolean" />
<MemberSignature Language="C++ CLI" Value="public:&#xA; static property bool EnableConnectionCache { bool get(); void set(bool value); };" />
<MemberSignature Language="F#" Value="member this.EnableConnectionCache : bool with get, set" Usage="System.Messaging.MessageQueue.EnableConnectionCache" />
<MemberType>Property</MemberType>
<AssemblyInfo>
<AssemblyName>System.Messaging</AssemblyName>
<AssemblyVersion>1.0.5000.0</AssemblyVersion>
<AssemblyVersion>2.0.0.0</AssemblyVersion>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
</AssemblyInfo>
<Attributes>
<Attribute FrameworkAlternate="netframework-1.1;netframework-2.0;netframework-3.0;netframework-3.5;netframework-4.0;netframework-4.5;netframework-4.5.1;netframework-4.5.2;netframework-4.6;netframework-4.6.1;netframework-4.6.2;netframework-4.7;netframework-4.7.1;netframework-4.7.2;xamarinmac-3.0;netframework-4.8">
<AttributeName>System.ComponentModel.Browsable(false)</AttributeName>
</Attribute>
</Attributes>
<ReturnValue>
<ReturnType>System.Boolean</ReturnType>
</ReturnValue>
<Docs>
<summary>Gets or sets a value that indicates whether a cache of connections will be maintained by the application.</summary>
<value>
<see langword="true" /> to create and use a connection cache; otherwise, <see langword="false" />.</value>
<remarks>
<format type="text/markdown"><![CDATA[
## Remarks
A connection cache is a list of references to structures that contain read or write handles to queues. When <xref:System.Messaging.MessageQueue.EnableConnectionCache%2A> is `true`, the <xref:System.Messaging.MessageQueue> borrows handles from the cache each time you call <xref:System.Messaging.MessageQueue.Send%28System.Object%29>, <xref:System.Messaging.MessageQueue.Peek%2A>, or <xref:System.Messaging.MessageQueue.Receive%2A>, rather than open new handles. This can improve performance. Using a connection cache also insulates the <xref:System.Messaging.MessageQueue> from changes in the network topology.
If you create a new connection to a queue when the connection cache is full, the <xref:System.Messaging.MessageQueue> overwrites the least recently accessed structure with the new connection. You can clear the cache entirely by calling <xref:System.Messaging.MessageQueue.ClearConnectionCache%2A>, for example, if the format names of the queues you are working with have changed so that the previous read and write handles are no longer valid.
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|
## Examples
The following code example gets and sets the value of a message queue's <xref:System.Messaging.MessageQueue.EnableConnectionCache%2A> property.
[!code-csharp[MessageQueue#11](~/samples/snippets/csharp/VS_Snippets_Remoting/MessageQueue/CS/class1.cs#11)]
]]></format>
</remarks>
<altmember cref="M:System.Messaging.MessageQueue.ClearConnectionCache" />
</Docs>
</Member>
<Member MemberName="EncryptionRequired">
<MemberSignature Language="C#" Value="public System.Messaging.EncryptionRequired EncryptionRequired { get; set; }" />
<MemberSignature Language="ILAsm" Value=".property instance valuetype System.Messaging.EncryptionRequired EncryptionRequired" />
<MemberSignature Language="DocId" Value="P:System.Messaging.MessageQueue.EncryptionRequired" />
<MemberSignature Language="VB.NET" Value="Public Property EncryptionRequired As EncryptionRequired" />
<MemberSignature Language="C++ CLI" Value="public:&#xA; property System::Messaging::EncryptionRequired EncryptionRequired { System::Messaging::EncryptionRequired get(); void set(System::Messaging::EncryptionRequired value); };" />
<MemberSignature Language="F#" Value="member this.EncryptionRequired : System.Messaging.EncryptionRequired with get, set" Usage="System.Messaging.MessageQueue.EncryptionRequired" />
<MemberType>Property</MemberType>
<AssemblyInfo>
<AssemblyName>System.Messaging</AssemblyName>
<AssemblyVersion>1.0.5000.0</AssemblyVersion>
<AssemblyVersion>2.0.0.0</AssemblyVersion>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
</AssemblyInfo>
<Attributes>
<Attribute FrameworkAlternate="netframework-1.1;netframework-2.0;netframework-3.0;netframework-3.5;netframework-4.0;netframework-4.5;netframework-4.5.1;netframework-4.5.2;netframework-4.6;netframework-4.6.1;netframework-4.6.2;netframework-4.7;netframework-4.7.1;netframework-4.7.2;xamarinmac-3.0;netframework-4.8">
<AttributeName>System.Messaging.MessagingDescription("MQ_EncryptionRequired")</AttributeName>
</Attribute>
<Attribute>
<AttributeName>System.ComponentModel.DesignerSerializationVisibility(System.ComponentModel.DesignerSerializationVisibility.Hidden)</AttributeName>
</Attribute>
</Attributes>
<ReturnValue>
<ReturnType>System.Messaging.EncryptionRequired</ReturnType>
</ReturnValue>
<Docs>
<summary>Gets or sets a value that indicates whether the queue accepts only non-private (non-encrypted) messages.</summary>
<value>One of the <see cref="T:System.Messaging.EncryptionRequired" /> values. The default is <see langword="None" />.</value>
<remarks>
<format type="text/markdown"><![CDATA[
## Remarks
When you specify that encryption is required for the messages sent to a queue, only the message bodies are encrypted. The other members (for example, the <xref:System.Messaging.Message.Label%2A> and <xref:System.Messaging.Message.SenderId%2A> properties) cannot be encrypted.
Setting this property modifies the Message Queuing queue. Therefore, any other <xref:System.Messaging.MessageQueue> instances are affected by the change.
Encrypting a message makes the message private. You can specify the queue's encryption requirement to be `None`, `Body`, or `Optional` by setting the <xref:System.Messaging.MessageQueue.EncryptionRequired%2A> property appropriately. The <xref:System.Messaging.Message.UseEncryption%2A> setting of the message must correspond to the encryption requirement of the queue. If the message is not encrypted but the queue specifies `Body`, or if the message is encrypted but the queue specifies `None`, the message is rejected by the queue. If the sending application requests a negative acknowledgment message in this event, Message Queuing indicates the message's rejection to the sending application. If the <xref:System.Messaging.Message.UseDeadLetterQueue%2A> property is `true`, a message that fails encryption is sent to the dead-letter queue. Otherwise, the message is lost.
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|No|
|Remote computer and direct format name|No|
## Examples
The following code example gets and sets the value of a message queue's <xref:System.Messaging.MessageQueue.EncryptionRequired%2A> property.
[!code-csharp[MessageQueue#12](~/samples/snippets/csharp/VS_Snippets_Remoting/MessageQueue/CS/class1.cs#12)]
]]></format>
</remarks>
<exception cref="T:System.Messaging.MessageQueueException">An error occurred when accessing a Message Queuing method.</exception>
<altmember cref="T:System.Messaging.Acknowledgment" />
<altmember cref="P:System.Messaging.Message.UseEncryption" />
</Docs>
</Member>
<Member MemberName="EndPeek">
<MemberSignature Language="C#" Value="public System.Messaging.Message EndPeek (IAsyncResult asyncResult);" />
<MemberSignature Language="ILAsm" Value=".method public hidebysig instance class System.Messaging.Message EndPeek(class System.IAsyncResult asyncResult) cil managed" />
<MemberSignature Language="DocId" Value="M:System.Messaging.MessageQueue.EndPeek(System.IAsyncResult)" />
<MemberSignature Language="VB.NET" Value="Public Function EndPeek (asyncResult As IAsyncResult) As Message" />
<MemberSignature Language="C++ CLI" Value="public:&#xA; System::Messaging::Message ^ EndPeek(IAsyncResult ^ asyncResult);" />
<MemberSignature Language="F#" Value="member this.EndPeek : IAsyncResult -&gt; System.Messaging.Message" Usage="messageQueue.EndPeek asyncResult" />
<MemberType>Method</MemberType>
<AssemblyInfo>
<AssemblyName>System.Messaging</AssemblyName>
<AssemblyVersion>1.0.5000.0</AssemblyVersion>
<AssemblyVersion>2.0.0.0</AssemblyVersion>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
</AssemblyInfo>
<ReturnValue>
<ReturnType>System.Messaging.Message</ReturnType>
</ReturnValue>
<Parameters>
<Parameter Name="asyncResult" Type="System.IAsyncResult" />
</Parameters>
<Docs>
<param name="asyncResult">The <see cref="T:System.IAsyncResult" /> that identifies the asynchronous peek operation to finish and from which to retrieve an end result.</param>
<summary>Completes the specified asynchronous peek operation.</summary>
<returns>The <see cref="T:System.Messaging.Message" /> associated with the completed asynchronous operation.</returns>
<remarks>
<format type="text/markdown"><![CDATA[
## Remarks
When the <xref:System.Messaging.MessageQueue.PeekCompleted> event is raised, <xref:System.Messaging.MessageQueue.EndPeek%28System.IAsyncResult%29> completes the operation that was initiated by the <xref:System.Messaging.MessageQueue.BeginPeek%2A> call. To do so, <xref:System.Messaging.MessageQueue.EndPeek%28System.IAsyncResult%29> peeks the message.
<xref:System.Messaging.MessageQueue.BeginPeek%2A> can specify a time-out, which causes the <xref:System.Messaging.MessageQueue.PeekCompleted> event to be raised if the time-out occurs before a message appears in the queue. When a time-out occurs without a message arriving in the queue, a subsequent call to <xref:System.Messaging.MessageQueue.EndPeek%28System.IAsyncResult%29> throws an exception.
<xref:System.Messaging.MessageQueue.EndPeek%28System.IAsyncResult%29> is used to read the message that caused the <xref:System.Messaging.MessageQueue.PeekCompleted> event to be raised.
If you want to continue to asynchronously peek messages, you can again call <xref:System.Messaging.MessageQueue.BeginPeek%2A> after calling <xref:System.Messaging.MessageQueue.EndPeek%28System.IAsyncResult%29>.
The following table shows whether this method is available in various Workgroup modes.
|Workgroup mode|Available|
|--------------------|---------------|
|Local computer|Yes|
|Local computer and direct format name|Yes|
|Remote computer|No|
|Remote computer and direct format name|Yes|
## Examples
The following code example creates an event handler named `MyPeekCompleted`, attaches it to the <xref:System.Messaging.MessageQueue.PeekCompleted> event handler delegate, and calls <xref:System.Messaging.MessageQueue.BeginPeek%2A> to initiate an asynchronous peek operation on the queue that is located at the path ".\myQueue". When a <xref:System.Messaging.MessageQueue.PeekCompleted> event is raised, the example peeks the message and writes its body to the screen. The example then calls <xref:System.Messaging.MessageQueue.BeginPeek%2A> again to initiate a new asynchronous peek operation.
[!code-cpp[MessageQueue.BeginPeek_noparms#1](~/samples/snippets/cpp/VS_Snippets_Remoting/MessageQueue.BeginPeek_noparms/CPP/mqbeginpeek_noparms.cpp#1)]
[!code-csharp[MessageQueue.BeginPeek_noparms#1](~/samples/snippets/csharp/VS_Snippets_Remoting/MessageQueue.BeginPeek_noparms/CS/mqbeginpeek_noparms.cs#1)]
[!code-vb[MessageQueue.BeginPeek_noparms#1](~/samples/snippets/visualbasic/VS_Snippets_Remoting/MessageQueue.BeginPeek_noparms/VB/mqbeginpeek_noparms.vb#1)]
]]></format>
</remarks>
<exception cref="T:System.ArgumentNullException">The <paramref name="asyncResult" /> parameter is <see langword="null" />.</exception>
<exception cref="T:System.ArgumentException">The syntax of the <paramref name="asyncResult" /> parameter is not valid.</exception>
<exception cref="T:System.Messaging.MessageQueueException">An error occurred when accessing a Message Queuing method.</exception>
<altmember cref="M:System.Messaging.MessageQueue.BeginPeek" />
<altmember cref="E:System.Messaging.MessageQueue.PeekCompleted" />
</Docs>
</Member>
<Member MemberName="EndReceive">
<MemberSignature Language="C#" Value="public System.Messaging.Message EndReceive (IAsyncResult asyncResult);" />
<MemberSignature Language="ILAsm" Value=".method public hidebysig instance class System.Messaging.Message EndReceive(class System.IAsyncResult asyncResult) cil managed" />
<MemberSignature Language="DocId" Value="M:System.Messaging.MessageQueue.EndReceive(System.IAsyncResult)" />
<MemberSignature Language="VB.NET" Value="Public Function EndReceive (asyncResult As IAsyncResult) As Message" />
<MemberSignature Language="C++ CLI" Value="public:&#xA; System::Messaging::Message ^ EndReceive(IAsyncResult ^ asyncResult);" />
<MemberSignature Language="F#" Value="member this.EndReceive : IAsyncResult -&gt; System.Messaging.Message" Usage="messageQueue.EndReceive asyncResult" />
<MemberType>Method</MemberType>
<AssemblyInfo>
<AssemblyName>System.Messaging</AssemblyName>
<AssemblyVersion>1.0.5000.0</AssemblyVersion>
<AssemblyVersion>2.0.0.0</AssemblyVersion>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
</AssemblyInfo>
<ReturnValue>
<ReturnType>System.Messaging.Message</ReturnType>
</ReturnValue>
<Parameters>
<Parameter Name="asyncResult" Type="System.IAsyncResult" />
</Parameters>
<Docs>
<param name="asyncResult">The <see cref="T:System.IAsyncResult" /> that identifies the asynchronous receive operation to finish and from which to retrieve an end result.</param>
<summary>Completes the specified asynchronous receive operation.</summary>
<returns>The <see cref="T:System.Messaging.Message" /> associated with the completed asynchronous operation.</returns>
<remarks>
<format type="text/markdown"><![CDATA[
## Remarks
When the <xref:System.Messaging.MessageQueue.ReceiveCompleted> event is raised, <xref:System.Messaging.MessageQueue.EndReceive%28System.IAsyncResult%29> completes the operation that was initiated by the <xref:System.Messaging.MessageQueue.BeginReceive%2A> call. To do so, <xref:System.Messaging.MessageQueue.EndReceive%28System.IAsyncResult%29> receives the message.
<xref:System.Messaging.MessageQueue.BeginReceive%2A> can specify a time-out, which causes the <xref:System.Messaging.MessageQueue.ReceiveCompleted> event to be raised if the time-out occurs before a message appears in the queue. When a time-out occurs without a message arriving in the queue, a subsequent call to <xref:System.Messaging.MessageQueue.EndReceive%28System.IAsyncResult%29> throws an exception.
<xref:System.Messaging.MessageQueue.EndReceive%28System.IAsyncResult%29> is used to read (removing from the queue) the message that caused the <xref:System.Messaging.MessageQueue.ReceiveCompleted> event to be raised.
If you want to continue to asynchronously receive messages, you can again call <xref:System.Messaging.MessageQueue.BeginReceive%2A> after calling <xref:System.Messaging.MessageQueue.EndReceive%28System.IAsyncResult%29>.
The following table shows whether this method is available in various Workgroup modes.
|Workgroup mode|Available|
|--------------------|---------------|
|Local computer|Yes|
|Local computer and direct format name|Yes|
|Remote computer|No|
|Remote computer and direct format name|Yes|
## Examples
The following code example chains asynchronous requests. It assumes there is a queue on the local computer called "myQueue". The `Main` function begins the asynchronous operation that is handled by the `MyReceiveCompleted` routine. `MyReceiveCompleted` processes the current message and begins a new asynchronous receive operation.
[!code-cpp[MessageQueue.BeginReceive_noparms_combined#1](~/samples/snippets/cpp/VS_Snippets_Remoting/MessageQueue.BeginReceive_noparms_combined/CPP/mqbeginreceive_noparms_mre.cpp#1)]
[!code-csharp[MessageQueue.BeginReceive_noparms_combined#1](~/samples/snippets/csharp/VS_Snippets_Remoting/MessageQueue.BeginReceive_noparms_combined/CS/mqbeginreceive_noparms_mre.cs#1)]
[!code-vb[MessageQueue.BeginReceive_noparms_combined#1](~/samples/snippets/visualbasic/VS_Snippets_Remoting/MessageQueue.BeginReceive_noparms_combined/VB/mqbeginreceive_noparms_mre.vb#1)]
]]></format>
</remarks>
<exception cref="T:System.ArgumentNullException">The <paramref name="asyncResult" /> parameter is <see langword="null" />.</exception>
<exception cref="T:System.ArgumentException">The syntax of the <paramref name="asyncResult" /> parameter is not valid.</exception>
<exception cref="T:System.Messaging.MessageQueueException">An error occurred when accessing a Message Queuing method.</exception>
<altmember cref="M:System.Messaging.MessageQueue.BeginReceive" />
<altmember cref="E:System.Messaging.MessageQueue.ReceiveCompleted" />
</Docs>
</Member>
<Member MemberName="Exists">
<MemberSignature Language="C#" Value="public static bool Exists (string path);" />
<MemberSignature Language="ILAsm" Value=".method public static hidebysig bool Exists(string path) cil managed" />
<MemberSignature Language="DocId" Value="M:System.Messaging.MessageQueue.Exists(System.String)" />
<MemberSignature Language="VB.NET" Value="Public Shared Function Exists (path As String) As Boolean" />
<MemberSignature Language="C++ CLI" Value="public:&#xA; static bool Exists(System::String ^ path);" />
<MemberSignature Language="F#" Value="static member Exists : string -&gt; bool" Usage="System.Messaging.MessageQueue.Exists path" />
<MemberType>Method</MemberType>
<AssemblyInfo>
<AssemblyName>System.Messaging</AssemblyName>
<AssemblyVersion>1.0.5000.0</AssemblyVersion>
<AssemblyVersion>2.0.0.0</AssemblyVersion>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
</AssemblyInfo>
<ReturnValue>
<ReturnType>System.Boolean</ReturnType>
</ReturnValue>
<Parameters>
<Parameter Name="path" Type="System.String" />
</Parameters>
<Docs>
<param name="path">The location of the queue to find.</param>
<summary>Determines whether a Message Queuing queue exists at the specified path.</summary>
<returns>
<see langword="true" /> if a queue with the specified path exists; otherwise, <see langword="false" />.</returns>
<remarks>
<format type="text/markdown"><![CDATA[
## Remarks
The <xref:System.Messaging.MessageQueue.Exists%28System.String%29> method determines whether a Message Queuing queue exists at a specified path. No method exists to determine whether a queue with a specified format name exists. For more information about the format name syntax and other path syntax forms, see the <xref:System.Messaging.MessageQueue.Path%2A> property.)
<xref:System.Messaging.MessageQueue.Exists%28System.String%29> is an expensive operation. Use it only when it is necessary within the application.
> [!NOTE]
> The <xref:System.Messaging.MessageQueue.Exists%28System.String%29> method does not support the <xref:System.Messaging.MessageQueue.FormatName%2A> prefix.
The syntax for the `path` parameter depends on the type of queue, as shown in the following table.
|Queue type|Syntax|
|----------------|------------|
|Public queue|`MachineName`\\`QueueName`|
<xref:System.Messaging.MessageQueue.Exists%28System.String%29> cannot be called to verify the existence of a remote private queue.
For more syntax, see the <xref:System.Messaging.MessageQueue.Path%2A> property.
Alternatively, you can use the <xref:System.Messaging.MessageQueue.Label%2A> to describe the queue path.
|Reference|Syntax|
|---------------|------------|
|Label|Label:[ `label` ]|
The following table shows whether this method is available in various Workgroup modes.
|Workgroup mode|Available|
|--------------------|---------------|
|Local computer|Yes|
|Local computer and direct format name|No|
|Remote computer|No|
|Remote computer and direct format name|No|
## Examples
The following code example verifies whether a Message Queuing queue exists, and then deletes it.
[!code-cpp[MessageQueue.ExistsDelete#1](~/samples/snippets/cpp/VS_Snippets_Remoting/MessageQueue.ExistsDelete/CPP/mqexistsdelete.cpp#1)]
[!code-csharp[MessageQueue.ExistsDelete#1](~/samples/snippets/csharp/VS_Snippets_Remoting/MessageQueue.ExistsDelete/CS/mqexistsdelete.cs#1)]
[!code-vb[MessageQueue.ExistsDelete#1](~/samples/snippets/visualbasic/VS_Snippets_Remoting/MessageQueue.ExistsDelete/VB/mqexistsdelete.vb#1)]
]]></format>
</remarks>
<exception cref="T:System.ArgumentException">The <paramref name="path" /> syntax is not valid.</exception>
<exception cref="T:System.Messaging.MessageQueueException">An error occurred when accessing a Message Queuing method.
-or-
The <see cref="M:System.Messaging.MessageQueue.Exists(System.String)" /> method is being called on a remote private queue</exception>
<exception cref="T:System.InvalidOperationException">The application used format name syntax when verifying queue existence.</exception>
<altmember cref="P:System.Messaging.MessageQueue.Path" />
</Docs>
</Member>
<Member MemberName="FormatName">
<MemberSignature Language="C#" Value="public string FormatName { get; }" />
<MemberSignature Language="ILAsm" Value=".property instance string FormatName" />
<MemberSignature Language="DocId" Value="P:System.Messaging.MessageQueue.FormatName" />
<MemberSignature Language="VB.NET" Value="Public ReadOnly Property FormatName As String" />
<MemberSignature Language="C++ CLI" Value="public:&#xA; property System::String ^ FormatName { System::String ^ get(); };" />
<MemberSignature Language="F#" Value="member this.FormatName : string" Usage="System.Messaging.MessageQueue.FormatName" />
<MemberType>Property</MemberType>
<AssemblyInfo>
<AssemblyName>System.Messaging</AssemblyName>
<AssemblyVersion>1.0.5000.0</AssemblyVersion>
<AssemblyVersion>2.0.0.0</AssemblyVersion>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
</AssemblyInfo>
<Attributes>
<Attribute FrameworkAlternate="netframework-1.1;netframework-2.0;netframework-3.0;netframework-3.5;netframework-4.0;netframework-4.5;netframework-4.5.1;netframework-4.5.2;netframework-4.6;netframework-4.6.1;netframework-4.6.2;netframework-4.7;netframework-4.7.1;netframework-4.7.2;xamarinmac-3.0;netframework-4.8">
<AttributeName>System.Messaging.MessagingDescription("MQ_FormatName")</AttributeName>
</Attribute>
<Attribute>
<AttributeName>System.ComponentModel.DesignerSerializationVisibility(System.ComponentModel.DesignerSerializationVisibility.Hidden)</AttributeName>
</Attribute>
</Attributes>
<ReturnValue>
<ReturnType>System.String</ReturnType>
</ReturnValue>
<Docs>
<summary>Gets the unique queue name that Message Queuing generated at the time of the queue's creation.</summary>
<value>The name for the queue, which is unique on the network.</value>
<remarks>
<format type="text/markdown"><![CDATA[
## Remarks
The <xref:System.Messaging.MessageQueue.FormatName%2A> property contains the format name of the queue. Message Queuing uses the format name to identify which queue to open and how to access it. Unlike most of a queue's characteristics, the format name is not a Message Queuing application queue property, so you cannot access it through the Message Queuing management tool. The format name is simply a unique name for the queue, which Message Queuing generates when it creates the queue or which the application generates later.
If you specify a path using the path name syntax (such as `myComputer\myQueue`) rather than using the format name syntax when you read or write to the queue, the primary domain controller (which uses Active Directory) translates the <xref:System.Messaging.MessageQueue.Path%2A> into the associated <xref:System.Messaging.MessageQueue.FormatName%2A> before accessing the queue. If your application is working offline, you must use the format name syntax; otherwise, the primary domain controller will not be available to perform the path translation.
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|
## Examples
The following code example displays the value of a message queue's <xref:System.Messaging.MessageQueue.FormatName%2A> property.
[!code-csharp[MessageQueue#13](~/samples/snippets/csharp/VS_Snippets_Remoting/MessageQueue/CS/class1.cs#13)]
]]></format>
</remarks>
<exception cref="T:System.Messaging.MessageQueueException">The <see cref="P:System.Messaging.MessageQueue.Path" /> is not set.
-or-
An error occurred when accessing a Message Queuing method.</exception>
<altmember cref="P:System.Messaging.MessageQueue.Path" />
<altmember cref="P:System.Messaging.MessageQueue.Label" />
<altmember cref="T:System.Messaging.MessageQueue" />
</Docs>
</Member>
<Member MemberName="Formatter">
<MemberSignature Language="C#" Value="public System.Messaging.IMessageFormatter Formatter { get; set; }" />
<MemberSignature Language="ILAsm" Value=".property instance class System.Messaging.IMessageFormatter Formatter" />
<MemberSignature Language="DocId" Value="P:System.Messaging.MessageQueue.Formatter" />
<MemberSignature Language="VB.NET" Value="Public Property Formatter As IMessageFormatter" />
<MemberSignature Language="C++ CLI" Value="public:&#xA; property System::Messaging::IMessageFormatter ^ Formatter { System::Messaging::IMessageFormatter ^ get(); void set(System::Messaging::IMessageFormatter ^ value); };" />
<MemberSignature Language="F#" Value="member this.Formatter : System.Messaging.IMessageFormatter with get, set" Usage="System.Messaging.MessageQueue.Formatter" />
<MemberType>Property</MemberType>
<AssemblyInfo>
<AssemblyName>System.Messaging</AssemblyName>
<AssemblyVersion>1.0.5000.0</AssemblyVersion>
<AssemblyVersion>2.0.0.0</AssemblyVersion>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
</AssemblyInfo>
<Attributes>
<Attribute FrameworkAlternate="netframework-1.1;netframework-2.0;netframework-3.0;netframework-3.5;netframework-4.0;netframework-4.5;netframework-4.5.1;netframework-4.5.2;netframework-4.6;netframework-4.6.1;netframework-4.6.2;netframework-4.7;netframework-4.7.1;netframework-4.7.2;xamarinmac-3.0;netframework-4.8">
<AttributeName>System.ComponentModel.Browsable(false)</AttributeName>
</Attribute>
<Attribute FrameworkAlternate="netframework-1.1;netframework-2.0;netframework-3.0;netframework-3.5;netframework-4.0;netframework-4.5;netframework-4.5.1;netframework-4.5.2;netframework-4.6;netframework-4.6.1;netframework-4.6.2;netframework-4.7;netframework-4.7.1;netframework-4.7.2;xamarinmac-3.0;netframework-4.8">
<AttributeName>System.ComponentModel.DefaultValue(null)</AttributeName>
</Attribute>
<Attribute FrameworkAlternate="netframework-1.1;netframework-2.0;netframework-3.0;netframework-3.5;netframework-4.0;netframework-4.5;netframework-4.5.1;netframework-4.5.2;netframework-4.6;netframework-4.6.1;netframework-4.6.2;netframework-4.7;netframework-4.7.1;netframework-4.7.2;xamarinmac-3.0;netframework-4.8">
<AttributeName>System.ComponentModel.TypeConverter(typeof(System.Messaging.Design.MessageFormatterConverter))</AttributeName>
</Attribute>
<Attribute FrameworkAlternate="netframework-1.1;netframework-2.0;netframework-3.0;netframework-3.5;netframework-4.0;netframework-4.5;netframework-4.5.1;netframework-4.5.2;netframework-4.6;netframework-4.6.1;netframework-4.6.2;netframework-4.7;netframework-4.7.1;netframework-4.7.2;xamarinmac-3.0;netframework-4.8">
<AttributeName>System.Messaging.MessagingDescription("MQ_Formatter")</AttributeName>
</Attribute>
</Attributes>
<ReturnValue>
<ReturnType>System.Messaging.IMessageFormatter</ReturnType>
</ReturnValue>
<Docs>
<summary>Gets or sets the formatter used to serialize an object into or deserialize an object from the body of a message read from or written to the queue.</summary>
<value>The <see cref="T:System.Messaging.IMessageFormatter" /> that produces a stream to be written to or read from the message body. The default is <see cref="T:System.Messaging.XmlMessageFormatter" />.</value>
<remarks>
<format type="text/markdown"><![CDATA[
## Remarks
The <xref:System.Messaging.MessageQueue.Formatter%2A> property contains an instance of a formatter object, which transforms messages when your application reads or writes to the queue.
When the application sends message to the queue, the formatter serializes the object into a stream and inserts it into the message body. When reading from a queue, the formatter deserializes the message data into the <xref:System.Messaging.Message.Body%2A> property of a <xref:System.Messaging.Message>.
The <xref:System.Messaging.XmlMessageFormatter> is loosely coupled, so it is not necessary to have the same object type on the sender and receiver when using this format. The <xref:System.Messaging.ActiveXMessageFormatter> and <xref:System.Messaging.BinaryMessageFormatter> serialize the data into binary representation. The <xref:System.Messaging.ActiveXMessageFormatter> is used when sending or receiving COM components.
<xref:System.Messaging.BinaryMessageFormatter> and <xref:System.Messaging.ActiveXMessageFormatter> provide faster throughput than the <xref:System.Messaging.XmlMessageFormatter>. The <xref:System.Messaging.ActiveXMessageFormatter> allows interoperability with Visual Basic 6.0 Message Queuing applications.
When your application sends messages to the queue, the <xref:System.Messaging.MessageQueue.Formatter%2A?displayProperty=nameWithType> applies only to those messages that use the default message properties, <xref:System.Messaging.MessageQueue.DefaultPropertiesToSend%2A>. If you send a <xref:System.Messaging.Message> to the queue, Message Queuing uses the formatter defined in the <xref:System.Messaging.Message.Formatter%2A?displayProperty=nameWithType> property to serialize the body instead.
The <xref:System.Messaging.MessageQueue> class will always use a <xref:System.Messaging.Message> to receive or peek a message from the queue. The message is deserialized using the <xref:System.Messaging.MessageQueue.Formatter%2A?displayProperty=nameWithType> property.
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|No|
|Remote computer and direct format name|Yes|
## Examples
The following code example demonstrates formatting a message body using <xref:System.Messaging.BinaryMessageFormatter>.
[!code-cpp[MessagingBinaryFormatter#1](~/samples/snippets/cpp/VS_Snippets_Remoting/MessagingBinaryFormatter/CPP/message_binaryformatter.cpp#1)]
[!code-csharp[MessagingBinaryFormatter#1](~/samples/snippets/csharp/VS_Snippets_Remoting/MessagingBinaryFormatter/CS/message_binaryformatter.cs#1)]
[!code-vb[MessagingBinaryFormatter#1](~/samples/snippets/visualbasic/VS_Snippets_Remoting/MessagingBinaryFormatter/VB/message_binaryformatter.vb#1)]
The following code example demonstrates formatting a message body using <xref:System.Messaging.XmlMessageFormatter>.
[!code-cpp[Message.Body#1](~/samples/snippets/cpp/VS_Snippets_Remoting/Message.Body/CPP/message_sendreceive.cpp#1)]
[!code-csharp[Message.Body#1](~/samples/snippets/csharp/VS_Snippets_Remoting/Message.Body/CS/message_sendreceive.cs#1)]
[!code-vb[Message.Body#1](~/samples/snippets/visualbasic/VS_Snippets_Remoting/Message.Body/VB/message_sendreceive.vb#1)]
]]></format>
</remarks>
<altmember cref="T:System.Messaging.XmlMessageFormatter" />
<altmember cref="T:System.Messaging.ActiveXMessageFormatter" />
<altmember cref="T:System.Messaging.BinaryMessageFormatter" />
<altmember cref="P:System.Messaging.Message.Formatter" />
</Docs>
</Member>
<Member MemberName="GetAllMessages">
<MemberSignature Language="C#" Value="public System.Messaging.Message[] GetAllMessages ();" />
<MemberSignature Language="ILAsm" Value=".method public hidebysig instance class System.Messaging.Message[] GetAllMessages() cil managed" />
<MemberSignature Language="DocId" Value="M:System.Messaging.MessageQueue.GetAllMessages" />
<MemberSignature Language="VB.NET" Value="Public Function GetAllMessages () As Message()" />
<MemberSignature Language="C++ CLI" Value="public:&#xA; cli::array &lt;System::Messaging::Message ^&gt; ^ GetAllMessages();" />
<MemberSignature Language="F#" Value="member this.GetAllMessages : unit -&gt; System.Messaging.Message[]" Usage="messageQueue.GetAllMessages " />
<MemberType>Method</MemberType>
<AssemblyInfo>
<AssemblyName>System.Messaging</AssemblyName>
<AssemblyVersion>1.0.5000.0</AssemblyVersion>
<AssemblyVersion>2.0.0.0</AssemblyVersion>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
</AssemblyInfo>
<ReturnValue>
<ReturnType>System.Messaging.Message[]</ReturnType>
</ReturnValue>
<Parameters />
<Docs>
<summary>Returns all the messages that are in the queue.</summary>
<returns>An array of type <see cref="T:System.Messaging.Message" /> that represents all the messages in the queue, in the same order as they appear in the Message Queuing queue.</returns>
<remarks>
<format type="text/markdown"><![CDATA[
## Remarks
<xref:System.Messaging.MessageQueue.GetAllMessages%2A> returns a static snapshot of the messages in the queue, not dynamic links to those messages. Therefore, you cannot use the array to modify the messages in the queue. If you want real-time, dynamic interaction with the queue (such as the ability to delete messages), call the <xref:System.Messaging.MessageQueue.GetMessageEnumerator2%2A> method, which returns a dynamic list of the messages in the queue.
Because <xref:System.Messaging.MessageQueue.GetAllMessages%2A> returns a copy of the messages in the queue at the time the method was called, the array does not reflect new messages that arrive in the queue or messages that are removed from the queue.
<xref:System.Messaging.MessageQueue.GetAllMessages%2A> retrieves only those properties not filtered out by the <xref:System.Messaging.MessageQueue.MessageReadPropertyFilter%2A> property.
The following table shows whether this method is available in various Workgroup modes.
|Workgroup mode|Available|
|--------------------|---------------|
|Local computer|Yes|
|Local computer and direct format name|Yes|
|Remote computer|No|
|Remote computer and direct format name|Yes|
## Examples
The following code example demonstrates the use of <xref:System.Messaging.MessageQueue.GetAllMessages%2A>.
[!code-cpp[MessageQueue2#21](~/samples/snippets/cpp/VS_Snippets_Remoting/MessageQueue2/cpp/class1.cpp#21)]
[!code-csharp[MessageQueue2#21](~/samples/snippets/csharp/VS_Snippets_Remoting/MessageQueue2/CS/class1.cs#21)]
]]></format>
</remarks>
<exception cref="T:System.Messaging.MessageQueueException">An error occurred when accessing a Message Queuing method.</exception>
<altmember cref="T:System.Messaging.Message" />
<altmember cref="M:System.Messaging.MessageQueue.GetMessageEnumerator2" />
</Docs>
</Member>
<Member MemberName="GetEnumerator">
<MemberSignature Language="C#" Value="public System.Collections.IEnumerator GetEnumerator ();" />
<MemberSignature Language="ILAsm" Value=".method public hidebysig newslot virtual instance class System.Collections.IEnumerator GetEnumerator() cil managed" />
<MemberSignature Language="DocId" Value="M:System.Messaging.MessageQueue.GetEnumerator" />
<MemberSignature Language="VB.NET" Value="Public Function GetEnumerator () As IEnumerator" />
<MemberSignature Language="C++ CLI" Value="public:&#xA; virtual System::Collections::IEnumerator ^ GetEnumerator();" />
<MemberSignature Language="F#" Value="abstract member GetEnumerator : unit -&gt; System.Collections.IEnumerator&#xA;override this.GetEnumerator : unit -&gt; System.Collections.IEnumerator" Usage="messageQueue.GetEnumerator " />
<MemberType>Method</MemberType>
<Implements>
<InterfaceMember>M:System.Collections.IEnumerable.GetEnumerator</InterfaceMember>
</Implements>
<AssemblyInfo>
<AssemblyName>System.Messaging</AssemblyName>
<AssemblyVersion>1.0.5000.0</AssemblyVersion>
<AssemblyVersion>2.0.0.0</AssemblyVersion>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
</AssemblyInfo>
<Attributes>
<Attribute FrameworkAlternate="xamarinmac-3.0">
<AttributeName>System.Obsolete</AttributeName>
</Attribute>
<Attribute FrameworkAlternate="netframework-2.0;netframework-3.0;netframework-3.5;netframework-4.0;netframework-4.5;netframework-4.5.1;netframework-4.5.2;netframework-4.6;netframework-4.6.1;netframework-4.6.2;netframework-4.7;netframework-4.7.1;netframework-4.7.2;netframework-4.8">
<AttributeName>System.Obsolete("This method returns a MessageEnumerator that implements RemoveCurrent family of methods incorrectly. Please use GetMessageEnumerator2 instead.")</AttributeName>
</Attribute>
</Attributes>
<ReturnValue>
<ReturnType>System.Collections.IEnumerator</ReturnType>
</ReturnValue>
<Parameters />
<Docs>
<summary>Enumerates the messages in a queue. <see cref="M:System.Messaging.MessageQueue.GetEnumerator" /> is deprecated. <see cref="M:System.Messaging.MessageQueue.GetMessageEnumerator2" /> should be used instead.</summary>
<returns>A <see cref="T:System.Collections.IEnumerator" /> that provides a dynamic connection to the messages in the queue.</returns>
<remarks>
<format type="text/markdown"><![CDATA[
## Remarks
The following table shows whether this method is available in various Workgroup modes.
|Workgroup mode|Available|
|--------------------|---------------|
|Local computer|Yes|
|Local computer and direct format name|Yes|
|Remote computer|No|
|Remote computer and direct format name|Yes|
## Examples
The following code example demonstrates the use of <xref:System.Messaging.MessageQueue.GetEnumerator%2A>.
[!code-cpp[MessageQueue2#22](~/samples/snippets/cpp/VS_Snippets_Remoting/MessageQueue2/cpp/class1.cpp#22)]
[!code-csharp[MessageQueue2#22](~/samples/snippets/csharp/VS_Snippets_Remoting/MessageQueue2/CS/class1.cs#22)]
]]></format>
</remarks>
<altmember cref="M:System.Messaging.MessageQueue.GetMessageEnumerator2" />
</Docs>
</Member>
<Member MemberName="GetMachineId">
<MemberSignature Language="C#" Value="public static Guid GetMachineId (string machineName);" />
<MemberSignature Language="ILAsm" Value=".method public static hidebysig valuetype System.Guid GetMachineId(string machineName) cil managed" />
<MemberSignature Language="DocId" Value="M:System.Messaging.MessageQueue.GetMachineId(System.String)" />
<MemberSignature Language="VB.NET" Value="Public Shared Function GetMachineId (machineName As String) As Guid" />
<MemberSignature Language="C++ CLI" Value="public:&#xA; static Guid GetMachineId(System::String ^ machineName);" />
<MemberSignature Language="F#" Value="static member GetMachineId : string -&gt; Guid" Usage="System.Messaging.MessageQueue.GetMachineId machineName" />
<MemberType>Method</MemberType>
<AssemblyInfo>
<AssemblyName>System.Messaging</AssemblyName>
<AssemblyVersion>1.0.5000.0</AssemblyVersion>
<AssemblyVersion>2.0.0.0</AssemblyVersion>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
</AssemblyInfo>
<ReturnValue>
<ReturnType>System.Guid</ReturnType>
</ReturnValue>
<Parameters>
<Parameter Name="machineName" Type="System.String" />
</Parameters>
<Docs>
<param name="machineName">The name of the computer that contains the queue, without the two preceding backslashes (\\\\).</param>
<summary>Gets the identifier of the computer on which the queue referenced by this <see cref="T:System.Messaging.MessageQueue" /> is located.</summary>
<returns>A <see cref="T:System.Guid" /> that represents a unique identifier for the computer on which the queue is located.</returns>
<remarks>
<format type="text/markdown"><![CDATA[
## Remarks
You can use a computer's identifier for two purposes, among others: to read the computer journal and to set security certificates. However, you cannot call <xref:System.Messaging.MessageQueue.GetMachineId%28System.String%29> for a remote computer when you are working offline because the application must have access to the directory service on the domain controller.
The computer identifier (or machine identifier) is a <xref:System.Guid> that Message Queuing creates when a computer is added to the enterprise. Message Queuing combines the computer identifier with the `Machine` and `Journal` keywords to create the machine journal's format name, which has the syntax `Machine=<computeridentifier>;Journal`. The machine journal, which is also known as the journal queue, is a system queue that stores copies of application-generated messages when the <xref:System.Messaging.MessageQueue.UseJournalQueue%2A> property is `true`.
This syntax for the journal is only valid when constructing the format name for the queue. The path name syntax is `MachineName`\\`Journal$`.
The following table shows whether this method is available in various Workgroup modes.
|Workgroup mode|Available|
|--------------------|---------------|
|L