.NET MAUI Local Notifications

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

davidortinau/maui-skills·0installs173stars

SKILL.md

Full skill instructions

.NET MAUI Local Notifications

Implementation overview

Define cross-platform INotificationManagerService interface and event args
Implement Android notification service (channel, AlarmManager, BroadcastReceiver)
Implement iOS/Mac Catalyst notification service (UNUserNotificationCenter)
Register platform implementations via DI
Configure platform permissions and MainActivity

See references/local-notifications-api.md for full implementation code.

Platform gotchas

Android

Issue	Fix
Notifications silently fail on API 33+	Must request `POST_NOTIFICATIONS` runtime permission first
`PendingIntent` crash on Android 12+	Must include `PendingIntentFlags.Immutable` for API 31+
Scheduled notifications lost on reboot	`AlarmManager` does not survive device restart — re-schedule on boot via `BOOT_COMPLETED` receiver
No notification appears	Channel not created — required on API 26+ (Android 8.0)
Notification tap doesn't return to app	`LaunchMode = LaunchMode.SingleTop` must be set on `MainActivity`

// ✅ Correct — API 31+ requires Immutable flag
var pendingIntentFlags = (Build.VERSION.SdkInt >= BuildVersionCodes.S)
    ? PendingIntentFlags.CancelCurrent | PendingIntentFlags.Immutable
    : PendingIntentFlags.CancelCurrent;

// ❌ Wrong — crashes on Android 12+
var pendingIntentFlags = PendingIntentFlags.CancelCurrent;

iOS / Mac Catalyst

Issue	Fix
No notification prompt appears	Permission already denied — user must re-enable in Settings
Foreground notifications don't show	Must implement `UNUserNotificationCenterDelegate` and set `Current.Delegate`
Notification shows `Alert` not `Banner`	Use `UNNotificationPresentationOptions.Banner` on iOS 14+

// ✅ iOS 14+ — use Banner
completionHandler(OperatingSystem.IsIOSVersionAtLeast(14)
    ? UNNotificationPresentationOptions.Banner
    : UNNotificationPresentationOptions.Alert);

// ❌ Always using Alert — deprecated on iOS 14+
completionHandler(UNNotificationPresentationOptions.Alert);

Windows

⚠️ Windows App SDK supports toast notifications but scheduled notifications are not yet supported. Immediate notifications work.

DI registration — platform-specific only

// ✅ Must use #if guards — there's no cross-platform implementation
#if ANDROID
    builder.Services.AddTransient<INotificationManagerService,
        Platforms.Android.NotificationManagerService>();
#elif IOS
    builder.Services.AddTransient<INotificationManagerService,
        Platforms.iOS.NotificationManagerService>();
#elif MACCATALYST
    builder.Services.AddTransient<INotificationManagerService,
        Platforms.MacCatalyst.NotificationManagerService>();
#endif

Common anti-patterns

// ❌ Sending without checking permission — silent failure on API 33+
notificationManager.SendNotification("Title", "Body");

// ✅ Request permission first
#if ANDROID
var status = await Permissions.RequestAsync<Platforms.Android.NotificationPermission>();
if (status != PermissionStatus.Granted) return;
#endif

// ❌ Updating UI directly from notification callback — cross-thread exception
notificationManager.NotificationReceived += (s, e) =>
    myLabel.Text = ((NotificationEventArgs)e).Title;

// ✅ Marshal to UI thread
notificationManager.NotificationReceived += (s, e) =>
    MainThread.BeginInvokeOnMainThread(() =>
        myLabel.Text = ((NotificationEventArgs)e).Title);

Decision framework

Need	Approach
Immediate notification	`SendNotification(title, message)` with `null` notifyTime
Scheduled reminder	`SendNotification(title, message, DateTime.Now.AddMinutes(30))`
Persist across reboot (Android)	Add `BOOT_COMPLETED` receiver to re-schedule alarms
Rich notifications (images, actions)	Extend platform implementations with native APIs
Push notifications from server	Use a different pattern entirely (FCM/APNs)

Quick checklist

Cross-platform INotificationManagerService interface defined
Android: notification channel created (API 26+)
Android: POST_NOTIFICATIONS permission in manifest + runtime request (API 33+)
Android: PendingIntentFlags.Immutable used (API 31+)
Android: MainActivity has LaunchMode.SingleTop and handles OnNewIntent
iOS: UNUserNotificationCenterDelegate set for foreground display
iOS: Banner used instead of Alert on iOS 14+
DI registration uses #if platform guards
UI updates from notification callbacks use MainThread.BeginInvokeOnMainThread

Install skill

Copy and run in your terminal

npx -y skills add https://github.com/davidortinau/maui-skills --skill maui-local-notifications

View on GitHub

plugins/maui-skills/skills/maui-local-notifications/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-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
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...
0 installs

More skills from davidortinau

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

.NET MAUI runtime permissions guidance — checking and requesting permissions, PermissionStatus handling, custom permissions via BasePlatformPermission, platform-specific manifest/plist declarations, and DI-friendly service patterns. USE FOR: "request permission", "check permission", "PermissionSt...

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