Migrate To Avalonia12

Avalonia 12 Migration Skill

Goals

1. Detect all breaking changes — Scan code for Avalonia 11 API usage incompatible with Avalonia 12, covering 50+ categories of changes.

2. Provide comprehensive guidance — Explain what changed, why, and how to fix it with clear examples.

3. Support multi-platform migration — Handle desktop, Android, iOS, browser, and headless platform changes.

4. Prioritize by impact — Categorize issues by severity and auto-fixability.

5. Ensure AOT compatibility — Identify and fix reflection-based API access with proper [DynamicDependency] patterns.

6. Verify compilation — After applying code changes, always run dotnet build to ensure the migrated code compiles successfully. Migration is only complete when the build succeeds.

Core Principle

CRITICAL: Avalonia 12 migration is ONLY about API compatibility, NOT about changing functionality.

Avalonia 12 is a major version with significant breaking changes across binding system, focus handling, clipboard API, window decorations, TopLevel architecture, Popup positioning, extension methods, dispatcher model, obsolete member removals, renamed APIs, and platform support. This skill automates detection and fixing of the most common issues while providing guidance for complex migrations and AOT-safe reflection patterns.

The ONLY goal of migration is to make the code compile and run on Avalonia 12 with IDENTICAL behavior to the original. Any change in control behavior, logic, or functionality is a migration error, not an improvement.

Trigger Conditions

Use this skill when the user:

• Asks to migrate to Avalonia 12
• Mentions Avalonia 12 breaking changes or compatibility
• Wants to check if code works with Avalonia 12
• Provides code that needs Avalonia 12 migration
• Asks about specific Avalonia 12 changes
• Asks to "upgrade" (升级) any code, file, or module — e.g., "请将 xxx 升级", "upgrade xxx"
• Asks to refactor or rewrite code "for Avalonia 12" / "按照 Avalonia 12" — e.g., "按照 Avalonia 12 进行重构", "refactor xxx for Avalonia 12"
• Asks to "改造" (transform/rework) code — e.g., "请将 xxx 改造为 Avalonia 12 标准"
• Uses keywords like "升级", "upgrade", "迁移", "migrate", "重构", "refactor", "改造", "适配 Avalonia 12", "升级至 Avalonia 12 标准写法" in the context of Avalonia code changes
• Any request involving modifying AtomUI source code to conform to Avalonia 12 standards, regardless of language (Chinese or English)
• Asks to port/migrate ShowCase or Gallery files from release/5.0 to release/6.0 with Avalonia 12 adaptation — e.g., "把 release/5.0 的 XXXShowCase 移植到 release/6.0，按照 Avalonia 12 标准", "migrate XXXShowCase from release/5.0 to release/6.0 with Avalonia 12"
• Any cross-branch file migration request that mentions "Avalonia 12 标准" or "Avalonia 12 standard"

Fundamental Rules

0. NEVER change control behavior or logic (MOST IMPORTANT)

ABSOLUTE RULE: Migration to Avalonia 12 MUST NOT change any control behavior, logic, or functionality. The ONLY purpose of migration is to replace Avalonia 11 APIs with Avalonia 12 equivalents while preserving 100% identical behavior.

Examples of FORBIDDEN changes during migration:

