MessageQueue.Peek 方法

定义

返回队列中第一条消息的副本,而不从队列中移除该消息。Returns a copy of the first message in the queue without removing the message from the queue.

重载

Peek()

返回但不移除(查看)此 MessageQueue 所引用的队列中的第一条消息。Returns without removing (peeks) the first message in the queue referenced by this MessageQueue. Peek() 方法是同步的,所以在有可用消息前,该方法阻塞当前线程。The Peek() method is synchronous, so it blocks the current thread until a message becomes available.

Peek(TimeSpan)

返回但不移除(查看)此 MessageQueue 所引用的队列中的第一条消息。Returns without removing (peeks) the first message in the queue referenced by this MessageQueue. Peek() 方法是同步的,因此在有可用消息或发生指定的超时之前,它一直阻止当前线程。The Peek() method is synchronous, so it blocks the current thread until a message becomes available or the specified time-out occurs.

Peek(TimeSpan, Cursor, PeekAction)

使用指定的游标返回但不移除(查看)队列中的当前消息或下一条消息。Returns without removing (peeks) the current or next message in the queue, using the specified cursor. Peek() 方法是同步的,因此在有可用消息或发生指定的超时之前,它一直阻止当前线程。The Peek() method is synchronous, so it blocks the current thread until a message becomes available or the specified time-out occurs.

Peek()

返回但不移除(查看)此 MessageQueue 所引用的队列中的第一条消息。Returns without removing (peeks) the first message in the queue referenced by this MessageQueue. Peek() 方法是同步的,所以在有可用消息前,该方法阻塞当前线程。The Peek() method is synchronous, so it blocks the current thread until a message becomes available.

public:
 System::Messaging::Message ^ Peek();
public System.Messaging.Message Peek ();
member this.Peek : unit -> System.Messaging.Message
Public Function Peek () As Message

返回

Message

Message 表示队列中第一条消息。The Message that represents the first message in the queue.

例外

访问“消息队列”方法时出错。An error occurred when accessing a Message Queuing method.

示例

下面的示例在队列中使用 Peek 方法。The following examples use the Peek method on a queue.

在第一个示例中,应用程序会等待,直到队列中有可用的消息。In the first example, the application waits until a message becomes available in the queue. 请注意,第一个示例不会访问到达的消息;它只是暂停处理直到消息到达。Note that the first example does not access the message that arrives; it merely pauses processing until a message arrives. 如果消息已在队列中存在,它将立即返回。If a message already exists in the queue, it will return immediately.

在第二个示例中,包含应用程序定义的类的消息将 Order 发送到队列,然后从队列中扫视。In the second example, a message that contains an application-defined Order class is sent to the queue, and then peeked from the queue.

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

using namespace System;
using namespace System::Messaging;

// This class represents an object the following example 
// sends to a queue and receives from a queue.
ref class Order
{
public:
   int orderId;
   DateTime orderTime;
};


