{"kind":"AgentDefinition","metadata":{"namespace":"community","name":"dotnet-maui-9-to-dotnet-maui-10-upgrade","version":"0.1.0"},"spec":{"agents_md":"---\ndescription: 'Instructions for upgrading .NET MAUI applications from version 9 to version 10, including breaking changes, deprecated APIs, and migration strategies for ListView to CollectionView.'\napplyTo: '**/*.csproj, **/*.cs, **/*.xaml'\n---\n\n# Upgrading from .NET MAUI 9 to .NET MAUI 10\n\nThis guide helps you upgrade your .NET MAUI application from .NET 9 to .NET 10 by focusing on the critical breaking changes and obsolete APIs that require code updates.\n\n---\n\n## Table of Contents\n\n1. [Quick Start](#quick-start)\n2. [Update Target Framework](#update-target-framework)\n3. [Breaking Changes (P0 - Must Fix)](#breaking-changes-p0---must-fix)\n   - [MessagingCenter Made Internal](#messagingcenter-made-internal)\n   - [ListView and TableView Deprecated](#listview-and-tableview-deprecated)\n4. [Deprecated APIs (P1 - Fix Soon)](#deprecated-apis-p1---fix-soon)\n   - [Animation Methods](#1-animation-methods)\n   - [DisplayAlert and DisplayActionSheet](#2-displayalert-and-displayactionsheet)\n   - [Page.IsBusy](#3-pageisbusy)\n   - [MediaPicker APIs](#4-mediapicker-apis)\n5. [Recommended Changes (P2)](#recommended-changes-p2)\n6. [Bulk Migration Tools](#bulk-migration-tools)\n7. [Testing Your Upgrade](#testing-your-upgrade)\n8. [Troubleshooting](#troubleshooting)\n\n---\n\n## Quick Start\n\n**Five-Step Upgrade Process:**\n\n1. **Update TargetFramework** to `net10.0`\n2. **Update CommunityToolkit.Maui** to 12.3.0+ (if you use it) - REQUIRED\n3. **Fix breaking changes** - MessagingCenter (P0)\n4. **Migrate ListView/TableView to CollectionView** (P0 - CRITICAL)\n5. **Fix deprecated APIs** - Animation methods, DisplayAlert, IsBusy, MediaPicker (P1)\n\n\u003e ⚠️ **Major Breaking Changes**: \n\u003e - CommunityToolkit.Maui **must** be version 12.3.0 or later\n\u003e - ListView and TableView are now obsolete (most significant migration effort)\n\n---\n\n## Update Target Framework\n\n### Single Platform\n\n```xml\n\u003cProject Sdk=\"Microsoft.NET.Sdk\"\u003e\n  \u003cPropertyGroup\u003e\n    \u003cTargetFramework\u003enet10.0\u003c/TargetFramework\u003e\n  \u003c/PropertyGroup\u003e\n\u003c/Project\u003e\n```\n\n### Multi-Platform\n\n```xml\n\u003cProject Sdk=\"Microsoft.NET.Sdk\"\u003e\n  \u003cPropertyGroup\u003e\n    \u003cTargetFrameworks\u003enet10.0-android;net10.0-ios;net10.0-maccatalyst;net10.0-windows10.0.19041.0\u003c/TargetFrameworks\u003e\n  \u003c/PropertyGroup\u003e\n\u003c/Project\u003e\n```\n\n### Optional: Linux Compatibility (GitHub Copilot, WSL, etc.)\n\n\u003e 💡 **For Linux Development**: If you're building on Linux (e.g., GitHub Codespaces, WSL, or using GitHub Copilot), you can make your project compile on Linux by conditionally excluding iOS/Mac Catalyst targets:\n\n```xml\n\u003cProject Sdk=\"Microsoft.NET.Sdk\"\u003e\n  \u003cPropertyGroup\u003e\n    \u003c!-- Start with Android (always supported) --\u003e\n    \u003cTargetFrameworks\u003enet10.0-android\u003c/TargetFrameworks\u003e\n    \n    \u003c!-- Add iOS/Mac Catalyst only when NOT on Linux --\u003e\n    \u003cTargetFrameworks Condition=\"!$([MSBuild]::IsOSPlatform('linux'))\"\u003e$(TargetFrameworks);net10.0-ios;net10.0-maccatalyst\u003c/TargetFrameworks\u003e\n    \n    \u003c!-- Add Windows only when on Windows --\u003e\n    \u003cTargetFrameworks Condition=\"$([MSBuild]::IsOSPlatform('windows'))\"\u003e$(TargetFrameworks);net10.0-windows10.0.19041.0\u003c/TargetFrameworks\u003e\n  \u003c/PropertyGroup\u003e\n\u003c/Project\u003e\n```\n\n**Benefits:**\n- ✅ Compiles successfully on Linux (no iOS/Mac tools required)\n- ✅ Works with GitHub Codespaces and Copilot\n- ✅ Automatically includes correct targets based on build OS\n- ✅ No changes needed when switching between OS environments\n\n**Reference:** [dotnet/maui#32186](https://github.com/dotnet/maui/pull/32186)\n\n### Update Required NuGet Packages\n\n\u003e ⚠️ **CRITICAL**: If you use CommunityToolkit.Maui, you **must** update to version 12.3.0 or later. Earlier versions are not compatible with .NET 10 and will cause compilation errors.\n\n```bash\n# Update CommunityToolkit.Maui (if you use it)\ndotnet add package CommunityToolkit.Maui --version 12.3.0\n\n# Update other common packages to .NET 10 compatible versions\ndotnet add package Microsoft.Maui.Controls --version 10.0.0\n```\n\n**Check all your NuGet packages:**\n```bash\n# List all packages and check for updates\ndotnet list package --outdated\n\n# Update all packages to latest compatible versions\ndotnet list package --outdated | grep \"\u003e\" | cut -d '\u003e' -f 1 | xargs -I {} dotnet add package {}\n```\n\n---\n\n## Breaking Changes (P0 - Must Fix)\n\n### MessagingCenter Made Internal\n\n**Status:** 🚨 **BREAKING** - `MessagingCenter` is now `internal` and cannot be accessed.\n\n**Error You'll See:**\n```\nerror CS0122: 'MessagingCenter' is inaccessible due to its protection level\n```\n\n**Migration Required:**\n\n#### Step 1: Install CommunityToolkit.Mvvm\n\n```bash\ndotnet add package CommunityToolkit.Mvvm --version 8.3.0\n```\n\n#### Step 2: Define Message Classes\n\n```csharp\n// OLD: No message class needed\nMessagingCenter.Send(this, \"UserLoggedIn\", userData);\n\n// NEW: Create a message class\npublic class UserLoggedInMessage\n{\n    public UserData Data { get; set; }\n    \n    public UserLoggedInMessage(UserData data)\n    {\n        Data = data;\n    }\n}\n```\n\n#### Step 3: Update Send Calls\n\n```csharp\n// ❌ OLD (Broken in .NET 10)\nusing Microsoft.Maui.Controls;\n\nMessagingCenter.Send(this, \"UserLoggedIn\", userData);\nMessagingCenter.Send\u003cApp, string\u003e(this, \"StatusChanged\", \"Active\");\n\n// ✅ NEW (Required)\nusing CommunityToolkit.Mvvm.Messaging;\n\nWeakReferenceMessenger.Default.Send(new UserLoggedInMessage(userData));\nWeakReferenceMessenger.Default.Send(new StatusChangedMessage(\"Active\"));\n```\n\n#### Step 4: Update Subscribe Calls\n\n```csharp\n// ❌ OLD (Broken in .NET 10)\nMessagingCenter.Subscribe\u003cApp, UserData\u003e(this, \"UserLoggedIn\", (sender, data) =\u003e\n{\n    // Handle message\n    CurrentUser = data;\n});\n\n// ✅ NEW (Required)\nWeakReferenceMessenger.Default.Register\u003cUserLoggedInMessage\u003e(this, (recipient, message) =\u003e\n{\n    // Handle message\n    CurrentUser = message.Data;\n});\n```\n\n#### ⚠️ Important Behavioral Difference: Duplicate Subscriptions\n\n**WeakReferenceMessenger** throws an `InvalidOperationException` if you try to register the same message type multiple times on the same recipient (MessagingCenter allowed this):\n\n```csharp\n// ❌ This THROWS InvalidOperationException in WeakReferenceMessenger\nWeakReferenceMessenger.Default.Register\u003cUserLoggedInMessage\u003e(this, (r, m) =\u003e Handler1(m));\nWeakReferenceMessenger.Default.Register\u003cUserLoggedInMessage\u003e(this, (r, m) =\u003e Handler2(m)); // ❌ THROWS!\n\n// ✅ Solution 1: Unregister before re-registering\nWeakReferenceMessenger.Default.Unregister\u003cUserLoggedInMessage\u003e(this);\nWeakReferenceMessenger.Default.Register\u003cUserLoggedInMessage\u003e(this, (r, m) =\u003e Handler1(m));\n\n// ✅ Solution 2: Handle multiple actions in one registration\nWeakReferenceMessenger.Default.Register\u003cUserLoggedInMessage\u003e(this, (r, m) =\u003e \n{\n    Handler1(m);\n    Handler2(m);\n});\n```\n\n**Why this matters:** If your code subscribes to the same message in multiple places (e.g., in a page constructor and in `OnAppearing`), you'll get a runtime crash.\n\n#### Step 5: Unregister When Done\n\n```csharp\n// ❌ OLD\nMessagingCenter.Unsubscribe\u003cApp, UserData\u003e(this, \"UserLoggedIn\");\n\n// ✅ NEW (CRITICAL - prevents memory leaks)\nWeakReferenceMessenger.Default.Unregister\u003cUserLoggedInMessage\u003e(this);\n\n// Or unregister all messages for this recipient\nWeakReferenceMessenger.Default.UnregisterAll(this);\n```\n\n#### Complete Before/After Example\n\n**Before (.NET 9):**\n```csharp\n// Sender\npublic class LoginViewModel\n{\n    public async Task LoginAsync()\n    {\n        var user = await AuthService.LoginAsync(username, password);\n        MessagingCenter.Send(this, \"UserLoggedIn\", user);\n    }\n}\n\n// Receiver\npublic partial class MainPage : ContentPage\n{\n    public MainPage()\n    {\n        InitializeComponent();\n        \n        MessagingCenter.Subscribe\u003cLoginViewModel, User\u003e(this, \"UserLoggedIn\", (sender, user) =\u003e\n        {\n            WelcomeLabel.Text = $\"Welcome, {user.Name}!\";\n        });\n    }\n    \n    protected override void OnDisappearing()\n    {\n        base.OnDisappearing();\n        MessagingCenter.Unsubscribe\u003cLoginViewModel, User\u003e(this, \"UserLoggedIn\");\n    }\n}\n```\n\n**After (.NET 10):**\n```csharp\n// 1. Define message\npublic class UserLoggedInMessage\n{\n    public User User { get; }\n    \n    public UserLoggedInMessage(User user)\n    {\n        User = user;\n    }\n}\n\n// 2. Sender\npublic class LoginViewModel\n{\n    public async Task LoginAsync()\n    {\n        var user = await AuthService.LoginAsync(username, password);\n        WeakReferenceMessenger.Default.Send(new UserLoggedInMessage(user));\n    }\n}\n\n// 3. Receiver\npublic partial class MainPage : ContentPage\n{\n    public MainPage()\n    {\n        InitializeComponent();\n        \n        WeakReferenceMessenger.Default.Register\u003cUserLoggedInMessage\u003e(this, (recipient, message) =\u003e\n        {\n            WelcomeLabel.Text = $\"Welcome, {message.User.Name}!\";\n        });\n    }\n    \n    protected override void OnDisappearing()\n    {\n        base.OnDisappearing();\n        WeakReferenceMessenger.Default.UnregisterAll(this);\n    }\n}\n```\n\n**Key Differences:**\n- ✅ Type-safe message classes\n- ✅ No magic strings\n- ✅ Better IntelliSense support\n- ✅ Easier to refactor\n- ⚠️ **Must remember to unregister!**\n\n---\n\n### ListView and TableView Deprecated\n\n**Status:** 🚨 **DEPRECATED (P0)** - `ListView`, `TableView`, and all Cell types are now obsolete. Migrate to `CollectionView`.\n\n**Warning You'll See:**\n```\nwarning CS0618: 'ListView' is obsolete: 'ListView is deprecated. Please use CollectionView instead.'\nwarning CS0618: 'TableView' is obsolete: 'Please use CollectionView instead.'\nwarning CS0618: 'TextCell' is obsolete: 'The controls which use TextCell (ListView and TableView) are obsolete. Please use CollectionView instead.'\n```\n\n**Obsolete Types:**\n- `ListView` → `CollectionView`\n- `TableView` → `CollectionView` (for settings pages, consider vertical StackLayout with BindableLayout)\n- `TextCell` → Custom DataTemplate with Label(s)\n- `ImageCell` → Custom DataTemplate with Image + Label(s)\n- `EntryCell` → Custom DataTemplate with Entry\n- `SwitchCell` → Custom DataTemplate with Switch\n- `ViewCell` → DataTemplate\n\n**Impact:** This is a **MAJOR** breaking change. ListView and TableView are among the most commonly used controls in MAUI apps.\n\n#### Why This Takes Time\n\nConverting ListView/TableView to CollectionView is not a simple find-replace:\n\n1. **Different event model** - `ItemSelected` → `SelectionChanged` with different arguments\n2. **Different grouping** - GroupDisplayBinding no longer exists\n3. **Context actions** - Must convert to SwipeView\n4. **Item sizing** - `HasUnevenRows` handled differently\n5. **Platform-specific code** - iOS/Android ListView platform configurations need removal\n6. **Testing required** - CollectionView virtualizes differently, may affect performance\n\n#### Migration Strategy\n\n**Step 1: Inventory Your ListViews**\n\n```bash\n# Find all ListView/TableView usages\ngrep -r \"ListView\\|TableView\" --include=\"*.xaml\" --include=\"*.cs\" .\n```\n\n**Step 2: Basic ListView → CollectionView**\n\n**Before (ListView):**\n```xaml\n\u003cListView ItemsSource=\"{Binding Items}\"\n          ItemSelected=\"OnItemSelected\"\n          HasUnevenRows=\"True\"\u003e\n    \u003cListView.ItemTemplate\u003e\n        \u003cDataTemplate\u003e\n            \u003cTextCell Text=\"{Binding Title}\"\n                     Detail=\"{Binding Description}\" /\u003e\n        \u003c/DataTemplate\u003e\n    \u003c/ListView.ItemTemplate\u003e\n\u003c/ListView\u003e\n```\n\n**After (CollectionView):**\n```xaml\n\u003cCollectionView ItemsSource=\"{Binding Items}\"\n                SelectionMode=\"Single\"\n                SelectionChanged=\"OnSelectionChanged\"\u003e\n    \u003cCollectionView.ItemTemplate\u003e\n        \u003cDataTemplate\u003e\n            \u003cVerticalStackLayout Padding=\"10\"\u003e\n                \u003cLabel Text=\"{Binding Title}\" \n                       FontAttributes=\"Bold\" /\u003e\n                \u003cLabel Text=\"{Binding Description}\"\n                       FontSize=\"12\"\n                       TextColor=\"{StaticResource Gray600}\" /\u003e\n            \u003c/VerticalStackLayout\u003e\n        \u003c/DataTemplate\u003e\n    \u003c/CollectionView.ItemTemplate\u003e\n\u003c/CollectionView\u003e\n```\n\n\u003e ⚠️ **Note:** CollectionView has `SelectionMode=\"None\"` by default (selection disabled). You must explicitly set `SelectionMode=\"Single\"` or `SelectionMode=\"Multiple\"` to enable selection.\n\n**Code-behind changes:**\n```csharp\n// ❌ OLD (ListView)\nvoid OnItemSelected(object sender, SelectedItemChangedEventArgs e)\n{\n    if (e.SelectedItem == null)\n        return;\n        \n    var item = (MyItem)e.SelectedItem;\n    // Handle selection\n    \n    // Deselect\n    ((ListView)sender).SelectedItem = null;\n}\n\n// ✅ NEW (CollectionView)\nvoid OnSelectionChanged(object sender, SelectionChangedEventArgs e)\n{\n    if (e.CurrentSelection.Count == 0)\n        return;\n        \n    var item = (MyItem)e.CurrentSelection.FirstOrDefault();\n    // Handle selection\n    \n    // Deselect (optional)\n    ((CollectionView)sender).SelectedItem = null;\n}\n```\n\n**Step 3: Grouped ListView → Grouped CollectionView**\n\n**Before (Grouped ListView):**\n```xaml\n\u003cListView ItemsSource=\"{Binding GroupedItems}\"\n          IsGroupingEnabled=\"True\"\n          GroupDisplayBinding=\"{Binding Key}\"\u003e\n    \u003cListView.ItemTemplate\u003e\n        \u003cDataTemplate\u003e\n            \u003cTextCell Text=\"{Binding Name}\" /\u003e\n        \u003c/DataTemplate\u003e\n    \u003c/ListView.ItemTemplate\u003e\n\u003c/ListView\u003e\n```\n\n**After (Grouped CollectionView):**\n```xaml\n\u003cCollectionView ItemsSource=\"{Binding GroupedItems}\"\n                IsGrouped=\"true\"\u003e\n    \u003cCollectionView.GroupHeaderTemplate\u003e\n        \u003cDataTemplate\u003e\n            \u003cLabel Text=\"{Binding Key}\"\n                   FontAttributes=\"Bold\"\n                   BackgroundColor=\"{StaticResource Gray100}\"\n                   Padding=\"10,5\" /\u003e\n        \u003c/DataTemplate\u003e\n    \u003c/CollectionView.GroupHeaderTemplate\u003e\n    \n    \u003cCollectionView.ItemTemplate\u003e\n        \u003cDataTemplate\u003e\n            \u003cVerticalStackLayout Padding=\"20,10\"\u003e\n                \u003cLabel Text=\"{Binding Name}\" /\u003e\n            \u003c/VerticalStackLayout\u003e\n        \u003c/DataTemplate\u003e\n    \u003c/CollectionView.ItemTemplate\u003e\n\u003c/CollectionView\u003e\n```\n\n**Step 4: Context Actions → SwipeView**\n\n\u003e ⚠️ **Platform Note:** SwipeView requires touch input. On Windows desktop, it only works with touch screens, not with mouse/trackpad. Consider providing alternative UI for desktop scenarios (e.g., buttons, right-click menu).\n\n**Before (ListView with ContextActions):**\n```xaml\n\u003cListView.ItemTemplate\u003e\n    \u003cDataTemplate\u003e\n        \u003cViewCell\u003e\n            \u003cViewCell.ContextActions\u003e\n                \u003cMenuItem Text=\"Delete\" \n                         IsDestructive=\"True\"\n                         Command=\"{Binding Source={RelativeSource AncestorType={x:Type local:MyPage}}, Path=DeleteCommand}\"\n                         CommandParameter=\"{Binding .}\" /\u003e\n            \u003c/ViewCell.ContextActions\u003e\n            \n            \u003cLabel Text=\"{Binding Title}\" Padding=\"10\" /\u003e\n        \u003c/ViewCell\u003e\n    \u003c/DataTemplate\u003e\n\u003c/ListView.ItemTemplate\u003e\n```\n\n**After (CollectionView with SwipeView):**\n```xaml\n\u003cCollectionView.ItemTemplate\u003e\n    \u003cDataTemplate\u003e\n        \u003cSwipeView\u003e\n            \u003cSwipeView.RightItems\u003e\n                \u003cSwipeItems\u003e\n                    \u003cSwipeItem Text=\"Delete\"\n                              BackgroundColor=\"Red\"\n                              Command=\"{Binding Source={RelativeSource AncestorType={x:Type local:MyPage}}, Path=DeleteCommand}\"\n                              CommandParameter=\"{Binding .}\" /\u003e\n                \u003c/SwipeItems\u003e\n            \u003c/SwipeView.RightItems\u003e\n            \n            \u003cVerticalStackLayout Padding=\"10\"\u003e\n                \u003cLabel Text=\"{Binding Title}\" /\u003e\n            \u003c/VerticalStackLayout\u003e\n        \u003c/SwipeView\u003e\n    \u003c/DataTemplate\u003e\n\u003c/CollectionView.ItemTemplate\u003e\n```\n\n**Step 5: TableView for Settings → Alternative Approaches**\n\nTableView is commonly used for settings pages. Here are modern alternatives:\n\n**Option 1: CollectionView with Grouped Data**\n```xaml\n\u003cCollectionView ItemsSource=\"{Binding SettingGroups}\"\n                IsGrouped=\"true\"\n                SelectionMode=\"None\"\u003e\n    \u003cCollectionView.GroupHeaderTemplate\u003e\n        \u003cDataTemplate\u003e\n            \u003cLabel Text=\"{Binding Title}\" \n                   FontAttributes=\"Bold\"\n                   Margin=\"10,15,10,5\" /\u003e\n        \u003c/DataTemplate\u003e\n    \u003c/CollectionView.GroupHeaderTemplate\u003e\n    \n    \u003cCollectionView.ItemTemplate\u003e\n        \u003cDataTemplate\u003e\n            \u003cGrid Padding=\"15,10\" ColumnDefinitions=\"*,Auto\"\u003e\n                \u003cLabel Text=\"{Binding Title}\" \n                       VerticalOptions=\"Center\" /\u003e\n                \u003cSwitch Grid.Column=\"1\" \n                        IsToggled=\"{Binding IsEnabled}\"\n                        IsVisible=\"{Binding ShowSwitch}\" /\u003e\n            \u003c/Grid\u003e\n        \u003c/DataTemplate\u003e\n    \u003c/CollectionView.ItemTemplate\u003e\n\u003c/CollectionView\u003e\n```\n\n**Option 2: Vertical StackLayout (for small settings lists)**\n```xaml\n\u003cScrollView\u003e\n    \u003cVerticalStackLayout BindableLayout.ItemsSource=\"{Binding Settings}\"\n                        Spacing=\"10\"\n                        Padding=\"15\"\u003e\n        \u003cBindableLayout.ItemTemplate\u003e\n            \u003cDataTemplate\u003e\n                \u003cBorder StrokeThickness=\"0\"\n                       BackgroundColor=\"{StaticResource Gray100}\"\n                       Padding=\"15,10\"\u003e\n                    \u003cGrid ColumnDefinitions=\"*,Auto\"\u003e\n                        \u003cLabel Text=\"{Binding Title}\" \n                              VerticalOptions=\"Center\" /\u003e\n                        \u003cSwitch Grid.Column=\"1\" \n                               IsToggled=\"{Binding IsEnabled}\" /\u003e\n                    \u003c/Grid\u003e\n                \u003c/Border\u003e\n            \u003c/DataTemplate\u003e\n        \u003c/BindableLayout.ItemTemplate\u003e\n    \u003c/VerticalStackLayout\u003e\n\u003c/ScrollView\u003e\n```\n\n**Step 6: Remove Platform-Specific ListView Code**\n\nIf you used platform-specific ListView features, remove them:\n\n```csharp\n// ❌ OLD - Remove these using statements (NOW OBSOLETE IN .NET 10)\nusing Microsoft.Maui.Controls.PlatformConfiguration;\nusing Microsoft.Maui.Controls.PlatformConfiguration.iOSSpecific;\nusing Microsoft.Maui.Controls.PlatformConfiguration.AndroidSpecific;\n\n// ❌ OLD - Remove ListView platform configurations (NOW OBSOLETE IN .NET 10)\nmyListView.On\u003ciOS\u003e().SetSeparatorStyle(SeparatorStyle.FullWidth);\nmyListView.On\u003cAndroid\u003e().IsFastScrollEnabled();\n\n// ❌ OLD - Remove Cell platform configurations (NOW OBSOLETE IN .NET 10)\nviewCell.On\u003ciOS\u003e().SetDefaultBackgroundColor(Colors.White);\nviewCell.On\u003cAndroid\u003e().SetIsContextActionsLegacyModeEnabled(false);\n```\n\n**Migration:** CollectionView does not have platform-specific configurations in the same way. If you need platform-specific styling:\n\n```csharp\n// ✅ NEW - Use conditional compilation\n#if IOS\nvar backgroundColor = Colors.White;\n#elif ANDROID\nvar backgroundColor = Colors.Transparent;\n#endif\n\nvar grid = new Grid\n{\n    BackgroundColor = backgroundColor,\n    // ... rest of cell content\n};\n```\n\nOr in XAML:\n```xaml\n\u003cCollectionView.ItemTemplate\u003e\n    \u003cDataTemplate\u003e\n        \u003cGrid\u003e\n            \u003cGrid.BackgroundColor\u003e\n                \u003cOnPlatform x:TypeArguments=\"Color\"\u003e\n                    \u003cOn Platform=\"iOS\" Value=\"White\" /\u003e\n                    \u003cOn Platform=\"Android\" Value=\"Transparent\" /\u003e\n                \u003c/OnPlatform\u003e\n            \u003c/Grid.BackgroundColor\u003e\n            \u003c!-- Cell content --\u003e\n        \u003c/Grid\u003e\n    \u003c/DataTemplate\u003e\n\u003c/CollectionView.ItemTemplate\u003e\n```\n\n#### Common Patterns \u0026 Pitfalls\n\n**1. Empty View**\n```xaml\n\u003c!-- CollectionView has built-in EmptyView support --\u003e\n\u003cCollectionView ItemsSource=\"{Binding Items}\"\u003e\n    \u003cCollectionView.EmptyView\u003e\n        \u003cContentView\u003e\n            \u003cVerticalStackLayout Padding=\"50\" VerticalOptions=\"Center\"\u003e\n                \u003cLabel Text=\"No items found\" \n                       HorizontalTextAlignment=\"Center\" /\u003e\n            \u003c/VerticalStackLayout\u003e\n        \u003c/ContentView\u003e\n    \u003c/CollectionView.EmptyView\u003e\n    \u003c!-- ... --\u003e\n\u003c/CollectionView\u003e\n```\n\n**2. Pull to Refresh**\n```xaml\n\u003cRefreshView IsRefreshing=\"{Binding IsRefreshing}\"\n             Command=\"{Binding RefreshCommand}\"\u003e\n    \u003cCollectionView ItemsSource=\"{Binding Items}\"\u003e\n        \u003c!-- ... --\u003e\n    \u003c/CollectionView\u003e\n\u003c/RefreshView\u003e\n```\n\n**3. Item Spacing**\n```xaml\n\u003c!-- Use ItemsLayout for spacing --\u003e\n\u003cCollectionView ItemsSource=\"{Binding Items}\"\u003e\n    \u003cCollectionView.ItemsLayout\u003e\n        \u003cLinearItemsLayout Orientation=\"Vertical\" \n                          ItemSpacing=\"10\" /\u003e\n    \u003c/CollectionView.ItemsLayout\u003e\n    \u003c!-- ... --\u003e\n\u003c/CollectionView\u003e\n```\n\n**4. Header and Footer**\n```xaml\n\u003cCollectionView ItemsSource=\"{Binding Items}\"\u003e\n    \u003cCollectionView.Header\u003e\n        \u003cLabel Text=\"My List\" \n               FontSize=\"24\" \n               Padding=\"10\" /\u003e\n    \u003c/CollectionView.Header\u003e\n    \n    \u003cCollectionView.Footer\u003e\n        \u003cLabel Text=\"End of list\" \n               Padding=\"10\" \n               HorizontalTextAlignment=\"Center\" /\u003e\n    \u003c/CollectionView.Footer\u003e\n    \n    \u003c!-- ItemTemplate --\u003e\n\u003c/CollectionView\u003e\n```\n\n**5. Load More / Infinite Scroll**\n```xaml\n\u003cCollectionView ItemsSource=\"{Binding Items}\"\n                RemainingItemsThreshold=\"5\"\n                RemainingItemsThresholdReachedCommand=\"{Binding LoadMoreCommand}\"\u003e\n    \u003c!-- ItemTemplate --\u003e\n\u003c/CollectionView\u003e\n```\n\n**6. Item Sizing Optimization**\n\nCollectionView uses `ItemSizingStrategy` to control item measurement:\n\n```xaml\n\u003c!-- Default: Each item measured individually (like HasUnevenRows=\"True\") --\u003e\n\u003cCollectionView ItemSizingStrategy=\"MeasureAllItems\"\u003e\n    \u003c!-- ... --\u003e\n\u003c/CollectionView\u003e\n\n\u003c!-- Performance: Only first item measured, rest use same height --\u003e\n\u003cCollectionView ItemSizingStrategy=\"MeasureFirstItem\"\u003e\n    \u003c!-- Use this when all items have similar heights --\u003e\n\u003c/CollectionView\u003e\n```\n\n\u003e 💡 **Performance Tip:** If your list items have consistent heights, use `ItemSizingStrategy=\"MeasureFirstItem\"` for better performance with large lists.\n\n#### .NET 10 Handler Changes (iOS/Mac Catalyst)\n\n\u003e ℹ️ **.NET 10 uses new optimized CollectionView and CarouselView handlers** on iOS and Mac Catalyst by default, providing improved performance and stability.\n\n**If you previously opted-in to the new handlers in .NET 9**, you should now **REMOVE** this code:\n\n```csharp\n// ❌ REMOVE THIS in .NET 10 (these handlers are now default)\n#if IOS || MACCATALYST\nbuilder.ConfigureMauiHandlers(handlers =\u003e\n{\n    handlers.AddHandler\u003cCollectionView, CollectionViewHandler2\u003e();\n    handlers.AddHandler\u003cCarouselView, CarouselViewHandler2\u003e();\n});\n#endif\n```\n\nThe optimized handlers are used automatically in .NET 10 - no configuration needed!\n\n**Only if you experience issues**, you can revert to the legacy handler:\n\n```csharp\n// In MauiProgram.cs - only if needed\n#if IOS || MACCATALYST\nbuilder.ConfigureMauiHandlers(handlers =\u003e\n{\n    handlers.AddHandler\u003cMicrosoft.Maui.Controls.CollectionView, \n                        Microsoft.Maui.Controls.Handlers.Items.CollectionViewHandler\u003e();\n});\n#endif\n```\n\nHowever, Microsoft recommends using the new default handlers for best results.\n\n#### Testing Checklist\n\nAfter migration, test these scenarios:\n\n- [ ] **Item selection** works correctly\n- [ ] **Grouped lists** display with proper headers\n- [ ] **Swipe actions** (if used) work on both iOS and Android\n- [ ] **Empty view** appears when list is empty\n- [ ] **Pull to refresh** works (if used)\n- [ ] **Scroll performance** is acceptable (especially for large lists)\n- [ ] **Item sizing** is correct (CollectionView auto-sizes by default)\n- [ ] **Selection visual state** shows/hides correctly\n- [ ] **Data binding** updates the list correctly\n- [ ] **Navigation** from list items works\n\n#### Migration Complexity Factors\n\nListView to CollectionView migration is complex because:\n- Each ListView may have unique behaviors\n- Platform-specific code needs updating\n- Extensive testing required\n- Context actions need SwipeView conversion\n- Grouped lists need template updates\n- ViewModel changes may be needed\n\n#### Quick Reference: ListView vs CollectionView\n\n| Feature | ListView | CollectionView |\n|---------|----------|----------------|\n| **Selection Event** | `ItemSelected` | `SelectionChanged` |\n| **Selection Args** | `SelectedItemChangedEventArgs` | `SelectionChangedEventArgs` |\n| **Getting Selected** | `e.SelectedItem` | `e.CurrentSelection.FirstOrDefault()` |\n| **Context Menus** | `ContextActions` | `SwipeView` |\n| **Grouping** | `IsGroupingEnabled=\"True\"` | `IsGrouped=\"true\"` |\n| **Group Header** | `GroupDisplayBinding` | `GroupHeaderTemplate` |\n| **Even Rows** | `HasUnevenRows=\"False\"` | Auto-sizes (default) |\n| **Empty State** | Manual | `EmptyView` property |\n| **Cells** | TextCell, ImageCell, etc. | Custom DataTemplate |\n\n---\n\n## Deprecated APIs (P1 - Fix Soon)\n\nThese APIs still work in .NET 10 but show compiler warnings. They will be removed in future versions.\n\n### 1. Animation Methods\n\n**Status:** ⚠️ **DEPRECATED** - All sync animation methods replaced with async versions.\n\n**Warning You'll See:**\n```\nwarning CS0618: 'ViewExtensions.FadeTo(VisualElement, double, uint, Easing)' is obsolete: 'Please use FadeToAsync instead.'\n```\n\n**Migration Table:**\n\n| Old Method | New Method | Example |\n|-----------|-----------|---------|\n| `FadeTo()` | `FadeToAsync()` | `await view.FadeToAsync(0, 500);` |\n| `ScaleTo()` | `ScaleToAsync()` | `await view.ScaleToAsync(1.5, 300);` |\n| `TranslateTo()` | `TranslateToAsync()` | `await view.TranslateToAsync(100, 100, 250);` |\n| `RotateTo()` | `RotateToAsync()` | `await view.RotateToAsync(360, 500);` |\n| `RotateXTo()` | `RotateXToAsync()` | `await view.RotateXToAsync(45, 300);` |\n| `RotateYTo()` | `RotateYToAsync()` | `await view.RotateYToAsync(45, 300);` |\n| `ScaleXTo()` | `ScaleXToAsync()` | `await view.ScaleXToAsync(2.0, 300);` |\n| `ScaleYTo()` | `ScaleYToAsync()` | `await view.ScaleYToAsync(2.0, 300);` |\n| `RelRotateTo()` | `RelRotateToAsync()` | `await view.RelRotateToAsync(90, 300);` |\n| `RelScaleTo()` | `RelScaleToAsync()` | `await view.RelScaleToAsync(0.5, 300);` |\n| `LayoutTo()` | `LayoutToAsync()` | See special note below |\n\n#### Migration Examples\n\n**Simple Animation:**\n```csharp\n// ❌ OLD (Deprecated)\nawait myButton.FadeTo(0, 500);\nawait myButton.ScaleTo(1.5, 300);\nawait myButton.TranslateTo(100, 100, 250);\n\n// ✅ NEW (Required)\nawait myButton.FadeToAsync(0, 500);\nawait myButton.ScaleToAsync(1.5, 300);\nawait myButton.TranslateToAsync(100, 100, 250);\n```\n\n**Sequential Animations:**\n```csharp\n// ❌ OLD\nawait image.FadeTo(0, 300);\nawait image.ScaleTo(0.5, 300);\nawait image.FadeTo(1, 300);\n\n// ✅ NEW\nawait image.FadeToAsync(0, 300);\nawait image.ScaleToAsync(0.5, 300);\nawait image.FadeToAsync(1, 300);\n```\n\n**Parallel Animations:**\n```csharp\n// ❌ OLD\nawait Task.WhenAll(\n    image.FadeTo(0, 300),\n    image.ScaleTo(0.5, 300),\n    image.RotateTo(360, 300)\n);\n\n// ✅ NEW\nawait Task.WhenAll(\n    image.FadeToAsync(0, 300),\n    image.ScaleToAsync(0.5, 300),\n    image.RotateToAsync(360, 300)\n);\n```\n\n**With Cancellation:**\n```csharp\n// NEW: Async methods support cancellation\nCancellationTokenSource cts = new();\n\ntry\n{\n    await view.FadeToAsync(0, 2000);\n}\ncatch (TaskCanceledException)\n{\n    // Animation was cancelled\n}\n\n// Cancel from elsewhere\ncts.Cancel();\n```\n\n#### Special Case: LayoutTo\n\n`LayoutToAsync()` is deprecated with a special message: \"Use Translation to animate layout changes.\"\n\n```csharp\n// ❌ OLD (Deprecated)\nawait view.LayoutToAsync(new Rect(100, 100, 200, 200), 250);\n\n// ✅ NEW (Use TranslateToAsync instead)\nawait view.TranslateToAsync(100, 100, 250);\n\n// Or animate Translation properties directly\nvar animation = new Animation(v =\u003e view.TranslationX = v, 0, 100);\nanimation.Commit(view, \"MoveX\", length: 250);\n```\n\n---\n\n### 2. DisplayAlert and DisplayActionSheet\n\n**Status:** ⚠️ **DEPRECATED** - Sync methods replaced with async versions.\n\n**Warning You'll See:**\n```\nwarning CS0618: 'Page.DisplayAlert(string, string, string)' is obsolete: 'Use DisplayAlertAsync instead'\n```\n\n#### Migration Examples\n\n**DisplayAlert:**\n```csharp\n// ❌ OLD (Deprecated)\nawait DisplayAlert(\"Success\", \"Data saved successfully\", \"OK\");\nawait DisplayAlert(\"Error\", \"Failed to save\", \"Cancel\");\nbool result = await DisplayAlert(\"Confirm\", \"Delete this item?\", \"Yes\", \"No\");\n\n// ✅ NEW (Required)\nawait DisplayAlertAsync(\"Success\", \"Data saved successfully\", \"OK\");\nawait DisplayAlertAsync(\"Error\", \"Failed to save\", \"Cancel\");\nbool result = await DisplayAlertAsync(\"Confirm\", \"Delete this item?\", \"Yes\", \"No\");\n```\n\n**DisplayActionSheet:**\n```csharp\n// ❌ OLD (Deprecated)\nstring action = await DisplayActionSheet(\n    \"Choose an action\",\n    \"Cancel\",\n    \"Delete\",\n    \"Edit\", \"Share\", \"Duplicate\"\n);\n\n// ✅ NEW (Required)\nstring action = await DisplayActionSheetAsync(\n    \"Choose an action\",\n    \"Cancel\",\n    \"Delete\",\n    \"Edit\", \"Share\", \"Duplicate\"\n);\n```\n\n**In ViewModels (with IDispatcher):**\n```csharp\n// If you're calling from a ViewModel, you'll need access to a Page\npublic class MyViewModel\n{\n    private readonly IDispatcher _dispatcher;\n    private readonly Page _page;\n    \n    public MyViewModel(IDispatcher dispatcher, Page page)\n    {\n        _dispatcher = dispatcher;\n        _page = page;\n    }\n    \n    public async Task ShowAlertAsync()\n    {\n        await _dispatcher.DispatchAsync(async () =\u003e\n        {\n            await _page.DisplayAlertAsync(\"Info\", \"Message from ViewModel\", \"OK\");\n        });\n    }\n}\n```\n\n---\n\n### 3. Page.IsBusy\n\n**Status:** ⚠️ **DEPRECATED** - Property will be removed in .NET 11.\n\n**Warning You'll See:**\n```\nwarning CS0618: 'Page.IsBusy' is obsolete: 'Page.IsBusy has been deprecated and will be removed in .NET 11'\n```\n\n**Why It's Deprecated:**\n- Inconsistent behavior across platforms\n- Limited customization options\n- Doesn't work well with modern MVVM patterns\n\n#### Migration Examples\n\n**Simple Page:**\n```xaml\n\u003c!-- ❌ OLD (Deprecated) --\u003e\n\u003cContentPage IsBusy=\"{Binding IsLoading}\"\u003e\n    \u003cStackLayout\u003e\n        \u003cLabel Text=\"Content here\" /\u003e\n    \u003c/StackLayout\u003e\n\u003c/ContentPage\u003e\n\n\u003c!-- ✅ NEW (Recommended) --\u003e\n\u003cContentPage\u003e\n    \u003cGrid\u003e\n        \u003c!-- Main content --\u003e\n        \u003cStackLayout\u003e\n            \u003cLabel Text=\"Content here\" /\u003e\n        \u003c/StackLayout\u003e\n        \n        \u003c!-- Loading indicator overlay --\u003e\n        \u003cActivityIndicator IsRunning=\"{Binding IsLoading}\"\n                          IsVisible=\"{Binding IsLoading}\"\n                          Color=\"{StaticResource Primary}\"\n                          VerticalOptions=\"Center\"\n                          HorizontalOptions=\"Center\" /\u003e\n    \u003c/Grid\u003e\n\u003c/ContentPage\u003e\n```\n\n**With Loading Overlay:**\n```xaml\n\u003c!-- ✅ Better: Custom loading overlay --\u003e\n\u003cContentPage\u003e\n    \u003cGrid\u003e\n        \u003c!-- Main content --\u003e\n        \u003cScrollView\u003e\n            \u003cVerticalStackLayout Padding=\"20\"\u003e\n                \u003cLabel Text=\"Your content here\" /\u003e\n            \u003c/VerticalStackLayout\u003e\n        \u003c/ScrollView\u003e\n        \n        \u003c!-- Loading overlay --\u003e\n        \u003cGrid IsVisible=\"{Binding IsLoading}\"\n              BackgroundColor=\"#80000000\"\u003e\n            \u003cVerticalStackLayout VerticalOptions=\"Center\"\n                               HorizontalOptions=\"Center\"\n                               Spacing=\"10\"\u003e\n                \u003cActivityIndicator IsRunning=\"True\"\n                                 Color=\"White\" /\u003e\n                \u003cLabel Text=\"Loading...\"\n                       TextColor=\"White\" /\u003e\n            \u003c/VerticalStackLayout\u003e\n        \u003c/Grid\u003e\n    \u003c/Grid\u003e\n\u003c/ContentPage\u003e\n```\n\n**In Code-Behind:**\n```csharp\n// ❌ OLD (Deprecated)\npublic partial class MyPage : ContentPage\n{\n    async Task LoadDataAsync()\n    {\n        IsBusy = true;\n        try\n        {\n            await LoadDataFromServerAsync();\n        }\n        finally\n        {\n            IsBusy = false;\n        }\n    }\n}\n\n// ✅ NEW (Recommended)\npublic partial class MyPage : ContentPage\n{\n    async Task LoadDataAsync()\n    {\n        LoadingIndicator.IsVisible = true;\n        LoadingIndicator.IsRunning = true;\n        try\n        {\n            await LoadDataFromServerAsync();\n        }\n        finally\n        {\n            LoadingIndicator.IsVisible = false;\n            LoadingIndicator.IsRunning = false;\n        }\n    }\n}\n```\n\n**In ViewModel:**\n```csharp\npublic class MyViewModel : INotifyPropertyChanged\n{\n    private bool _isLoading;\n    public bool IsLoading\n    {\n        get =\u003e _isLoading;\n        set\n        {\n            _isLoading = value;\n            OnPropertyChanged();\n        }\n    }\n    \n    public async Task LoadDataAsync()\n    {\n        IsLoading = true;\n        try\n        {\n            await LoadDataFromServerAsync();\n        }\n        finally\n        {\n            IsLoading = false;\n        }\n    }\n}\n```\n\n---\n\n### 4. MediaPicker APIs\n\n**Status:** ⚠️ **DEPRECATED** - Single-selection methods replaced with multi-selection variants.\n\n**Warning You'll See:**\n```\nwarning CS0618: 'MediaPicker.PickPhotoAsync(MediaPickerOptions)' is obsolete: 'Switch to PickPhotosAsync which also allows multiple selections.'\nwarning CS0618: 'MediaPicker.PickVideoAsync(MediaPickerOptions)' is obsolete: 'Switch to PickVideosAsync which also allows multiple selections.'\n```\n\n**What Changed:**\n- `PickPhotoAsync()` → `PickPhotosAsync()` (returns `List\u003cFileResult\u003e`)\n- `PickVideoAsync()` → `PickVideosAsync()` (returns `List\u003cFileResult\u003e`)\n- New `SelectionLimit` property on `MediaPickerOptions` (default: 1)\n- Old methods still work but are marked obsolete\n\n**Key Behavior:**\n- **Default behavior preserved:** `SelectionLimit = 1` (single selection)\n- Set `SelectionLimit = 0` for unlimited multi-select\n- Set `SelectionLimit \u003e 1` for specific limits\n\n**Platform Notes:**\n- ✅ **iOS:** Selection limit enforced by native picker UI\n- ⚠️ **Android:** Not all custom pickers honor `SelectionLimit` - be aware!\n- ⚠️ **Windows:** `SelectionLimit` not supported - implement your own validation\n\n#### Migration Examples\n\n**Simple Photo Picker (maintain single-selection behavior):**\n```csharp\n// ❌ OLD (Deprecated)\nvar photo = await MediaPicker.PickPhotoAsync(new MediaPickerOptions\n{\n    Title = \"Pick a photo\"\n});\n\nif (photo != null)\n{\n    var stream = await photo.OpenReadAsync();\n    MyImage.Source = ImageSource.FromStream(() =\u003e stream);\n}\n\n// ✅ NEW (maintains same behavior - picks only 1 photo)\nvar photos = await MediaPicker.PickPhotosAsync(new MediaPickerOptions\n{\n    Title = \"Pick a photo\",\n    SelectionLimit = 1  // Explicit: only 1 photo\n});\n\nvar photo = photos.FirstOrDefault();\nif (photo != null)\n{\n    var stream = await photo.OpenReadAsync();\n    MyImage.Source = ImageSource.FromStream(() =\u003e stream);\n}\n```\n\n**Simple Video Picker (maintain single-selection behavior):**\n```csharp\n// ❌ OLD (Deprecated)\nvar video = await MediaPicker.PickVideoAsync(new MediaPickerOptions\n{\n    Title = \"Pick a video\"\n});\n\nif (video != null)\n{\n    VideoPlayer.Source = video.FullPath;\n}\n\n// ✅ NEW (maintains same behavior - picks only 1 video)\nvar videos = await MediaPicker.PickVideosAsync(new MediaPickerOptions\n{\n    Title = \"Pick a video\",\n    SelectionLimit = 1  // Explicit: only 1 video\n});\n\nvar video = videos.FirstOrDefault();\nif (video != null)\n{\n    VideoPlayer.Source = video.FullPath;\n}\n```\n\n**Photo Picker without Options (uses defaults):**\n```csharp\n// ❌ OLD (Deprecated)\nvar photo = await MediaPicker.PickPhotoAsync();\n\n// ✅ NEW (default SelectionLimit = 1, so same behavior)\nvar photos = await MediaPicker.PickPhotosAsync();\nvar photo = photos.FirstOrDefault();\n```\n\n**Multi-Photo Selection (new capability):**\n```csharp\n// ✅ NEW: Pick up to 5 photos\nvar photos = await MediaPicker.PickPhotosAsync(new MediaPickerOptions\n{\n    Title = \"Pick up to 5 photos\",\n    SelectionLimit = 5\n});\n\nforeach (var photo in photos)\n{\n    var stream = await photo.OpenReadAsync();\n    // Process each photo\n}\n\n// ✅ NEW: Unlimited selection\nvar allPhotos = await MediaPicker.PickPhotosAsync(new MediaPickerOptions\n{\n    Title = \"Pick photos\",\n    SelectionLimit = 0  // No limit\n});\n```\n\n**Multi-Video Selection (new capability):**\n```csharp\n// ✅ NEW: Pick up to 3 videos\nvar videos = await MediaPicker.PickVideosAsync(new MediaPickerOptions\n{\n    Title = \"Pick up to 3 videos\",\n    SelectionLimit = 3\n});\n\nforeach (var video in videos)\n{\n    // Process each video\n    Console.WriteLine($\"Selected: {video.FileName}\");\n}\n```\n\n**Handling Empty Results:**\n```csharp\n// NEW: Returns empty list if user cancels (not null)\nvar photos = await MediaPicker.PickPhotosAsync(new MediaPickerOptions\n{\n    SelectionLimit = 1\n});\n\n// ✅ Check for empty list\nif (photos.Count == 0)\n{\n    await DisplayAlertAsync(\"Cancelled\", \"No photo selected\", \"OK\");\n    return;\n}\n\nvar photo = photos.First();\n// Process photo...\n```\n\n**With Try-Catch (same as before):**\n```csharp\ntry\n{\n    var photos = await MediaPicker.PickPhotosAsync(new MediaPickerOptions\n    {\n        Title = \"Pick a photo\",\n        SelectionLimit = 1\n    });\n    \n    if (photos.Count \u003e 0)\n    {\n        await ProcessPhotoAsync(photos.First());\n    }\n}\ncatch (PermissionException)\n{\n    await DisplayAlertAsync(\"Permission Denied\", \"Camera access required\", \"OK\");\n}\ncatch (Exception ex)\n{\n    await DisplayAlertAsync(\"Error\", $\"Failed to pick photo: {ex.Message}\", \"OK\");\n}\n```\n\n#### Migration Checklist\n\nWhen migrating to the new MediaPicker APIs:\n\n- [ ] Replace `PickPhotoAsync()` with `PickPhotosAsync()`\n- [ ] Replace `PickVideoAsync()` with `PickVideosAsync()`\n- [ ] Set `SelectionLimit = 1` to maintain single-selection behavior\n- [ ] Change `FileResult?` to `List\u003cFileResult\u003e` (or use `.FirstOrDefault()`)\n- [ ] Update null checks to empty list checks (`photos.Count == 0`)\n- [ ] Test on Android - ensure custom pickers respect limit (or add validation)\n- [ ] Test on Windows - add your own limit validation if needed\n- [ ] Consider if multi-select would improve your UX (optional)\n\n#### Platform-Specific Validation (Windows \u0026 Android)\n\n```csharp\n// ✅ Recommended: Validate selection limit on platforms that don't enforce it\nvar photos = await MediaPicker.PickPhotosAsync(new MediaPickerOptions\n{\n    Title = \"Pick up to 5 photos\",\n    SelectionLimit = 5\n});\n\n// On Windows and some Android pickers, the limit might not be enforced\nif (photos.Count \u003e 5)\n{\n    await DisplayAlertAsync(\n        \"Too Many Photos\", \n        $\"Please select up to 5 photos. You selected {photos.Count}.\", \n        \"OK\"\n    );\n    return;\n}\n\n// Continue processing...\n```\n\n#### Capture Methods (unchanged)\n\n**Note:** Capture methods (`CapturePhotoAsync`, `CaptureVideoAsync`) are **NOT** deprecated and remain unchanged:\n\n```csharp\n// ✅ These still work as-is (no changes needed)\nvar photo = await MediaPicker.CapturePhotoAsync();\nvar video = await MediaPicker.CaptureVideoAsync();\n```\n\n#### Quick Migration Pattern\n\n**For all existing single-selection code, use this pattern:**\n\n```csharp\n// ❌ OLD\nvar photo = await MediaPicker.PickPhotoAsync(options);\nif (photo != null)\n{\n    // Process photo\n}\n\n// ✅ NEW (drop-in replacement)\nvar photos = await MediaPicker.PickPhotosAsync(options ?? new MediaPickerOptions { SelectionLimit = 1 });\nvar photo = photos.FirstOrDefault();\nif (photo != null)\n{\n    // Process photo (same code as before)\n}\n```\n\n---\n\n## Recommended Changes (P2)\n\nThese changes are recommended but not required immediately. Consider migrating during your next refactoring cycle.\n\n### Application.MainPage\n\n**Status:** ⚠️ **DEPRECATED** - Property will be removed in future version.\n\n**Warning You'll See:**\n```\nwarning CS0618: 'Application.MainPage' is obsolete: 'This property is deprecated. Initialize your application by overriding Application.CreateWindow...'\n```\n\n#### Migration Example\n\n```csharp\n// ❌ OLD (Deprecated)\npublic partial class App : Application\n{\n    public App()\n    {\n        InitializeComponent();\n        MainPage = new AppShell();\n    }\n    \n    // Changing page later\n    public void SwitchToLoginPage()\n    {\n        MainPage = new LoginPage();\n    }\n}\n\n// ✅ NEW (Recommended)\npublic partial class App : Application\n{\n    public App()\n    {\n        InitializeComponent();\n    }\n    \n    protected override Window CreateWindow(IActivationState? activationState)\n    {\n        return new Window(new AppShell());\n    }\n    \n    // Changing page later\n    public void SwitchToLoginPage()\n    {\n        if (Windows.Count \u003e 0)\n        {\n            Windows[0].Page = new LoginPage();\n        }\n    }\n}\n```\n\n**Benefits of CreateWindow:**\n- Better multi-window support\n- More explicit initialization\n- Cleaner separation of concerns\n- Works better with Shell\n\n---\n\n## Bulk Migration Tools\n\nUse these find/replace patterns to quickly update your codebase.\n\n### Visual Studio / VS Code\n\n**Regex Mode - Find/Replace**\n\n#### Animation Methods\n\n```regex\nFind:    \\.FadeTo\\(\nReplace: .FadeToAsync(\n\nFind:    \\.ScaleTo\\(\nReplace: .ScaleToAsync(\n\nFind:    \\.TranslateTo\\(\nReplace: .TranslateToAsync(\n\nFind:    \\.RotateTo\\(\nReplace: .RotateToAsync(\n\nFind:    \\.RotateXTo\\(\nReplace: .RotateXToAsync(\n\nFind:    \\.RotateYTo\\(\nReplace: .RotateYToAsync(\n\nFind:    \\.ScaleXTo\\(\nReplace: .ScaleXToAsync(\n\nFind:    \\.ScaleYTo\\(\nReplace: .ScaleYToAsync(\n\nFind:    \\.RelRotateTo\\(\nReplace: .RelRotateToAsync(\n\nFind:    \\.RelScaleTo\\(\nReplace: .RelScaleToAsync(\n```\n\n#### Display Methods\n\n```regex\nFind:    DisplayAlert\\(\nReplace: DisplayAlertAsync(\n\nFind:    DisplayActionSheet\\(\nReplace: DisplayActionSheetAsync(\n```\n\n#### MediaPicker Methods\n\n**⚠️ Note:** MediaPicker migration requires manual code changes due to return type changes (`FileResult?` → `List\u003cFileResult\u003e`). Use these searches to find instances:\n\n```bash\n# Find PickPhotoAsync usages\ngrep -rn \"PickPhotoAsync\" --include=\"*.cs\" .\n\n# Find PickVideoAsync usages\ngrep -rn \"PickVideoAsync\" --include=\"*.cs\" .\n```\n\n**Manual Migration Pattern:**\n```csharp\n// Find: await MediaPicker.PickPhotoAsync(\n// Replace with:\nvar photos = await MediaPicker.PickPhotosAsync(new MediaPickerOptions { SelectionLimit = 1 });\nvar photo = photos.FirstOrDefault();\n\n// Find: await MediaPicker.PickVideoAsync(\n// Replace with:\nvar videos = await MediaPicker.PickVideosAsync(new MediaPickerOptions { SelectionLimit = 1 });\nvar video = videos.FirstOrDefault();\n```\n\n#### ListView/TableView Detection (Manual Migration Required)\n\n**⚠️ Note:** ListView/TableView migration CANNOT be automated. Use these searches to find instances:\n\n```bash\n# Find all ListView usages in XAML\ngrep -r \"\u003cListView\" --include=\"*.xaml\" .\n\n# Find all TableView usages in XAML\ngrep -r \"\u003cTableView\" --include=\"*.xaml\" .\n\n# Find ListView in C# code\ngrep -r \"new ListView\\|ListView \" --include=\"*.cs\" .\n\n# Find Cell types in XAML\ngrep -r \"TextCell\\|ImageCell\\|EntryCell\\|SwitchCell\\|ViewCell\" --include=\"*.xaml\" .\n\n# Find ItemSelected handlers (need to change to SelectionChanged)\ngrep -r \"ItemSelected=\" --include=\"*.xaml\" .\ngrep -r \"ItemSelected\\s*\\+=\" --include=\"*.cs\" .\n\n# Find ContextActions (need to change to SwipeView)\ngrep -r \"ContextActions\" --include=\"*.xaml\" .\n\n# Find platform-specific ListView code (needs removal)\ngrep -r \"PlatformConfiguration.*ListView\" --include=\"*.cs\" .\n```\n\n**Create a Migration Inventory:**\n```bash\n# Generate a report of all ListView/TableView instances\necho \"=== ListView/TableView Migration Inventory ===\" \u003e migration-report.txt\necho \"\" \u003e\u003e migration-report.txt\necho \"XAML ListView instances:\" \u003e\u003e migration-report.txt\ngrep -rn \"\u003cListView\" --include=\"*.xaml\" . \u003e\u003e migration-report.txt\necho \"\" \u003e\u003e migration-report.txt\necho \"XAML TableView instances:\" \u003e\u003e migration-report.txt\ngrep -rn \"\u003cTableView\" --include=\"*.xaml\" . \u003e\u003e migration-report.txt\necho \"\" \u003e\u003e migration-report.txt\necho \"ItemSelected handlers:\" \u003e\u003e migration-report.txt\ngrep -rn \"ItemSelected\" --include=\"*.xaml\" --include=\"*.cs\" . \u003e\u003e migration-report.txt\necho \"\" \u003e\u003e migration-report.txt\ncat migration-report.txt\n```\n\n### PowerShell Script\n\n```powershell\n# Replace animation methods in all .cs files\nGet-ChildItem -Path . -Recurse -Filter *.cs | ForEach-Object {\n    $content = Get-Content $_.FullName -Raw\n    \n    # Animation methods\n    $content = $content -replace '\\.FadeTo\\(', '.FadeToAsync('\n    $content = $content -replace '\\.ScaleTo\\(', '.ScaleToAsync('\n    $content = $content -replace '\\.TranslateTo\\(', '.TranslateToAsync('\n    $content = $content -replace '\\.RotateTo\\(', '.RotateToAsync('\n    $content = $content -replace '\\.RotateXTo\\(', '.RotateXToAsync('\n    $content = $content -replace '\\.RotateYTo\\(', '.RotateYToAsync('\n    $content = $content -replace '\\.ScaleXTo\\(', '.ScaleXToAsync('\n    $content = $content -replace '\\.ScaleYTo\\(', '.ScaleYToAsync('\n    $content = $content -replace '\\.RelRotateTo\\(', '.RelRotateToAsync('\n    $content = $content -replace '\\.RelScaleTo\\(', '.RelScaleToAsync('\n    \n    # Display methods\n    $content = $content -replace 'DisplayAlert\\(', 'DisplayAlertAsync('\n    $content = $content -replace 'DisplayActionSheet\\(', 'DisplayActionSheetAsync('\n    \n    Set-Content $_.FullName $content\n}\n\nWrite-Host \"✅ Migration complete!\"\n```\n\n---\n\n## Testing Your Upgrade\n\n### Build Validation\n\n```bash\n# Clean solution\ndotnet clean\n\n# Restore packages\ndotnet restore\n\n# Build for each platform\ndotnet build -f net10.0-android -c Release\ndotnet build -f net10.0-ios -c Release\ndotnet build -f net10.0-maccatalyst -c Release\ndotnet build -f net10.0-windows -c Release\n\n# Check for warnings\ndotnet build --no-incremental 2\u003e\u00261 | grep -i \"warning CS0618\"\n```\n\n### Enable Warnings as Errors (Temporary)\n\n```xml\n\u003c!-- Add to your .csproj to catch all obsolete API usage --\u003e\n\u003cPropertyGroup\u003e\n  \u003cWarningsAsErrors\u003eCS0618\u003c/WarningsAsErrors\u003e\n\u003c/PropertyGroup\u003e\n```\n\n### Test Checklist\n\n- [ ] App launches successfully on all platforms\n- [ ] All animations work correctly\n- [ ] Dialogs (alerts/action sheets) display properly\n- [ ] Loading indicators work (if you used IsBusy)\n- [ ] Inter-component communication works (MessagingCenter replacement)\n- [ ] No CS0618 warnings in build output\n- [ ] No runtime exceptions related to obsolete APIs\n\n---\n\n## Troubleshooting\n\n### Error: 'MessagingCenter' is inaccessible due to its protection level\n\n**Cause:** MessagingCenter is now internal in .NET 10.\n\n**Solution:**\n1. Install `CommunityToolkit.Mvvm` package\n2. Replace with `WeakReferenceMessenger` (see [MessagingCenter section](#messagingcenter-made-internal))\n3. Create message classes for each message type\n4. Don't forget to unregister!\n\n---\n\n### Warning: Animation method is obsolete\n\n**Cause:** Using sync animation methods (`FadeTo`, `ScaleTo`, etc.)\n\n**Quick Fix:**\n```bash\n# Use PowerShell script from Bulk Migration Tools section\n# Or use Find/Replace patterns\n```\n\n**Manual Fix:**\nAdd `Async` to the end of each animation method call:\n- `FadeTo` → `FadeToAsync`\n- `ScaleTo` → `ScaleToAsync`\n- etc.\n\n---\n\n### Page.IsBusy doesn't work anymore\n\n**Cause:** IsBusy still works but is deprecated.\n\n**Solution:** Replace with explicit ActivityIndicator (see [IsBusy section](#3-pageisbusy))\n\n---\n\n### Build fails with \"Target framework 'net10.0' not found\"\n\n**Cause:** .NET 10 SDK not installed or not latest version.\n\n**Solution:**\n```bash\n# Check SDK version\ndotnet --version  # Should be 10.0.100 or later\n\n# Install .NET 10 SDK from:\n# https://dotnet.microsoft.com/download/dotnet/10.0\n\n# Update workloads\ndotnet workload update\n```\n\n---\n\n### MessagingCenter migration breaks existing code\n\n**Common Issues:**\n\n1. **Forgot to unregister:**\n   ```csharp\n   // ⚠️ Memory leak if you don't unregister\n   protected override void OnDisappearing()\n   {\n       base.OnDisappearing();\n       WeakReferenceMessenger.Default.UnregisterAll(this);\n   }\n   ```\n\n2. **Wrong message type:**\n   ```csharp\n   // ❌ Wrong\n   WeakReferenceMessenger.Default.Register\u003cUserLoggedIn\u003e(this, handler);\n   WeakReferenceMessenger.Default.Send(new UserData());  // Wrong type!\n   \n   // ✅ Correct\n   WeakReferenceMessenger.Default.Register\u003cUserLoggedInMessage\u003e(this, handler);\n   WeakReferenceMessenger.Default.Send(new UserLoggedInMessage(userData));\n   ```\n\n3. **Recipient parameter confusion:**\n   ```csharp\n   // The recipient parameter is the object that registered (this)\n   WeakReferenceMessenger.Default.Register\u003cMyMessage\u003e(this, (recipient, message) =\u003e\n   {\n       // recipient == this\n       // message == the message that was sent\n   });\n   ```\n\n---\n\n### Warning: MediaPicker methods are obsolete\n\n**Cause:** Using deprecated `PickPhotoAsync` or `PickVideoAsync` methods.\n\n**Solution:** Migrate to `PickPhotosAsync` or `PickVideosAsync`:\n\n```csharp\n// ❌ OLD\nvar photo = await MediaPicker.PickPhotoAsync(options);\n\n// ✅ NEW (maintain single-selection)\nvar photos = await MediaPicker.PickPhotosAsync(new MediaPickerOptions \n{ \n    Title = options?.Title,\n    SelectionLimit = 1 \n});\nvar photo = photos.FirstOrDefault();\n```\n\n**Key Changes:**\n- Return type changes from `FileResult?` to `List\u003cFileResult\u003e`\n- Use `.FirstOrDefault()` to get single result\n- Set `SelectionLimit = 1` to maintain old behavior\n- Check `photos.Count == 0` instead of `photo == null`\n\n---\n\n### MediaPicker returns more items than SelectionLimit\n\n**Cause:** Windows and some Android custom pickers don't enforce `SelectionLimit`.\n\n**Solution:** Add manual validation:\n\n```csharp\nvar photos = await MediaPicker.PickPhotosAsync(new MediaPickerOptions\n{\n    SelectionLimit = 5\n});\n\nif (photos.Count \u003e 5)\n{\n    await DisplayAlertAsync(\"Error\", \"Too many photos selected\", \"OK\");\n    return;\n}\n```\n\n---\n\n### Animation doesn't complete after migration\n\n**Cause:** Forgetting `await` keyword.\n\n```csharp\n// ❌ Wrong - animation runs but code continues immediately\nview.FadeToAsync(0, 500);\nDoSomethingElse();\n\n// ✅ Correct - wait for animation to complete\nawait view.FadeToAsync(0, 500);\nDoSomethingElse();\n```\n\n---\n\n### Warning: ListView/TableView/TextCell is obsolete\n\n**Cause:** Using deprecated ListView, TableView, or Cell types.\n\n**Solution:** Migrate to CollectionView (see [ListView and TableView section](#listview-and-tableview-deprecated))\n\n**Quick Decision Guide:**\n- **Simple list** → CollectionView with custom DataTemplate\n- **Settings page with \u003c20 items** → VerticalStackLayout with BindableLayout\n- **Settings page with 20+ items** → Grouped CollectionView\n- **Grouped data list** → CollectionView with `IsGrouped=\"True\"`\n\n---\n\n### CollectionView doesn't have SelectedItem event\n\n**Cause:** CollectionView uses `SelectionChanged` instead of `ItemSelected`.\n\n**Solution:**\n```csharp\n// ❌ OLD (ListView)\nvoid OnItemSelected(object sender, SelectedItemChangedEventArgs e)\n{\n    var item = e.SelectedItem as MyItem;\n}\n\n// ✅ NEW (CollectionView)\nvoid OnSelectionChanged(object sender, SelectionChangedEventArgs e)\n{\n    var item = e.CurrentSelection.FirstOrDefault() as MyItem;\n}\n```\n\n---\n\n### Platform-specific ListView configuration is obsolete\n\n**Cause:** Using `Microsoft.Maui.Controls.PlatformConfiguration.*Specific.ListView` extensions.\n\n**Error:**\n```\nwarning CS0618: 'ListView' is obsolete: 'With the deprecation of ListView, this class is obsolete. Please use CollectionView instead.'\n```\n\n**Solution:**\n1. Remove platform-specific ListView using statements:\n   ```csharp\n   // ❌ Remove these\n   using Microsoft.Maui.Controls.PlatformConfiguration;\n   using Microsoft.Maui.Controls.PlatformConfiguration.iOSSpecific;\n   using Microsoft.Maui.Controls.PlatformConfiguration.AndroidSpecific;\n   ```\n\n2. Remove platform-specific ListView calls:\n   ```csharp\n   // ❌ Remove these\n   myListView.On\u003ciOS\u003e().SetSeparatorStyle(SeparatorStyle.FullWidth);\n   myListView.On\u003cAndroid\u003e().IsFastScrollEnabled();\n   viewCell.On\u003ciOS\u003e().SetDefaultBackgroundColor(Colors.White);\n   ```\n\n3. CollectionView has different platform customization options - consult CollectionView docs for alternatives.\n\n---\n\n### CollectionView performance issues after ListView migration\n\n**Common Causes:**\n\n1. **Not using DataTemplate caching:**\n   ```xaml\n   \u003c!-- ❌ Bad performance --\u003e\n   \u003cCollectionView.ItemTemplate\u003e\n       \u003cDataTemplate\u003e\n           \u003cComplexView /\u003e\n       \u003c/DataTemplate\u003e\n   \u003c/CollectionView.ItemTemplate\u003e\n   \n   \u003c!-- ✅ Better - use simpler templates --\u003e\n   \u003cCollectionView.ItemTemplate\u003e\n       \u003cDataTemplate\u003e\n           \u003cVerticalStackLayout Padding=\"10\"\u003e\n               \u003cLabel Text=\"{Binding Title}\" /\u003e\n           \u003c/VerticalStackLayout\u003e\n       \u003c/DataTemplate\u003e\n   \u003c/CollectionView.ItemTemplate\u003e\n   ```\n\n2. **Complex nested layouts:**\n   - Avoid deeply nested layouts in ItemTemplate\n   - Use Grid instead of StackLayout when possible\n   - Consider FlexLayout for complex layouts\n\n3. **Images not being cached:**\n   ```xaml\n   \u003cImage Source=\"{Binding ImageUrl}\"\n          Aspect=\"AspectFill\"\n          HeightRequest=\"80\"\n          WidthRequest=\"80\"\u003e\n       \u003cImage.Behaviors\u003e\n           \u003c!-- Add caching behavior if needed --\u003e\n       \u003c/Image.Behaviors\u003e\n   \u003c/Image\u003e\n   ```\n\n---\n\n## Quick Reference Card\n\n### Priority Checklist\n\n**Must Fix (P0 - Breaking/Critical):**\n- [ ] Replace `MessagingCenter` with `WeakReferenceMessenger`\n- [ ] Migrate `ListView` to `CollectionView`\n- [ ] Migrate `TableView` to `CollectionView` or `BindableLayout`\n- [ ] Replace `TextCell`, `ImageCell`, etc. with custom DataTemplates\n- [ ] Convert `ContextActions` to `SwipeView`\n- [ ] Remove platform-specific ListView configurations\n\n**Should Fix (P1 - Deprecated):**\n- [ ] Update animation methods: add `Async` suffix\n- [ ] Update `DisplayAlert` → `DisplayAlertAsync`\n- [ ] Update `DisplayActionSheet` → `DisplayActionSheetAsync`  \n- [ ] Replace `Page.IsBusy` with `ActivityIndicator`\n- [ ] Replace `PickPhotoAsync` → `PickPhotosAsync` (with `SelectionLimit = 1`)\n- [ ] Replace `PickVideoAsync` → `PickVideosAsync` (with `SelectionLimit = 1`)\n\n**Nice to Have (P2):**\n- [ ] Migrate `Application.MainPage` to `CreateWindow`\n\n### Common Patterns\n\n```csharp\n// Animation\nawait view.FadeToAsync(0, 500);\n\n// Alert\nawait DisplayAlertAsync(\"Title\", \"Message\", \"OK\");\n\n// Messaging\nWeakReferenceMessenger.Default.Send(new MyMessage());\nWeakReferenceMessenger.Default.Register\u003cMyMessage\u003e(this, (r, m) =\u003e { });\nWeakReferenceMessenger.Default.UnregisterAll(this);\n\n// Loading\nIsLoading = true;\ntry { await LoadAsync(); }\nfinally { IsLoading = false; }\n```\n\n---\n\n## Additional Resources\n\n- **Official Docs:** https://learn.microsoft.com/dotnet/maui/\n- **Migration Guide:** https://learn.microsoft.com/dotnet/maui/migration/\n- **GitHub Issues:** https://github.com/dotnet/maui/issues\n- **CommunityToolkit.Mvvm:** https://learn.microsoft.com/dotnet/communitytoolkit/mvvm/\n\n---\n\n**Document Version:** 2.0  \n**Last Updated:** November 2025  \n**Applies To:** .NET MAUI 10.0.100 and later\n","description":"Instructions for upgrading .NET MAUI applications from version 9 to version 10, including breaking changes, deprecated APIs, and migration strategies for ListView to CollectionView.","import":{"commit_sha":"541b7819d8c3545c6df122491af4fa1eae415779","imported_at":"2026-05-18T20:05:35Z","license_text":"MIT License\n\nCopyright GitHub, Inc.\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.","owner":"github","repo":"github/awesome-copilot","source_url":"https://github.com/github/awesome-copilot/blob/541b7819d8c3545c6df122491af4fa1eae415779/instructions/dotnet-maui-9-to-dotnet-maui-10-upgrade.instructions.md"},"manifest":{}},"content_hash":[236,157,23,18,75,95,110,41,76,101,171,219,79,228,19,214,218,201,231,3,236,115,220,23,188,226,171,49,91,216,139,190],"trust_level":"unsigned","yanked":false}