Spec: MauiXamlHotReload MSBuild Property for Source Generator-based XAML Hot Reload #34027
Description
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
| Value | Description |
|---|---|
Legacy |
Traditional XAML Hot Reload implementation (current behavior) |
SourceGen |
Source generator-based XAML Hot Reload |
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.