/// <summary>
/// Provides a container class for the example.
/// </summary>
ref class MyNewQueue
{
public:

   //*************************************************
   // Posts a notification when a message arrives in 
   // the queue S"monitoredQueue". Does not retrieve any 
   // message information when peeking the message.
   //*************************************************
   void NotifyArrived()
   {
      // Connect to a queue.
      MessageQueue^ myQueue = gcnew MessageQueue( ".\\monitoredQueue" );

      // Specify to retrieve no message information.
      myQueue->MessageReadPropertyFilter->ClearAll();

      // Wait for a message to arrive. 
      Message^ emptyMessage = myQueue->Peek();

      // Post a notification when a message arrives.
      Console::WriteLine( "A message has arrived in the queue." );
      return;
   }


   //*************************************************
   // Sends an Order to a queue.
   //*************************************************
   void SendMessage()
   {
      // Create a new order and set values.
      Order^ sentOrder = gcnew Order;
      sentOrder->orderId = 3;
      sentOrder->orderTime = DateTime::Now;

      // Connect to a queue on the local computer.
      MessageQueue^ myQueue = gcnew MessageQueue( ".\\myQueue" );

      // Send the Order to the queue.
      myQueue->Send( sentOrder );
      return;
   }

   //*************************************************
   // Peeks a message containing an Order.
   //*************************************************
   void PeekFirstMessage()
   {
      // Connect to a queue.
      MessageQueue^ myQueue = gcnew MessageQueue( ".\\myQueue" );

      // Set the formatter to indicate the body contains an Order.
      array<Type^>^p = gcnew array<Type^>(1);
      p[ 0 ] = Order::typeid;
      myQueue->Formatter = gcnew XmlMessageFormatter( p );
      try
      {
         // Peek and format the message. 
         Message^ myMessage = myQueue->Peek();
         Order^ myOrder = static_cast<Order^>(myMessage->Body);

         // Display message information.
         Console::WriteLine( "Order ID: {0}", myOrder->orderId );
         Console::WriteLine( "Sent: {0}", myOrder->orderTime );
      }
      catch ( MessageQueueException^ ) 
      {
         // Handle Message Queuing exceptions.
      }
      // Handle invalid serialization format.
      catch ( InvalidOperationException^ e ) 
      {
         Console::WriteLine( e->Message );
      }

      // Catch other exceptions as necessary.
      return;
   }
};

//*************************************************
// Provides an entry point into the application.
//         
// This example posts a notification that a message
// has arrived in a queue. It sends a message 
// containing an other to a separate queue, and then
// peeks the first message in the queue.
//*************************************************
int main()
{
   // Create a new instance of the class.
   MyNewQueue^ myNewQueue = gcnew MyNewQueue;

   // Wait for a message to arrive in the queue.
   myNewQueue->NotifyArrived();

   // Send a message to a queue.
   myNewQueue->SendMessage();

   // Peek the first message in the queue.
   myNewQueue->PeekFirstMessage();
   return 0;
}
using System;
using System.Messaging;

namespace MyProject
{

    // This class represents an object the following example
    // sends to a queue and receives from a queue.
    public class Order
    {
        public int orderId;
        public DateTime orderTime;
    };	

    /// <summary>
    /// Provides a container class for the example.
    /// </summary>
    public class MyNewQueue
    {

        //**************************************************
        // Provides an entry point into the application.
        //		
        // This example posts a notification that a message
        // has arrived in a queue. It sends a message
        // containing an other to a separate queue, and then
        // peeks the first message in the queue.
        //**************************************************

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

            // Wait for a message to arrive in the queue.
            myNewQueue.NotifyArrived();

            // Send a message to a queue.
            myNewQueue.SendMessage();	

            // Peek the first message in the queue.
            myNewQueue.PeekFirstMessage();
                        
            return;
        }

        //**************************************************
        // Posts a notification when a message arrives in
        // the queue "monitoredQueue". Does not retrieve any
        // message information when peeking the message.
        //**************************************************
        
        public void NotifyArrived()
        {

            // Connect to a queue.
            MessageQueue myQueue = new
                MessageQueue(".\\monitoredQueue");
    
            // Specify to retrieve no message information.
            myQueue.MessageReadPropertyFilter.ClearAll();

            // Wait for a message to arrive.
            Message emptyMessage = myQueue.Peek();

            // Post a notification when a message arrives.
            Console.WriteLine("A message has arrived in the queue.");

            return;
        }

        //**************************************************
        // Sends an Order to a queue.
        //**************************************************
        
        public void SendMessage()
        {
            
            // Create a new order and set values.
            Order sentOrder = new Order();
            sentOrder.orderId = 3;
            sentOrder.orderTime = DateTime.Now;

            // Connect to a queue on the local computer.
            MessageQueue myQueue = new MessageQueue(".\\myQueue");

            // Send the Order to the queue.
            myQueue.Send(sentOrder);

            return;
        }

        //**************************************************
        // Peeks a message containing an Order.
        //**************************************************
        
