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), VS Code (Linux, macOS, Windows, CodeSpaces, and GitPod) and Rider (Linux, macOS, Windows)
- 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
- Hot Reload Indicator visuals for an enhanced development experience on Uno Platform targets
- 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 per OS
Visual Studio | VS Code | Rider | ||||
---|---|---|---|---|---|---|
Target | C# | XAML | C# | XAML | C# | XAML |
Desktop Windows | ✅🐞 | ✅🐞 | ✅🐞 | ✅🐞 | ✅ | ✅ |
Desktop/WSL | ⌛[1] | ⌛[1] | ✅ | ✅ | 🔳[2] | 🔳[2] |
iOS | ⌛[3] | ✅[4] | ⌛[3]🛜 | ✅[4]🛜 | 🔳 | 🔳 |
Android | ⌛[3] | ✅[4] | ⌛[3] | ✅[4] | ⌛[3] | ✅[4] |
WinAppSDK | ✅🐞 | ✅🐞 | 🔳 | 🔳 | 🔳 | 🔳 |
WebAssembly | ✅🐞 | ✅🐞 | ✅ | ✅ | ✅ | ✅ |
Catalyst | 🔳 | 🔳 | ⌛[3]🛜 | ✅[4]🛜 | 🔳 | 🔳 |
Legend:
- ✅ Supported
- 🐞 Supported with the debugger
- ⌛ Upcoming support
- 🛜 Supported through SSH to a Mac
- 🔳 Not supported by the environment/IDE
Notes
- [1]: Support is pending support in the .NET SDK.
- [2]: Support is not available.
- [3]: C# Hot Reload is affected by a .NET Runtime issue.
- [4]: XAML Hot Reload is using the XAML Reader, pending C# Hot Reload update and a VS/VS Code update.
Supported features per Platform
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 or C# 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
- Rider
- Hot Reload is only supported without the debugger.
- Adding new C# or XAML files to a project is not yet supported
Hot Reload Indicator
Hot Reload displays a visual indicator to help you further monitor changes while developing. It displays new information every time Hot Reload is triggered. The indicator is enabled by default within the EnableHotReload()
method which is located in the root App.xaml.cs
file. This displays an overlay which hosts the visual indicator. If you wish to disable it, you simply have to provide the following boolean: EnableHotReload(disableIndicator: true)
, removing the overlay from the view.
Tip
The overlay can be moved by using the anchor on the left hand side.
The indicator displays the current connection status. Clicking on it will open a flyout containing all events or changes that were applied by Hot Reload. These events display more details about Hot Reload changes, such as its status and impacted files.
Statuses
Here's a summary of what icons and statuses you can expect:
Connection:
Success
Failed
Warning (Usually indicates an issue that can be solved by restarting your IDE)
Operation:
Success
Failed
Processing (Hot Reload is processing the changes or initializing)
Troubleshooting
- 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)
The output window in Visual Studio has an output named
Uno Platform
in its drop-down. Diagnostics messages from the VS integration appear there. You will need to have the MSBuild project build output verbosity above "minimal" in Tools > Options > Projects and Solutions > Build And Run to start having some logs in theUno Platform
output. These changes should take effect immediately without requiring a restart of Visual Studio. However, if you seem to not have more additional logs, try restarting Visual Studio. For more information regarding verbosity for build log, see the related VS documentation.
- When a file is reloaded, XAML parsing errors will appear in the application's logs, on the device or in the 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
- For
net8.0-windows10.xx
:- Ensure that the
net8.0-windows10.xxx
target framework is selected in the top-left dropdown list of the XAML editor. Selecting any other platform will break hot reload. - A VS issue for WinUI may be hit. If XAML hot reload does not work, ensure that the
Uno Platform
output window exists, and that it mentions that the extension has successfully loaded. To do so, try closing and reopening the solution, and make sure that the Visual Studio extension is installed.
- Ensure that the
- If the indicator is red and indicates that connection failed, make sure that you have the latests versions of Uno.SDK and the VS extension, then rebuild your application.
Next Steps
Learn more about:
- Uno Platform features and architecture
- Uno Platform App solution structure
- Troubleshooting
- List of views implemented in Uno for the set of available controls and their properties.
- You can head to How-tos and tutorials on how to work on your Uno Platform app.