.NET MAUI XAML 热重载

.NET Multi-platform App UI (.NET MAUI) XAML 热重载是一项 Visual Studio 功能，可用于查看正在运行的应用中 XAML 更改的结果，而无需重新生成项目。 如果没有 XAML 热重载，每次要查看 XAML 更改结果时，都需要生成和部署应用。

当 .NET MAUI 应用连接了调试器并在调试配置下运行时，XAML 热重载会分析 XAML 编辑内容，并将相关更改发送到正在运行的应用。 由于它不会为整个页面重新创建 UI，因此会保留 UI 状态，并更新受编辑影响的控件上被更改的属性。 此外，可保持导航状态和数据，这样既可快速迭代 UI，又不影响在应用中的即时位置。 因此，可减少重新生成和部署应用以验证 UI 更改的时间。

默认情况下，无需保存 XAML 文件即可查看编辑结果。 并在键入时立即应用更新。 但在 Windows 上，可将此行为更改为仅在文件保存时更新。 具体实现方式如下：从 Visual Studio 菜单栏中选择“调试”>“选项”>“XAML 热重载”，然后在“热重载 IDE”设置中选中“文件保存时应用 XAML 热重载”复选框。 有时，如果要进行较大 XAML 更新但不希望在更新完成之前显示更新，则仅在文件保存时更新就会很有用。

注意

如果要编写本机 UWP 或 WPF 应用但不使用 .NET MAUI，请参阅 WPF 和 UWP 应用的 XAML 热重载是什么。

Visual Studio 2022 和 Visual Studio 2022 for Mac 中均可使用 XAML 热重载。 在 Windows 上，XAML 热重载可在仿真器、模拟器和物理设备上的 Android、iOS 和 WinUI 中使用。 在 Mac 上，XAML 热重载可在仿真器、模拟器和物理设备上的 Android、iOS 和 Mac Catalyst 中使用。

重要说明

XAML 热重载不会重载 C# 代码，包括事件处理程序。

启用 XAML 热重载

Visual Studio

Visual Studio 2022 中默认启用 XAML 热重载。 如果之前已将其禁用，可从 Visual Studio 菜单栏中选择“调试”>“选项”>“XAML 热重载”，将其启用。 接下来在“选项”对话框中，确保选中“启用 XAML 热重载”、“WinUI (包括 .NET MAUI)”和“Android 和 iOS (.NET MAUI)”选项：

然后在 iOS 的生成设置中，检查“链接器”是否设置为“不链接”。

Visual Studio for Mac

注意

根据 Microsoft 的现代生命周期策略，Visual Studio for Mac 计划于 2024 年 8 月 31 日停用。 2024 年 8 月 31 日之前，Visual Studio for Mac 17.6 将继续受支持，Apple 将提供安全问题和更新平台的服务更新。 有关详细信息（包括在 Mac 上进行开发的替代选项），请参阅 Visual Studio for Mac 进行了哪些更新。

Visual Studio 2022 for Mac 中默认启用 XAML 热重载。 如果之前已将其禁用，可从 Visual Studio 菜单栏中选择“Visual Studio”>“首选项”>“其他”>“XAML 热重载”，将其启用。 接下来在“首选项”对话框中，确保选中“启用 XAML 热重载”和“.NET MAUI”选项：

然后在 iOS 的生成设置中，检查“链接器”是否设置为“不链接”。

在多个平台上重载

XAML 热重载支持在 Visual Studio 和 Visual Studio for Mac 中同时调试多个平台，前提是每个平台都有独立的头部项目，而不是单项目应用。 例如，可同时部署 Android 和 iOS 目标，同时看到所做更改在两个平台上的体现。 要在 Windows 上的多个平台中调试，请参阅操作指南：设置多个启动项目。 要在 Mac 上的多个平台中调试，请参阅设置多个启动项目。

故障排除

XAML 热重载输出中显示有助于进行故障排除的状态消息。 在 Visual Studio 中显示这些消息的方法：从菜单栏中选择“查看”>“输出”，然后选择“显示输出来源:”下拉列表中的“Xamarin 热重载”。 在 Visual Studio for Mac 中显示这些消息的方法：将鼠标光标悬停在状态栏中的“XAML 热重载”上。

如果 XAML 热重载未能初始化，应确保使用的是最新版本的 .NET MAUI、最新版本的 IDE，且项目生成设置中的 iOS 链接器设置已设置为“不链接”。

如果在保存 XAML 文件时没有任何反应，请确保在 IDE 中启用了 XAML 热重载。 有关详细信息，请参阅启用 XAML 热重载。

如果所作更改被 XAML 热重载分析器视为无效，它会在编辑器中用下划线来指示相关错误，并将其包含在“错误列表”窗口中。 热重载错误的错误代码以“XHR”（表示 XAML Hot Reload，即热重载）开头。 如果页面上存在任何这类错误，则在错误消除之前，XAML 热重载不会对正在运行的应用进行更改。

在 XAML 热重载会话期间，无法添加、删除或重命名文件或 NuGet 包。 如果添加或删除了文件或 NuGet 包，需重新生成并重新部署应用才能继续使用 XAML 热重载。

不支持使用 [XamlCompilation(XamlCompilationOptions.Skip)] 禁用 XAML 编译，此操作可能导致实时可视化树出现问题。 有关实时可视化树的详细信息，请参阅查看 .NET MAUI 应用的可视化树。