MessageQueue.Peek Method (TimeSpan, Cursor, PeekAction)


The .NET API Reference documentation has a new home. Visit the .NET API Browser on to see the new experience.

Returns without removing (peeks) the current or next message in the queue, using the specified cursor. 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,
	Cursor cursor,
	PeekAction action


Type: System.TimeSpan

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

Type: System.Messaging.Cursor

A Cursor that maintains a specific position in the message queue.

Type: System.Messaging.PeekAction

One of the PeekAction values. Indicates whether to peek at the current message in the queue, or the next message.

Return Value

Type: System.Messaging.Message

A Message that represents a message in the queue.

Exception Condition

A value other than PeekAction.Current or PeekAction.Next was specified for the action parameter.


The cursor parameter is null.


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 2.0

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, a message from the queue. The Receive method, on the other hand, both reads and removes a message from the queue.

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 is 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


Return to top