A compiler directive controls which source code is included for a target platform. In a .NET MAUI app, it is useful when a feature or native customization belongs on Android, Windows, iOS, or Mac Catalyst but should not be compiled into the others. This differs from checking the current platform at run time: directives decide during compilation, while DeviceInfo can report the platform or device idiom after the app is running. section 10.3 section 10.4
Use directives for platform differences, not device idioms. A phone, tablet, desktop, TV, or watch is an idiom; use DeviceInfo.Current.Idiom when logic depends on that classification. Directives instead select a named platform, and can keep desktop-only functionality out of mobile builds entirely. section 10.3 section 10.4
Isolate native handler code
A custom BorderlessEntry modifies the shared EntryHandler mapping, then checks that the view is actually a BorderlessEntry so ordinary Entry controls remain unchanged. Inside that check, a conditional compiler block separates native changes: ANDROID can clear an AppCompatEditText background, WINDOWS can remove BorderThickness and FocusVisualMargin, and IOS or MACCATALYST can clear the UIKit border. Keeping these branches together centralizes custom-control logic; partial classes in platform folders are an alternative. section 11.3.3
Listing 11.13 The compiler directives to isolate platform logic
#if ANDROID #1 #elif WINDOWS #2 #elif IOS || MACCATALYST #3 #endif
This directive skeleton creates mutually exclusive branches for Android, Windows, and iOS or Mac Catalyst. Put only the native API calls for each target inside its matching branch. section 11.3.3
Use a compiler directive when you need to:
- Compile native handler changes only for the platform whose PlatformView API they use. section 11.3.3
- Exclude functionality that must not exist in another platform build, such as desktop-only behavior in a mobile app. section 10.3
- Keep platform-specific branches near one custom control when that is clearer than splitting modifications into partial classes. section 11.3.3
For appearance-only differences that can stay in shared XAML, consider OnIdiom or OnPlatform instead. For example, an OnPlatform value can give a SearchBar wrapper a stroke on WinUI and no stroke by default, without using a compiler block. Choose directives when the code itself calls platform-native APIs or must be absent from other builds. section 10.4 section 11.3.3
