Index of every page on this site: llms.txt
All skills
davidortinau avatar

/maui-file-handling

@79bb4bf
Run it yourself

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

Use this Skill: https://skilld.dev/gh/davidortinau/maui-skills/maui-file-handling

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈156 tokens for metadata: the name and description. ≈1.1k when used: this file. ≈1.3k more on demand in 1 file.

Description uses 7.8% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈624 characters, or 7.8%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

.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

Source: SKILL.md on GitHub

No rule matched.

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No alerts2mo4 checks · Risk SAFE
  • Gen Agent Trust Hub2mo

    This skill provides educational guidance and API references for handling files in .NET MAUI applications across various platforms (Android, iOS, macOS, Windows). It covers best practices for using the FilePicker, platform-specific path handling, and managing app data directories. No malicious patterns or security risks were detected.

  • Socket2mo

    No alerts

  • Snyk2mo

    Risk: LOW · No issues

  • Runlayer8mo

    1 file scanned · No issues

Signed by skilld at 79bb4bf. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub last month.

Steadyupdated 8 months ago

README badge

README badge for davidortinau/maui-skills/maui-file-handling