uno-migration-troubleshoot

name	uno-migration-troubleshoot
description	Migration paths and troubleshooting for Uno Platform: upgrading to Single Project, migrating from UWP/WPF/Silverlight, .NET version upgrades, and resolving common build/runtime errors. Use when: (1) Migrating to Uno.Sdk Single Project, (2) Upgrading from .NET 8 to .NET 9, (3) Migrating from WPF or Silverlight, (4) Fixing common build errors (UNOB0011, UNOB0013), (5) Resolving platform-specific runtime issues, (6) Troubleshooting Visual Studio 2022 problems. Do NOT use for: new project setup (see uno-platform-agent) or Wasm-specific optimization (see uno-wasm-pwa).
license	Apache 2.0 (patterns derived from Uno Platform documentation)
metadata	{"version":"1.0.0"}

Uno Platform Migration and Troubleshooting

Patterns for migrating to modern Uno Platform project structures, upgrading .NET versions, and resolving the most common build and runtime errors.

Migration to Single Project (Uno.Sdk 5.2+)

Overview

Single Project consolidates multiple platform-specific .csproj files into one project using Uno.Sdk. Migration is optional; existing multi-project structures remain supported.

Step-by-Step

1. Create a reference project with the same name using dotnet new unoapp:

   dotnet new unoapp -o MyApp --preset=recommended
   

2. Add global.json next to the solution:

   {
       "msbuild-sdks": {
           "Uno.Sdk": "{current Uno.Sdk version}"
       }
   }
   

3. Copy the new .csproj structure from the reference project

4. Merge platform folders into Platforms/:

   • MyApp.Wasm/ content to Platforms/WebAssembly/
   • MyApp.Mobile/Android/, MyApp.Mobile/iOS/ to Platforms/
   • MyApp.Skia.* content to Platforms/Desktop/

5. Copy App.xaml and App.xaml.cs from reference, then merge your custom changes (OnLaunched, RegisterRoutes, InitializeLogging)

6. Use conditional TFM blocks for platform-specific config:

   <Choose>
       <When Condition="'$(TargetFramework)'=='net9.0-browserwasm'">
           <PropertyGroup>
               <WasmShellMonoRuntimeExecutionMode>InterpreterAndAOT</WasmShellMonoRuntimeExecutionMode>
           </PropertyGroup>
       </When>
   </Choose>
   

7. Replace AppHead with App in all .cs files

8. Delete old platform projects and folders

Critical TFM Ordering

<TargetFrameworks>
    net9.0-android;net9.0-ios;net9.0-browserwasm;net9.0-desktop;net9.0
</TargetFrameworks>

Never put net9.0 first. VS2022 uses the first TFM for IntelliSense, and net9.0 alone lacks platform APIs. Putting it first causes UNOB0011 and UNOB0013 errors.

.NET Version Upgrades

.NET 8 to .NET 9

1. Update global.json to latest Uno.Sdk version
2. Change all TFMs from net8.0-* to net9.0-*
3. Update wasm-tools workload: dotnet workload install wasm-tools
4. If using Wasm bootstrapper 8.x, upgrade to 9.x:
   • Change SDK from Microsoft.NET.Sdk.Web to Microsoft.NET.Sdk.WebAssembly
   • Remove Uno.Wasm.Bootstrap.DevServer package
   • Replace deprecated MSBuild properties (see Wasm skill)

Uno.Extensions 5.2+ Breaking Changes

• MSAL: AddMsal() now requires a Window parameter
• Navigation: Some route registration APIs changed
• Themes: Uno Themes 5.1+ has color naming changes

WPF Migration

Key mapping:

WPF	Uno Platform
Window	Page (single-window model)
{Binding}	{x:Bind} (preferred) or {Binding}
ICommand	[RelayCommand] or MVUX auto-commands
DataGrid	ListView / third-party via MAUI Embedding
System.Windows.*	Microsoft.UI.Xaml.*
DispatcherInvoke	DispatcherQueue.TryEnqueue
x:Static	Not supported; use {StaticResource}
MultiBinding	Not supported; use computed properties

