AvaloniaUI.DiagnosticsSupport.HotReload 1.0.1

AvaloniaUI.DiagnosticsSupport.HotReload

XAML and C# hot reload for Avalonia applications.

What it does

When your application is running under the .NET Hot Reload pipeline, edits to .axaml and .cs files are applied live:

• Controls (files with x:Class) — the old and new XAML are diffed and only the changed portions of live instances are patched: an attribute edit becomes a single property assignment, adding/removing an element rebuilds only that subtree, and wrapping/unwrapping moves the live controls instead of recreating them. Runtime state (text input, selection, scroll position, view models, event wiring) survives because the controls holding it are never destroyed. Edits the differ cannot express fall back to rebuilding the instance in place, preserving state where possible.
• Styles — application- and control-level styles are re-applied so selector and setter changes take effect immediately.
• Resource dictionaries — merged dictionaries are reloaded and dependents are refreshed.
• Data templates — templates are regenerated and controls bound to them are refreshed.
• {StaticResource} rewriting — by default, {StaticResource ...} references are rewritten to {DynamicResource ...} during hot reload so resource edits propagate without having to restart.

A file-system fallback watcher can also pick up .axaml edits when the .NET Hot Reload agent is not available.

Installation

Add the package to your Avalonia application project:

<ItemGroup Condition="'$(Configuration)' == 'Debug'">
  <PackageReference Include="AvaloniaUI.DiagnosticsSupport.HotReload" Version="..." />
</ItemGroup>

Licensing

AvaloniaUI.DiagnosticsSupport.HotReload is a licensed library. A valid runtime license key covering the AvaloniaUI.DiagnosticsSupport.HotReload product must be present at build time, or initialization will throw AvaloniaLicensingException the first time hot reload activates.

Add your key in the application's .csproj:

<ItemGroup>
  <AvaloniaUILicenseKey Include="$(AvaloniaUILicenseKey)" />
</ItemGroup>

…and supply the key value as an MSBuild property, environment variable, or through your CI secret store, e.g.:

<PropertyGroup>
  <AvaloniaUILicenseKey>...your runtime license key...</AvaloniaUILicenseKey>
</PropertyGroup>

The same key may already be configured for other licensed AvaloniaUI libraries (Charts, Markdown, TreeDataGrid, etc.); a single key that lists AvaloniaUI.DiagnosticsSupport.HotReload among its products is sufficient. The license is validated at runtime against the build timestamp embedded in this assembly, so keep the key valid for the date your application is built.

Because hot reload is intended for development builds, you typically only need the key in Debug (matching the PackageReference condition above).

Configuration

Set it in your .csproj:

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

Manual initialization

Auto-setup is sufficient for almost all scenarios. For advanced cases (custom lifecycle, multiple Application instances, deferred startup), call the API directly:

using AvaloniaUI.DiagnosticsSupport.HotReload;

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

Subsequent calls are no-ops — the engine can only be initialized once per process.

Access the live engine via HotReloadExtensions.Engine if you need to trigger reloads programmatically or inspect state.

Embedded hosts

Hot reload works when Avalonia runs as an embedded control. Live TopLevels (including EmbeddableControlRoots) are tracked automatically as they load and unload.

If your embedded root was already live before hot reload initialized, or never raises Loaded, register it explicitly:

using AvaloniaUI.DiagnosticsSupport.HotReload;

IDisposable registration = HotReloadExtensions.RegisterTopLevel(embeddableControlRoot);

Limitations

• C# changes follow the normal .NET Hot Reload rules — adding fields, changing method signatures, etc. are subject to the usual "rude edit" restrictions.
• Edits the incremental differ cannot express (root type or x:Class changes, xmlns changes, renames, very large edits) rebuild the affected instances; non-XAML runtime state inside rebuilt subtrees is reset except for what ReloadStatePreserver carries over (nested x:Class controls, common interaction state).
• Edits inside DataTemplate/ControlTemplate bodies reload the template value and refresh consumers; already-instantiated template content is rebuilt.