Skip to main content

Hot reload

Hot reload applies edits to .axaml and .cs files in a running Avalonia application without restarting it. The AvaloniaUI.DiagnosticsSupport.HotReload package plugs into the .NET Hot Reload pipeline: when you save a file, matching controls, styles, resources and data templates are rebuilt in place.

What hot reload updates​

With the hot reload package, these edits are applied live to your running application:

ChangeBehavior
Controls (files with x:Class)Existing instances in the visual tree are rebuilt in place, keeping their positions where possible.
StylesApplication-level and control-level styles are reapplied. Selector and setter changes take effect at once.
Resource dictionariesMerged dictionaries are reloaded and dependents are refreshed.
Data templatesTemplates are regenerated and controls bound to them are refreshed.
{StaticResource} referencesRewritten to {DynamicResource} during hot reload, so resource edits propagate without a restart.
Some common uses of hot reload are:
  • Resource brushes and values. Change a color, brush, or font size in a resource dictionary and every control that references it updates. Both {DynamicResource} and {StaticResource} references pick up the change, because static references are rewritten during hot reload.
  • Data templates. Change the icon, colors, spacing, or layout of a data template, and every control that uses it, including list items and content presenters, rebuilds with the new template.
  • Control markup. Adjust the layout, add or remove elements, or edit text in a view (a file with x:Class). The live instance is rebuilt in place.
  • Styles. Edit a selector or setter in an application-level or control-level style, and the new styling is re-applied at once.
  • Code-behind. Change an event handler or method body in an .axaml.cs file. C# edits apply under the standard .NET Hot Reload rules.

Prerequisites​

Before you begin, make sure you have:

  1. Avalonia 12.0 or newer.
  2. A valid Avalonia license key that includes access to AvaloniaUI.DiagnosticsSupport.HotReload. You can get a key from the Avalonia customer portal. The same key may cover other licensed Avalonia packages, such as Charts or TreeDataGrid.
  3. A hot reload driver. Either the dotnet watch command or an IDE that supports .NET Hot Reload (such as Visual Studio). See Step 3.

Getting started​

  1. Install the AvaloniaUI.DiagnosticsSupport.HotReload NuGet package by running dotnet add package.

  2. To keep hot reload out of release builds, go to your .csproj file and wrap the <PackageReference> for the hot reload package in a Debug condition. This ensures it never ships.

  3. Include your Avalonia license key in the executable project file (.csproj). Your license key is available from the Avalonia portal.

Running with hot reload​

Start your application through a tool that supports .NET Hot Reload.

Run dotnet watch on the platform head project. It rebuilds and applies changes when you save.

dotnet watch --project YourApp.Desktop

This is the most reliable driver and works the same across every editor and platform.

note

On mobile platforms, dotnet watch requires .NET 11 or newer.

Enabling the file-system watcher​

Avalonia hot reload can still pick up .axaml edits with a built-in file-system watcher, even if .NET Hot Reload is not attached. This can occur if you run the app outside dotnet watch, or if you are using Rider.

To enable the file-system watcher, add an MSBuild property in your .csproj:

<PropertyGroup>
  <AvaloniaHotReloadEnableFileWatcher>true</AvaloniaHotReloadEnableFileWatcher>
</PropertyGroup>
tip

The file-system watcher can hot-reload .axaml files without .NET Hot Reload, but not .cs files. If you need hot reload for your C# code-behind, pair the watcher with dotnet watch.

Verifying hot reload​

With the app running:

  1. Open an .axaml file. Change a property, for example, a Background color or some text. Save the file.
  2. Watch the running window. It should update without losing its current view.
  3. Open the matching .axaml.cs file. Adjust an event handler. Save the file.
  4. Trigger the event.
  5. In the running window, confirm that the adjusted event reflects your edit. Diagnostic output is written to the trace log under the HotReload category.
info

C# changes follow the standard .NET Hot Reload rules.

Initializing manually​

The auto-setup method described above covers most usages of hot reload. If you need a custom lifecycle, multiple Application instances, or deferred startup, you can instead call the initializer manually:

using AvaloniaUI.DiagnosticsSupport.HotReload;

HotReloadExtensions.InitializeHotReload(
    Application.Current!,
    enableFileWatcher: true,
    rewriteStaticResources: true);

The engine initializes once per process, so later calls have no effect. To surface hot reload activity in your logging, subscribe to HotReloadDiagnostics.EntryLogged.

Limitations​

  • WebAssembly is not supported. Hot reload works on desktop and mobile platforms only.
  • C# edits follow the normal .NET Hot Reload rules. Adding fields or changing method signatures counts as a rude edit and needs a restart.
  • Controls are rebuilt rather than mutated, so non-XAML states are reset when a control reloads.

See also​

On this page