|EwsDownloadFolderByFullName Method (String, Int32)|
public EwsFolder DownloadFolderByFullName( string folderFullName, int recursionLevel )
Public Function DownloadFolderByFullName ( folderFullName As String, recursionLevel As Integer ) As EwsFolder
To delimit levels of hierarchy in the folder name, use the same character which is set by FolderLevelDelimiter property. By default, it's '/' (forward slash).
|This overload exists only for optimization purposes when dealing with very complex and deeply nested folder hierarchies in Exchange accounts.|
Scanning the entire folder tree is an expensive operation. If your Exchange account has thousands of folders, this method can be used as an optimization. While DownloadFolderByFullName(string) overload internally downloads the entire folder tree in a single call (this can time out with complex hierachies), the current overload makes multiple queries, one per hierarchy level. Each query returns only the folder on the current level, not going deeply.
So, it will find "Inbox" in the message root, then will search "Inbox" folder for "Nested folder", and finally will search "Nested folder" for "Deeply nested folder". This approach is much eaiser for the server and produces less traffic. The drawback is that multiple requests to the server needed instead of a single one. If you have deeply nested folders, the number of queries can become very high.
At the same time, the value of reducing load on the server with making "flat" searches instead of "deep traversal" diminishes with every level of hierarchy. If you, let's say, have 15625 folders on 6th level of hierarchy (each folder contains 5 sub-folders, the formula is 5x5x5x5x5x5), you'll typically have 125 lowest-level subfolders in Level 3 folders. It would be a disaster to search through 15625 in a single query but 125 is another deal. Normally, we'd need 6 queries for each of 6 levels but we can make 3 flat queries to get on Level 3 and then one deep-traversal query over the remaining 125 folders down the road. 4 queries instead of 6.
recursionLevel provides tradeoff between request complexity and number of requests. If you set it to 3 (or any larger value), then in the current example we'll do 3 queries, like shown above. However, if you set it to, let's say, 2, it will do only two queries. The first will search message root for "Inbox" while the second query will load the entire sub-tree of "Inbox" folder. If your entire account has hundreds of folders but Inbox particularly has not so many sub-folders (although they can be nested quite deeply), you'll get signifacant performance benefit.
The most optimal value of recursionLevel depends on the folder structure of a particular account but the value of 3 can be a good starting point.
Another method of optimization is using DownloadFolderByFullName(FolderId, string) overload (it lets you specify the containing folder under which tree to perform deep search).