.NET MAUI Media Picker — Gotchas & Best Practices

maui-media-picker

Guidance for picking photos/videos, capturing from camera, multi-select (.NET 10), MediaPickerOptions, platform permissions, and FileResult handling in .NET MAUI. USE FOR: "pick photo", "capture photo", "take picture", "pick video", "camera capture", "MediaPicker", "photo gallery", "image picker", "multi-select photos", "MediaPickerOptions". DO NOT USE FOR: general file picking (use maui-file-handling), image display or optimization (use maui-performance), or camera streaming (use maui-platform-invoke).

davidortinau/maui-skills·0installs173stars

SKILL.md

Full skill instructions

.NET MAUI Media Picker — Gotchas & Best Practices

Common Mistakes

1. Forgetting to check for cancellation

Single-select returns null, multi-select returns an empty list. Not checking causes NullReferenceException.

// ❌ Crashes when user cancels
var photo = await MediaPicker.Default.PickPhotoAsync();
using var stream = await photo.OpenReadAsync();

// ✅ Always check for null / empty
var photo = await MediaPicker.Default.PickPhotoAsync();
if (photo is null) return;
using var stream = await photo.OpenReadAsync();

2. Calling from a background thread

All MediaPicker methods must run on the UI thread or they throw.

// ❌ Will throw on some platforms
await Task.Run(async () => await MediaPicker.Default.PickPhotoAsync());

// ✅ Call directly from a command or event handler on the UI thread
var photo = await MediaPicker.Default.PickPhotoAsync();

3. Not checking IsCaptureSupported

Devices without cameras (emulators, some tablets) will throw if you call capture methods.

// ❌ Crashes on devices without a camera
var photo = await MediaPicker.Default.CapturePhotoAsync();

// ✅ Guard with capability check
if (MediaPicker.Default.IsCaptureSupported)
{
    var photo = await MediaPicker.Default.CapturePhotoAsync();
}

4. Not disposing streams

OpenReadAsync() returns a stream that must be disposed.

// ❌ Leaks the stream
var stream = await photo.OpenReadAsync();
var bytes = ReadAllBytes(stream);

// ✅ Dispose with using
using var stream = await photo.OpenReadAsync();

Platform Pitfalls

⚠️ SelectionLimit is not enforced on Android/Windows

MediaPickerOptions.SelectionLimit is advisory. Always validate the count yourself:

var options = new MediaPickerOptions { SelectionLimit = 5 };
var results = await MediaPicker.Default.PickPhotosAsync(options);
if (results.Count() > 5)
{
    // Warn user or take only the first 5
    results = results.Take(5);
}

⚠️ Android storage permissions split at API 33

API ≤ 32: needs READ_EXTERNAL_STORAGE / WRITE_EXTERNAL_STORAGE
API ≥ 33: needs READ_MEDIA_IMAGES / READ_MEDIA_VIDEO (broad storage permissions are ignored)
Use android:maxSdkVersion="32" on the old permissions to avoid Play Store warnings

⚠️ iOS requires all four plist keys for full functionality

Missing any one of NSCameraUsageDescription, NSMicrophoneUsageDescription, NSPhotoLibraryUsageDescription, or NSPhotoLibraryAddUsageDescription causes a runtime crash when that feature is accessed.

⚠️ Android requires `<queries>` for camera intents

Without the IMAGE_CAPTURE query in AndroidManifest.xml, CapturePhotoAsync may fail silently on Android 11+ due to package visibility restrictions.

Decision Framework

Scenario	Method
User picks one photo	`PickPhotoAsync()`
User picks multiple (.NET 10+)	`PickPhotosAsync()` with `SelectionLimit`
App needs camera capture	Check `IsCaptureSupported` → `CapturePhotoAsync()`
Save picked file permanently	Copy stream to `FileSystem.AppDataDirectory`
Need photo metadata	Set `PreserveMetaData = true` in `MediaPickerOptions`

Checklist

All picker calls run on the UI thread
Null/empty checks after every pick/capture call
IsCaptureSupported guard before capture methods
Streams disposed with using
Android manifest has both old and new storage permissions with maxSdkVersion
Android manifest has <queries> block for camera intent
iOS Info.plist has all four usage description keys
SelectionLimit validated in code, not trusted from platform

Install skill

Copy and run in your terminal

npx -y skills add https://github.com/davidortinau/maui-skills --skill maui-media-picker

View on GitHub

plugins/maui-skills/skills/maui-media-picker/SKILL.md

