From 89afe4a2c0c0811b478a8be32a3a052bdb571be1 Mon Sep 17 00:00:00 2001 From: Gerald Versluis Date: Tue, 10 Feb 2026 12:57:49 +0100 Subject: [PATCH 1/7] Add llms.txt for AI-friendly documentation discovery Introduces a /llms.txt file following the llmstxt.org specification to make .NET MAUI documentation more discoverable and effective for LLMs and AI-powered tools. The file provides a curated, structured overview of the most important documentation pages organized by topic area. Includes critical anti-pattern guidance (obsolete controls like ListView, TableView, Frame; layout pitfalls) and control selection recommendations informed by community best practices. --- docs/llms.txt | 152 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 152 insertions(+) create mode 100644 docs/llms.txt diff --git a/docs/llms.txt b/docs/llms.txt new file mode 100644 index 0000000000..2c7ec4affa --- /dev/null +++ b/docs/llms.txt @@ -0,0 +1,152 @@ +# .NET MAUI Documentation + +> .NET Multi-platform App UI (.NET MAUI) is a cross-platform framework for creating native mobile and desktop apps with C# and XAML. It targets Android, iOS, macOS (via Mac Catalyst), and Windows from a single shared codebase. .NET MAUI is the evolution of Xamarin.Forms, rebuilt for performance and extensibility. + +Important notes: + +- .NET MAUI uses a single-project architecture with platform-specific code organized via multi-targeting, not separate platform projects. +- The handler architecture replaces Xamarin.Forms renderers. Handlers map cross-platform controls to native platform views and are the recommended extensibility point. Never use renderers — use handlers instead. +- .NET MAUI integrates Xamarin.Essentials as built-in platform APIs (sensors, file pickers, geolocation, etc.) under the `Microsoft.Maui.Essentials` namespace. +- Shell is the recommended app structure for most apps, providing URI-based navigation, a flyout menu, and tabs. Do not mix Shell with NavigationPage, TabbedPage, or FlyoutPage. Do not nest tabs in Shell. +- .NET MAUI supports Blazor Hybrid apps via `BlazorWebView`, enabling Razor/Blazor UI components inside native apps. +- XAML is the primary declarative UI language; C# markup is also supported via the .NET MAUI Community Toolkit. +- Data binding, MVVM, and dependency injection are first-class patterns. Always use compiled bindings with `x:DataType` for 8-20x performance improvement over reflection-based bindings. Prefer expression-based `SetBinding` overloads over string-based ones in C#. + +Obsolete controls and patterns — do not use: + +- **ListView** is obsolete — always use CollectionView instead. ListView will be removed in a future release. +- **TableView** is obsolete — use Grid or VerticalStackLayout with appropriate controls instead. +- **Frame** is obsolete — use Border with `StrokeShape="RoundRectangle"` instead. Frame is only acceptable for drop shadows on older targets. +- **AndExpand** layout options (e.g. `FillAndExpand`, `CenterAndExpand`) are obsolete — use Grid or `LayoutOptions.Fill` with proper layout containers. +- **BackgroundColor** property is obsolete — always use the `Background` property instead. + +Control selection guidance: + +- Use **CollectionView** for lists of more than ~20 items (virtualized, high-performance). Never place CollectionView inside a StackLayout — it breaks virtualization. +- Use **BindableLayout** (attached to StackLayout/FlexLayout) for small collections of ≤20 items where virtualization is not needed. +- Never place **ScrollView** inside a StackLayout — it prevents proper scrolling. ScrollView must have a constrained parent (Grid, AbsoluteLayout, or root). +- Prefer **Grid** over StackLayout for complex layouts. Use **VerticalStackLayout** / **HorizontalStackLayout** (not `StackLayout` with `Orientation`). +- Prefer **Border** over Frame for containers with rounded corners or strokes. +- Reference images as **PNG** in XAML/code (e.g. ``), even when the source asset is SVG. .NET MAUI converts SVGs to PNGs at build time. +- For UI updates from background threads, prefer `BindableObject.Dispatcher` or inject `IDispatcher` via DI. Use `MainThread.BeginInvokeOnMainThread()` only as a fallback. + +## Getting started + +- [What is .NET MAUI](https://learn.microsoft.com/dotnet/maui/what-is-maui): Overview of the framework, architecture, and supported platforms +- [Installation](https://learn.microsoft.com/dotnet/maui/get-started/installation): How to install and configure .NET MAUI workloads +- [Build your first app](https://learn.microsoft.com/dotnet/maui/get-started/first-app): Step-by-step guide to creating a .NET MAUI app +- [Supported platforms](https://learn.microsoft.com/dotnet/maui/supported-platforms): Minimum OS versions for Android, iOS, macOS, and Windows +- [Tutorial: Create a .NET MAUI app](https://learn.microsoft.com/dotnet/maui/tutorials/notes-app): End-to-end tutorial building a Notes app +- [Tutorial: Upgrade with MVVM](https://learn.microsoft.com/dotnet/maui/tutorials/notes-mvvm): Refactor the Notes app using MVVM and dependency injection + +## XAML + +- [XAML overview](https://learn.microsoft.com/dotnet/maui/xaml/): Introduction to XAML in .NET MAUI +- [Essential XAML syntax](https://learn.microsoft.com/dotnet/maui/xaml/fundamentals/essential-syntax): Property elements, attached properties, and content properties +- [Markup extensions](https://learn.microsoft.com/dotnet/maui/xaml/fundamentals/markup-extensions): StaticResource, Binding, x:Static, and other extensions +- [Data binding basics](https://learn.microsoft.com/dotnet/maui/xaml/fundamentals/data-binding-basics): How data binding works in XAML +- [XAML and MVVM](https://learn.microsoft.com/dotnet/maui/xaml/fundamentals/mvvm): Using XAML with Model-View-ViewModel pattern +- [XAML compilation](https://learn.microsoft.com/dotnet/maui/xaml/xamlc): Compile XAML for faster startup and validation +- [XAML Hot Reload](https://learn.microsoft.com/dotnet/maui/xaml/hot-reload): Live UI updates during debugging + +## Fundamentals + +- [App lifecycle](https://learn.microsoft.com/dotnet/maui/fundamentals/app-lifecycle): Application lifecycle events and platform-specific lifecycle mapping +- [Single project](https://learn.microsoft.com/dotnet/maui/fundamentals/single-project): How .NET MAUI single-project architecture works with multi-targeting +- [Dependency injection](https://learn.microsoft.com/dotnet/maui/fundamentals/dependency-injection): Register and resolve services using the built-in DI container +- [Data binding overview](https://learn.microsoft.com/dotnet/maui/fundamentals/data-binding/): How to connect UI to data sources +- [Compiled bindings](https://learn.microsoft.com/dotnet/maui/fundamentals/data-binding/compiled-bindings): Critical for performance — use `x:DataType` for 8-20x faster bindings with compile-time validation +- [Shell overview](https://learn.microsoft.com/dotnet/maui/fundamentals/shell/): URI-based navigation, flyout, and tab structure +- [Shell navigation](https://learn.microsoft.com/dotnet/maui/fundamentals/shell/navigation): Route registration, navigation with parameters, and back navigation +- [Gestures](https://learn.microsoft.com/dotnet/maui/fundamentals/gestures/tap): Tap, pan, pinch, swipe, drag-and-drop, and pointer gesture recognizers +- [Behaviors](https://learn.microsoft.com/dotnet/maui/fundamentals/behaviors): Attach reusable behavior to controls without subclassing +- [Triggers](https://learn.microsoft.com/dotnet/maui/fundamentals/triggers): Respond to property changes and events declaratively in XAML +- [Resource dictionaries](https://learn.microsoft.com/dotnet/maui/fundamentals/resource-dictionaries): Share styles, templates, and other resources +- [Accessibility](https://learn.microsoft.com/dotnet/maui/fundamentals/accessibility): Make apps accessible with semantic properties and automation +- [Localization](https://learn.microsoft.com/dotnet/maui/fundamentals/localization): Localize strings, images, and app names + +## User interface + +- [Controls overview](https://learn.microsoft.com/dotnet/maui/user-interface/controls/): Full list of built-in .NET MAUI controls +- [Layouts overview](https://learn.microsoft.com/dotnet/maui/user-interface/layouts/): Grid, VerticalStackLayout, HorizontalStackLayout, FlexLayout, AbsoluteLayout, and custom layouts +- [Grid](https://learn.microsoft.com/dotnet/maui/user-interface/layouts/grid): Row and column layout with proportional, absolute, and auto sizing — preferred for complex layouts +- [CollectionView](https://learn.microsoft.com/dotnet/maui/user-interface/controls/collectionview/): High-performance virtualized list — the recommended control for data lists, replacing ListView +- [Pages](https://learn.microsoft.com/dotnet/maui/user-interface/pages/contentpage): ContentPage, FlyoutPage, NavigationPage, and TabbedPage +- [Pop-ups](https://learn.microsoft.com/dotnet/maui/user-interface/pop-ups): Display alerts, action sheets, and prompts +- [Handlers overview](https://learn.microsoft.com/dotnet/maui/user-interface/handlers/): Architecture for mapping cross-platform controls to native views +- [Create custom controls](https://learn.microsoft.com/dotnet/maui/user-interface/handlers/create): Build new cross-platform controls with the handler pattern +- [Customize controls](https://learn.microsoft.com/dotnet/maui/user-interface/handlers/customize): Modify existing control behavior per platform using handler mappers +- [Styles](https://learn.microsoft.com/dotnet/maui/user-interface/styles/xaml): Define and apply XAML styles to controls +- [Theming](https://learn.microsoft.com/dotnet/maui/user-interface/theming): Implement light/dark themes and dynamic theming +- [Visual states](https://learn.microsoft.com/dotnet/maui/user-interface/visual-states): Change control appearance based on state (Normal, Disabled, Focused, etc.) +- [Fonts](https://learn.microsoft.com/dotnet/maui/user-interface/fonts): Register and use custom fonts +- [Graphics](https://learn.microsoft.com/dotnet/maui/user-interface/graphics/): Draw shapes, paths, and images using Microsoft.Maui.Graphics +- [Animation](https://learn.microsoft.com/dotnet/maui/user-interface/animation/basic): Animate controls with built-in and custom animations + +## Hybrid and Blazor + +- [Hybrid apps overview](https://learn.microsoft.com/dotnet/maui/hybrid-apps/): Combine native and web UI in a single app +- [BlazorWebView](https://learn.microsoft.com/dotnet/maui/user-interface/controls/blazorwebview): Host Blazor Razor components inside a native .NET MAUI app +- [HybridWebView](https://learn.microsoft.com/dotnet/maui/user-interface/controls/hybridwebview): Host custom web content with JS interop in a native app + +## Platform integration + +- [Platform integration overview](https://learn.microsoft.com/dotnet/maui/platform-integration/): Access native platform APIs from shared code +- [Invoke platform code](https://learn.microsoft.com/dotnet/maui/platform-integration/invoke-platform-code): Use partial classes and conditional compilation for platform-specific code +- [Configure multi-targeting](https://learn.microsoft.com/dotnet/maui/platform-integration/configure-multi-targeting): Set up platform-specific compilation +- [Permissions](https://learn.microsoft.com/dotnet/maui/platform-integration/appmodel/permissions): Request and check runtime permissions +- [Geolocation](https://learn.microsoft.com/dotnet/maui/platform-integration/device/geolocation): Access device GPS location +- [Device sensors](https://learn.microsoft.com/dotnet/maui/platform-integration/device/sensors): Accelerometer, barometer, compass, gyroscope, magnetometer, orientation +- [File picker](https://learn.microsoft.com/dotnet/maui/platform-integration/storage/file-picker): Let users select files from the device +- [Photos and videos](https://learn.microsoft.com/dotnet/maui/platform-integration/device-media/picker): Capture or pick photos and videos using the device camera and gallery +- [Secure storage](https://learn.microsoft.com/dotnet/maui/platform-integration/storage/secure-storage): Store key-value pairs securely using platform keystores +- [Preferences](https://learn.microsoft.com/dotnet/maui/platform-integration/storage/preferences): Simple key-value app settings stored natively +- [Connectivity](https://learn.microsoft.com/dotnet/maui/platform-integration/communication/networking): Monitor network state and connection type +- [Web authenticator](https://learn.microsoft.com/dotnet/maui/platform-integration/communication/authentication): Browser-based authentication flows (OAuth, OIDC) +- [Native embedding](https://learn.microsoft.com/dotnet/maui/platform-integration/native-embedding): Embed .NET MAUI controls inside native Android, iOS, or Windows apps + +## Data and cloud services + +- [Consume REST web services](https://learn.microsoft.com/dotnet/maui/data-cloud/rest): Use HttpClient to call REST APIs +- [Local SQLite databases](https://learn.microsoft.com/dotnet/maui/data-cloud/database-sqlite): Store data locally with SQLite +- [.NET Aspire integration](https://learn.microsoft.com/dotnet/maui/data-cloud/aspire-integration): Connect .NET MAUI apps to .NET Aspire service defaults + +## Deployment and testing + +- [Deployment overview](https://learn.microsoft.com/dotnet/maui/deployment/): Publishing and distributing .NET MAUI apps +- [Improve app performance](https://learn.microsoft.com/dotnet/maui/deployment/performance): Startup tracing, compiled bindings, trimming, and profiling tips +- [Trimming](https://learn.microsoft.com/dotnet/maui/deployment/trimming): Reduce app size by removing unused code +- [Native AOT](https://learn.microsoft.com/dotnet/maui/deployment/nativeaot): Ahead-of-time compilation for faster startup and smaller footprint +- [Unit testing](https://learn.microsoft.com/dotnet/maui/deployment/unit-testing): Strategies for testing .NET MAUI apps +- [Publish for Android](https://learn.microsoft.com/dotnet/maui/android/deployment/): Publish to Google Play or for ad-hoc distribution +- [Publish for iOS](https://learn.microsoft.com/dotnet/maui/ios/deployment/): Publish to the App Store, TestFlight, or ad-hoc +- [Publish for Mac Catalyst](https://learn.microsoft.com/dotnet/maui/mac-catalyst/deployment/): Publish for the Mac App Store or direct distribution +- [Publish for Windows](https://learn.microsoft.com/dotnet/maui/windows/deployment/overview): Publish packaged or unpackaged Windows apps + +## Migration from Xamarin + +- [Migration overview](https://learn.microsoft.com/dotnet/maui/migration/): Guidance for upgrading Xamarin.Forms and Xamarin native projects to .NET MAUI +- [Upgrade with .NET Upgrade Assistant](https://learn.microsoft.com/dotnet/maui/migration/upgrade-assistant): Automated migration tooling +- [Custom renderers to handlers](https://learn.microsoft.com/dotnet/maui/migration/renderer-to-handler): Migrate Xamarin.Forms custom renderers to .NET MAUI handlers + +## What's new + +- [What's new in .NET MAUI for .NET 10](https://learn.microsoft.com/dotnet/maui/whats-new/dotnet-10): Latest features, improvements, and breaking changes in .NET 10 +- [What's new in .NET MAUI for .NET 9](https://learn.microsoft.com/dotnet/maui/whats-new/dotnet-9): Features and changes introduced in .NET 9 + +## Optional + +- [Bindable properties](https://learn.microsoft.com/dotnet/maui/fundamentals/bindable-properties): Create custom bindable properties for controls +- [Attached properties](https://learn.microsoft.com/dotnet/maui/fundamentals/attached-properties): Define properties that can be set on any object +- [Control templates](https://learn.microsoft.com/dotnet/maui/fundamentals/controltemplate): Define reusable visual structures for custom controls +- [Data templates](https://learn.microsoft.com/dotnet/maui/fundamentals/datatemplate): Define the visual representation of data in lists and collections +- [XAML namespaces](https://learn.microsoft.com/dotnet/maui/xaml/namespaces/): Custom namespace schemas and prefixes +- [XAML generics](https://learn.microsoft.com/dotnet/maui/xaml/generics): Use generic types in XAML +- [CSS styling](https://learn.microsoft.com/dotnet/maui/user-interface/styles/css): Style .NET MAUI apps using a subset of CSS +- [Shapes](https://learn.microsoft.com/dotnet/maui/user-interface/controls/shapes/): Draw ellipses, rectangles, polygons, paths, and polylines +- [CarouselView](https://learn.microsoft.com/dotnet/maui/user-interface/controls/carouselview/): Horizontally scrollable item view with snap points +- [App icons](https://learn.microsoft.com/dotnet/maui/user-interface/images/app-icons): Configure app icons across platforms from a single SVG source +- [Splash screen](https://learn.microsoft.com/dotnet/maui/user-interface/images/splashscreen): Configure splash screens across platforms +- [Safe area layout](https://learn.microsoft.com/dotnet/maui/user-interface/safe-area): Handle device notches and system UI overlaps +- [Keyboard accelerators](https://learn.microsoft.com/dotnet/maui/user-interface/keyboard-accelerators): Define keyboard shortcuts for menu items +- [Troubleshooting](https://learn.microsoft.com/dotnet/maui/troubleshooting): Common issues and solutions From 0fe157add91d5329815be195315ff86a64547ea5 Mon Sep 17 00:00:00 2001 From: Gerald Versluis Date: Tue, 10 Feb 2026 15:42:22 +0100 Subject: [PATCH 2/7] Reference new conceptual guides from llms.txt Add handler architecture, CollectionView, and performance best practices guides as primary entries in their respective sections. Move the detailed handler reference pages (create, customize) to the Optional section since the guide covers those topics comprehensively. --- docs/llms.txt | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/docs/llms.txt b/docs/llms.txt index 2c7ec4affa..4fccc4fefd 100644 --- a/docs/llms.txt +++ b/docs/llms.txt @@ -67,15 +67,15 @@ Control selection guidance: ## User interface +- [**Handler architecture guide**](https://learn.microsoft.com/dotnet/maui/user-interface/handlers/handler-architecture): Comprehensive, self-contained guide to the handler architecture — what handlers are, creating custom controls, customizing existing controls via Mapper, handler lifecycle, and common recipes - [Controls overview](https://learn.microsoft.com/dotnet/maui/user-interface/controls/): Full list of built-in .NET MAUI controls - [Layouts overview](https://learn.microsoft.com/dotnet/maui/user-interface/layouts/): Grid, VerticalStackLayout, HorizontalStackLayout, FlexLayout, AbsoluteLayout, and custom layouts - [Grid](https://learn.microsoft.com/dotnet/maui/user-interface/layouts/grid): Row and column layout with proportional, absolute, and auto sizing — preferred for complex layouts +- [**CollectionView guide**](https://learn.microsoft.com/dotnet/maui/user-interface/controls/collectionview/collectionview-guide): Comprehensive, self-contained guide to CollectionView — data binding, layouts (list/grid), selection, grouping, empty views, scrolling, SwipeView, and performance tips - [CollectionView](https://learn.microsoft.com/dotnet/maui/user-interface/controls/collectionview/): High-performance virtualized list — the recommended control for data lists, replacing ListView - [Pages](https://learn.microsoft.com/dotnet/maui/user-interface/pages/contentpage): ContentPage, FlyoutPage, NavigationPage, and TabbedPage - [Pop-ups](https://learn.microsoft.com/dotnet/maui/user-interface/pop-ups): Display alerts, action sheets, and prompts - [Handlers overview](https://learn.microsoft.com/dotnet/maui/user-interface/handlers/): Architecture for mapping cross-platform controls to native views -- [Create custom controls](https://learn.microsoft.com/dotnet/maui/user-interface/handlers/create): Build new cross-platform controls with the handler pattern -- [Customize controls](https://learn.microsoft.com/dotnet/maui/user-interface/handlers/customize): Modify existing control behavior per platform using handler mappers - [Styles](https://learn.microsoft.com/dotnet/maui/user-interface/styles/xaml): Define and apply XAML styles to controls - [Theming](https://learn.microsoft.com/dotnet/maui/user-interface/theming): Implement light/dark themes and dynamic theming - [Visual states](https://learn.microsoft.com/dotnet/maui/user-interface/visual-states): Change control appearance based on state (Normal, Disabled, Focused, etc.) @@ -114,6 +114,7 @@ Control selection guidance: ## Deployment and testing - [Deployment overview](https://learn.microsoft.com/dotnet/maui/deployment/): Publishing and distributing .NET MAUI apps +- [**Performance best practices guide**](https://learn.microsoft.com/dotnet/maui/deployment/performance-best-practices): Comprehensive, self-contained guide to .NET MAUI performance — compiled bindings, control selection, layout optimization, images, startup, async/threading, memory management, trimming, and AOT - [Improve app performance](https://learn.microsoft.com/dotnet/maui/deployment/performance): Startup tracing, compiled bindings, trimming, and profiling tips - [Trimming](https://learn.microsoft.com/dotnet/maui/deployment/trimming): Reduce app size by removing unused code - [Native AOT](https://learn.microsoft.com/dotnet/maui/deployment/nativeaot): Ahead-of-time compilation for faster startup and smaller footprint @@ -140,6 +141,8 @@ Control selection guidance: - [Attached properties](https://learn.microsoft.com/dotnet/maui/fundamentals/attached-properties): Define properties that can be set on any object - [Control templates](https://learn.microsoft.com/dotnet/maui/fundamentals/controltemplate): Define reusable visual structures for custom controls - [Data templates](https://learn.microsoft.com/dotnet/maui/fundamentals/datatemplate): Define the visual representation of data in lists and collections +- [Create custom controls](https://learn.microsoft.com/dotnet/maui/user-interface/handlers/create): Step-by-step guide to building custom controls with handlers (detailed reference) +- [Customize controls](https://learn.microsoft.com/dotnet/maui/user-interface/handlers/customize): Modify existing control behavior per platform using handler mappers (detailed reference) - [XAML namespaces](https://learn.microsoft.com/dotnet/maui/xaml/namespaces/): Custom namespace schemas and prefixes - [XAML generics](https://learn.microsoft.com/dotnet/maui/xaml/generics): Use generic types in XAML - [CSS styling](https://learn.microsoft.com/dotnet/maui/user-interface/styles/css): Style .NET MAUI apps using a subset of CSS From 0434cdcb99c6f9aa994eea91a3217df1edfb8df2 Mon Sep 17 00:00:00 2001 From: Gerald Versluis Date: Wed, 11 Feb 2026 13:50:57 +0100 Subject: [PATCH 3/7] Use raw GitHub markdown URLs instead of learn.microsoft.com MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Address review feedback: link to raw markdown files on GitHub instead of rendered HTML pages. Raw markdown is cleaner for LLM consumption — no navigation chrome, JavaScript, or HTML conversion artifacts. All URLs now follow the pattern: https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/... --- docs/llms.txt | 182 +++++++++++++++++++++++++------------------------- 1 file changed, 91 insertions(+), 91 deletions(-) diff --git a/docs/llms.txt b/docs/llms.txt index 4fccc4fefd..0339dd4b19 100644 --- a/docs/llms.txt +++ b/docs/llms.txt @@ -32,124 +32,124 @@ Control selection guidance: ## Getting started -- [What is .NET MAUI](https://learn.microsoft.com/dotnet/maui/what-is-maui): Overview of the framework, architecture, and supported platforms -- [Installation](https://learn.microsoft.com/dotnet/maui/get-started/installation): How to install and configure .NET MAUI workloads -- [Build your first app](https://learn.microsoft.com/dotnet/maui/get-started/first-app): Step-by-step guide to creating a .NET MAUI app -- [Supported platforms](https://learn.microsoft.com/dotnet/maui/supported-platforms): Minimum OS versions for Android, iOS, macOS, and Windows -- [Tutorial: Create a .NET MAUI app](https://learn.microsoft.com/dotnet/maui/tutorials/notes-app): End-to-end tutorial building a Notes app -- [Tutorial: Upgrade with MVVM](https://learn.microsoft.com/dotnet/maui/tutorials/notes-mvvm): Refactor the Notes app using MVVM and dependency injection +- [What is .NET MAUI](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/what-is-maui.md): Overview of the framework, architecture, and supported platforms +- [Installation](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/get-started/installation.md): How to install and configure .NET MAUI workloads +- [Build your first app](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/get-started/first-app.md): Step-by-step guide to creating a .NET MAUI app +- [Supported platforms](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/supported-platforms.md): Minimum OS versions for Android, iOS, macOS, and Windows +- [Tutorial: Create a .NET MAUI app](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/tutorials/notes-app.md): End-to-end tutorial building a Notes app +- [Tutorial: Upgrade with MVVM](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/tutorials/notes-mvvm.md): Refactor the Notes app using MVVM and dependency injection ## XAML -- [XAML overview](https://learn.microsoft.com/dotnet/maui/xaml/): Introduction to XAML in .NET MAUI -- [Essential XAML syntax](https://learn.microsoft.com/dotnet/maui/xaml/fundamentals/essential-syntax): Property elements, attached properties, and content properties -- [Markup extensions](https://learn.microsoft.com/dotnet/maui/xaml/fundamentals/markup-extensions): StaticResource, Binding, x:Static, and other extensions -- [Data binding basics](https://learn.microsoft.com/dotnet/maui/xaml/fundamentals/data-binding-basics): How data binding works in XAML -- [XAML and MVVM](https://learn.microsoft.com/dotnet/maui/xaml/fundamentals/mvvm): Using XAML with Model-View-ViewModel pattern -- [XAML compilation](https://learn.microsoft.com/dotnet/maui/xaml/xamlc): Compile XAML for faster startup and validation -- [XAML Hot Reload](https://learn.microsoft.com/dotnet/maui/xaml/hot-reload): Live UI updates during debugging +- [XAML overview](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/xaml/index.md): Introduction to XAML in .NET MAUI +- [Essential XAML syntax](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/xaml/fundamentals/essential-syntax.md): Property elements, attached properties, and content properties +- [Markup extensions](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/xaml/fundamentals/markup-extensions.md): StaticResource, Binding, x:Static, and other extensions +- [Data binding basics](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/xaml/fundamentals/data-binding-basics.md): How data binding works in XAML +- [XAML and MVVM](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/xaml/fundamentals/mvvm.md): Using XAML with Model-View-ViewModel pattern +- [XAML compilation](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/xaml/xamlc.md): Compile XAML for faster startup and validation +- [XAML Hot Reload](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/xaml/hot-reload.md): Live UI updates during debugging ## Fundamentals -- [App lifecycle](https://learn.microsoft.com/dotnet/maui/fundamentals/app-lifecycle): Application lifecycle events and platform-specific lifecycle mapping -- [Single project](https://learn.microsoft.com/dotnet/maui/fundamentals/single-project): How .NET MAUI single-project architecture works with multi-targeting -- [Dependency injection](https://learn.microsoft.com/dotnet/maui/fundamentals/dependency-injection): Register and resolve services using the built-in DI container -- [Data binding overview](https://learn.microsoft.com/dotnet/maui/fundamentals/data-binding/): How to connect UI to data sources -- [Compiled bindings](https://learn.microsoft.com/dotnet/maui/fundamentals/data-binding/compiled-bindings): Critical for performance — use `x:DataType` for 8-20x faster bindings with compile-time validation -- [Shell overview](https://learn.microsoft.com/dotnet/maui/fundamentals/shell/): URI-based navigation, flyout, and tab structure -- [Shell navigation](https://learn.microsoft.com/dotnet/maui/fundamentals/shell/navigation): Route registration, navigation with parameters, and back navigation -- [Gestures](https://learn.microsoft.com/dotnet/maui/fundamentals/gestures/tap): Tap, pan, pinch, swipe, drag-and-drop, and pointer gesture recognizers -- [Behaviors](https://learn.microsoft.com/dotnet/maui/fundamentals/behaviors): Attach reusable behavior to controls without subclassing -- [Triggers](https://learn.microsoft.com/dotnet/maui/fundamentals/triggers): Respond to property changes and events declaratively in XAML -- [Resource dictionaries](https://learn.microsoft.com/dotnet/maui/fundamentals/resource-dictionaries): Share styles, templates, and other resources -- [Accessibility](https://learn.microsoft.com/dotnet/maui/fundamentals/accessibility): Make apps accessible with semantic properties and automation -- [Localization](https://learn.microsoft.com/dotnet/maui/fundamentals/localization): Localize strings, images, and app names +- [App lifecycle](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/fundamentals/app-lifecycle.md): Application lifecycle events and platform-specific lifecycle mapping +- [Single project](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/fundamentals/single-project.md): How .NET MAUI single-project architecture works with multi-targeting +- [Dependency injection](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/fundamentals/dependency-injection.md): Register and resolve services using the built-in DI container +- [Data binding overview](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/fundamentals/data-binding/index.md): How to connect UI to data sources +- [Compiled bindings](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/fundamentals/data-binding/compiled-bindings.md): Critical for performance — use `x:DataType` for 8-20x faster bindings with compile-time validation +- [Shell overview](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/fundamentals/shell/index.md): URI-based navigation, flyout, and tab structure +- [Shell navigation](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/fundamentals/shell/navigation.md): Route registration, navigation with parameters, and back navigation +- [Gestures](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/fundamentals/gestures/tap.md): Tap, pan, pinch, swipe, drag-and-drop, and pointer gesture recognizers +- [Behaviors](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/fundamentals/behaviors.md): Attach reusable behavior to controls without subclassing +- [Triggers](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/fundamentals/triggers.md): Respond to property changes and events declaratively in XAML +- [Resource dictionaries](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/fundamentals/resource-dictionaries.md): Share styles, templates, and other resources +- [Accessibility](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/fundamentals/accessibility.md): Make apps accessible with semantic properties and automation +- [Localization](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/fundamentals/localization.md): Localize strings, images, and app names ## User interface -- [**Handler architecture guide**](https://learn.microsoft.com/dotnet/maui/user-interface/handlers/handler-architecture): Comprehensive, self-contained guide to the handler architecture — what handlers are, creating custom controls, customizing existing controls via Mapper, handler lifecycle, and common recipes -- [Controls overview](https://learn.microsoft.com/dotnet/maui/user-interface/controls/): Full list of built-in .NET MAUI controls -- [Layouts overview](https://learn.microsoft.com/dotnet/maui/user-interface/layouts/): Grid, VerticalStackLayout, HorizontalStackLayout, FlexLayout, AbsoluteLayout, and custom layouts -- [Grid](https://learn.microsoft.com/dotnet/maui/user-interface/layouts/grid): Row and column layout with proportional, absolute, and auto sizing — preferred for complex layouts -- [**CollectionView guide**](https://learn.microsoft.com/dotnet/maui/user-interface/controls/collectionview/collectionview-guide): Comprehensive, self-contained guide to CollectionView — data binding, layouts (list/grid), selection, grouping, empty views, scrolling, SwipeView, and performance tips -- [CollectionView](https://learn.microsoft.com/dotnet/maui/user-interface/controls/collectionview/): High-performance virtualized list — the recommended control for data lists, replacing ListView -- [Pages](https://learn.microsoft.com/dotnet/maui/user-interface/pages/contentpage): ContentPage, FlyoutPage, NavigationPage, and TabbedPage -- [Pop-ups](https://learn.microsoft.com/dotnet/maui/user-interface/pop-ups): Display alerts, action sheets, and prompts -- [Handlers overview](https://learn.microsoft.com/dotnet/maui/user-interface/handlers/): Architecture for mapping cross-platform controls to native views -- [Styles](https://learn.microsoft.com/dotnet/maui/user-interface/styles/xaml): Define and apply XAML styles to controls -- [Theming](https://learn.microsoft.com/dotnet/maui/user-interface/theming): Implement light/dark themes and dynamic theming -- [Visual states](https://learn.microsoft.com/dotnet/maui/user-interface/visual-states): Change control appearance based on state (Normal, Disabled, Focused, etc.) -- [Fonts](https://learn.microsoft.com/dotnet/maui/user-interface/fonts): Register and use custom fonts -- [Graphics](https://learn.microsoft.com/dotnet/maui/user-interface/graphics/): Draw shapes, paths, and images using Microsoft.Maui.Graphics -- [Animation](https://learn.microsoft.com/dotnet/maui/user-interface/animation/basic): Animate controls with built-in and custom animations +- [**Handler architecture guide**](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/handlers/handler-architecture.md): Comprehensive, self-contained guide to the handler architecture — what handlers are, creating custom controls, customizing existing controls via Mapper, handler lifecycle, and common recipes +- [Controls overview](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/controls/index.md): Full list of built-in .NET MAUI controls +- [Layouts overview](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/layouts/index.md): Grid, VerticalStackLayout, HorizontalStackLayout, FlexLayout, AbsoluteLayout, and custom layouts +- [Grid](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/layouts/grid.md): Row and column layout with proportional, absolute, and auto sizing — preferred for complex layouts +- [**CollectionView guide**](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/controls/collectionview/collectionview-guide.md): Comprehensive, self-contained guide to CollectionView — data binding, layouts (list/grid), selection, grouping, empty views, scrolling, SwipeView, and performance tips +- [CollectionView](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/controls/collectionview/index.md): High-performance virtualized list — the recommended control for data lists, replacing ListView +- [Pages](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/pages/contentpage.md): ContentPage, FlyoutPage, NavigationPage, and TabbedPage +- [Pop-ups](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/pop-ups.md): Display alerts, action sheets, and prompts +- [Handlers overview](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/handlers/index.md): Architecture for mapping cross-platform controls to native views +- [Styles](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/styles/xaml.md): Define and apply XAML styles to controls +- [Theming](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/theming.md): Implement light/dark themes and dynamic theming +- [Visual states](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/visual-states.md): Change control appearance based on state (Normal, Disabled, Focused, etc.) +- [Fonts](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/fonts.md): Register and use custom fonts +- [Graphics](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/graphics/index.md): Draw shapes, paths, and images using Microsoft.Maui.Graphics +- [Animation](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/animation/basic.md): Animate controls with built-in and custom animations ## Hybrid and Blazor -- [Hybrid apps overview](https://learn.microsoft.com/dotnet/maui/hybrid-apps/): Combine native and web UI in a single app -- [BlazorWebView](https://learn.microsoft.com/dotnet/maui/user-interface/controls/blazorwebview): Host Blazor Razor components inside a native .NET MAUI app -- [HybridWebView](https://learn.microsoft.com/dotnet/maui/user-interface/controls/hybridwebview): Host custom web content with JS interop in a native app +- [Hybrid apps overview](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/hybrid-apps/index.md): Combine native and web UI in a single app +- [BlazorWebView](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/controls/blazorwebview.md): Host Blazor Razor components inside a native .NET MAUI app +- [HybridWebView](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/controls/hybridwebview.md): Host custom web content with JS interop in a native app ## Platform integration -- [Platform integration overview](https://learn.microsoft.com/dotnet/maui/platform-integration/): Access native platform APIs from shared code -- [Invoke platform code](https://learn.microsoft.com/dotnet/maui/platform-integration/invoke-platform-code): Use partial classes and conditional compilation for platform-specific code -- [Configure multi-targeting](https://learn.microsoft.com/dotnet/maui/platform-integration/configure-multi-targeting): Set up platform-specific compilation -- [Permissions](https://learn.microsoft.com/dotnet/maui/platform-integration/appmodel/permissions): Request and check runtime permissions -- [Geolocation](https://learn.microsoft.com/dotnet/maui/platform-integration/device/geolocation): Access device GPS location -- [Device sensors](https://learn.microsoft.com/dotnet/maui/platform-integration/device/sensors): Accelerometer, barometer, compass, gyroscope, magnetometer, orientation -- [File picker](https://learn.microsoft.com/dotnet/maui/platform-integration/storage/file-picker): Let users select files from the device -- [Photos and videos](https://learn.microsoft.com/dotnet/maui/platform-integration/device-media/picker): Capture or pick photos and videos using the device camera and gallery -- [Secure storage](https://learn.microsoft.com/dotnet/maui/platform-integration/storage/secure-storage): Store key-value pairs securely using platform keystores -- [Preferences](https://learn.microsoft.com/dotnet/maui/platform-integration/storage/preferences): Simple key-value app settings stored natively -- [Connectivity](https://learn.microsoft.com/dotnet/maui/platform-integration/communication/networking): Monitor network state and connection type -- [Web authenticator](https://learn.microsoft.com/dotnet/maui/platform-integration/communication/authentication): Browser-based authentication flows (OAuth, OIDC) -- [Native embedding](https://learn.microsoft.com/dotnet/maui/platform-integration/native-embedding): Embed .NET MAUI controls inside native Android, iOS, or Windows apps +- [Platform integration overview](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/platform-integration/index.md): Access native platform APIs from shared code +- [Invoke platform code](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/platform-integration/invoke-platform-code.md): Use partial classes and conditional compilation for platform-specific code +- [Configure multi-targeting](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/platform-integration/configure-multi-targeting.md): Set up platform-specific compilation +- [Permissions](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/platform-integration/appmodel/permissions.md): Request and check runtime permissions +- [Geolocation](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/platform-integration/device/geolocation.md): Access device GPS location +- [Device sensors](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/platform-integration/device/sensors.md): Accelerometer, barometer, compass, gyroscope, magnetometer, orientation +- [File picker](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/platform-integration/storage/file-picker.md): Let users select files from the device +- [Photos and videos](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/platform-integration/device-media/picker.md): Capture or pick photos and videos using the device camera and gallery +- [Secure storage](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/platform-integration/storage/secure-storage.md): Store key-value pairs securely using platform keystores +- [Preferences](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/platform-integration/storage/preferences.md): Simple key-value app settings stored natively +- [Connectivity](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/platform-integration/communication/networking.md): Monitor network state and connection type +- [Web authenticator](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/platform-integration/communication/authentication.md): Browser-based authentication flows (OAuth, OIDC) +- [Native embedding](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/platform-integration/native-embedding.md): Embed .NET MAUI controls inside native Android, iOS, or Windows apps ## Data and cloud services -- [Consume REST web services](https://learn.microsoft.com/dotnet/maui/data-cloud/rest): Use HttpClient to call REST APIs -- [Local SQLite databases](https://learn.microsoft.com/dotnet/maui/data-cloud/database-sqlite): Store data locally with SQLite -- [.NET Aspire integration](https://learn.microsoft.com/dotnet/maui/data-cloud/aspire-integration): Connect .NET MAUI apps to .NET Aspire service defaults +- [Consume REST web services](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/data-cloud/rest.md): Use HttpClient to call REST APIs +- [Local SQLite databases](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/data-cloud/database-sqlite.md): Store data locally with SQLite +- [.NET Aspire integration](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/data-cloud/aspire-integration.md): Connect .NET MAUI apps to .NET Aspire service defaults ## Deployment and testing -- [Deployment overview](https://learn.microsoft.com/dotnet/maui/deployment/): Publishing and distributing .NET MAUI apps -- [**Performance best practices guide**](https://learn.microsoft.com/dotnet/maui/deployment/performance-best-practices): Comprehensive, self-contained guide to .NET MAUI performance — compiled bindings, control selection, layout optimization, images, startup, async/threading, memory management, trimming, and AOT -- [Improve app performance](https://learn.microsoft.com/dotnet/maui/deployment/performance): Startup tracing, compiled bindings, trimming, and profiling tips -- [Trimming](https://learn.microsoft.com/dotnet/maui/deployment/trimming): Reduce app size by removing unused code -- [Native AOT](https://learn.microsoft.com/dotnet/maui/deployment/nativeaot): Ahead-of-time compilation for faster startup and smaller footprint -- [Unit testing](https://learn.microsoft.com/dotnet/maui/deployment/unit-testing): Strategies for testing .NET MAUI apps -- [Publish for Android](https://learn.microsoft.com/dotnet/maui/android/deployment/): Publish to Google Play or for ad-hoc distribution -- [Publish for iOS](https://learn.microsoft.com/dotnet/maui/ios/deployment/): Publish to the App Store, TestFlight, or ad-hoc -- [Publish for Mac Catalyst](https://learn.microsoft.com/dotnet/maui/mac-catalyst/deployment/): Publish for the Mac App Store or direct distribution -- [Publish for Windows](https://learn.microsoft.com/dotnet/maui/windows/deployment/overview): Publish packaged or unpackaged Windows apps +- [Deployment overview](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/deployment/index.md): Publishing and distributing .NET MAUI apps +- [**Performance best practices guide**](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/deployment/performance-best-practices.md): Comprehensive, self-contained guide to .NET MAUI performance — compiled bindings, control selection, layout optimization, images, startup, async/threading, memory management, trimming, and AOT +- [Improve app performance](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/deployment/performance.md): Startup tracing, compiled bindings, trimming, and profiling tips +- [Trimming](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/deployment/trimming.md): Reduce app size by removing unused code +- [Native AOT](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/deployment/nativeaot.md): Ahead-of-time compilation for faster startup and smaller footprint +- [Unit testing](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/deployment/unit-testing.md): Strategies for testing .NET MAUI apps +- [Publish for Android](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/android/deployment/index.md): Publish to Google Play or for ad-hoc distribution +- [Publish for iOS](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/ios/deployment/index.md): Publish to the App Store, TestFlight, or ad-hoc +- [Publish for Mac Catalyst](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/mac-catalyst/deployment/index.md): Publish for the Mac App Store or direct distribution +- [Publish for Windows](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/windows/deployment/overview.md): Publish packaged or unpackaged Windows apps ## Migration from Xamarin -- [Migration overview](https://learn.microsoft.com/dotnet/maui/migration/): Guidance for upgrading Xamarin.Forms and Xamarin native projects to .NET MAUI -- [Upgrade with .NET Upgrade Assistant](https://learn.microsoft.com/dotnet/maui/migration/upgrade-assistant): Automated migration tooling -- [Custom renderers to handlers](https://learn.microsoft.com/dotnet/maui/migration/renderer-to-handler): Migrate Xamarin.Forms custom renderers to .NET MAUI handlers +- [Migration overview](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/migration/index.md): Guidance for upgrading Xamarin.Forms and Xamarin native projects to .NET MAUI +- [Upgrade with .NET Upgrade Assistant](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/migration/upgrade-assistant.md): Automated migration tooling +- [Custom renderers to handlers](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/migration/renderer-to-handler.md): Migrate Xamarin.Forms custom renderers to .NET MAUI handlers ## What's new -- [What's new in .NET MAUI for .NET 10](https://learn.microsoft.com/dotnet/maui/whats-new/dotnet-10): Latest features, improvements, and breaking changes in .NET 10 -- [What's new in .NET MAUI for .NET 9](https://learn.microsoft.com/dotnet/maui/whats-new/dotnet-9): Features and changes introduced in .NET 9 +- [What's new in .NET MAUI for .NET 10](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/whats-new/dotnet-10.md): Latest features, improvements, and breaking changes in .NET 10 +- [What's new in .NET MAUI for .NET 9](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/whats-new/dotnet-9.md): Features and changes introduced in .NET 9 ## Optional -- [Bindable properties](https://learn.microsoft.com/dotnet/maui/fundamentals/bindable-properties): Create custom bindable properties for controls -- [Attached properties](https://learn.microsoft.com/dotnet/maui/fundamentals/attached-properties): Define properties that can be set on any object -- [Control templates](https://learn.microsoft.com/dotnet/maui/fundamentals/controltemplate): Define reusable visual structures for custom controls -- [Data templates](https://learn.microsoft.com/dotnet/maui/fundamentals/datatemplate): Define the visual representation of data in lists and collections -- [Create custom controls](https://learn.microsoft.com/dotnet/maui/user-interface/handlers/create): Step-by-step guide to building custom controls with handlers (detailed reference) -- [Customize controls](https://learn.microsoft.com/dotnet/maui/user-interface/handlers/customize): Modify existing control behavior per platform using handler mappers (detailed reference) -- [XAML namespaces](https://learn.microsoft.com/dotnet/maui/xaml/namespaces/): Custom namespace schemas and prefixes -- [XAML generics](https://learn.microsoft.com/dotnet/maui/xaml/generics): Use generic types in XAML -- [CSS styling](https://learn.microsoft.com/dotnet/maui/user-interface/styles/css): Style .NET MAUI apps using a subset of CSS -- [Shapes](https://learn.microsoft.com/dotnet/maui/user-interface/controls/shapes/): Draw ellipses, rectangles, polygons, paths, and polylines -- [CarouselView](https://learn.microsoft.com/dotnet/maui/user-interface/controls/carouselview/): Horizontally scrollable item view with snap points -- [App icons](https://learn.microsoft.com/dotnet/maui/user-interface/images/app-icons): Configure app icons across platforms from a single SVG source -- [Splash screen](https://learn.microsoft.com/dotnet/maui/user-interface/images/splashscreen): Configure splash screens across platforms -- [Safe area layout](https://learn.microsoft.com/dotnet/maui/user-interface/safe-area): Handle device notches and system UI overlaps -- [Keyboard accelerators](https://learn.microsoft.com/dotnet/maui/user-interface/keyboard-accelerators): Define keyboard shortcuts for menu items -- [Troubleshooting](https://learn.microsoft.com/dotnet/maui/troubleshooting): Common issues and solutions +- [Bindable properties](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/fundamentals/bindable-properties.md): Create custom bindable properties for controls +- [Attached properties](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/fundamentals/attached-properties.md): Define properties that can be set on any object +- [Control templates](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/fundamentals/controltemplate.md): Define reusable visual structures for custom controls +- [Data templates](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/fundamentals/datatemplate.md): Define the visual representation of data in lists and collections +- [Create custom controls](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/handlers/create.md): Step-by-step guide to building custom controls with handlers (detailed reference) +- [Customize controls](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/handlers/customize.md): Modify existing control behavior per platform using handler mappers (detailed reference) +- [XAML namespaces](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/xaml/namespaces/index.md): Custom namespace schemas and prefixes +- [XAML generics](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/xaml/generics.md): Use generic types in XAML +- [CSS styling](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/styles/css.md): Style .NET MAUI apps using a subset of CSS +- [Shapes](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/controls/shapes/index.md): Draw ellipses, rectangles, polygons, paths, and polylines +- [CarouselView](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/controls/carouselview/index.md): Horizontally scrollable item view with snap points +- [App icons](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/images/app-icons.md): Configure app icons across platforms from a single SVG source +- [Splash screen](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/images/splashscreen.md): Configure splash screens across platforms +- [Safe area layout](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/safe-area.md): Handle device notches and system UI overlaps +- [Keyboard accelerators](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/keyboard-accelerators.md): Define keyboard shortcuts for menu items +- [Troubleshooting](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/troubleshooting.md): Common issues and solutions From 031641d482706315fd4d13070d2b0d98fa3b7493 Mon Sep 17 00:00:00 2001 From: Gerald Versluis Date: Tue, 10 Feb 2026 14:45:46 +0100 Subject: [PATCH 4/7] Add self-contained conceptual guides for LLM and human readability Three new standalone guides with inline code examples, no external snippet references or moniker ranges, designed to be fully self-contained for both human readers and LLM consumption: - Handler architecture: what handlers are, creating custom controls, customizing existing controls via Mapper, lifecycle, common recipes - CollectionView: data binding, layouts (list/grid), selection, grouping, empty views, scrolling, SwipeView, performance tips - Performance best practices: compiled bindings, control selection (Grid vs StackLayout, CollectionView vs ListView, Border vs Frame), layout optimization, images, startup, async/threading, memory, trimming/AOT --- docs/deployment/performance-best-practices.md | 562 ++++++++++++ .../collectionview/collectionview-guide.md | 816 ++++++++++++++++++ .../handlers/handler-architecture.md | 590 +++++++++++++ 3 files changed, 1968 insertions(+) create mode 100644 docs/deployment/performance-best-practices.md create mode 100644 docs/user-interface/controls/collectionview/collectionview-guide.md create mode 100644 docs/user-interface/handlers/handler-architecture.md diff --git a/docs/deployment/performance-best-practices.md b/docs/deployment/performance-best-practices.md new file mode 100644 index 0000000000..19d22cddf3 --- /dev/null +++ b/docs/deployment/performance-best-practices.md @@ -0,0 +1,562 @@ +--- +title: "Performance best practices for .NET MAUI" +description: "A practical guide to building high-performance .NET MAUI apps — covering compiled bindings, layout optimization, control selection, image handling, async patterns, startup time, and deployment options." +ms.date: 02/10/2026 +ms.topic: conceptual +--- + +# Performance best practices for .NET MAUI + +This guide covers the most impactful performance optimizations for .NET MAUI apps. Recommendations are ordered roughly by impact — start at the top. + +## 1. Compiled bindings + +This is the single biggest performance win in most MAUI apps. + +### The problem + +Reflection-based bindings resolve property paths at runtime using `System.Reflection`. This adds overhead on every property change notification, every binding evaluation, and every `DataTemplate` instantiation. In a list with hundreds of items, this cost compounds fast. + +### The fix + +Set `x:DataType` on your page and on every `DataTemplate`. This tells the XAML compiler to generate direct property access code at build time instead of using reflection, resulting in 8–20x faster binding resolution. + +```xaml + + + +``` + +```xaml + + + +``` + +Set `x:DataType` on `DataTemplate` elements too — they don't inherit it from the page: + +```xaml + + + + + + +``` + +In C#, use the expression-based `SetBinding` overload for compiled, type-safe bindings: + +```csharp +// DO: Compiled, type-safe — no reflection +label.SetBinding(Label.TextProperty, static (MainViewModel vm) => vm.UserName); + +// DON'T: String-based — uses reflection at runtime +label.SetBinding(Label.TextProperty, "UserName"); +``` + +### Don't bind static values + +If a value never changes and doesn't come from a view model, set it directly. Every binding — even a compiled one — has overhead compared to a direct property assignment. + +```xaml + +