maui-file-handling

name

maui-file-handling

description

Guidance for file picker, file system helpers, bundled assets, and app data storage in .NET MAUI applications. Covers FilePicker APIs, FileResult handling, platform permissions, and common pitfalls across Android, iOS, macOS, and Windows. USE FOR: "file picker", "FilePicker", "pick file", "open file", "save file", "bundled assets", "FileSystem helpers", "AppDataDirectory", "CacheDirectory", "FileResult", "read file MAUI". DO NOT USE FOR: media capture or photo picking (use maui-media-picker), secure credential storage (use maui-secure-storage), or SQLite database files (use maui-sqlite-database).

.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.

Platform	Format	Example
Android	MIME types	"application/json"
iOS / macOS	UTType identifiers	"public.json"
Windows	Dot-prefixed extensions	".json"

// ❌ 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.

Android version	Required permission
≤ 12 (API 32)	READ_EXTERNAL_STORAGE
≥ 13 (API 33)	READ_MEDIA_IMAGES, READ_MEDIA_VIDEO, READ_MEDIA_AUDIO

---

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