MessageQueue::Peek Method ()

.NET Framework (current version)
 

Returns without removing (peeks) the first message in the queue referenced by this MessageQueue. The Peek method is synchronous, so it blocks the current thread until a message becomes available.

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

C#
C++
F#
VB
Copy 
public:
Message^ Peek()

Return Value

Type: System.Messaging::Message^

The Message that represents the first message in the queue.

Exception Condition
MessageQueueException

An error occurred when accessing a Message Queuing method.

.NET Framework
Available since 1.1

The method is not thread safe.

Use this overload to peek a queue, or to wait until a message exists in the queue.

The Peek method reads, but does not remove, the first message from the queue. Therefore, repeated calls to Peek return the same message, unless a higher priority message arrives in the queue. The Receive method, on the other hand, both reads and removes the first message from the queue. 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.

Use 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. If you need the application processing to continue without waiting, use the asynchronous BeginPeek method. Alternatively, 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

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.

In the second example, a message that contains an application-defined Order class is sent to the queue, and then peeked from the queue.

C#
C++
VB
Copy 
#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;
}
Return to top
Show: