EwsDownloadFolderByFullName Method (String, Int32)
Gets the reference to the folder denoted by its full name in the MS Exchange account.

Namespace: MailBee.EwsMail
Assembly: MailBee.NET (in MailBee.NET.dll) Version: 12.2.0 build 630 for .NET 4.5
public EwsFolder DownloadFolderByFullName(
	string folderFullName,
	int recursionLevel


Type: SystemString
The full folder name, such as "Inbox/Nested folder/Deeply nested folder". Null reference (Nothing in Visual Basic) or empty string not allowed.
Type: SystemInt32
Specifies how many levels of folder hierarchy to scan in shallow mode before switching to deep traversal mode. If 0, the entire account will be searched in a single operation (deep traversal). Higher values increase the number of search queries to the server but make each query more lightweight. Negative values not allowed.

Return Value

Type: EwsFolder
The EwsFolder object if the folder exists; otherwise, a null reference (or if an error occurred and ThrowExceptions is false).
MailBeeExceptionAn error occurred and ThrowExceptions is true.
NotImplementedExceptionThe .NET runtime is .NET Core.

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).

Note Note
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).

Note Note
This method is not implemented in .NET Core. Use DownloadFolderByFullNameAsync(String, Int32) instead.
See Also