• ❌ Adding new logic in event handlers (e.g., adding SetCurrentValue(IsSelectedProperty, true) in HandleSubMenuOpenChanged)
• ❌ Removing existing logic "because it seems redundant"
• ❌ Changing conditional logic (e.g., adding if (menuItem.IsTopLevel) checks that didn't exist before)
• ❌ Adding new methods (e.g., PointerMoved, KeyDown) that didn't exist in the original
• ❌ Changing when events fire or in what order
• ❌ Modifying state management logic
• ❌ "Simplifying" or "cleaning up" code that changes behavior

ONLY allowed changes:

• ✅ Replace removed Avalonia 11 APIs with Avalonia 12 equivalents (e.g., IRenderRoot → TopLevel, GotFocusEventArgs → FocusChangedEventArgs)
• ✅ Update namespace imports (e.g., remove using Avalonia.Rendering if no longer needed)
• ✅ Use ReflectionExtensions for internalized APIs
• ✅ Fix compilation errors caused by API changes

Verification before committing:

1. Compare line-by-line with release/5.0 source code
2. Every logic change must be justified by an Avalonia 12 API breaking change
3. If you added/removed logic that's not directly caused by an API change, you did it wrong
4. When in doubt, copy the exact logic from release/5.0 and ONLY change the API calls

Real-world example of migration error:

// ❌ WRONG - Added logic that didn't exist in release/5.0
if (value)
{
    foreach (var item in ItemsView.OfType<NavMenuItem>())
    {
        item.TryUpdateCanExecute();
    }
    SetCurrentValue(IsSelectedProperty, true);  // ← This is NEW logic, NOT an API change!
    RaiseEvent(new RoutedEventArgs(SubmenuOpenedEvent));
}

// ✅ CORRECT - Only API changes, logic unchanged
if (value)
{
    foreach (var item in ItemsView.OfType<NavMenuItem>())
    {
        item.TryUpdateCanExecute();
    }
    RaiseEvent(new RoutedEventArgs(SubmenuOpenedEvent));
}

1. Comprehensive scanning

Check all 50+ categories of breaking changes, not just the most common ones. Pay special attention to:

• Custom extension methods wrapping removed APIs
• Helper utilities using removed interfaces
• Internal utility classes that may need updating
• Reflection-based access to private/internal members

1.1. Scope closure and zero-residual validation

For any migration scoped to a file, folder, module, project, or branch port, you MUST treat the requested scope as a closed set and verify it end-to-end:

1. Determine the exact migration scope first (single file, control folder, project, or directory tree)
2. Run broad pre-change scans across the entire requested scope, not just the files you expect to touch
3. After edits, rerun the same scans across the entire scope
4. Do NOT consider the migration complete until the critical residual patterns for that scope are reduced to zero or explicitly explained as out-of-scope

Why: Avalonia 12 migration often leaves behind APIs that still compile but violate the migration goal. Build success alone is not a sufficient completion signal.

Minimum residual scan set for Avalonia 12 migrations:

• Dispatcher\\.UIThread
• PlacementMode\\s*=
• MotionAwareOpen|MotionAwareClose
• Gestures\\.
• KeyboardNavigationHandler
• BindingPlugins
• DataFormats\\.
• \\bWatermark\\b|UseFloatingWatermark
• \\bSystemDecorations\\b|ExtendClientAreaChromeHints

Add more patterns as needed based on the target module. The important rule is: scan the full requested scope, not only edited files.

2. Platform-aware migration

Consider target platforms (Desktop, Android, iOS, Browser, Headless) when suggesting fixes.

3. Provide context

Explain the rationale behind each breaking change from Avalonia's perspective.

4. Suggest alternatives

For removed APIs, always provide the recommended replacement.

5. Default to dry-run

Analyze and report without modifying files unless explicitly requested.

6. Check extension methods

Scan for custom extension methods that use removed or internalized APIs like:

• GetVisualRoot() using GetPresentationSource()
• GetRootElement() on IInputRoot (note: IInputRoot itself is still public and usable)
• Any method returning IRenderRoot or ILayoutRoot (these are truly internal)
• Any code referencing IPopupHost (now internal)
• Any code using Gestures class directly (now internal)
• Any code using BindingPlugins (now internal)
• Any code using KeyboardNavigationHandler (now internal)

7. Check renamed members

Scan for renamed APIs that will still compile but may cause confusion:

• Popup.PlacementMode → Popup.Placement (property renamed, enum still exists)
• TextBox.Watermark → TextBox.PlaceholderText
• TextBox.UseFloatingWatermark → TextBox.UseFloatingPlaceholder
• Window.SystemDecorations → Window.WindowDecorations
• RenderOptions.TextRenderingMode → TextOptions.TextRenderingMode
• TextBlock.LetterSpacing → TextElement.LetterSpacing
• Color.ToUint32() → Color.ToUInt32() (case change)
• Screen.PixelDensity → Screen.Scaling
• Screen.Primary → Screen.IsPrimary
• BindingPriority.TemplatedParent → BindingPriority.Template
• CubicBezierEasing → SplineEasing
• CustomAnimatorBase → InterpolatingAnimator<T>
• ContextMenu.PlacementMode → ContextMenu.Placement
• PseudolassesExtensions → PseudoClassesExtensions (typo fix)

8. Distinguish [PrivateApi] public interfaces from truly internal interfaces

[PrivateApi] is a documentation attribute — it does NOT change the accessibility of the type. A public interface annotated with [PrivateApi] is still fully compilable and usable. NEVER replace such interfaces with alternatives like TopLevel.

• [PrivateApi] public interfaces (USE DIRECTLY): IInputRoot — still public, compiles fine, use as-is
• Truly internal interfaces (NEED reflection or extraction): IRenderRoot, ILayoutRoot — cannot be referenced from external assemblies

When you encounter [PrivateApi] on a public type, check the actual C# access modifier. If it's public, use it directly. Only use reflection/extraction for types that are genuinely internal or private.

9. Prefer existing ReflectionExtensions over new reflection code

AtomUI already has a comprehensive set of ReflectionExtensions that wrap internal/private Avalonia members. Before writing new reflection code during migration, check the AtomUI ReflectionExtensions Catalog section below. If an extension already exists for the member you need, use it directly. Only create new ReflectionExtensions when no existing one covers the target member.

10. AOT-safe reflection patterns

When accessing private/internal Avalonia APIs:

• Use [DynamicDependency] attributes to mark members for AOT preservation
• Use Lazy<T> to cache reflection info
• Use GetXxxInfoOrThrow() for safe reflection
• Follow ReflectionExtensions naming convention
• Document in reflection-extensions-pattern.md

11. Always scan base classes in AtomUI.Controls

AtomUI uses a layered architecture for multi-platform support:

• AtomUI.Controls — Platform-agnostic base controls (shared across all platforms)
• AtomUI.Desktop.Controls — Desktop-specific control implementations
• AtomUI.Mobile.Controls (planned) — Mobile-specific control implementations

Desktop and Mobile controls typically inherit from abstract base classes in AtomUI.Controls. For example:

• AtomUI.Desktop.Controls.ScrollBar → AtomUI.Controls.Commons.AbstractScrollBar
• AtomUI.Desktop.Controls.ScrollViewer → AtomUI.Controls.Commons.AbstractScrollViewer

When migrating a control in AtomUI.Desktop.Controls (or AtomUI.Mobile.Controls):

1. Identify the base class by reading the class declaration
2. If the base class is in AtomUI.Controls, scan it for breaking changes too
3. Apply fixes to both the base class and the derived class
4. Report issues from both layers in the migration report

Why: Breaking changes in the base class affect all platform-specific implementations. Missing base class issues leads to runtime bugs (e.g., RawInputEventArgs.Root comparison failures) that are hard to trace back to the migration.

12. Verify API from local reference source, not assembly metadata

When you need to check whether an API exists, what properties/methods a type exposes, or how a type is defined, look up the source code under .referenceprojects/ first. These are local checkouts of the exact versions used by the project. Do NOT attempt to decompile NuGet assemblies, parse strings output, or guess API shapes. Source is authoritative and always available.

Available reference repositories:

• .referenceprojects/Avalonia/src — Avalonia 12 core (Avalonia.Base / Avalonia.Controls / Avalonia.Themes.Fluent / Avalonia.Skia / platform backends). Use for all Avalonia 11→12 breaking-change verification, accessibility checks (public / [PrivateApi] / internal), template slot names, default property values.
• .referenceprojects/Avalonia.Controls.DataGrid — Avalonia official DataGrid. Use when AtomUI's DataGrid derives from or aligns with upstream behavior.
• .referenceprojects/Svg.Skia/src/Svg.Controls.Avalonia — Svg.Controls.Avalonia package source (the Avalonia.Svg.Svg control, AvaloniaPicture, SvgSource, etc.). Use when touching atom:ImagePreviewer, atom:Empty, atom:Result or anywhere SVG is rendered.
• .referenceprojects/avalonia-docs — Avalonia official docs (api/, api_versioned_docs/). Use for conceptual/migration prose, API usage examples, and cross-version comparisons before confirming details in the code tree above.

Examples:

• Check if TextOptions has a TextRenderingModeProperty: rg in .referenceprojects/Avalonia/src/Avalonia.Base and Avalonia.Controls
• Check if IInputManager is still public: read the interface definition in .referenceprojects/Avalonia/src
• Check what Avalonia.Svg.Svg exposes in 12.0.0.5: .referenceprojects/Svg.Skia/src/Svg.Controls.Avalonia/Svg.cs (e.g. Model is SKPicture?, there is no GetSKPicture())
• Check DataGrid column internals: .referenceprojects/Avalonia.Controls.DataGrid

Rule: Before making any claim like "API X was removed" / "method Y is internal" / "property Z exists", grep one of these four trees. If you haven't looked at the source, don't speculate — reflect reading NuGet metadata is lossy and has already caused incorrect conclusions (e.g. claiming Avalonia.Svg.Svg didn't exist when it very much does).

13. Token definitions and language packs are copy-only

When migrating a control module, the following files do NOT need breaking-change scanning or dependency analysis — copy them directly from release/5.0 to the target branch:

• *Token.cs — Control design token definitions (e.g., AlertToken.cs, AdornerLayerToken.cs). Only apply the ScopeProvider field addition to match main's pattern.
• *LangResource*.cs / *Lang*.resx — Control language pack / localization resource files.

These files contain only data declarations (token values, string resources) with no Avalonia API usage that could be affected by breaking changes. Scanning them wastes time.

14. Preserve behavior and functionality during migration

CRITICAL PRINCIPLE: Migration to Avalonia 12 or code optimization MUST NOT change the control's behavior, functionality, or user-facing features. This applies to both controls and their ShowCases.

For Control Migration:

What MUST be preserved:

1. All public APIs — Properties, methods, events, attached properties must remain unchanged
2. Control behavior — User interactions, state transitions, visual feedback must work identically
3. Default values — All property defaults must match the original
4. Event firing order — Event sequences must remain the same
5. Visual appearance — Layout, styling, animations must look identical (unless explicitly fixing a bug)
6. Data binding support — All bindable properties must remain bindable
7. Template structure — Control template parts and their roles must be preserved

What you CAN change for Avalonia 12:

• Replace removed Avalonia 11 APIs with Avalonia 12 equivalents (e.g., IDataObject → IAsyncDataTransfer)
• Use ReflectionExtensions for internalized Avalonia APIs (e.g., IRenderRoot, ILayoutRoot)
• Update namespace imports for Avalonia 12 compatibility
• Optimize internal implementation (e.g., reduce allocations, improve performance) WITHOUT changing behavior
• Fix actual bugs (but document them clearly in commit message)

What you CANNOT change:

• Remove features or properties "because they seem unused"
• Simplify logic "to make it cleaner" if it changes behavior
• Change default values "to match other controls"
• Skip initialization steps "because they seem redundant"
• Remove event handlers "because they look empty" (they may be overridden in derived classes)

For ShowCase Migration:

What MUST be preserved:

1. Layout structure — Keep all original containers (StackPanel, WrapPanel, Grid, Border, etc.) with their exact properties (HorizontalAlignment, Orientation, Spacing, Margin, ColumnDefinitions, RowDefinitions, etc.)
2. All showcase items — If the original has 3 CheckBoxGroup examples, keep all 3. If it shows UnChecked/Indeterminate/Checked states, keep all 3.
3. Element content — If the original says "Checkbox", don't change it to "CheckBox". If it uses "A, B, C, D, D", don't change it to "Apple, Pear, Orange".
4. Styles — If the original has ShowCasePanel.Styles, keep it exactly as-is.
5. ViewModel initialization — Copy ALL property initializations from the constructor (initial values, default states, etc.). Missing initialization causes incorrect initial UI state.
6. Command logic — Preserve all command handler logic, helper methods, and state update sequences. Do NOT simplify or "optimize" logic that changes behavior.
7. Property types — Keep exact property types (e.g., IList<T>? vs IList?, bool vs bool?). Type changes can break binding or change null-handling behavior.
8. CommandParameter bindings — If the original uses CommandParameter="{Binding ElementName=...}", keep it. Don't assume ReactiveUI bindings can replace all patterns.

CRITICAL: Do NOT redefine existing types

Before defining any class, interface, or enum in a ShowCase ViewModel:

1. Check src/AtomUI.Controls first — Most control-related types (e.g., CheckBoxOption, RadioOption, SelectOption) are already defined in the control's namespace
2. Check src/AtomUI.Desktop.Controls — Platform-specific types may be defined here
3. Use the official type — Import the correct namespace and use the existing type directly
4. NEVER create a duplicate class — Defining your own CheckBoxOption when AtomUI.Controls.CheckBoxOption exists causes type mismatches, binding failures, and runtime errors

Example of what NOT to do:

// WRONG - Redefining CheckBoxOption in ViewModel file
public class CheckBoxOption
{
    public string? Content { get; set; }
    public bool IsEnabled { get; set; } = true;
}

Correct approach:

// RIGHT - Use the official type from AtomUI.Controls
using AtomUI.Controls;

// CheckBoxOption is already defined in AtomUI.Controls namespace
// Just use it directly with IList<CheckBoxOption>

Verification before committing:

• Search the codebase: find src -name "*.cs" -exec grep -l "class YourType" {} \;
• If the type exists in src/, use it. Do NOT redefine it.
• If you defined a type in the ViewModel file, you probably did it wrong.

What you CAN change for Avalonia 12:

• Add xmlns:vm="using:..." and x:DataType="vm:XxxViewModel" for compiled bindings
• Change ViewModel base class from ShowCaseViewModelBase to ReactiveObject, IRoutableViewModel (release/6.0 pattern)
• Remove IActivatableViewModel and ViewModelActivator (release/6.0 doesn't use them)
• IMPORTANT: Keep public static EntityKey ID unchanged (release/6.0 pattern) — do NOT change to public const string ID
• Change public string UrlPathSegment { get; } = ID; to public string? UrlPathSegment => ID.ToString(); (release/6.0 pattern)
• Change ReactiveCommand<Button, Unit> to ReactiveCommand<Unit, Unit> and remove sender parameters (Avalonia 12 optimization)
• Add using ReactiveUI.Avalonia and using System.Reactive.Disposables.Fluent if needed
• Adjust namespace imports for Avalonia 12 compatibility

CRITICAL: Code-behind initialization must match release/5.0

ShowCase views in release/5.0 use ReactiveUserControl<TViewModel> with WhenActivated for initialization. When migrating:

1. Check the code-behind file — Read release/5.0:controlgallery/.../Views/.../XxxShowCase.axaml.cs to see if it has WhenActivated logic
2. Copy ALL initialization code — If the original has ViewModel property initialization, ReactiveUI bindings, or event subscriptions in WhenActivated, copy them exactly
3. Do NOT simplify to basic IViewFor — Don't replace ReactiveUserControl<T> + WhenActivated with just UserControl, IViewFor<T> if the original has initialization logic
4. Missing initialization causes bugs — For example, SliderShowCase needs WhenActivated to create and bind Marks to all 7 Slider controls. Without it, Marks won't display.

Example of WRONG migration (missing initialization):

// WRONG - Simplified to basic IViewFor, lost all initialization logic
public partial class SliderShowCase : UserControl, IViewFor<SliderViewModel>
{
    public SliderShowCase() { InitializeComponent(); }
    object? IViewFor.ViewModel { get => ViewModel; set => ViewModel = value as SliderViewModel; }
    public SliderViewModel? ViewModel { get; set; }
}

Correct migration (preserves initialization):

// RIGHT - Keeps ReactiveUserControl + WhenActivated with all initialization
public partial class SliderShowCase : ReactiveUserControl<SliderViewModel>
{
    public SliderShowCase()
    {
        this.WhenActivated(disposables =>
        {
            if (DataContext is SliderViewModel viewModel)
            {
                // Copy ALL initialization from release/5.0
                var marks = new List<SliderMark>();
                marks.Add(new SliderMark("0°C", 0));
                // ... rest of initialization
                viewModel.SliderMarks = marks;
                
                // Copy ALL bindings from release/5.0
                this.OneWayBind(ViewModel, vm => vm.SliderMarks, v => v.Slider1.Marks)
                    .DisposeWith(disposables);
                // ... rest of bindings
            }
        });
        InitializeComponent();
    }
}

Verification checklist before committing:

1. Read release/5.0 code-behind FIRST — Check if it has WhenActivated logic before writing the migration
2. Compare line-by-line with the original AXAML — every container, every property, every showcase item
3. Compare ViewModel constructor initialization — every property must have its initial value
4. Compare code-behind initialization — every WhenActivated block, every binding, every subscription
5. Compare all command handler logic — every helper method, every state update sequence
6. Compare property types — IList<T>? vs IList?, bool vs bool?, etc.
7. Build and verify no compilation errors
8. Test the ShowCase — verify all interactions work identically to release/5.0
9. If you removed, simplified, or changed any logic/layout/types/initialization, you did it wrong — revert and copy exactly, then apply ONLY Avalonia 12 compatibility changes

Execution Steps

Step 1: Determine scope and platform

• Single file or entire project?
• Target platform(s): Desktop, Android, iOS, Browser, Headless?
• Current .NET version?
• Existing Avalonia version?
• AOT compilation planned?

Step 2: Scan for all breaking changes

Check all 50+ categories:

Core Framework (13 categories)

1. .NET version requirements (8+ required, 10 recommended)
2. Avalonia package versions (all must be v12)
3. Binding class hierarchy (IBinding → BindingBase, InstancedBinding removed)
4. Compiled bindings (now enabled by default)
5. Binding plugins (now internal, data validation disabled by default)
6. Text shaper configuration (must call UseHarfBuzz)
7. Touch/pen selection behavior (triggers on release, not press)
8. TopLevel API changes (VisualRoot now protected internal, IInputRoot still public with [PrivateApi], IRenderRoot/ILayoutRoot truly internal)
9. Window decoration redesign (TitleBar/CaptionButtons/ChromeOverlayLayer removed → WindowDrawnDecorations)
10. Focus event improvements (unified FocusChangedEventArgs, KeyboardNavigationHandler now internal)
11. Extension methods & helper utilities (GetVisualRoot, GetRootElement, etc.)
12. Multiple dispatchers support (one per thread, use AvaloniaObject.Dispatcher)
13. Animations stopped on invisible controls (set PlaybackBehavior to Always to restore)

Data & Clipboard (4 categories) 14. Clipboard API (IDataObject → IAsyncDataTransfer) 15. Drag-drop API (DoDragDrop → DoDragDropAsync) 16. DataFormats (DataFormats.* → DataFormat.*) 17. Windows BinaryFormatter removed (explicit serialization needed for clipboard)

Text & Rendering (5 categories) 18. Text formatting constructors (parameter order changed) 19. Access keys (now triggered by symbol, not virtual key; AccessKey is string?) 20. Font support (Type 1 fonts no longer supported) 21. Direct2D1 removed (use Skia instead) 22. Render target and platform surface interfaces reworked (CRITICAL for custom backends)

Platform-Specific (9 categories) 23. Android app initialization (AvaloniaMainActivity non-generic + AvaloniaAndroidApplication<TApp>) 24. Android lifetime (IActivityApplicationLifetime replaces ISingleViewApplicationLifetime) 25. Android CreateAppBuilder/CustomizeAppBuilder removed 26. iOS scene-based lifecycle (AvaloniaAppDelegate.Window stays null) 27. Browser Blazor package (removed, use Avalonia.Browser) 28. Tizen support (removed) 29. Diagnostics package (Avalonia.Diagnostics → AvaloniaUI.DiagnosticsSupport) 30. xUnit.net v3 (updated from v2) 31. NUnit v4 (updated from v3)

API Changes (12 categories) 32. Screen class (now abstract) 33. ResourcesChangedEventArgs (now readonly record struct) 34. Gesture events (Gestures class now internal, events moved to InputElement) 35. Window.WindowState (now direct property, not styled) 36. Data validation (enabled by default in custom controls) 37. IPopupHost now internal (was public) 38. IRenderer now [PrivateApi] (was public) 39. VisualLayerManager changes (AdornerLayer/OverlayLayer access changed) 40. FuncMultiValueConverter (new IReadOnlyList<TIn> constructor, IEnumerable kept for compat) 41. Popup changes (new properties: OverlayDismissEventPassThrough, ShouldUseOverlayLayer, etc.) 42. Popup.PlacementMode renamed to Popup.Placement (enum PlacementMode still exists)

Renamed & Removed Members (5 categories) 43. Renamed members (TextBox.Watermark→PlaceholderText, RenderOptions→TextOptions, etc.) 44. Comprehensive obsolete member removals (40+ items from Avalonia 11 now removed) 45. Extension methods & helper utilities using internalized APIs 46. ReflectionExtensions pattern for AOT (DynamicDependency, Lazy<T> caching) 47. Internal API extraction strategy (extract vs reflect for internal APIs)

AtomUI-Specific (6 categories) 48. PlacementMode usage in PopupUtils (property renamed, refactor needed) 49. IInputRoot is [PrivateApi] but still public — use directly, only use reflection for truly internal members 50. ReflectionExtensions for internal members (wrap internal/private access) 51. Windows ExtendClientAreaToDecorationsHint behavior improved 52. Popup.MotionAwareOpen/MotionAwareClose removed in AtomUI 6.0 — use Popup.IsOpen directly 53. SelectingItemsControl.UpdateSelection obsolete — prefer UpdateSelectionFromEvent, fall back to Selection.Select/Deselect for non-input events 54. SelectingItemsControl selection trigger timing changed — override ShouldTriggerSelection for custom pointer event handling

Step 3: Categorize by severity and platform

• CRITICAL — Compilation errors, must fix
• HIGH — Breaking changes, should fix
• MEDIUM — Compatibility issues, consider fixing
• LOW — Improvements, optional

Step 4: Generate comprehensive report

Include:

• Total issues by category
• Issues by severity
• Platform-specific issues
• Files affected
• Suggested fixes with code examples
• Auto-fixable vs manual fixes

Step 5: Apply fixes (if requested)

Only auto-fix safe transformations. Flag complex changes for manual review.

Step 5.5: Residual pattern scan (MANDATORY after code changes)

After applying code changes during migration, you MUST rerun full-scope scans for the critical Avalonia 12 patterns relevant to the target:

1. Use the full requested scope — scan the whole target directory/project, not just touched files
2. Rerun the key patterns — at minimum include the residual scan set defined in Rule 1.1, plus any task-specific patterns discovered during the migration
3. Require zero unexplained matches — if a pattern still matches, either fix it or explicitly explain why it is intentionally left unchanged
4. Do NOT stop at the first clean subset — the verification target is the full requested scope

Example residual scan commands:

rg "Dispatcher\\.UIThread|MotionAwareOpen|MotionAwareClose|KeyboardNavigationHandler" src/AtomUI.Desktop.Controls
rg "PlacementMode\\s*=|Gestures\\.|BindingPlugins|DataFormats\\." src/AtomUI.Desktop.Controls

Residual scan is NOT optional — it catches:

• APIs that still compile but violate Avalonia 12 migration standards
• untouched files in the requested scope that were skipped by file-by-file editing
• partial migrations where only the currently inspected files were updated
• regressions caused by new code copying old Avalonia 11 patterns

Step 6: Build verification (MANDATORY after code changes)

After applying any code changes during migration, you MUST verify the changes compile successfully:

1. Identify the project file — Find the .csproj file for the module being migrated
2. Run dotnet build — Execute dotnet build <project-file> to verify compilation
3. Check for errors — If build fails:
   • Read the error messages carefully
   • Identify which migration changes caused the errors
   • Fix the errors (common issues: missing using directives, incorrect API usage, typos)
   • Rebuild until successful
4. Report build status — Always report whether the build succeeded or failed in your final summary

Build verification is NOT optional — it catches:

• Typos in renamed APIs
• Missing namespace imports
• Incorrect method signatures
• Breaking changes not covered by the migration rules
• Syntax errors introduced during editing

Example build command:

dotnet build src/AtomUI.Desktop.Controls/AtomUI.Desktop.Controls.csproj

If build fails multiple times:

• Review the local reference source under .referenceprojects/ (see Rule 12 for the full list: Avalonia/src, Avalonia.Controls.DataGrid, Svg.Skia/src/Svg.Controls.Avalonia, avalonia-docs)
• Check if the API you're using actually exists in Avalonia 12
• Verify the correct namespace and assembly
• Consider whether reflection/extraction is needed for internal APIs

Step 7: Gallery ShowCase registration (MANDATORY for ShowCase migration)

When migrating a ShowCase from release/5.0 to release/6.0, you MUST complete ALL 7 registration steps. Missing ANY step causes the ShowCase to not display or not appear in the menu.

COMPLETE REGISTRATION CHECKLIST (ALL 7 STEPS REQUIRED):

Step 7.1: Create ViewModel

Location: controlgallery/AtomUIGallery/ShowCases/ViewModels/{Category}/

using AtomUI.Controls;
using ReactiveUI;

namespace AtomUIGallery.ShowCases.ViewModels;

public class YourViewModel : ReactiveObject, IRoutableViewModel
{
    public static EntityKey ID = "YourControl";

    public IScreen HostScreen { get; }

    public string? UrlPathSegment => ID.ToString();

    public YourViewModel(IScreen screen)
    {
        HostScreen = screen;
    }
}

IMPORTANT: ViewModel ID pattern in release/6.0:

• Use public static EntityKey ID = "YourControl"; (NOT public const string ID)
• Use public string? UrlPathSegment => ID.ToString(); (expression-bodied property, NOT { get; } = ID;)
• This pattern is standard in release/6.0 and must be preserved during migration

Step 7.2: Create View (AXAML + Code-behind)

Location: controlgallery/AtomUIGallery/ShowCases/Views/{Category}/

AXAML:

<UserControl xmlns="https://github.com/avaloniaui"
             xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
             x:Class="AtomUIGallery.ShowCases.Views.YourShowCase"
             xmlns:atom="https://atomui.net"
             xmlns:gallery="https://atomui.net/oss-controls/gallery">
    <gallery:ShowCasePanel>
        <!-- ShowCase items here -->
    </gallery:ShowCasePanel>
</UserControl>

Code-behind:

using AtomUIGallery.ShowCases.ViewModels;
using ReactiveUI;
using ReactiveUI.Avalonia;

namespace AtomUIGallery.ShowCases.Views;

public partial class YourShowCase : ReactiveUserControl<YourViewModel>
{
    public YourShowCase()
    {
        this.WhenActivated(disposables => { });
        InitializeComponent();
    }
}

Step 7.3: Register ViewModel in Navigation System

File: controlgallery/AtomUIGallery/Workspace/ViewModels/CaseNavigationViewModel.cs

private void RegisterShowCaseViewModels()
{
    // ... existing registrations ...
    _showCaseViewModelFactories.Add(YourViewModel.ID, () => new YourViewModel(HostScreen));
}

Step 7.4: Register View Mapping

File: controlgallery/AtomUIGallery/ShowCases/ShowCaseRegister.cs

public void RegisterViews(DefaultViewLocator locator)
{
    // ... existing mappings ...
    locator.Map<YourViewModel, YourShowCase>(() => new YourShowCase());
}

Step 7.5: Add Menu Item (CRITICAL - MOST COMMONLY FORGOTTEN)

File: controlgallery/AtomUIGallery/Workspace/Views/CaseNavigation.axaml

Add under the appropriate category node:

<atom:NavMenuNode Header="{gallery:CaseNavigationLangResource Category_YourControl}"
                  ItemKey="{x:Static viewmodels:YourViewModel.ID}" />

Categories:

• General（通用）
• Layout（布局）
• Navigation（导航）
• DataEntry（数据录入）
• DataDisplay（数据展示）
• Feedback（反馈）

Step 7.6: Add Chinese Language Resource (CRITICAL - MOST COMMONLY FORGOTTEN)

File: controlgallery/AtomUIGallery/Workspace/Localization/CaseNavigationLang/zh_CN.cs

public const string Category_YourControl = "YourControl 中文名称";

Example:

public const string Feedback_Watermark = "Watermark 水印";
public const string DataEntry_CheckBox = "CheckBox 多选框";

Step 7.7: Add English Language Resource (CRITICAL - MOST COMMONLY FORGOTTEN)

File: controlgallery/AtomUIGallery/Workspace/Localization/CaseNavigationLang/en_US.cs

public const string Category_YourControl = "YourControl";

Example:

public const string Feedback_Watermark = "Watermark";
public const string DataEntry_CheckBox = "CheckBox";

VERIFICATION CHECKLIST (Check ALL before considering migration complete):

• Step 7.1: ViewModel created in ViewModels/{Category}/
• Step 7.2: View (AXAML + Code-behind) created in Views/{Category}/
• Step 7.3: ViewModel registered in CaseNavigationViewModel.cs
• Step 7.4: View mapped in ShowCaseRegister.cs
• Step 7.5: Menu item added to CaseNavigation.axaml (MOST COMMONLY FORGOTTEN)
• Step 7.6: Chinese language resource added to zh_CN.cs (MOST COMMONLY FORGOTTEN)
• Step 7.7: English language resource added to en_US.cs (MOST COMMONLY FORGOTTEN)
• Build succeeds: dotnet build controlgallery/AtomUIGallery.Desktop
• Menu item appears in Gallery app
• Clicking menu item displays the ShowCase correctly

COMMON MISTAKES AND SYMPTOMS:

CRITICAL: Steps 7.5, 7.6, and 7.7 are the MOST COMMONLY FORGOTTEN. Always double-check these three steps before considering the migration complete.

Verification: After completing ALL 7 steps, build the Gallery app and verify:

1. Menu item appears in the correct category
2. Menu item shows correct text in both Chinese and English
3. Clicking the menu item displays the ShowCase correctly

Migration Rules (36+ Categories)

Core Framework Changes

1. .NET Version Requirements (CRITICAL)

What changed: Avalonia 12 requires .NET 8+. Android/iOS require .NET 10.

Detection:

<TargetFramework>netstandard2.0</TargetFramework>
<TargetFramework>net7.0</TargetFramework>

Fix:

<TargetFramework>net10.0</TargetFramework>

2. Avalonia Package Versions (CRITICAL)

What changed: All Avalonia packages must be v12.

Detection:

<PackageReference Include="Avalonia" Version="11.3.12" />

Fix:

<PackageReference Include="Avalonia" Version="12.0.0" />

3. Binding Class Hierarchy (HIGH)

What changed: IBinding removed, use BindingBase. InstancedBinding removed, use BindingExpressionBase.

Detection:

IBinding binding = new Binding("Property");
var instanced = new InstancedBinding(...);

Fix:

BindingBase binding = new ReflectionBinding(nameof(Item.Property));
var instanced = new CompiledBinding(...);

4. Compiled Bindings Default (MEDIUM)

What changed: AvaloniaUseCompiledBindingsByDefault is now true by default.

Impact: All {Binding} in XAML now use compiled bindings.

Action: Verify compiled bindings work with your data context.

5. Binding Plugins Now Internal (MEDIUM)

What changed: BindingPlugins class is now internal. Data validation plugin disabled by default. Related types removed: DataValidationBase, ExceptionValidationPlugin, IDataValidationPlugin, IndeiValidationPlugin, IPropertyAccessorPlugin, IStreamPlugin, PropertyAccessorBase, PropertyError.

Detection:

BindingPlugins.DataValidators.Add(new ExceptionValidationPlugin());

Fix: Remove plugin registration. Enable validation with .WithDataAnnotationsValidation() in AppBuilder if needed.

6. Text Shaper Configuration (HIGH)

What changed: Text shaper must be configured independently.

Detection:

AppBuilder.Configure<App>()
    .UseSkia()
    // Missing UseHarfBuzz()

Fix:

AppBuilder.Configure<App>()
    .UseSkia()
    .UseHarfBuzz()

Also add package:

<PackageReference Include="Avalonia.HarfBuzz" Version="12.0.0" />

7. Touch/Pen Selection (MEDIUM)

What changed: Touch/pen selection triggers on release, not press. Container types handle selection directly.

Detection:

protected override void UpdateSelection(ItemsControl itemsControl, int index, bool selected)
{
    // Old selection logic
}

Fix:

protected override void UpdateSelectionFromEvent(ItemsControl itemsControl, RoutedEventArgs e)
{
    // New selection logic
}

8. TopLevel API Changes (HIGH)

What changed: Visual.VisualRoot changed from public to protected internal (not removed, but inaccessible from outside). Use TopLevel.GetTopLevel(visual). IRenderRoot and ILayoutRoot are now truly internal. IInputRoot is marked [PrivateApi] but remains a public interface — it can and should be used directly. New IPresentationSource interface introduced (internal). KeyboardNavigationHandler is now internal — use FocusManager.GetNextElement instead.

IMPORTANT: [PrivateApi] is a documentation attribute only. It does NOT change the C# access modifier. IInputRoot is still public and fully usable. Do NOT replace IInputRoot with TopLevel — this will break code because RawInputEventArgs.Root returns PresentationSource (which implements IInputRoot), NOT TopLevel.

Detection patterns:

// Pattern 1: Direct VisualRoot access (now protected internal)
var root = visual.VisualRoot as IRenderRoot;
if (root != null) { }

// Pattern 2: IRenderRoot / ILayoutRoot usage (now truly internal)
IRenderRoot renderRoot = ...;
ILayoutRoot layoutRoot = ...;

// Pattern 3: KeyboardNavigationHandler usage (now internal)
KeyboardNavigationHandler.GetNext(element, direction)

Fix:

// Pattern 1: Use TopLevel.GetTopLevel()
var topLevel = TopLevel.GetTopLevel(visual);
if (topLevel is WindowBase window) { }

// Pattern 2: Use reflection or extraction for IRenderRoot/ILayoutRoot
// See Category 35 for internal API extraction strategy

// Pattern 3: Use FocusManager instead
focusManager.TryMoveFocus(NavigationDirection.Next)

NO fix needed for IInputRoot usage:

// These are ALL CORRECT in Avalonia 12 — do NOT change them:
public void Update(IInputRoot root, Visual? candidateToolTipHost)  // OK
if (root == currentToolTip?.GetVisualRoot() as IInputRoot)          // OK
if (e.Root == currentTip.GetVisualRoot() as IInputRoot)             // OK
e.Root.GetRootElement() == _tipControl?.GetVisualRoot()             // OK

Why: The visual tree architecture was refactored. TopLevel is now the primary way to access the root visual. IPresentationSource is the new internal abstraction that implements IInputRoot. Visual.VisualRoot still exists but is protected internal. IInputRoot is marked [PrivateApi] but remains public — it compiles and works correctly. IRenderRoot and ILayoutRoot are truly internal and need reflection/extraction.

9. Window Decoration Redesign (HIGH)

What changed: Complete redesign of window decoration system. Many types removed, replaced by WindowDrawnDecorations template-based system.

Removed types:

• Chrome.TitleBar class
• Chrome.CaptionButtons class
• ChromeOverlayLayer class
• LightDismissOverlayLayer class
• SystemDecorations enum
• ExtendClientAreaChromeHints enum
• IPopupHostProvider interface
• IPopupHost interface (now internal)

Removed properties:

• VisualLayerManager.AdornerLayer → use AdornerLayer.GetAdornerLayer()
• VisualLayerManager.ChromeOverlayLayer → use WindowDrawnDecorations
• VisualLayerManager.LightDismissOverlayLayer → removed
• VisualLayerManager.OverlayLayer → use OverlayLayer.GetOverlayLayer()
• Window.ExtendClientAreaChromeHints → use Window.WindowDecorations + ExtendClientAreaToDecorationsHint

New types:

• WindowDrawnDecorations — template-based decoration manager
• WindowDrawnDecorationsContent — holds Overlay, Underlay, FullscreenPopover slots
• IWindowDrawnDecorationsTemplate — template interface
• DrawnWindowDecorationParts enum — flags for Shadow, Border, TitleBar, ResizeGrips
• WindowDecorationsElementRole enum — roles: None, TitleBar, CloseButton, MinimizeButton, MaximizeButton, ResizeN/S/E/W/NE/NW/SE/SW, etc.
• WindowDecorationProperties.ElementRoleProperty — attached property for marking element roles

Detection:

<Chrome:TitleBar />
<Chrome:CaptionButtons />

var layer = VisualLayerManager.ChromeOverlayLayer;
Window.ExtendClientAreaChromeHints = ExtendClientAreaChromeHints.PreferSystemChrome;

Fix:

<Chrome:WindowDrawnDecorations />

var adorner = AdornerLayer.GetAdornerLayer(visual);
var overlay = OverlayLayer.GetOverlayLayer(visual);
// Use Window.WindowDecorations instead of ExtendClientAreaChromeHints

Why: The old decoration system was inflexible. The new template-based system allows full customization of window chrome with explicit role-based hit testing.

10. Focus Event Changes (HIGH)

What changed: Both GotFocus and LostFocus now use FocusChangedEventArgs (with NewFocusedElement, OldFocusedElement, NavigationMethod, KeyModifiers). GotFocusEventArgs class removed. KeyboardNavigationHandler is now internal — use IFocusManager.TryMoveFocus(direction, options) instead.

Detection:

protected override void OnGotFocus(GotFocusEventArgs e)
protected override void OnLostFocus(RoutedEventArgs e)
KeyboardNavigationHandler.GetNext(element, direction)

Fix:

protected override void OnGotFocus(FocusChangedEventArgs e)
protected override void OnLostFocus(FocusChangedEventArgs e)
focusManager.TryMoveFocus(NavigationDirection.Next)

Data & Clipboard Changes

11. Clipboard API (HIGH)

What changed: IDataObject removed. Use IAsyncDataTransfer. Methods moved to extensions.

Detection:

var data = new DataObject();
data.Set(DataFormats.Text, "text");
await clipboard.SetDataObjectAsync(data);
var text = await clipboard.GetTextAsync();

Fix:

var item = new DataTransferItem();
item.Set(DataFormat.Text, "text");
var data = new DataTransfer();
data.Add(item);
await clipboard.SetDataAsync(data);
var text = await clipboard.TryGetTextAsync();

Add using:

using Avalonia.Input.Platform;

12. Drag-Drop API (HIGH)

What changed: DoDragDrop → DoDragDropAsync. DragEventArgs.Data → DragEventArgs.DataTransfer.

Detection:

DragDrop.DoDragDrop(dragEventArgs, dataObject);
var data = dragEventArgs.Data;

Fix:

await DragDrop.DoDragDropAsync(dragEventArgs, dataTransfer);
var data = dragEventArgs.DataTransfer;

13. DataFormats Changes (MEDIUM)

What changed: DataFormats.* → DataFormat.*

Detection:

data.Set(DataFormats.Text, "text");
data.Set(DataFormats.Files, files);

Fix:

data.Set(DataFormat.Text, "text");
data.Set(DataFormat.Files, files);

Text & Rendering Changes

14. Text Formatting Constructors (HIGH)

What changed: GenericTextRunProperties, TextCollapsingProperties, TextShaperOptions merged constructors. FontFeatureCollection now last parameter.

Detection:

new GenericTextRunProperties(typeface, features, size, decorations, brush)

Fix:

new GenericTextRunProperties(typeface, size, decorations, brush, fontFeatures: features)

15. Access Keys (MEDIUM)

What changed: Access keys triggered by symbol, not virtual key. AccessText.AccessKey is now string? not char.

Detection:

public char AccessKey { get; set; }

Fix:

public string? AccessKey { get; set; }

16. Font Support (LOW)

What changed: Type 1 fonts (.pfb/.pfm) no longer supported.

Action: Use TrueType (.ttf) or OpenType (.otf) fonts instead.

17. Direct2D1 Removed (HIGH - Windows)

What changed: Direct2D1 backend removed. Use Skia.

Detection:

<PackageReference Include="Avalonia.Direct2D1" Version="11.3.12" />

Fix:

<PackageReference Include="Avalonia.Skia" Version="12.0.0" />

Code:

AppBuilder.Configure<App>()
    .UseSkia()

Platform-Specific Changes

18. Android App Initialization (CRITICAL - Android)

What changed: AvaloniaMainActivity<TApp> → AvaloniaMainActivity + AvaloniaAndroidApplication<TApp>.

Detection:

[Activity]
public class MainActivity : AvaloniaMainActivity<App>
{
}

Fix:

[Activity]
public class MainActivity : AvaloniaMainActivity
{
}

[Application]
public class AndroidApp : AvaloniaAndroidApplication<App>
{
    protected AndroidApp(IntPtr javaReference, JniHandleOwnership transfer)
        : base(javaReference, transfer)
    {
    }
}

19. Android Lifetime (HIGH - Android)

What changed: ISingleViewApplicationLifetime → IActivityApplicationLifetime with MainViewFactory.

Detection:

if (ApplicationLifetime is ISingleViewApplicationLifetime singleView)
    singleView.MainView = new MainView();

Fix:

if (ApplicationLifetime is IActivityApplicationLifetime activityLifetime)
    activityLifetime.MainViewFactory = () => new MainView();
else if (ApplicationLifetime is ISingleViewApplicationLifetime singleView)
    singleView.MainView = new MainView();

20. iOS Scene-Based Lifecycle (MEDIUM - iOS)

What changed: iOS now uses scene-based lifecycle. AvaloniaAppDelegate.Window stays null.

Action: Override AvaloniaView.MovedToWindow to detect window attachment.

21. Browser Blazor Removed (HIGH - Browser)

What changed: Avalonia.Browser.Blazor package removed. Use Avalonia.Browser.

Detection:

<PackageReference Include="Avalonia.Browser.Blazor" Version="11.3.12" />

Fix:

<PackageReference Include="Avalonia.Browser" Version="12.0.0" />

22. Tizen Removed (CRITICAL - Tizen)

What changed: Tizen platform no longer supported.

Action: Migrate to supported platform or maintain custom fork.

23. Diagnostics Package (MEDIUM)

What changed: Avalonia.Diagnostics package → AvaloniaUI.DiagnosticsSupport. The extension method AttachDevTools() may be renamed to AttachDeveloperTools() in the new package (verify with the package version you use).

Detection:

AttachDevTools();

<PackageReference Include="Avalonia.Diagnostics" Version="11.x" />

Fix:

// Method name depends on AvaloniaUI.DiagnosticsSupport version
AttachDeveloperTools();
// or AttachDevTools() — check the package API

Package:

<PackageReference Include="AvaloniaUI.DiagnosticsSupport" Version="2.2.0" />

24-25. Test Framework Updates (MEDIUM - Headless)

What changed: xUnit.net v3 (from v2), NUnit v4 (from v3).

Action: Update test projects and follow official migration guides.

API Changes

26. Screen Class (LOW)

What changed: Screen is now abstract. Don't construct it.

Detection:

var screen = new Screen();

Fix:

var screen = Screens.Primary;
var screens = Screens.All;

27. ResourcesChangedEventArgs (LOW)

What changed: Now a readonly record struct (was class). Use ResourcesChangedEventArgs.Create() to construct with auto-incremented sequence numbers.

Detection:

var args = new ResourcesChangedEventArgs();

Fix:

var args = ResourcesChangedEventArgs.Create();