maui-platform-invoke

name

maui-platform-invoke

description

Guidance for calling platform-specific native APIs from .NET MAUI apps. Covers partial classes, conditional compilation, multi-targeting configuration, and dependency injection patterns for cross-platform code that needs Android, iOS, Mac Catalyst, or Windows functionality. USE FOR: "platform-specific code", "conditional compilation", "partial class", "#if ANDROID", "#if IOS", "multi-targeting", "native API call", "platform invoke", "platform-specific DI", "DeviceInfo.Platform". DO NOT USE FOR: custom control handlers (use maui-custom-handlers), permission requests (use maui-permissions), or dependency injection patterns (use maui-dependency-injection).

Platform Invoke — Gotchas & Best Practices

Decision Framework

Scenario	Approach
1–5 lines, one-off check	#if ANDROID conditional compilation
Service with logic, testable	Partial classes in Platforms/ folders
Swappable implementations, mocking	Interface + DI registration
Team prefers *.android.cs naming	Custom file patterns in .csproj

Default choice: partial classes + interface + DI. Only use #if for trivial inline checks.

Common Mistakes

1. Overusing #if directives

// ❌ Complex logic buried in #if blocks — untestable, hard to read
public async Task<bool> CheckConnectivity()
{
#if ANDROID
    // 30 lines of Android networking code...
#elif IOS
    // 25 lines of iOS networking code...
#endif
}

// ✅ Use partial classes — each platform file is clean and testable
// Services/ConnectivityService.cs (shared)
public partial class ConnectivityService
{
    public partial Task<bool> CheckConnectivityAsync();
}
// Platforms/Android/Services/ConnectivityService.cs
public partial class ConnectivityService
{
    public partial Task<bool> CheckConnectivityAsync() { /* Android impl */ }
}

2. Mismatched namespaces in partial classes

All partial class files must use the same namespace, or they become separate classes.

// ❌ Different namespaces — creates TWO unrelated classes
// Services/MyService.cs
namespace MyApp.Services;
public partial class MyService { }

// Platforms/Android/MyService.cs
namespace MyApp.Platforms.Android;  // WRONG!
public partial class MyService { }

// ✅ Same namespace everywhere
namespace MyApp.Services;
public partial class MyService { }

3. Depending on concrete classes in shared code

// ❌ Shared code depends on concrete platform type — can't mock in tests
public class MyViewModel
{
    readonly DeviceOrientationService _service = new();
}

// ✅ Depend on interface — enables unit testing and swapping
public class MyViewModel
{
    readonly IDeviceOrientationService _service;
    public MyViewModel(IDeviceOrientationService service) => _service = service;
}

4. Forgetting the #else fallback

// ❌ Fails compilation on unsupported platforms
public string GetDeviceName()
{
#if ANDROID
    return Android.OS.Build.Model;
#elif IOS
    return UIKit.UIDevice.CurrentDevice.Name;
#endif  // No return for Windows or other platforms!
}

// ✅ Always include a fallback
#else
    return "Unknown";
#endif

Platform Pitfalls

⚠️ Android: Platform.CurrentActivity can be null

Platform.CurrentActivity is null before OnCreate completes or when the app is in the background. Always null-check or throw a clear exception.

⚠️ MSBuild auto-includes Platforms/{Platform}/ files

Files under Platforms/Android/ are only compiled for Android — no #if needed. But if you put platform code in a shared folder (e.g., Services/), you must use #if or conditional <Compile> items.

⚠️ Custom file patterns need explicit MSBuild conditions

If using *.android.cs naming, files won't auto-include. Add <Compile> items with platform conditions in your .csproj.

Checklist

• Partial classes share the same namespace across all files
• Complex platform code uses partial classes, not #if blocks
• Shared code depends on interfaces, not concrete implementations
• Interfaces registered in DI in MauiProgram.cs
• #if blocks include #else fallback for unsupported platforms
• Platform.CurrentActivity null-checked before use (Android)
• Custom file patterns (if used) have MSBuild <Compile> conditions