Add MauiXamlHotReload property for IDE communication by StephaneDelcroix · Pull Request #34028 · dotnet/maui

StephaneDelcroix · 2026-02-12T21:48:34Z

Description

Introduces the MauiXamlHotReload MSBuild property to communicate to the IDE which type of XAML Hot Reload implementation the application expects.

Values

Value	Description
`Legacy` (default)	Traditional XAML Hot Reload implementation
`SourceGen`	Source generator-based XAML Hot Reload (experimental)

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

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

Warning

When MauiXamlHotReload=SourceGen is set, warning MAUI1002 is emitted:

MauiXamlHotReload is set to 'SourceGen'. Source generator-based XAML Hot Reload is experimental and not yet fully implemented. Use at your own risk.

Migration Note

This property exists to facilitate migration from legacy XAML Hot Reload to the source generator-based approach. In a future release, Legacy may be deprecated with SourceGen becoming the only supported mode.

Fixes #34027

Introduces the MauiXamlHotReload MSBuild property to communicate to the IDE which type of XAML Hot Reload implementation the application expects. Values: - Legacy (default): Traditional XAML Hot Reload - SourceGen: Source generator-based XAML Hot Reload (experimental) When SourceGen is selected, a warning (MAUI1002) is emitted indicating this feature is experimental and not yet fully implemented. This property exists to facilitate migration from legacy XAML Hot Reload to the source generator-based approach. In a future release, Legacy may be deprecated with SourceGen becoming the only supported mode. Fixes dotnet#34027

Copilot

Pull request overview

Adds a new MSBuild property, MauiXamlHotReload, intended as an IDE-facing signal for which XAML Hot Reload implementation the app expects (Legacy vs SourceGen), and emits a build warning when opting into the experimental SourceGen mode.

Changes:

Introduce MauiXamlHotReload with default value Legacy.
Add an MSBuild validation target that emits warning MAUI1002 when MauiXamlHotReload=SourceGen.

Copilot · 2026-02-12T21:52:05Z

...ontrols/src/Build.Tasks/nuget/buildTransitive/netstandard2.0/Microsoft.Maui.Controls.targets

+	<!-- Warn when MauiXamlHotReload is set to SourceGen (not yet fully implemented) -->
+	<Target Name="_ValidateMauiXamlHotReload" BeforeTargets="_CheckForInvalidConfigurationAndPlatform" Condition="'$(MauiXamlHotReload)' == 'SourceGen'">
+		<Warning 
+			Code="MAUI1002"
+			Text="MauiXamlHotReload is set to 'SourceGen'. Source generator-based XAML Hot Reload is experimental and not yet fully implemented. Use at your own risk." />


The _ValidateMauiXamlHotReload target only checks for an exact, case-sensitive match to SourceGen. This means values like sourcegen, SourceGen (trailing space), or typos (e.g., Sourcegen) will silently bypass the warning and may lead to IDE misconfiguration. Consider normalizing (trim + case-insensitive compare) and also emitting an error/warning for any value other than Legacy/SourceGen to make misconfiguration obvious.

Suggested change



<Target Name="_ValidateMauiXamlHotReload" BeforeTargets="_CheckForInvalidConfigurationAndPlatform" Condition="'$(MauiXamlHotReload)' == 'SourceGen'">

<Warning

Code="MAUI1002"

Text="MauiXamlHotReload is set to 'SourceGen'. Source generator-based XAML Hot Reload is experimental and not yet fully implemented. Use at your own risk." />



<Target Name="_ValidateMauiXamlHotReload" BeforeTargets="_CheckForInvalidConfigurationAndPlatform">

<PropertyGroup>



<_MauiXamlHotReloadNormalized>$([System.String]::Copy('$(MauiXamlHotReload)').Trim())</_MauiXamlHotReloadNormalized>

<_MauiXamlHotReloadIsSourceGen Condition="'$([System.String]::Copy('$(_MauiXamlHotReloadNormalized)').ToUpperInvariant())' == 'SOURCEGEN'">true</_MauiXamlHotReloadIsSourceGen>

<_MauiXamlHotReloadIsLegacy Condition="'$([System.String]::Copy('$(_MauiXamlHotReloadNormalized)').ToUpperInvariant())' == 'LEGACY'">true</_MauiXamlHotReloadIsLegacy>

</PropertyGroup>



<Warning

Code="MAUI1002"

Text="MauiXamlHotReload is set to 'SourceGen'. Source generator-based XAML Hot Reload is experimental and not yet fully implemented. Use at your own risk."

Condition="'$(_MauiXamlHotReloadIsSourceGen)' == 'true'" />



<Warning

Code="MAUI1003"

Text="MauiXamlHotReload is set to an unrecognized value '$(MauiXamlHotReload)'. Supported values are 'Legacy' and 'SourceGen'."

