Add info on how to control the Essentials Android FileProvider locations

[mattleibow]

I have been looking at this and was thinking semi-major changes needed to be done, but in fact this is doable today using all the designed features. Maybe it is a bit of effort and less automatic, but we can have a look at streamline the changes in .NET 10.

But for .NET 9, this is pretty easy, and I have a sample:

OverwriteFileProviderPaths.zip

Basically, this is a 2-step process before sharing/emailing/launching:
Add a file provider file paths override file:
Add a file named microsoft_maui_essentials_fileprovider_file_paths.xml to the Platforms\Android\Resources\xml directory such that the full, relative name to the project is:
Platforms\Android\Resources\xml\microsoft_maui_essentials_fileprovider_file_paths.xml
Set the contents to be the paths you want:

 <?xml version="1.0" encoding="UTF-8" ?>
 <paths>
    <external-path name="external_files" path="sharing-root" />
    <cache-path name="internal_cache" path="sharing-root" />
    <external-cache-path name="external_cache" path="sharing-root" />  
 </paths>

Ensure that when sharing you first move/copy/write the file you want to share into the sharing-root folder in one of the locations:

 // write into the specific sub-directory
 var dir = Path.Combine(FileSystem.CacheDirectory, "sharing-root");  
 Directory.CreateDirectory(dir);
 var file = Path.Combine(dir, "secrets.txt");
 await File.WriteAllTextAsync(file, $"Secrets: {count}"); 

 // share the file
 await Launcher.OpenAsync(new OpenFileRequest
 {
     Title = "Accidental Sharing Of Secrets",
     File = new ReadOnlyFile(file),
 });

Troubleshooting:
You can verify that the file being shared is correctly if the shared URI excludes the sharing root directory. For example, if you share the file

<CacheDirectory>/sharing-root/secrets.txt
and the shared URI is
content://com.companyname.overwritefileproviderpaths.fileProvider/internal_cache/sharing-root/secrets.txt
then the file provider is not using the correct paths, but if it is
content://com.companyname.overwritefileproviderpaths.fileProvider/internal_cache/secrets.txt
then the file paths are correct. Notice the sharing-root is missing from the path.
If you get an exception when sharing the file, then it most likely means you are sharing a file that is outside the sharing-root :

Java.Lang.IllegalArgumentException: Failed to find configured root that contains /data/data/com.companyname.overwritefileproviderpaths/cache/some-non-sharing-path/secrets.txt

This is because the file is not under one of the specified paths, but outside and the resolver will throw.

---

Associated WorkItem - 401976

[mattleibow]

This docs change is related to dotnet/maui#27685