maui-authentication
Add authentication to .NET MAUI apps. Covers WebAuthenticator for generic OAuth 2.0 / social login, and MSAL.NET for Microsoft Entra ID (Azure AD) with broker support (Microsoft Authenticator), token caching, Conditional Access, platform-specific setup (Android, iOS, Windows), DelegatingHandler f...
0 installs
maui-geolocation
Add geolocation capabilities to .NET MAUI apps using Microsoft.Maui.Devices.Sensors. Covers one-shot and continuous location, platform permissions (Android, iOS, macOS, Windows), accuracy levels, CancellationToken usage, mock-location detection, and a DI-friendly service wrapper. USE FOR: "geoloc...
0 installs
maui-local-notifications
Add local notifications to .NET MAUI apps on Android, iOS, and Mac Catalyst. Covers notification channels, permissions, scheduling, foreground/background handling, and DI registration. Works with XAML/MVVM, C# Markup, and MauiReactor. USE FOR: "local notification", "schedule notification", "notif...
0 installs
maui-app-icons-splash
.NET MAUI app icon configuration, splash screen setup, SVG to PNG conversion at build time, composed/adaptive icons, and platform-specific icon and splash screen requirements for Android, iOS, Mac Catalyst, and Windows. USE FOR: "app icon", "splash screen", "MauiIcon", "MauiSplashScreen", "adapti...
0 installs

More skills from davidortinau

davidortinau/maui-skills

maui-aspire

Guide for .NET MAUI apps consuming .NET Aspire-hosted backend services. Covers AppHost configuration, service discovery for mobile clients, HttpClient DI setup, Entra ID authentication with MSAL.NET for calling protected APIs, development workflow (Aspire dashboard + MAUI debugging), Blazor Hybri...

173 0

View

davidortinau/maui-skills

maui-maps

Guidance for adding map controls, pins, polygons, polylines, geocoding, Google Maps API key configuration, and platform setup in .NET MAUI apps using Microsoft.Maui.Controls.Maps. USE FOR: "add map", "map control", "map pins", "polygons on map", "polylines", "geocoding", "Google Maps API key", "M...

173 0

View

davidortinau/maui-skills

maui-hybridwebview

Guidance for embedding web content in .NET MAUI apps using HybridWebView, including JavaScript–C# interop, bidirectional communication, raw messaging, and trimming/NativeAOT considerations. USE FOR: "HybridWebView", "JavaScript interop", "embed web content", "JS to C# interop", "C# to JavaScript"...

173 0

View

davidortinau/maui-skills

maui-safe-area

.NET MAUI safe area and edge-to-edge layout guidance for .NET 10+. Covers SafeAreaEdges property, SafeAreaRegions enum, per-edge control, keyboard avoidance, Blazor Hybrid CSS safe areas, migration from legacy APIs, and platform-specific behavior for Android, iOS, and Mac Catalyst. USE FOR: "safe...

173 0

View

davidortinau/maui-skills

maui-app-lifecycle

.NET MAUI app lifecycle guidance covering the four app states (not running, running, deactivated, stopped), cross-platform Window lifecycle events, backgrounding and resume behaviour, platform-specific lifecycle mapping for Android and iOS/Mac Catalyst, and state-preservation patterns. USE FOR: "...

173 0

View

davidortinau/maui-skills

maui-collectionview

Guidance for implementing CollectionView in .NET MAUI apps — data display, layouts (list & grid), selection, grouping, scrolling, empty views, templates, incremental loading, swipe actions, and pull-to-refresh. USE FOR: "CollectionView", "list view", "grid layout", "data template", "item template...

173 0

View

davidortinau/maui-skills

maui-sqlite-database

Add SQLite local database storage to .NET MAUI apps using sqlite-net-pcl. Covers data models with ORM attributes, async database service with lazy init, DI registration, WAL mode, and file management. Works with any UI pattern (XAML/MVVM, C# Markup, MauiReactor). USE FOR: "SQLite database", "loca...

173 0

View

davidortinau/maui-skills

maui-dependency-injection

Guidance for dependency injection in .NET MAUI apps — service registration, lifetime selection (Singleton/Transient/Scoped), constructor injection, automatic resolution via Shell navigation, explicit resolution patterns, platform-specific registrations, and testability best practices. USE FOR: "d...

173 0

View

davidortinau/maui-skills

maui-custom-handlers

Guide for creating custom .NET MAUI handlers, customizing existing handlers with property mappers, and implementing platform-specific native views. Covers PrependToMapping/ModifyMapping/AppendToMapping, PropertyMapper, CommandMapper, partial handler classes, and handler registration. USE FOR: "cu...

173 0

View

davidortinau/maui-skills

maui-performance

Performance optimization guidance for .NET MAUI apps covering profiling, compiled bindings, layout efficiency, image optimization, resource dictionaries, startup time, trimming, and NativeAOT configuration. USE FOR: "performance optimization", "slow startup", "app performance", "compiled bindings...

173 0

View

davidortinau/maui-skills

maui-theming

Guide for theming .NET MAUI apps—light/dark mode support, AppThemeBinding, dynamic resources, ResourceDictionary theme switching, and system theme detection. USE FOR: "dark mode", "light mode", "theming", "AppThemeBinding", "theme switching", "ResourceDictionary theme", "dynamic resources", "syst...

173 0

View

davidortinau/maui-skills

maui-accessibility

Guide for making .NET MAUI apps accessible — screen reader support via SemanticProperties, heading levels, AutomationProperties visibility control, programmatic focus and announcements, and platform-specific gotchas for TalkBack, VoiceOver, and Narrator. USE FOR: "add accessibility", "screen read...

173 0

View