Peek Method (TimeSpan)
Collapse the table of content
Expand the table of content

MessageQueue.Peek Method (TimeSpan)


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 or the specified time-out occurs.

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

public Message Peek(
	TimeSpan timeout


Type: System.TimeSpan

A TimeSpan that indicates the maximum time to wait for the queue to contain a message.

Return Value

Type: System.Messaging.Message

The Message that represents the first message in the queue.

Exception Condition

The value specified for the timeout parameter is not valid, possibly timeout is less than TimeSpan.Zero or greater than MessageQueue.InfiniteTimeout.


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 a specified period of time until a message exists in the queue. The method returns immediately if a message already 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. The thread will be blocked up to the specified period of time, or indefinitely if you indicated InfiniteTimeout. 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


Local computer


Local computer and direct format name


Remote computer


Remote computer and direct format name


The following code example uses the Peek method with a time-out of zero to check whether the queue is empty.

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();


		// 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");

				// 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 == 
					// 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;

Return to top
© 2016 Microsoft