Applies to: Exchange Server 2010 SP3, Exchange Server 2010 SP2
Topic Last Modified: 2009-12-07
This topic explains how you can use the cmdlets and parameter sets in the Exchange Management Shell to create a query, retrieve the results, and perform modifying actions. For more information about the queue tasks and how they can be used for monitoring and troubleshooting, see Understanding Transport Queues.
In Microsoft Exchange Server 2010, you can use the Shell to perform management and configuration tasks and to create scripts to automate tasks. You can also use the Shell to view information about queues on a server and the messages in those queues, and to perform management actions on queues and mail items. These operations are useful for troubleshooting mail flow and identifying spam. For more information about how to use the Shell, see Exchange Management Shell.
Looking for management tasks related to queues? See Managing Transport Queues.
Contents
Managing Queues and Messages
Queue tasks are grouped into two categories:
- Viewing actions display queues and messages queued on the
server and select how that data is grouped and sorted when it's
displayed.
- Modifying actions change the status of queues and messages.
Both types of tasks access data by connecting to the transport worker process by using a remote procedure call (RPC).
By default, Queue Viewer focuses on the queuing database located on the server that Queue Viewer connects to, to run the tasks. However, you can connect to a different server than the one that you are running the Queue Viewer tasks on.
For more information about the Exchange 2010 transport process, see Understanding Transport Pipeline. For more information about how to use the Shell to view queues and messages, see View Queues and View Queued Message Properties.
Queue Cmdlets
The following table lists the cmdlets available in the Shell for managing queues and the messages in the queues. For more information about how to use each cmdlet, see the Help topics listed in the For more information column.
Queue cmdlets
| Cmdlet | Usage | For more information |
|---|---|---|
|
Export-Message |
This cmdlet saves a copy of a message in an administrator-specified file path. |
|
|
Get-Message |
This cmdlet displays the details of the messages currently queued for delivery. You can use the Get-Message cmdlet to retrieve a set of messages and then pipe the results to one of the other message management cmdlets. |
|
|
Get-Queue |
This cmdlet displays the configuration details of the queues on transport servers. You can use the Get-Queue cmdlet to retrieve a set of queues and then pipe the results to one of the other queue management cmdlets. |
|
|
Remove-Message |
This cmdlet deletes a message from a queue. You can select whether a non-delivery report (NDR) is sent. |
|
|
Resume-Message |
This cmdlet resumes delivery of a previously suspended message. You can also use the Resume-Message cmdlet to resubmit messages in the poison message queue to the Submission queue for the categorizer to reprocess. |
|
|
Resume-Queue |
This cmdlet resumes deliveries of messages from a previously suspended queue. |
|
|
Retry-Queue |
This cmdlet forces a connection attempt for a queue that currently has a status of Retry. This connection attempt overrides the next scheduled retry. You can also use the Retry-Queue cmdlet together with the Resubmit parameter to send messages in delivery queues or in the Unreachable queue to the Submission queue for the categorizer to reprocess. |
|
|
Suspend-Message |
This cmdlet suspends delivery of a message located in a queue on an Exchange 2010 transport server. |
|
|
Suspend-Queue |
This cmdlet suspends outgoing activities for a queue on an Exchange 2010 transport server. |
Queue Task Parameter Sets
Queue tasks support multiple parameter sets. These parameter sets are as follows: Identity, Filter, and Queue. The Identity, Filter, and Queue parameter sets can't be combined in a command. The Queue parameter set is available only with message commands.
You can also use the advanced paging parameters available in the Shell in combination with the Identity, Filter, and Queue parameter sets. The advanced paging parameters are used with the Get-Message and Get-Queue cmdlets to control how the result set is sorted and displayed. The advanced paging parameters are described in a table in "Advanced Paging Parameters" later in this topic.
You must use an Identity, Filter, or Queue parameter set when using a command that modifies messages or queues. If you don't provide any parameters, the Get-Message and Get-Queue cmdlets display every message or queue object that exists on the local server.
If the result set for a queue or message query contains more than 250,000 items, an error occurs, and you will be prompted to apply a filter to reduce the number of results.
Identity Parameter
Use the Identity parameter when the specific message or queue that you want to view or that you will take action against is known. The search by identity is faster than formulating the same query as a filter.
The server name can be expressed as a host name or as a fully qualified domain name (FQDN). You can enter the name of a remote server as part of the identity to initiate an RPC connection to that server so that you can query the queues on that server. If you don't use a server name, the local host is implied.
When an identity is provided to a modifying action, the object identified must be fully defined and unique. If the identity isn't explicit, the action won't be performed. If you omit the server part of the identity, the local computer will be assumed.
When you use the Identity parameter as part of a Get-Queue or Get-Message cmdlet, the Identity parameter supports the use of wildcard expressions.
Queue Identity
Persistent queues have unique names and can be specified by name. Delivery queues are assigned a unique database identity. You can use this database identity to specify a queue, or you can use the name of the delivery destination to specify a queue. To perform an operation on a queue by specifying its unique database identity, you must first run the Get-Queue cmdlet. The database identity will be returned in the results. The accepted identity formats for queues are shown in the following table.
Queue identity formats
| Queue identity format | Usage |
|---|---|
|
Server\QueueJetID (Int64) |
The complete, unique identity for a delivery queue. |
|
\QueueJetID |
The identity of a queue on the local server. The server name is omitted. Therefore, the local server is implied. |
|
Server\* |
Any queue on the specified server. |
|
Server\NextHopDomain |
A queue on the specified server holding messages for delivery to a specific remote domain. |
|
\NextHopDomain |
A queue holding messages destined for a specific domain and located on the local server. |
|
Server\Poison |
The poison message queue located on the specified server. |
|
Server\Submission |
The queue that contains items waiting to be processed by the categorizer. |
|
Server\Unreachable |
The queue that contains items that can't be routed and located on the specified server. |
The following code is an example of how to use a queue identity with the Get-Queue cmdlet. This example returns a list of all queues holding messages for delivery to SMTP domain names that end in Contoso.com. This example also formats the result set as a detailed list.
Get-Queue -Identity Server\*Contoso.com |
format-list
Message Identity
The identity of a message is an aggregation of the unique database mail item and the queue identity. An identity, in the form of an integer, is assigned to a message when the message enters the queuing Extensible Storage Engine (ESE) database (formerly known as Jet), and that integer is appended to the queue identity to create the message identity.
To perform an operation on a message by specifying its database identity, you must first run the Get-Message cmdlet. The identity is returned in the results. If you want to connect to a remote server, you can include the server name as part of the message identity. If the server name is omitted, the local server is assumed.
A message being sent to more than one recipient may be located in multiple queues. You can use a wildcard character to specify that you want to locate the message in every queue to which the message was routed. The following table provides examples of a valid message identity.
Message identity formats
| Message identity format | Usage |
|---|---|
|
Server\QueueJetId\MessageJetID |
Full denomination of a message in a queue. |
|
Server\Poison\MessageJetID |
A message in the poison message queue. |
|
MessageJetID |
All messages that have this database identity and are routed to any queue on the local server (one message routed to multiple queues). |
|
Server\*\MessageJetID |
All messages that have this database identity and are routed to any queue on the specified server. |
The following code is an example of how to use a message identity with the Get-Message cmdlet. This example returns a list of all messages that have the specified identity and are located in any queue on the specified server. This example also formats the result set as a detailed list.
Get-message -Identity Server\*\1234 |
Format-List
Filter Parameter
Queue tasks support the Filter parameter so you can specify criteria for which queues and messages should be retrieved. The queue and message properties are used as filter criteria. Create a filter to display a limited set of queues or messages. After you locate the queues and messages that you want to monitor, you can view property information for each object. This information is helpful when you troubleshoot mail flow problems.
Use the Filter parameter to supply an expression with logical and relational operators so that only the queue or message objects that meet the filter criteria are displayed. You can use the -and logical operator to specify multiple conditions that the results will match. If you use the -and operator, only objects that match all specified conditions of the expression are displayed. A subset of the properties of a message or a queue is used to specify the filter criteria. When you specify a property, it must be a valid property for the object for which you are querying, and the value to match must be expressed by using the correct syntax. When a property value is expressed as anything other than a single integer, make sure that you enclose the value in quotation marks.
The Server parameter can be included in a command together with the Filter parameter. Use the Server parameter to specify the host name or FQDN of the server that you want to connect to by using RPC to query the queues and messages on that server and retrieve a result set.
For more information about the properties that can be used for filtering, the correct syntax for these properties, and the supported operators, see the following topics:
Queue Parameter
The Queue parameter is used only with message commands. Use this parameter to specify the identity of the queue from which messages are retrieved. If a queue is specified, all messages in that queue are retrieved. You can retrieve all messages from a particular queue without having to use a filter expression. You can retrieve messages in multiple queues by using a wildcard character.
When you use the Queue parameter with a message command, use the queue identity format from the table in "Queue Identity" earlier in this topic. The following code example shows how to use the Queue parameter with a Get-Message cmdlet. This example produces a result set that contains only messages located on the specified server and queued for delivery to the SMTP domain Contoso.com.
Get-message -Queue Server\Contoso.com
Advanced Paging Parameters
Depending on current mail flow, queries against queues and messages can return a large set of objects. You can use the advanced paging parameters to control how query results are retrieved and displayed.
When you use the Shell to view queues and the messages in the queues, your query retrieves one page of information at a time. The advanced paging parameters control the size of the result set and can also be used to sort the results. All advanced paging parameters are optional and can be combined with any one of the parameter sets that can be used with the Get-Queue and Get-Message cmdlets. If you don't specify any advanced paging parameters, the query returns the results in ascending order of identity.
By default, when a sort order is specified, the message identity property is always included and is sorted in an ascending order. This is the default ordering relationship. The message identity property is included because the other properties that can be included in a sort order aren't unique. By explicitly including the message identity property in the sort order, you can specify that the results display the message identity sorted in descending order.
You can use the BookmarkIndex and BookmarkObject parameters to mark a position in the sorted result set. If the bookmark object no longer exists when the next page of results is retrieved, the default ordering relationship makes sure that the result set starts with the closest object to the bookmark. The closest object depends on the specified sort order.
The following table describes the advanced paging parameters.
Advanced paging parameters
| Parameter | Description |
|---|---|
|
BookmarkIndex |
The BookmarkIndex parameter specifies the position in the result set where the displayed results start. The value of the BookmarkIndex parameter is a 1-based index in the total result set. If the value is less than or equal to zero, the first complete page of results is returned. If the value is set to Int.MaxValue, the last complete page of results is returned. |
|
BookmarkObject |
The BookmarkObject parameter specifies the object in the result set where the displayed results start. If you specify a bookmark object, that object is used as the point to start the search. The rows before or after that object, depending on the value of the SearchForward parameter, are retrieved. You can't combine the BookmarkObject parameter and the BookmarkIndex parameter in a single query. |
|
IncludeBookmark |
The IncludeBookmark parameter specifies whether to
include the bookmark object in the result set. By default, this
value is set to |
|
ResultSize |
The ResultSize parameter specifies the number of results to display per page. If you don't specify a value, the default result size of 1,000 objects is used. Exchange 2010 limits the result set to 250,000. |
|
ReturnPageInfo |
The ReturnPageInfo parameter is a hidden parameter. It
returns information about the total number of results and the index
of the first object of the current page. The default value is
|
|
SearchForward |
The SearchForward parameter specifies whether to search forward or backward in the result set. This parameter doesn't affect the order in which the result set is returned. It determines the direction of search relative to the bookmark index or object. If no bookmark index or object is specified, the SearchForward parameter determines whether the search starts from the first or last object in the result set. The default value for this parameter is If the SearchForward parameter is set to
|
|
SortOrder |
The SortOrder parameter specifies an array of message properties used to control the sort order of the result set. The sort order properties are specified in descending order of precedence. Each property is separated by a comma and appended with a plus sign (+) to sort in ascending order, or a minus sign (-) to sort in descending order. If an explicit sort order isn't specified by using this parameter, the records that match the query are displayed and sorted by the Identity field for the respective object type. The results are always sorted by identity in ascending order when a sort order isn't explicitly specified. |
The following code example shows how to use the advanced paging parameters in a query. In this example, the command connects to the specified server and retrieves a result set that contains 500 objects. The results are displayed in a sorted order, first in ascending order by sender address, and then in descending order of message size.
Get-message -Server Exchange.Contoso.com
-ResultSize 500 -SortOrder +FromAddress,-Size
If you want to view successive pages, you can set a bookmark for the last object retrieved in a result set and run an additional query. You must use the scripting capabilities of the Shell to perform this procedure.
The following example uses scripting to retrieve the first page of results, sets the bookmark object, excludes the bookmark object from the result set, and then retrieves the next 500 objects on the specified server.
- Open the Shell and type the following command to retrieve the
first page of results.
Copy Code$Results=Get-message -Server Exchange.Contoso.com -ResultSize 500 -SortOrder +FromAddress,-Size
- To set the bookmark object, type the following command to save
the last element of the first page to a variable.
Copy Code$temp=$results[$results.length-1]
- To retrieve the next 500 objects on the specified server and to
exclude the bookmark object, type the following command.
Copy CodeGet-message -Server Exchange.Contoso.com -BookmarkObject:$temp -IncludeBookmark $False -ResultSize 500 -SortOrder +FromAddress,-Size