通过

.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 Code 中都提供了 XAML 热重载。 在 Windows 上，XAML 热重载可在仿真器、模拟器和物理设备上的 Android、iOS 和 WinUI 中使用。 在 Mac 上，XAML 热重载可在仿真器、模拟器和物理设备上的 Android、iOS 和 Mac Catalyst 中使用。 在所有情况下，XAML 热重载都要求将调试配置命名为 Debug。

重要

XAML 热重载不会重载 C# 代码。 如果在代码中添加新的事件处理程序，则只能在重载代码后在 XAML 中使用。 此外，如果添加了具有 x:Name 的新 XAML 元素，则在重载代码之前，不能在代码中使用该名称。

整页重载

在某些情况下，XAML 热重载不会按预期更新正在运行的应用。 例如，可能在 .NET MAUI 控件上更改颜色属性，但在正在运行的应用中却看不到颜色更改。 若要解决此问题，可以通过单击热重载工具栏按钮或按 Alt+F10 来完全重载 XAML 文件。 仅重载已编辑的 XAML 文件。 例外情况是，如果更改资源字典文件，则将重载所有 XAML 文件，以应用新资源。

重要

重载 XAML 时，某些 UI 状态可能会丢失，例如当前焦点和选择。

启用 XAML 热重载

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

Visual Studio 中 .NET MAUI 的 XAML 热重载选项。

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

在多个平台上重载

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

故障排除

XAML 热重载输出中显示有助于进行故障排除的状态消息。 在 Visual Studio 中，可以通过从菜单栏中选择“查看”>“输出”，然后在“显示输出来源：”下拉列表中选择“热重载”来显示这些信息。

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

XAML 热重载要求将调试配置命名为 Debug。 如果使用自定义生成配置，则当生成配置未命名为 Debug 时，XAML 热重载会停止工作。

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

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

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

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