TryGetFolder(Async)

[n9]

That would not fail if a folder did not exist.

Existing alternatives:

• listing all folders - unnecessarily cumbersome
• try/catch GetFolder(Async) - using exceptions in 'normal' control flow

References: https://stackoverflow.com/q/51643815

[jstedfast]

First, I want to 100% agree that recursively listing all folders and traversing the tree to find the desired folder is extremely cumbersome and I believe that that StackOverflow question that you linked to (or perhaps a similar question or feature-request on GitHub) pushed me to add the ImapClient.GetFolder(string path, ...) method, so I would definitely recommend the use of that API instead of listing all folders.

Second, I want to say that in general, I wholeheartedly agree with you that TryX() methods are wonderful and I personally always strive to use them instead of the non-Try variants whenever and wherever possible. I also hear you with regards to having to use try/catch being less than ideal in 'normal' control-flow.

That said... a few points:

1. The async paradigm doesn't mesh well with TryX methods because it does not allow out parameters, so a TryGetFolder() method could only work in a synchronous API (C# won't let you do async Task<bool> TryGetFolderAsync (string path, ... out IMailFolder folder)). That kinda sucks because I would prefer to keep the sync and async APIs a 1:1 equivalent.
2. Even if I did add an ImapClient.TryGetFolder(string path, ..., out IMailFolder folder) method, you'd still have to catch exceptions, so it's not much of a gain in terms of control-flow (you would still need to catch ImapCommandException, ImapProtocolException, ServerNotAuthenticatedException, ServerNotConnectedException, etc. unless the TryGetFolder() method caught them and returned false, but that's also not ideal because then you don't know why it failed to get the folder).
3. I make it a point to provide a CancellationToken argument to all APIs that (can) hit the network. This adds complication to any TryGetFolder(string path, CancellationToken cancellationToken, out IMailFolder folder) - I have never seen a .NET API anywhere that provides a TryX() method that also takes a cancellationToken because what should that method do if/when that cancellationToken gets cancelled? Should the exception propagate up to the caller? Should it be caught and then return false? Unfortunately, it would be a non-intuitive API and leave a lot of ambiguity.

[n9]

ad 1) Yes, the prefix "Try" is misleading. Let's name it e.g. "MayGetFolder(Async)" and it will return e.g. a (nullable) reference.

ad 2) It is not about catching the exceptions, but about the 'normal' control-flow. What is a normal situation and what is an exception.

• UC1: fetch mails from the folder (use GetFolderAsync if the folder does not exist, fail)
• UC2: check if the folder does not exist and if do not, do something else (use MayGetFolderAsync and e.g. if statement)

ad 3) Solved by a different pattern (1).