MauiXamlHotReload MSBuild Property Specification

Overview

The MauiXamlHotReload MSBuild property communicates to the IDE which type of XAML Hot Reload implementation the application expects. This enables the IDE to configure its Hot Reload behavior accordingly.

Property Definition

Name: MauiXamlHotReload
Type: String (enumerated)
Default: Legacy

Values

Usage

<PropertyGroup>
  <MauiXamlHotReload>SourceGen</MauiXamlHotReload>
</PropertyGroup>

IDE Behavior

When MauiXamlHotReload=Legacy (Default)

The IDE should behave as it currently does:

• XAML Hot Reload enabled
• Full page refresh supported
• Incremental XAML Hot Reload supported
• VisualDiagnostics supported
• BindingDiagnostics supported

When MauiXamlHotReload=SourceGen

The IDE MUST:

• Ensure C# Hot Reload is enabled
• Ensure legacy XAML Hot Reload is disabled
• Provide a mechanism to trigger the MAUI Update Handler (MUH)

The IDE MUST NOT:

• Trigger full page refresh (i.e., send updated XAML to the app)
• Use incremental XAML Hot Reload

The IDE MAY continue to support:

• VisualDiagnostics
• BindingDiagnostics
• Other diagnostic capabilities

Migration Note

This property exists to facilitate a smooth migration path from the legacy XAML Hot Reload implementation to the source generator-based approach. The Legacy value is provided for backward compatibility during this transition period.

In a future release, the Legacy option may be deprecated and removed, with SourceGen becoming the only supported mode. Developers are encouraged to test their applications with MauiXamlHotReload=SourceGen to prepare for this transition.

Rationale

Source generator-based XAML Hot Reload leverages C# Hot Reload infrastructure. XAML changes are processed by the source generator at design-time, producing C# code that is then hot-reloaded via the standard C# Hot Reload mechanism. This eliminates the need for runtime XAML parsing and provides a more consistent hot reload experience.