        public void PeekFirstMessage()
        {
            // Connect to a queue.
            MessageQueue myQueue = new MessageQueue(".\\myQueue");
    
            // Set the formatter to indicate the body contains an Order.
            myQueue.Formatter = new XmlMessageFormatter(new Type[]
                {typeof(MyProject.Order)});
            
            try
            {
                // Peek and format the message.
                Message myMessage =	myQueue.Peek();
                Order myOrder = (Order)myMessage.Body;

                // Display message information.
                Console.WriteLine("Order ID: " +
                    myOrder.orderId.ToString());
                Console.WriteLine("Sent: " +
                    myOrder.orderTime.ToString());
            }
            
            catch (MessageQueueException)
            {
                // Handle Message Queuing exceptions.
            }

            // Handle invalid serialization format.
            catch (InvalidOperationException e)
            {
                Console.WriteLine(e.Message);
            }
            
            // Catch other exceptions as necessary.

            return;
        }
    }
}
Imports System.Messaging



    ' This class represents an object the following example 
    ' sends to a queue and peeks from a queue.
    Public Class Order
        Public orderId As Integer
        Public orderTime As DateTime
    End Class


   
    Public Class MyNewQueue


        
        ' Provides an entry point into the application.
        '		 
        ' This example posts a notification that a message
        ' has arrived in a queue. It sends a message 
        ' containing an other to a separate queue, and then
        ' peeks the first message in the queue.
        

        Public Shared Sub Main()

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

            ' Wait for a message to arrive in the queue.
            myNewQueue.NotifyArrived()

            ' Send a message to a queue.
            myNewQueue.SendMessage()

            ' Peek the first message in the queue.
            myNewQueue.PeekFirstMessage()

            Return

        End Sub


        
        ' Posts a notification when a message arrives in 
        ' the queue "monitoredQueue". Does not retrieve any 
        ' message information when peeking the message.
        
        Public Sub NotifyArrived()

            ' Connect to a queue.
            Dim myQueue As New MessageQueue(".\monitoredQueue")

            ' Specify to retrieve no message information.
            myQueue.MessageReadPropertyFilter.ClearAll()

            ' Wait for a message to arrive. 
            Dim emptyMessage As Message = myQueue.Peek()

            ' Post a notification when a message arrives.
            Console.WriteLine("A message has arrived in the queue.")

            Return

        End Sub


        
        ' Sends an Order to a queue.
        

        Public Sub SendMessage()

            ' Create a new order and set values.
            Dim sentOrder As New Order()
            sentOrder.orderId = 3
            sentOrder.orderTime = DateTime.Now

            ' Connect to a queue on the local computer.
            Dim myQueue As New MessageQueue(".\myQueue")

            ' Send the Order to the queue.
            myQueue.Send(sentOrder)

            Return

        End Sub


        
        ' Peeks a message containing an Order.
        

        Public Sub PeekFirstMessage()

            ' Connect to a queue.
            Dim myQueue As New MessageQueue(".\myQueue")

            ' Set the formatter to indicate body contains an Order.
            myQueue.Formatter = New XmlMessageFormatter(New Type() _
                {GetType(Order)})

            Try

                ' Peek and format the message. 
                Dim myMessage As Message = myQueue.Peek()
                Dim myOrder As Order = CType(myMessage.Body, Order)

                ' Display message information.
                Console.WriteLine(("Order ID: " + _
                    myOrder.orderId.ToString()))
                Console.WriteLine(("Sent: " + _
                    myOrder.orderTime.ToString()))

            Catch m as MessageQueueException
                ' Handle Message Queuing exceptions.


            Catch e As InvalidOperationException
                ' Handle invalid serialization format.
                Console.WriteLine(e.Message)

                ' Catch other exceptions as necessary.

            End Try

            Return

        End Sub

End Class

注解

使用此重载可查看队列,或等待队列中存在消息。Use this overload to peek a queue, or to wait until a message exists in the queue.

