MessageQueue.Peek 方法

定義

命名空間:

System.Messaging

組件:

System.Messaging.dll

傳回佇列中第一個訊息的複本，但不從佇列中移除訊息。

多載

Peek()	傳回而不移除 (窺視) 這個 MessageQueue 所參考佇列中的第一個訊息。 Peek() 方法是同步的，因此會封鎖目前的執行緒，直到訊息可以使用為止。
Peek(TimeSpan)	傳回而不移除 (窺視) 這個 MessageQueue 所參考佇列中的第一個訊息。 Peek() 方法是同步的，因此會封鎖目前的執行緒，直到訊息可以使用或發生指定的逾時為止。
Peek(TimeSpan, Cursor, PeekAction)	使用指定的游標傳回而不移除 (窺視) 佇列中的目前或下一則訊息。 Peek() 方法是同步的，因此會封鎖目前的執行緒，直到訊息可以使用或發生指定的逾時為止。

Peek()

傳回而不移除 (窺視) 這個 MessageQueue 所參考佇列中的第一個訊息。 Peek() 方法是同步的，因此會封鎖目前的執行緒，直到訊息可以使用為止。

C#

public System.Messaging.Message Peek ();

傳回

Message

表示佇列中第一個訊息的 Message。

例外狀況

MessageQueueException

存取訊息佇列方法時發生錯誤。

範例

下列範例會在 Peek 佇列上使用 方法。

在第一個範例中，應用程式會等候訊息在佇列中變成可用為止。 請注意，第一個範例不會存取抵達的訊息;它只會暫停處理，直到訊息送達為止。 如果訊息已存在於佇列中，則會立即傳回。

在第二個範例中，包含應用程式定義 Order 類別的訊息會傳送至佇列，然後從佇列查看。

C#

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;
        }
    }
}

備註

使用此多載來查看佇列，或等候訊息存在於佇列中。

方法 Peek 會讀取佇列中的第一個訊息，但不會移除。 因此，除非較高的優先順序訊息抵達佇列，否則重複呼叫會 Peek 傳回相同的訊息。 另一方面，方法 Receive 會讀取並移除佇列中的第一則訊息。 重複呼叫 Receive，因此會傳回不同的訊息。

消息佇列會根據優先順序和抵達時間排序佇列中的訊息。 只有在較舊的訊息優先順序較高時，才會在較舊的訊息之前放置。

當目前的執行緒可接受進行封鎖並同時等候訊息到達佇列時，請使用 Peek。 由於此多載未指定逾時，因此應用程式可能會無限期等候。 當您需要應用程式繼續執行而不要等候，請使用非同步的 BeginPeek 方法。 或者，您可以使用指定逾時的 Peek 多載，指定訊息抵達佇列中的逾時。

下表顯示此方法是否可在各種工作組模式中使用。

工作組模式	可用
本機電腦	是
本機計算機和直接格式名稱	是
遠端電腦	否
遠端電腦和直接格式名稱	是

另請參閱

• Receive()
• BeginPeek()

Peek(TimeSpan)

傳回而不移除 (窺視) 這個 MessageQueue 所參考佇列中的第一個訊息。 Peek() 方法是同步的，因此會封鎖目前的執行緒，直到訊息可以使用或發生指定的逾時為止。

C#

public System.Messaging.Message Peek (TimeSpan timeout);

參數

timeout

TimeSpan

TimeSpan，指出等待含有訊息之佇列的最長時間。

傳回

Message

表示佇列中第一個訊息的 Message。

例外狀況

ArgumentException

為 timeout 參數指定的值無效，可能是 timeout 小於 Zero 或大於 InfiniteTimeout。

MessageQueueException

存取訊息佇列方法時發生錯誤。

範例

下列程式代碼範例會 Peek 使用 方法與零逾時，檢查佇列是否為空白。

C#

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;
        }
    }
}

備註

使用此多載來查看佇列，或等候指定的一段時間，直到訊息存在於佇列中為止。 如果佇列中已有訊息，方法會立即傳回 。

方法 Peek 會讀取佇列中的第一個訊息，但不會移除。 因此，除非較高的優先順序訊息抵達佇列，否則重複呼叫會 Peek 傳回相同的訊息。 另一方面，方法 Receive 會讀取並移除佇列中的第一則訊息。 重複呼叫 Receive，因此會傳回不同的訊息。

消息佇列會根據優先順序和抵達時間排序佇列中的訊息。 只有在較舊的訊息優先順序較高時，才會在較舊的訊息之前放置。

當目前的執行緒可接受進行封鎖並同時等候訊息到達佇列時，請使用 Peek。 線程會封鎖到指定的時間週期，或者如果您指出 InfiniteTimeout，則無限期地封鎖線程。 當您需要應用程式繼續執行而不要等候，請使用非同步的 BeginPeek 方法。

下表顯示此方法是否可在各種工作組模式中使用。

工作組模式	可用
本機電腦	是
本機計算機和直接格式名稱	是
遠端電腦	否
遠端電腦和直接格式名稱	是

另請參閱

• InfiniteTimeout
• Receive()
• BeginPeek()

Peek(TimeSpan, Cursor, PeekAction)

使用指定的游標傳回而不移除 (窺視) 佇列中的目前或下一則訊息。 Peek() 方法是同步的，因此會封鎖目前的執行緒，直到訊息可以使用或發生指定的逾時為止。

C#

public System.Messaging.Message Peek (TimeSpan timeout, System.Messaging.Cursor cursor, System.Messaging.PeekAction action);

參數

timeout

TimeSpan

TimeSpan，指出等待含有訊息之佇列的最長時間。

cursor

Cursor

Cursor，保留訊息佇列中的特定位置。

action

PeekAction

其中一個 PeekAction 值。 指出要窺視佇列中的目前訊息，還是下一則訊息。

傳回

Message

Message，表示佇列中的訊息。

例外狀況

ArgumentOutOfRangeException

為 action 參數指定 PeekAction.Current 或 PeekAction.Next 以外的值。

ArgumentNullException

cursor 參數為 null。

ArgumentException

指定給 timeout 參數的值無效。 可能是 timeout 小於 Zero 或大於 InfiniteTimeout。

MessageQueueException

存取訊息佇列方法時發生錯誤。

備註

使用此多載來查看佇列，或等候指定的一段時間，直到訊息存在於佇列中為止。 如果佇列中已有訊息，方法會立即傳回 。

方法 Peek 會讀取佇列中的訊息，但不會移除。 另一方面，方法 Receive 會讀取和移除佇列中的訊息。

當目前的執行緒可接受進行封鎖並同時等候訊息到達佇列時，請使用 Peek。 線程會封鎖到指定的時間週期，或者如果您指出 InfiniteTimeout，則無限期地封鎖線程。 當您需要應用程式繼續執行而不要等候，請使用非同步的 BeginPeek 方法。

下表顯示此方法是否可在各種工作組模式中使用。

工作組模式	可用
本機電腦	是
本機計算機和直接格式名稱	是
遠端電腦	否
遠端電腦和直接格式名稱	是

另請參閱

• Cursor
• PeekAction
• InfiniteTimeout
• Receive()
• BeginPeek()

執行緒安全性

方法不是安全線程。