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

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.

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

Add case-insensitive comparison for SourceGen/Legacy values and emit MAUI1003 warning for unrecognized values. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

StephaneDelcroix · 2026-02-24T21:32:04Z

/backport to release/11.0.1xx-preview2

github-actions · 2026-02-24T21:32:15Z

Started backporting to release/11.0.1xx-preview2 (link to workflow run)

…4260) This PR merges commits from `net11.0` into `release/11.0.1xx-preview2`. Commits include: - Add Circle, Polygon, and Polyline click events for Map control (#29101) - [automated] Merge branch 'main' => 'net11.0' (#34203) - Fix empty string binding to nullable value types (#33536) - Add MapElement.IsVisible and MapElement.ZIndex properties (#33993) - Add MauiXamlHotReload property for IDE communication (#34028) ## Instructions for merging Complete this PR by creating a **merge commit**, *not* a squash or rebase commit.

The MauiXamlHotReload MSBuild property was introduced in #34028 but was not registered as a compiler-visible property. Without this entry, Roslyn source generators cannot read the property value via AnalyzerConfigOptions.GlobalOptions. This change makes it accessible so IDE and source generators can adjust their behavior based on the configured hot reload mode (Legacy or SourceGen). Co-authored-by: Kirill Ovchinnikov <kovchinnikov@microsoft.com>

…t#34405) The MauiXamlHotReload MSBuild property was introduced in dotnet#34028 but was not registered as a compiler-visible property. Without this entry, Roslyn source generators cannot read the property value via AnalyzerConfigOptions.GlobalOptions. This change makes it accessible so IDE and source generators can adjust their behavior based on the configured hot reload mode (Legacy or SourceGen). Co-authored-by: Kirill Ovchinnikov <kovchinnikov@microsoft.com>

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

kubaflo previously approved these changes Feb 18, 2026

View reviewed changes

StephaneDelcroix force-pushed the feature/maui-xaml-hotreload-property branch from 3755e67 to bc4033d Compare February 24, 2026 18:56

Make MauiXamlHotReload validation case-insensitive

21b7212

Add case-insensitive comparison for SourceGen/Legacy values and emit MAUI1003 warning for unrecognized values. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

StephaneDelcroix dismissed kubaflo’s stale review via 21b7212 February 24, 2026 20:05

StephaneDelcroix merged commit 49bc594 into dotnet:net11.0 Feb 24, 2026
1 of 10 checks passed

github-actions bot mentioned this pull request Feb 24, 2026

[release/11.0.1xx-preview2] Add MauiXamlHotReload property for IDE communication #34219

Closed

PureWeen mentioned this pull request Feb 26, 2026

[automated] Merge branch 'net11.0' => 'release/11.0.1xx-preview2' #34260

Merged

noiseonwires mentioned this pull request Mar 10, 2026

Add MauiXamlHotReload to the list of CompilerVisibleProperties #34405

Merged

github-actions bot locked and limited conversation to collaborators Mar 27, 2026

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 merged 2 commits 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!

Uh oh!

StephaneDelcroix commented Feb 24, 2026

Uh oh!

github-actions bot commented Feb 24, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

-	<!-- 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!

Uh oh!

StephaneDelcroix commented Feb 24, 2026

Uh oh!

github-actions bot commented Feb 24, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

When `MauiXamlHotReload=Legacy` (Default)

When `MauiXamlHotReload=SourceGen`