Peek 方法从队列中读取并不删除第一条消息。The Peek method reads, but does not remove, the first message from the queue. 因此,重复调用将 Peek 返回相同的消息,除非队列中有较高优先级的消息到达。Therefore, repeated calls to Peek return the same message, unless a higher priority message arrives in the queue. Receive另一方面,方法会读取和删除队列中的第一条消息。The Receive method, on the other hand, both reads and removes the first message from the queue. 因此,对的重复调用将 Receive 返回不同的消息。Repeated calls to Receive, therefore, return different messages.

消息队列根据优先级和到达时间对队列中的消息进行排序。Message Queuing orders messages in the queue according to priority and arrival time. 仅当较高优先级的消息超过较高优先级时,才会将其放在旧消息之前。A newer message is placed before an older one only if it is of a higher priority.

如果当前线程在等待消息到达队列时可以被阻塞,则使用 PeekUse Peek when it is acceptable for the current thread to be blocked while it waits for a message to arrive in the queue. 由于此重载未指定超时,因此应用程序可能会无限期等待。Because this overload does not specify a time-out, the application might wait indefinitely. 如果需要应用程序处理继续进行而不等待,则使用异步 BeginPeek 方法。If you need the application processing to continue without waiting, use the asynchronous BeginPeek method. 或者,您可以通过使用指定超时的的重载来指定消息到达队列的超时时间 PeekAlternatively, you can specify a time-out for a message to arrive in the queue by using the overload of Peek that specifies a time-out.

下表显示了此方法是否在各种工作组模式下可用。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

另请参阅

适用于

Peek(TimeSpan)

返回但不移除(查看)此 MessageQueue 所引用的队列中的第一条消息。Returns without removing (peeks) the first message in the queue referenced by this MessageQueue. Peek() 方法是同步的,因此在有可用消息或发生指定的超时之前,它一直阻止当前线程。The Peek() method is synchronous, so it blocks the current thread until a message becomes available or the specified time-out occurs.

public:
 System::Messaging::Message ^ Peek(TimeSpan timeout);
public System.Messaging.Message Peek (TimeSpan timeout);
member this.Peek : TimeSpan -> System.Messaging.Message
Public Function Peek (timeout As TimeSpan) As Message

参数

timeout
TimeSpan

一个 TimeSpan 指示等待队列包含消息所用的最长时间。A TimeSpan that indicates the maximum time to wait for the queue to contain a message.

返回

Message

Message 表示队列中第一条消息。The Message that represents the first message in the queue.

例外

timeout 参数指定的值无效,可能是 timeout 小于 Zero 或大于 InfiniteTimeoutThe value specified for the timeout parameter is not valid, possibly timeout is less than Zero or greater than InfiniteTimeout.

访问“消息队列”方法时出错。An error occurred when accessing a Message Queuing method.

示例

下面的代码示例使用超时 Peek 值为零的方法来检查队列是否为空。The following code example uses the Peek method with a time-out of zero to check whether the queue is empty.

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

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

   //*************************************************
   // Determines whether a queue is empty. The Peek()
   // method throws an exception if there is no message
   // in the queue. This method handles that exception 
   // by returning true to the calling method.
   //*************************************************
   bool IsQueueEmpty()
   {
      bool isQueueEmpty = false;
      
      // Connect to a queue.
      MessageQueue^ myQueue = gcnew MessageQueue( ".\\myQueue" );
      try
      {
         
         // Set Peek to return immediately.
         myQueue->Peek( TimeSpan(0) );
         
         // If an IOTime->Item[Out] was* not thrown, there is a message 
         // in the queue.
         isQueueEmpty = false;
      }
      catch ( MessageQueueException^ e ) 
      {
         if ( e->MessageQueueErrorCode == MessageQueueErrorCode::IOTimeout )
         {
            
            // No message was in the queue.
            isQueueEmpty = true;
         }

         
         // Handle other sources of MessageQueueException.
      }

      
      // Handle other exceptions as necessary.
      // Return true if there are no messages in the queue.
      return isQueueEmpty;
   }

};


//*************************************************
// Provides an entry point into the application.
//         
// This example determines whether a queue is empty.
//*************************************************
int main()
{
   
   // Create a new instance of the class.
   MyNewQueue^ myNewQueue = gcnew MyNewQueue;
   
   // Determine whether a queue is empty.
   bool isQueueEmpty = myNewQueue->IsQueueEmpty();
   return 0;
}

