Edit

Share via

File picker

  • Article

Browse sample. Browse the sample

This article describes how you can use the .NET Multi-platform App UI (.NET MAUI) IFilePicker interface. With the IFilePicker interface, you can prompt the user to pick one or more files from the device.

The default implementation of the IFilePicker interface is available through the FilePicker.Default property. Both the IFilePicker interface and FilePicker class are contained in the Microsoft.Maui.Storage namespace.

Get started

To access the FilePicker functionality, the following platform specific setup is required.

If your app targets Android 12 or lower, you must request the READ_EXTERNAL_STORAGE permission. If your app targets Android 13 or higher and needs access to files that other apps have created, you must request one or more of the following granular permissions instead of the READ_EXTERNAL_STORAGE permission:

  • READ_MEDIA_IMAGES
  • READ_MEDIA_VIDEO
  • READ_MEDIA_AUDIO

These permissions can be added in the following ways:

  • Add the assembly-based permission:

    Open the Platforms/Android/MainApplication.cs file and add the following assembly attributes after using directives:

    [assembly: UsesPermission(Android.Manifest.Permission.ReadExternalStorage, MaxSdkVersion = 32)]
[assembly: UsesPermission(Android.Manifest.Permission.ReadMediaAudio)]
[assembly: UsesPermission(Android.Manifest.Permission.ReadMediaImages)]
[assembly: UsesPermission(Android.Manifest.Permission.ReadMediaVideo)]

    - or -

  • Update the Android Manifest:

    Open the Platforms/Android/AndroidManifest.xml file and add the following in the manifest node:

    <uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" android:maxSdkVersion="32" />
<!-- Required only if your app needs to access images or photos that other apps created -->
<uses-permission android:name="android.permission.READ_MEDIA_IMAGES" />
<!-- Required only if your app needs to access videos that other apps created -->
<uses-permission android:name="android.permission.READ_MEDIA_VIDEO" />
<!-- Required only if your app needs to access audio files that other apps created -->
<uses-permission android:name="android.permission.READ_MEDIA_AUDIO" />

    - or -

  • Update the Android Manifest in the manifest editor:

    In Visual Studio double-click on the Platforms/Android/AndroidManifest.xml file to open the Android manifest editor. Then, under Required permissions check the permissions listed above. This will automatically update the AndroidManifest.xml file.

Important

All methods must be called on the UI thread because permission checks and requests are automatically handled by .NET MAUI.

Pick a file

The PickAsync method prompts the user to pick a file from the device. Use the PickOptions type to specify the title and file types allowed with the picker. The following example demonstrates opening the picker and processing the selected image:

public async Task<FileResult> PickAndShow(PickOptions options)
{
    try
    {
        var result = await FilePicker.Default.PickAsync(options);
        if (result != null)
        {
            if (result.FileName.EndsWith("jpg", StringComparison.OrdinalIgnoreCase) ||
                result.FileName.EndsWith("png", StringComparison.OrdinalIgnoreCase))
            {
                using var stream = await result.OpenReadAsync();
                var image = ImageSource.FromStream(() => stream);
            }
        }

        return result;
    }
    catch (Exception ex)
    {
        // The user canceled or something went wrong
    }

    return null;
}

Default file types are provided with FilePickerFileType.Images, FilePickerFileType.Png, and FilePickerFilerType.Videos. You can specify custom file types per platform, by creating an instance of the FilePickerFileType class. The constructor of this class takes a dictionary that is keyed by the DevicePlatform type to identify the platform. The value of the dictionary key is a collection of strings representing the file types. For example here's how you would specify specific comic file types:

var customFileType = new FilePickerFileType(
                new Dictionary<DevicePlatform, IEnumerable<string>>
                {
                    { DevicePlatform.iOS, new[] { "public.my.comic.extension" } }, // UTType values
                    { DevicePlatform.Android, new[] { "application/comics" } }, // MIME type
                    { DevicePlatform.WinUI, new[] { ".cbr", ".cbz" } }, // file extension
                    { DevicePlatform.Tizen, new[] { "*/*" } },
                    { DevicePlatform.macOS, new[] { "cbr", "cbz" } }, // UTType values
                });

PickOptions options = new()
{
    PickerTitle = "Please select a comic file",
    FileTypes = customFileType,
};

Searching for files based on the file type may be different from one platform to the other. For more information, see Platform differences.

Pick multiple files

If you want the user to pick multiple files, call the FilePicker.PickMultipleAsync method. This method also takes a PickOptions parameter to specify additional information. The results are the same as PickAsync, but instead of the FileResult type returned, an IEnumerable<FileResult> type is returned with all of the selected files.

Tip

The FullPath property doesn't always return the physical path to the file. To get the file, use the OpenReadAsync method.

Platform differences

This section describes the platform-specific differences with the file picker.

The PickOptions.PickerTitle is displayed on the initial prompt to the user, but not in the picker dialog itself.

When filtering files by type, use the file's MIME type. For a list of MIME types, see Mozilla - Common MIME types.