Add FileSaverResult and FolderPickerResult, Fix Initial folder on Android

[VladislavAntonyuk]

Description of Change

Add new safe methods that return result instead of throwing exception.
A;so fixes initial path on Android

PR Checklist

• Has a linked Issue, and the Issue has been approved(bug) or Championed (feature/proposal)
• Has tests (if omitted, state reason in description)
• Has samples (if omitted, state reason in description)
• Rebased on top of main at time of PR
• Changes adhere to coding standard
• Documentation created or updated: FileSaverResult and FolderPickerResult MicrosoftDocs/CommunityToolkit#234

Additional information

[pictos]

@VladislavAntonyuk I've a couple of requests and suggestions (:

[brminnick]

Thanks Vlad! Just a thought about adding an .EnsureSuccess() method, similar to HttpResponseMethod.EnsureSuccessStatusCode()

[brminnick]

Hey Vlad! After giving this some thought, let's re-write the existing SaveAsync() methods' behavior instead of creating new SaveSafeAsync() APIs.

I know it's a breaking change, but having one API that returns FIleSaverResult / FolderPickerResult is a better API surface in the long run for our developers to consume, and it's less confusing for developers who would be trying to figure out the difference between SaveAsync() and SaveSafeAsync() and when to choose one vs the other.

Plus, we have to bump our major version for our next release anyways because of a breaking change we've already merged in a different PR.

Here's what I'm thinking:

• Move logic from SaveSafeAsync() methods to SaveAsync()
• Remove the SaveSafeAsync() methods

Does that make sense?

For example, FileSaver.SaveAsync() would look like this:

public Task<FileSaverResult> SaveAsync(string fileName, Stream stream, CancellationToken cancellationToken)
{
   try
   {
 	  cancellationToken.ThrowIfCancellationRequested();
 	  // existing SaveAsync logic here
 	  return new FileSaverResult(path, null);
   }
   catch (Exception e)
   {
 	  return new FileSaverResult(null, e);
   }
}

[brminnick]

Hey Vlad! What do you think about making changing FolderSaverImplementation and FileSaverImplementation from public to internal?

public sealed partial class FolderSaverImplementation -> sealed partial class FolderSaverImplementation
public sealed partial class FileSaverImplementation -> sealed partial class FileSaverImplementation

I think it might be confusing to devs to see both FolderSaver and FolderSaverImplementation in the docs/intellisense. Plus, we can always make them public later without causing a breaking change.

We'd also have to remove the example from the sample app that demonstrates new *Implemetation().

[pictos]

@brminnick those are publics because they live on Core, we shouldn't have internal there, since it's intended to be used for other libs or future toolkits

[brminnick]

@pictos Good point 💯

Requested changed addressed

[brminnick]

Thanks Vlad!!

[brminnick]

@bijington Are you able to help update the docs for this PR? I've added do not merge Do not merge this PR and pending documentation This feature requires documentation for now to ensure we update the docs.

We modified the return Type of IFileSaver.SaveAsync() + IFolderPicker.PickAsync():

Modified APIs

public interface IFileSaver
{
  Task<FileSaverResult> SaveAsync(string initialPath, string fileName, Stream stream, CancellationToken cancellationToken);
  Task<FileSaverResult> SaveAsync(string fileName, Stream stream, CancellationToken cancellationToken);
}

public class FileSaver
{
  Task<FolderPickerResult> PickAsync(string initialPath, CancellationToken cancellationToken);
  Task<FolderPickerResult> PickAsync(CancellationToken cancellationToken);
}

^@jfversluis FYI - these are breaking changes that we'll need to note in our release notes for v5.0.0

[VladislavAntonyuk]

@brminnick , @bijington updated docs MicrosoftDocs/CommunityToolkit#234