using System;
using System.Messaging;

namespace MyProject
{
    /// <summary>
    /// Provides a container class for the example.
    /// </summary>
    public class MyNewQueue
    {

        //**************************************************
        // Provides an entry point into the application.
        //		
        // This example determines whether a queue is empty.
        //**************************************************

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

            // Determine whether a queue is empty.
            bool isQueueEmpty = myNewQueue.IsQueueEmpty();
                        
            return;
        }

        //**************************************************
        // Determines whether a queue is empty. The Peek()
        // method throws an exception if there is no message
        // in the queue. This method handles that exception
        // by returning true to the calling method.
        //**************************************************
        
        public bool IsQueueEmpty()
        {
            bool isQueueEmpty = false;

            // Connect to a queue.
            MessageQueue myQueue = new MessageQueue(".\\myQueue");

            try
            {
                // Set Peek to return immediately.
                myQueue.Peek(new TimeSpan(0));

                // If an IOTimeout was not thrown, there is a message
                // in the queue.
                isQueueEmpty = false;
            }

            catch(MessageQueueException e)
            {
                if (e.MessageQueueErrorCode ==
                    MessageQueueErrorCode.IOTimeout)
                {
                    // No message was in the queue.
                    isQueueEmpty = true;
                }

                // Handle other sources of MessageQueueException.
            }

            // Handle other exceptions as necessary.

            // Return true if there are no messages in the queue.
            return isQueueEmpty;
        }
    }
}
Imports System.Messaging



   
    Public Class MyNewQueue


        '
        ' Provides an entry point into the application.
        '		 
        ' This example determines whether a queue is empty.
        '

        Public Shared Sub Main()

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

            ' Determine whether a queue is empty.
            Dim IsQueueEmpty As Boolean = myNewQueue.IsQueueEmpty()
        if IsQueueEMpty=True Then Console.WriteLine("Empty")
            

            Return

        End Sub


        '
        ' Determines whether a queue is empty. The Peek()
        ' method throws an exception if there is no message
        ' in the queue. This method handles that exception 
        ' by returning true to the calling method.
        '

        Public Function IsQueueEmpty() As Boolean

            'Dim QueueEmpty As Boolean = False

            ' Connect to a queue.
            Dim myQueue As New MessageQueue(".\myQueue")

            Try

                ' Set Peek to return immediately.
                myQueue.Peek(New TimeSpan(0))

                ' If an IOTimeout was not thrown, there is a message 
                ' in the queue.
                'queueEmpty = False

            Catch e As MessageQueueException

                If e.MessageQueueErrorCode = _
                    MessageQueueErrorCode.IOTimeout Then

                    ' No message was in the queue.
                    IsQueueEmpty = True

                End If

                ' Handle other sources of MessageQueueException as necessary.

                ' Handle other exceptions as necessary.

            End Try

            ' Return true if there are no messages in the queue.
            'Return queueEmpty
        IsQueueEmpty = False

        End Function 'IsQueueEmpty 

End Class

注解

使用此重载可查看队列,或在队列中存在消息之前等待指定的时间段。Use this overload to peek a queue, or to wait a specified period of time until a message exists in the queue. 如果队列中已经存在消息,则该方法立即返回。The method returns immediately if a message already exists in the queue.

Peek 方法从队列中读取并不删除第一条消息。The Peek method reads, but does not remove, the first message from the queue. 因此,重复调用将 Peek 返回相同的消息,除非队列中有较高优先级的消息到达。Therefore, repeated calls to Peek return the same message, unless a higher priority message arrives in the queue. Receive另一方面,方法会读取和删除队列中的第一条消息。The Receive method, on the other hand, both reads and removes the first message from the queue. 因此,对的重复调用将 Receive 返回不同的消息。Repeated calls to Receive, therefore, return different messages.

