Hot Reload

The Uno Platform Hot Reload feature provides a way to modify the XAML and C# of your running application, in order to iterate faster on UI or code changes. This makes the inner developer loop faster.

Features

  • Supported in Visual Studio 2022 (Windows) and VS Code (Linux, macOS, Windows, CodeSpaces, and GitPod)
  • XAML and C# Markup Hot Reload for iOS, Catalyst, Android, WebAssembly, and Skia (X11, Windows, macOS and FrameBuffer)
  • All C# of Hot Reload in both Visual Studio and VS Code. See supported code changes.
  • Simulator and physical devices support
  • What can be Hot Reloaded:
    • XAML files in the main project and referenced projects libraries
    • C# Markup controls
    • Bindings
    • Full x:Bind expressions
    • App.xaml and referenced resource dictionaries
    • DataTemplates
    • Styles
    • Extensible State restoration
    • Support for partial tree hot reload, where modifying a UserControl instantiated in multiple locations will reload it without reloading its parents

Hot Reload features vary between platforms and IDE, you can check below the list of currently supported features.

How to use Hot Reload

  • Setup your environment by following our getting started guides.
  • Start your application (with or without the debugger, depending on the supported features below)
  • Make changes to your XAML or C# code, save your file then press the red flame icon in the toolbar or use Alt+F10
Important

Using .NET 8 or later (net8.0 in the TargetFrameworks property) is required for Hot Reload to be available when your solution contains iOS, Android, Mac Catalyst, or WebAssembly project heads. On Windows, Visual Studio 17.8 or later is required.

Supported features

Skia-based targets provide support for full XAML Hot Reload and C# Hot Reload. There are some restrictions that are listed below:

  • The Visual Studio 2022 for Windows support is fully available, with and without running under the debugger
  • As of VS 2022 17.9 XAML Hot Reload under WSL is not supported
  • VS Code
    • With the debugger: The C# Dev Kit is handling hot reload when enabled. As of December 20th, 2023, C# Dev Kit hot reload does not handle class libraries. To experience the best hot reload, do not use the debugger.
    • Without the debugger: The VS Code Uno Platform extension is handling Hot Reload (C# or XAML)
    • Adding new C# or XAML files to a project is not yet supported

Troubleshooting

Common issues

  • Observe the application logs, you should see diagnostics messages in the app when a XAML file is reloaded.

  • The file named RemoteControlGenerator\RemoteControl.g.cs in the analyzers node for your project contains the connection information, verify that the information host addresses and the port number.

  • WinAppSDK on Windows-specific issues

  • If you're getting ENC0003: Updating 'attribute' requires restarting the application, add the following in the Directory.Build.props (or in each csproj project heads):

    <PropertyGroup>
  <!-- Required for Hot Reload (See https://github.com/unoplatform/uno.templates/issues/376) -->
  <GenerateAssemblyInfo Condition="'$(Configuration)'=='Debug'">false</GenerateAssemblyInfo>
</PropertyGroup>

  • If you're getting the Unable to access Dispatcher/DispatcherQueue error, you'll need to update your app startup to Uno 5 or later:

    • Add the following lines to the shared library project csproj file :

      <ItemGroup>
    <PackageReference Include="Uno.WinUI.DevServer" Version="$UnoWinUIVersion$" Condition="'$(Configuration)'=='Debug'" />
</ItemGroup>
      Note

      If your application is using the UWP API set (Uno.UI packages) you'll need to use the Uno.UI.DevServer package instead.

    • Then, in your App.cs file, add the following:

      using Uno.UI;

//... in the OnLaunched method

#if DEBUG
        MainWindow.EnableHotReload();
#endif

Visual Studio 2022

  • Make sure that C# Hot Reload is not disabled in Visual Studio
    • Open Tools / Options
    • Search for .NET / C++ Hot Reload
    • Ensure that all three checkboxes are checked (Enable hot reload when debugging, Enable Hot Reload without debugging and Apply Hot Reload on File Save)
  • Hot Reload for WebAssembly is not supported when using the debugger. Start your app using Ctrl+F5.
  • The output window in VS has an output named Uno Platform in its drop-down. Diagnostics messages from the VS integration appear there. Changing the MSBuild build output verbosity in Tools/Options/Projects and Solutions/Build And Run controls the log level.
  • When a file is reloaded, XAML parsing errors will appear in the application's logs, on device or in browser.
  • If there are multiple versions of the Uno.WinUI Package present in the solution, the newest will be used, regardless of the started application
  • The app does not update its XAML, because the port number in RemoteControl.g.cs is 0.
    • Ensure you have the latest version of the Visual Studio extension installed.
    • Rebuild the app until the number is different than zero.

VS Code

  • The output window in Code has an output named "Uno Platform - Hot Reload" in its drop-down. Diagnostics messages from the extension appear there.
  • Hot Reload is not supported for WebAssembly and Skia Desktop when using the debugger. Start your app using Ctrl+F5.
  • Depending on your machine's performance, the hot reload engine may take a few moments to initialize and take your project modifications into account.
  • Make sure that the selected project in the status bar is not the solution file, but rather the project platform you are debugging.
  • If Hot Reload does not function properly, you can try using the Developer: Reload Window command in the palette (using Ctrl+Shift+P)
  • When working on Skia Desktop apps, make sure to start the app without the debugger, and make sure that in the debugger tab, the Uno Platform Desktop (Debug) target is selected.

Next Steps

Learn more about: