Get-MapiTree

Description

This cmdlet retrieves the subtree of a specified folder.

Syntax
Note: Parameters in orange are optional.
Get-MapiProp
-SessionMapiObject
-CommonFolderPowerMapi.CommonFolders
-ShowFullPathsSwitchParameter
-PathDelimiterString
-DoNotIndentFolderNamesSwitchParameter
-ImmediateChildrenOnlySwitchParameter
Get-MapiProp
-SessionMapiObject
-FolderIDMapiObject
-ShowFullPathsSwitchParameter
-PathDelimiterString
-DoNotIndentFolderNamesSwitchParameter
-ImmediateChildrenOnlySwitchParameter
Get-MapiProp
-SessionMapiObject
-FolderPathString
-ShowFullPathsSwitchParameter
-PathDelimiterString
-DoNotIndentFolderNamesSwitchParameter
-ImmediateChildrenOnlySwitchParameter
Get-MapiProp
-StoreMapiObject
-CommonFolderPowerMapi.CommonFolders
-ShowFullPathsSwitchParameter
-PathDelimiterString
-DoNotIndentFolderNamesSwitchParameter
-ImmediateChildrenOnlySwitchParameter
Get-MapiProp
-StoreMapiObject
-FolderIDMapiObject
-ShowFullPathsSwitchParameter
-PathDelimiterString
-DoNotIndentFolderNamesSwitchParameter
-ImmediateChildrenOnlySwitchParameter
Get-MapiProp
-StoreMapiObject
-FolderPathString
-ShowFullPathsSwitchParameter
-PathDelimiterString
-DoNotIndentFolderNamesSwitchParameter
-ImmediateChildrenOnlySwitchParameter
Get-MapiProp
-ParentFolderMapiObject
-ShowFullPathsSwitchParameter
-PathDelimiterString
-DoNotIndentFolderNamesSwitchParameter
-ImmediateChildrenOnlySwitchParameter
Parameters
SessionA Mapi.NET.Session object from which the specified folder is selected, from the session's default store.
StoreA Mapi.NET.Store object from which the specified folder is selected.
ParentFolderA Mapi.NET.Folder object for which the subtree is retrieved.
CommonFolderOne of the values from the PowerMapi.CommonFolders enumeration for which the subtree is retrieved.
FolderIDA Mapi.NET.EntryID of a specific folder in Store or Session's default store for which the subtree is retrieved.
FolderPathA String which is the full folder path in Store or Session's default store for which the subtree is retrieved.
ShowFullPathsA SwitchParameter which, if present, will cause the cmdlet to return full folder paths.
PathDelimiterA String value which is used as the folder separator in the returned paths. This parameter is also used when using the FolderPath parameter.
DoNotIndentFolderNamesA SwitchParameter which, if present, will cause the cmdlet to not indent folder names based on the folder's depth.
ImmediateChildrenOnlyA SwitchParameter which, if present, will cause the cmdlet to only list the specified folder's immediate chidren.
Remarks

 

This cmdlet is used to list the subfolders of a specified folder, either the entire subtree, or it's immediate children.

This cmdlet does not "open" each child folder and as such no concern about maximum open objects is necessary.  This cmdlet uses MAPI's internal method to get the Hierarchy Table for a specific folder, of which the internal results are a table of information.  Get-MapiTree converts the results of the returned hierarchy table to usable PowerMapi objects.

The list of objects returned by this cmdlet are a list of MapiObject<Mapi.NET.EntryID> objects with the folder's name or path and it's depth in the tree.  The objects in the list can be passed to any other PowerMapi cmdlet that expects the EntryID of a folder.

Not only can this cmdlet produce a formatted tree structure of the subfolders, the resulting list can be used to enumerate a subtree in order to do automated processing against many folders.  It is quite common that Get-MapiTree is used with Get-MapiFolder in a loop.

Note that the default PathDelimiter value is "/".  Many of Microsoft's cmdlets for Exchange use ""; adjust the PathDelimiter parameter as appropriate for the intended use.  Furthermore, PowerMapi handles cases of a folder name containing the PathDelimiter simply by doubling the value in the folder name.  For example, if a folder is named 'Up/Down' and the PathDelimiter is left as default, the returned path for that folder will be 'Parent/Up//Down'. 

The FolderPath parameter also follows the double-delimiter-escape rule.  If a folder path is to be used, and any folder has the delimiter in its name, that value must be doubled before passing to the cmdlet.

Note that there is not a property in MAPI on a folder that can report the total number of folders in the subtree.  As such, if the selected folder's subtree is very large, it may take many seconds to minutes to produce the entire tree.  However, the design of this cmdlet is such that subfolder elements are returned on the pipeline as soon as possible; the processing of the subtree can be canceled by CTRL+C at any time.