Silverlight Migration

Uno Platform provides a dedicated migration path. Key changes:

• Silverlight navigation (Page/Frame) maps to Uno Navigation Extensions
• RIA Services replaced with Kiota/Refit HTTP clients
• Silverlight Toolkit controls have Uno Toolkit equivalents
• IsolatedStorage replaced with ApplicationData.Current.LocalFolder

Common Build Errors

UNOB0011 / UNOB0013

Cause: net9.0 (base TFM) listed first in TargetFrameworks Fix: Move platform TFMs before base TFM:

net9.0-android;net9.0-ios;net9.0-browserwasm;net9.0-desktop;net9.0

"The 'MonoAOTCompiler' task was not found"

Cause: Missing wasm-tools workload Fix: dotnet workload install wasm-tools

"Native WebAssembly assets were detected, but the wasm-tools workload could not be located" (UNOWA0001)

Fix: Run uno-check or dotnet workload install wasm-tools in the project folder

Android build failures

• Java heap space: Add to .csproj:

  <JavaMaximumHeapSize>1g</JavaMaximumHeapSize>
  

• SDK version mismatch: Run uno-check to verify Android SDK setup
• Binding generation errors: Clean and rebuild; check for namespace conflicts

iOS build failures

• Provisioning profile: Ensure valid profile in Platforms/iOS/Entitlements.plist
• Linker errors: Add [Preserve] attribute to types consumed by reflection
• Simulator arch mismatch: Use net9.0-iossimulator TFM for simulator builds

Visual Studio 2022 Issues

• IntelliSense errors on valid code: Restart VS2022; check TFM ordering
• Hot Reload not working: Ensure DOTNET_MODIFIABLE_ASSEMBLIES=debug is set
• XAML designer blank: Expected; use Hot Design or Hot Reload instead
• Build succeeds but app crashes: Check Output window for platform-specific errors

Runtime Issues

Blank screen on Wasm

1. Check browser console (F12) for JavaScript errors
2. Verify MIME types on hosting server (application/wasm required)
3. Ensure index.html references correct bootstrapper path

App crash on Android startup

1. Check adb logcat for unhandled exceptions
2. Verify minimum SDK version matches device
3. Check for missing permissions in AndroidManifest.xml

Layout differences across platforms

• Use SafeArea for notch/status bar handling
• Test responsive breakpoints on each target size
• Skia renderer may render text metrics slightly differently than native

Diagnostic Tools

Tool	Purpose
uno-check	Verify environment setup and dependencies
dotnet workload list	Check installed workloads
adb logcat	Android runtime logs
Browser F12 Console	Wasm runtime errors
VS2022 Output Window	Build and runtime diagnostics

Common Mistakes

• Migrating by hand instead of using dotnet new unoapp as a reference project
• Not updating global.json when upgrading Uno.Sdk version
• Keeping deprecated MSBuild properties from older bootstrapper versions
• Ignoring uno-check warnings about outdated workloads
• Copying App.xaml.cs without merging custom OnLaunched logic

Related Skills

Skill	Use instead when...
uno-platform-agent	Creating new projects (not migrating existing ones)
uno-extensions-services	Configuring auth, HTTP, or DI (this skill covers breaking changes in those areas)
uno-wasm-pwa	Wasm bootstrapper setup, debugging, or deployment (not just migration)
winui-xaml	XAML best practices and performance (not migration-specific issues)

Detailed References

• references/01-single-project-migration.md - Read when migrating from multi-project to Single Project structure
• references/02-dotnet-version-upgrade.md - Read when upgrading .NET 8 to 9 or updating Uno.Extensions
• references/03-wpf-silverlight-migration.md - Read when migrating from WPF or Silverlight to Uno Platform
• references/04-common-errors.md - Read when encountering build errors, runtime crashes, or platform-specific issues