Maui File Handling

.NET MAUI File Handling

Critical: Always Use OpenReadAsync(), Not FullPath

Some platforms (especially Android) return content URIs, not file system paths. Reading FullPath directly will throw or return empty data.

// ❌ Breaks on Android — FullPath may be a content:// URI
var result = await FilePicker.Default.PickAsync();
var bytes = File.ReadAllBytes(result.FullPath);

// ✅ Works on all platforms
var result = await FilePicker.Default.PickAsync();
if (result is not null)
{
    using var stream = await result.OpenReadAsync();
    // process stream
}

---

Platform File-Type Format Gotcha

Each platform uses a different format for custom FilePickerFileType. Mixing them up causes the picker to show no files or crash.

// ❌ Using file extensions for Android — picker shows nothing
{ DevicePlatform.Android, new[] { ".json", ".txt" } }

// ✅ Correct MIME types for Android
{ DevicePlatform.Android, new[] { "application/json", "text/plain" } }

---

Common Pitfalls

Bundled files are read-only

Resources/Raw assets cannot be modified at runtime. Attempting to write throws an exception (or silently fails on some platforms).

// ❌ Trying to write to a bundled file
var path = "data.json"; // inside Resources/Raw
File.WriteAllText(path, newContent); // fails

// ✅ Copy to AppDataDirectory first, then modify
string targetPath = Path.Combine(FileSystem.Current.AppDataDirectory, "data.json");
if (!File.Exists(targetPath))
{
    using var source = await FileSystem.Current.OpenAppPackageFileAsync("data.json");
    using var dest = File.Create(targetPath);
    await source.CopyToAsync(dest);
}
// Now safe to read/write targetPath

Bundled subdirectories are flattened

On some platforms, Resources/Raw/subdir/file.txt becomes just file.txt. Use unique file names regardless of subdirectory structure.

iOS sandbox path changes on rebuild

The iOS sandbox path includes an app GUID that changes across clean builds. Hard-coded absolute paths break silently.

// ❌ Hard-coded path — breaks after clean rebuild
var path = "/var/mobile/.../Documents/data.json";

// ✅ Always use the FileSystem helper
var path = Path.Combine(FileSystem.Current.AppDataDirectory, "data.json");

Android: bundled stream has no Length

OpenAppPackageFileAsync may return a stream where .Length throws NotSupportedException. Copy to a MemoryStream if you need the size.

// ❌ Throws on Android
using var stream = await FileSystem.Current.OpenAppPackageFileAsync("data.json");
var size = stream.Length; // NotSupportedException

// ✅ Copy first if you need the length
using var stream = await FileSystem.Current.OpenAppPackageFileAsync("data.json");
using var ms = new MemoryStream();
await stream.CopyToAsync(ms);
var size = ms.Length;

Windows: virtualized file system

Packaged apps silently redirect writes to classic paths like %AppData%. Always use AppDataDirectory and CacheDirectory for reliable cross-platform paths.

FilePicker returns null on cancellation

// ❌ NullReferenceException when user cancels
var result = await FilePicker.Default.PickAsync();
using var stream = await result.OpenReadAsync();

// ✅ Always null-check
var result = await FilePicker.Default.PickAsync();
if (result is null) return;
using var stream = await result.OpenReadAsync();

---

Android Permissions (API 33+ change)

Android 13 replaced READ_EXTERNAL_STORAGE with granular media permissions. Using the old permission on API 33+ silently grants nothing.

---

Checklist

• [ ] Use OpenReadAsync() — never read FullPath directly
• [ ] Null-check FilePicker result before accessing properties
• [ ] Custom FilePickerFileType uses correct format per platform (MIME / UTType / extension)
• [ ] Bundled files copied to AppDataDirectory before modification
• [ ] Unique file names in Resources/Raw (subdirectories are flattened)
• [ ] Android manifest declares correct permission for target API level
• [ ] macOS: App Sandbox entitlement includes file access

File Handling API Reference

FilePicker API

Use FilePicker.Default to let users select files from the device.

Single file

var result = await FilePicker.Default.PickAsync(new PickOptions
{
    PickerTitle = "Select a file",
    FileTypes = FilePickerFileType.Images
});

if (result is not null)
{
    using var stream = await result.OpenReadAsync();
    // process stream
}

Multiple files

var results = await FilePicker.Default.PickMultipleAsync(new PickOptions
{
    PickerTitle = "Select files",
    FileTypes = FilePickerFileType.Videos
});

foreach (var file in results)
{
    // file.FileName, file.FullPath, file.ContentType
}

PickOptions

FilePickerFileType

Built-in types

• FilePickerFileType.Images — common image formats
• FilePickerFileType.Png — PNG only
• FilePickerFileType.Jpeg — JPEG only
• FilePickerFileType.Videos — common video formats
• FilePickerFileType.Pdf — PDF files

Custom per-platform type

var customFileType = new FilePickerFileType(
    new Dictionary<DevicePlatform, IEnumerable<string>>
    {
        { DevicePlatform.Android, new[] { "application/json", "text/plain" } },   // MIME types
        { DevicePlatform.iOS, new[] { "public.json", "public.plain-text" } },     // UTTypes
        { DevicePlatform.macOS, new[] { "public.json", "public.plain-text" } },   // UTTypes
        { DevicePlatform.WinUI, new[] { ".json", ".txt" } }                       // file extensions
    });

FileResult

Returned by PickAsync and PickMultipleAsync.

FileSystem Helpers

Access via FileSystem.Current.

Directory paths

Reading bundled files

using var stream = await FileSystem.Current.OpenAppPackageFileAsync("data.json");
using var reader = new StreamReader(stream);
string contents = await reader.ReadToEndAsync();

Bundled Files (Resources/Raw)

Place files in the Resources/Raw folder. They receive the MauiAsset build action automatically.

• Files are read-only at runtime.
• Access via OpenAppPackageFileAsync("filename.ext").
• Subdirectories are flattened on some platforms—use unique file names.

Copy bundled file to writable location

public async Task<string> CopyToAppDataAsync(string filename)
{
    string targetPath = Path.Combine(FileSystem.Current.AppDataDirectory, filename);

    if (!File.Exists(targetPath))
    {
        using var source = await FileSystem.Current.OpenAppPackageFileAsync(filename);
        using var dest = File.Create(targetPath);
        await source.CopyToAsync(dest);
    }

    return targetPath;
}

Permissions

Android

Declare in Platforms/Android/AndroidManifest.xml. Request at runtime with Permissions.RequestAsync<Permissions.StorageRead>() or the granular media permissions.

iOS

• FilePicker works without special permissions for on-device files.
• For iCloud access, enable the iCloud capability and configure entitlements.

macOS (Mac Catalyst)

• Enable App Sandbox entitlements.
• Grant com.apple.security.files.user-selected.read-only (or read-write) for picker access.

Windows

• Packaged apps have full picker access without extra declarations.

Platform Path Differences