消息队列根据优先级和到达时间对队列中的消息进行排序。Message Queuing orders messages in the queue according to priority and arrival time. 仅当较高优先级的消息超过较高优先级时,才会将其放在旧消息之前。A newer message is placed before an older one only if it is of a higher priority.

如果当前线程在等待消息到达队列时可以被阻塞,则使用 PeekUse Peek when it is acceptable for the current thread to be blocked while it waits for a message to arrive in the queue. 线程将被阻塞一段指定的时间,或在你指示的情况下无限期阻塞 InfiniteTimeoutThe thread will be blocked up to the specified period of time, or indefinitely if you indicated InfiniteTimeout. 如果需要应用程序处理继续进行而不等待,则使用异步 BeginPeek 方法。If you need the application processing to continue without waiting, use the asynchronous BeginPeek method.

下表显示了此方法是否在各种工作组模式下可用。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

另请参阅

适用于

Peek(TimeSpan, Cursor, PeekAction)

使用指定的游标返回但不移除(查看)队列中的当前消息或下一条消息。Returns without removing (peeks) the current or next message in the queue, using the specified cursor. Peek() 方法是同步的,因此在有可用消息或发生指定的超时之前,它一直阻止当前线程。The Peek() method is synchronous, so it blocks the current thread until a message becomes available or the specified time-out occurs.

public:
 System::Messaging::Message ^ Peek(TimeSpan timeout, System::Messaging::Cursor ^ cursor, System::Messaging::PeekAction action);
public System.Messaging.Message Peek (TimeSpan timeout, System.Messaging.Cursor cursor, System.Messaging.PeekAction action);
member this.Peek : TimeSpan * System.Messaging.Cursor * System.Messaging.PeekAction -> System.Messaging.Message
Public Function Peek (timeout As TimeSpan, cursor As Cursor, action As PeekAction) As Message

参数

timeout
TimeSpan

一个 TimeSpan 指示等待队列包含消息所用的最长时间。A TimeSpan that indicates the maximum time to wait for the queue to contain a message.

cursor
Cursor

维持消息队列中特定位置的 CursorA Cursor that maintains a specific position in the message queue.

action
PeekAction

PeekAction 值之一。One of the PeekAction values. 指示是查看队列中的当前消息还是下一条消息。Indicates whether to peek at the current message in the queue, or the next message.

返回

Message

一个 Message,表示队列中的消息。A Message that represents a message in the queue.

例外

action 参数指定的值不是 PeekAction.CurrentPeekAction.NextA value other than PeekAction.Current or PeekAction.Next was specified for the action parameter.

cursor 参数为 nullThe cursor parameter is null.

timeout 参数指定的值无效。The value specified for the timeout parameter is not valid. timeout 可能小于 Zero 或大于 InfiniteTimeoutPossibly timeout is less than Zero or greater than InfiniteTimeout.

访问“消息队列”方法时出错。An error occurred when accessing a Message Queuing method.

注解

使用此重载可查看队列,或在队列中存在消息之前等待指定的时间段。Use this overload to peek a queue, or to wait a specified period of time until a message exists in the queue. 如果队列中已经存在消息,则该方法立即返回。The method returns immediately if a message already exists in the queue.

Peek 方法从队列中读取消息,但不从队列中移除消息。The Peek method reads, but does not remove, a message from the queue. Receive另一方面,方法会读取和删除队列中的消息。The Receive method, on the other hand, both reads and removes a message from the queue.

如果当前线程在等待消息到达队列时可以被阻塞,则使用 PeekUse Peek when it is acceptable for the current thread to be blocked while it waits for a message to arrive in the queue. 在指定的时间段内阻塞线程,或在指示的情况下无限期阻塞 InfiniteTimeoutThe thread is blocked up to the specified period of time, or indefinitely if you indicated InfiniteTimeout. 如果需要应用程序处理继续进行而不等待,则使用异步 BeginPeek 方法。If you need the application processing to continue without waiting, use the asynchronous BeginPeek method.

下表显示了此方法是否在各种工作组模式下可用。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

另请参阅

适用于

线程安全性

方法不是线程安全的。The method is not thread safe.