Note: Parameters in orange are optional.
|Store||A Mapi.NET.Store object from which to retrieve items|
|Folder||A Mapi.NET.Folder object from which to retrieve items|
|EntryID||One or more Mapi.NET.EntryID objects each being the identifier of an item in the message store of either the Store or Folder object.|
|First||An Int32 value which indicates the maximum number of items to open and return.|
|Skip||An Int32 value with indicates the number of items to skip over before items are opened and returned.|
|SuppressWarnings||A switch parameter, which if present, prevents the display of the warning message when not supplying one or more EntryIDs|
This cmdlet is used to open specific items in a message store.
Note that "opening" and item means that a connection and handle is created for the item and creates a sort of "view" of an item in a message store. This is different than the results of Get-MapiContents, where that cmdlet simply returns property values about items.
MAPI message stores have limits on the number of "open" objects that may exist concurrently. Attempting to open 100s of objects in a message store will often fail as the quota is exceeded. Powermapi takes special care to release objects when they go out of scope, but a more deterministic approach is recommended whereby "opened" objects should be placed in variables and "released" when no longer needed.
An opened object can be released by calling the Dispose method available on such objects: object.MapiObject.Dispose().
If working on items in a loop, it is recommended to process work on items inside the loop, calling Dispose after each task on an item has completed.
When using the EntryID parameter, these values can be retrieve as the output of Get-MapiContents - this cmdlet is designed to naturally consume its output without modification.
The EntryID list can also be manually set as a list of string values. PowerMAPI has internal conversion functions that can convert a hex string representation of a MAPI EntryID to an EntryID object for use in cmdlets. This can be useful for cases where the item identifiers are being pulled from another system, CSV file, or data location.
Note that a MAPI EntryID for Exchange message stores are unique for the item AND its location. If an item is moved from one folder to another, that item's EntryID changes and a previously saved EntryID would then be invalid.
This cmdlet supports paging parameters (First and Skip) in order to select one or more items in a range. This becomes quickly convenient for selecting the first item in a folder (-First 1) or selecting a few items after skipping several.