HotAvalonia

HotAvalonia

HotAvalonia is a hot reload plugin for Avalonia that enables you to see UI changes in real time as you edit XAML files, drastically accelerating your design and development workflow.

NuGet Packages

Installation

To instantly enable hot reload for Debug builds of your application, simply add the HotAvalonia package to your startup project (i.e., the project that produces the executable) by inserting the following snippet into your project file (e.g., .csproj, .fsproj, .vbproj, etc.):

<PackageReference Include=\"HotAvalonia\" Version=\"...\" PrivateAssets=\"All\" Publish=\"True\" />

If you\’re developing a mobile app, please double-check that Publish=\"True\" is set. Otherwise, Debug builds of your app will immediately crash on startup due to an old .NET SDK bug (dotnet/sdk#47332).

If you have a multi-project setup, it is highly recommended to add HotAvalonia to every project that contains Avalonia controls. You can either do this manually for each project, or include a PackageReference to HotAvalonia in your Directory.Build.targets.

HotAvalonia is a development-only dependency, meaning it doesn\’t affect your Release builds in any way, shape, or form, and its binaries are not shipped with your application.

Examples

Here are some examples demonstrating HotAvalonia in action:

To try it out yourself, you can run the samples/HotReloadDemo.Desktop and/or samples/HotReloadDemo.Android applications included in the repository.

Usage

HotAvalonia is designed in such a way that you usually don\’t need to do anything else after installation – it just works™. However, here are some tips and tricks for more advanced users who want to tweak their hot reload experience:

[AvaloniaHotReload]

If you want to refresh a control\’s state during a hot reload, you can apply the [AvaloniaHotReload] attribute to one or more parameterless instance methods of the said control. For example:

  using Avalonia.Controls;
+ using HotAvalonia;

  public partial class FooControl : UserControl
  {
      public FooControl()
      {
          InitializeComponent();
          Initialize();
      }

+     [AvaloniaHotReload]
      private void Initialize()
      {
          // Code to initialize or refresh
          // the control during hot reload.
      }
  }

\’StaticResource\’

When you reference a static resource, Avalonia effectively inlines its value, turning it into a constant. As a result, hot reloading a resource dictionary, for example, from which the value originally came will not affect any StaticResource definitions – you would need to hot reload the document containing them for those constant values to be recomputed.

However, if you\’re actively working on something referenced this way, having to hot reload two documents at a time just to see the changes can be pretty annoying. To make this a bit more convenient, you can use a special \'StaticResource\' syntax like this:

<TextBox Watermark=\"{\'StaticResource\' Watermark}\" />

This syntax is valid because Avalonia\’s parser allows quoting parts of your queries. However, since no sane person would ever quote StaticResource under normal circumstances, HotAvalonia treats it as a virtue signal to dynamically replace it with a DynamicResource at runtime.

With this trick, your production builds will retain the intended semantics of optimized and inlined static resources, while your debug builds empowered by HotAvalonia will convert those resources into dynamic ones, making hot reloading them much more convenient.

MSBuild Properties

HotAvalonia is highly configurable, and lots of its options can be adjusted via MSBuild properties directly in your project file (e.g., .csproj, .fsproj, .vbproj), like so:

<PropertyGroup>
  <HotAvaloniaLite>enable</HotAvaloniaLite>
</PropertyGroup>

Below is a non-exhaustive list of the most common and useful properties supported by HotAvalonia:

Also, if you are using hot reload on a remote device (for example, if you are developing a mobile app), there are some additional options to configure HotAvalonia.Remote (also known as HotAvalonia Remote File System, or just HARFS for short):

As mentioned earlier, this list is far from exhaustive. For a complete overview of available options, please check out the HotAvalonia.targets file. However, note that any properties not listed here (especially those prefixed with _) are considered internal and may be renamed, replaced, or completely removed without notice. So, feel free to experiment with those, but do not rely on them for long-term compatibility.

Optional Dependencies

To enhance your experience with HotAvalonia, you may want to install the following optional dependencies:

Miscellaneous

HotAvalonia.Core and HotAvalonia.Extensions, provided by the main HotAvalonia package, can be fine-tuned even further. For more details about their internals, please refer to their respective READMEs.

License

Licensed under the terms of the MIT License.