Get-MapiContents

Description

This cmdlet retrieves a listing of items from a specific folder and optionally its subfolders.

Syntax

Note: Parameters in orange are optional.

Get-MapiContents
-FolderMapiObject<Mapi.NET.Folder>
-ItemTypesToGetPowerMapi.Commands.GetMapiContents.ItemTypes
-PropertiesToGetMapi.NET.Tags[]
-RowRequestCountInt32
-RecurseSwitchParameter
-FirstInt32
-SkipInt32

 

Parameters
FolderA Mapi.NET.Folder object from which to list its items
ItemTypesToGetOne of the values from the PowerMapi.Commands.GetMapiContents.ItemTypes enumeration:
  • Normal
  • Associated
  • SoftDeleted
If omitted, the cmdlet defaults to Normal
PropertiesToGetAn array of one or more Mapi.NET.Tags values that represent the attributes to retrieve into the resulting output. If omitted, the cmdlet defaults to the following properties: Mapi.NET.Tags.PR_LONGTERM_ENTRYID_FROM_TABLE and Mapi.NET.Tags.PR_SUBJECT. See remarks for more detail.
RowRequestCountAn Int32 value with indicates the max number of rows of items to pull in the background. If omitted, the default value is 20. See remarks for more detail.
RecurseA switch parameter, which if present, causes the cmdlet to enumerate items from the Folder's subtree.
FirstAn Int32 value that represents the maximum number of items to return, or all items if there are fewer than First
SkipAn Int32 value that represents the number of items to skip over before outputting data.
Remarks

This cmdlet retrieves a list of items from the selected folder, and optionally it's child folders.  This cmdlet is very lightweight in that it only works off the internal MAPI table methods.  In contrast, Get-MapiItem will generate an instance of each object which in turn is a connection to the store and for which there are limits as to how many "open" objects a MAPI session may have.  Get-MapiContents does not open individual items and as such can return lists of 100s or 1000s of items without issue.

This cmdlet works calling a folder's internal GetContentsTable and converting each returned table row to a Powershell object.  MAPI's internal method allows for a value to be passed as the maximum row count to return for each call and is represented in this cmdlet by the RowRequestCount parameter.  If a folder has 100 items and the RowRequestCount is 20 (the default), this will mean 5 round trips between the cmdlet and the message store in order to pull all 100 items.  The RowRequestCount value does not limit how many items the cmdlet will return, only how many are in each "page" of requests to the store.

Higher requested row counts are allowed, but there is a memory size limit that can prevent a high row count from returning.  Twenty (20) rows is a recommended value as a balance between round trips and speed.  However, for small tables and for which only one or 2 properties are being requested, it may be valuable to increase the RowRequestCount so as to reduce the round trips.

ItemTypes:  This cmdlet allows for retrieval of items that can be of one of the three types: Normal, Associated, or SoftDeleted.

A Normal item is one that is visible in the folder to an end user.

An Associated item is one that is not visible to an end user and is often used to store configuration, settings, or other non-user information on a per-folder basis.  Outlook and Exchange use these items to store, for example, Out-of-office and Inbox rules.  It is possible to store script or application specific information on folders that can be inspected each time the application or script is executed.  Furthermore, because Associated items are part of the folder, those items move or are copied when the folder is moved or copied.

SoftDeleted items are those typically found in Microsoft Exchange message stores in the "Deleted Retention" area of a folder; note that this is not the same as items that get moved to the "Deleted Items" folder.  These are items that have been marked for deletion to be purged based on the message store's retention policy.  A user can SoftDelete items by deleting items from their "Deleted Items" folder, or by holding the SHIFT key when deleting items.

Note that PST files do not have deleted retention concepts.

The PropertiesToGet array indicate the properties, and order, to retrieve for items in the resulting output.  Note that not all properties can be retrieved, especially attachment and recipient details as those exist in secondary tables on each item.  Furthermore, most message stores limit the amount of data that is returned in any "column" of about 256 characters/bytes.  As such, requesting the body of a message may be truncated if requested.  

There is a total byte size limit for MAPI table calls.  If too many properties are requested, and the RowRequestCount is too high, the entire table call can fail as the resulting size of the data stream to be returned exceeds the max buffer size.  Such limits are not concretely documented and vary between versions of Exchange and MAPI.  It is best to use a model of asking for only those properties necessary upon which to make decisions, then to use Get-MapiItem to open the object and gain access to all of its attributes.

The Recurse option of this cmdlet allows for the enumeration of the selected folder's subtree, listing contents from each child folder.  Note that caution should be had with Recurse since it is possible to discover that a folder, including its subfolders, may contain may 1000s of items, causing the resulting list to be quite large and consuming much memory.