Condition="'$(_MauiXamlHotReloadNormalized)' != '' and '$(_MauiXamlHotReloadIsSourceGen)' != 'true' and '$(_MauiXamlHotReloadIsLegacy)' != 'true'" />

Copilot · 2026-02-12T21:52:06Z

...ontrols/src/Build.Tasks/nuget/buildTransitive/netstandard2.0/Microsoft.Maui.Controls.targets

+	<Target Name="_ValidateMauiXamlHotReload" BeforeTargets="_CheckForInvalidConfigurationAndPlatform" Condition="'$(MauiXamlHotReload)' == 'SourceGen'">
+		<Warning 
+			Code="MAUI1002"
+			Text="MauiXamlHotReload is set to 'SourceGen'. Source generator-based XAML Hot Reload is experimental and not yet fully implemented. Use at your own risk." />
+	</Target>


This PR introduces a new build warning (MAUI1002) and a new MSBuild property default. There are existing MSBuild unit tests validating Microsoft.Maui.Controls.targets behavior (e.g., src/Controls/tests/Xaml.UnitTests/MSBuild/MSBuildTests.cs). Please add coverage that asserts MAUI1002 is (a) not emitted by default and (b) emitted when /p:MauiXamlHotReload=SourceGen is set, so future target changes don’t accidentally remove/rename the signal IDEs rely on.

Copilot AI review requested due to automatic review settings February 12, 2026 21:48

Copilot started reviewing on behalf of StephaneDelcroix February 12, 2026 21:49 View session

StephaneDelcroix added this to the .NET 11.0-preview2 milestone Feb 12, 2026

Copilot AI reviewed Feb 12, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add MauiXamlHotReload property for IDE communication#34028

Add MauiXamlHotReload property for IDE communication#34028
StephaneDelcroix wants to merge 1 commit intodotnet:net11.0from
StephaneDelcroix:feature/maui-xaml-hotreload-property

StephaneDelcroix commented Feb 12, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Feb 12, 2026

Uh oh!

Copilot AI Feb 12, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

-	<!-- Warn when MauiXamlHotReload is set to SourceGen (not yet fully implemented) -->
-	<Target Name="_ValidateMauiXamlHotReload" BeforeTargets="_CheckForInvalidConfigurationAndPlatform" Condition="'$(MauiXamlHotReload)' == 'SourceGen'">
-		<Warning
-			Code="MAUI1002"
-			Text="MauiXamlHotReload is set to 'SourceGen'. Source generator-based XAML Hot Reload is experimental and not yet fully implemented. Use at your own risk." />
+	<!-- Warn when MauiXamlHotReload is set to SourceGen (not yet fully implemented) and validate allowed values -->
+	<Target Name="_ValidateMauiXamlHotReload" BeforeTargets="_CheckForInvalidConfigurationAndPlatform">
+		<PropertyGroup>
+			<!-- Normalize MauiXamlHotReload for comparison (trim + case-insensitive) -->
+			<_MauiXamlHotReloadNormalized>$([System.String]::Copy('$(MauiXamlHotReload)').Trim())</_MauiXamlHotReloadNormalized>
+			<_MauiXamlHotReloadIsSourceGen Condition="'$([System.String]::Copy('$(_MauiXamlHotReloadNormalized)').ToUpperInvariant())' == 'SOURCEGEN'">true</_MauiXamlHotReloadIsSourceGen>
+			<_MauiXamlHotReloadIsLegacy Condition="'$([System.String]::Copy('$(_MauiXamlHotReloadNormalized)').ToUpperInvariant())' == 'LEGACY'">true</_MauiXamlHotReloadIsLegacy>
+		</PropertyGroup>
+		<!-- Preserve existing warning when MauiXamlHotReload is (normalized) SourceGen -->
+		<Warning
+			Code="MAUI1002"
+			Text="MauiXamlHotReload is set to 'SourceGen'. Source generator-based XAML Hot Reload is experimental and not yet fully implemented. Use at your own risk."
+			Condition="'$(_MauiXamlHotReloadIsSourceGen)' == 'true'" />
+		<!-- Warn on any unrecognized MauiXamlHotReload value -->
+		<Warning
+			Code="MAUI1003"
+			Text="MauiXamlHotReload is set to an unrecognized value '$(MauiXamlHotReload)'. Supported values are 'Legacy' and 'SourceGen'."
+			Condition="'$(_MauiXamlHotReloadNormalized)' != '' and '$(_MauiXamlHotReloadIsSourceGen)' != 'true' and '$(_MauiXamlHotReloadIsLegacy)' != 'true'" />

Conversation

StephaneDelcroix commented Feb 12, 2026

Description

Values

Usage

IDE Behavior

When MauiXamlHotReload=Legacy (Default)

When MauiXamlHotReload=SourceGen

Warning

Migration Note

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Feb 12, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 12, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

When `MauiXamlHotReload=Legacy` (Default)

When `MauiXamlHotReload=SourceGen`