Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add Mac instructions to hot reload #1034

Merged
merged 1 commit into from
Oct 25, 2022
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
39 changes: 24 additions & 15 deletions docs/xaml/hot-reload.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
title: "XAML Hot Reload for .NET MAUI"
description: "Learn how to reload changes to your .NET MAUI XAML file instantly on your running app, so you don't have to rebuild your .NET MAUI project after every XAML change."
ms.date: 06/23/2022
ms.date: 10/25/2022
---

# XAML Hot Reload for .NET MAUI
Expand All @@ -10,20 +10,12 @@ ms.date: 06/23/2022

When your .NET MAUI app is running in debug configuration, with the debugger attached, XAML Hot Reload parses your XAML edits and sends those changes to the running app. It preserves your UI state, since it doesn't recreate the UI for the full page, and updates changed properties on controls affected by edits. In addition, your navigate state and data will be maintained, enabling you to quickly iterate on your UI without losing your location in the app. Therefore, you'll spend less time rebuilding and deploying your apps to validate UI changes.

By default, you don't need to save your XAML file to see the results of your edits. Instead, updates are applied immediately as you type. However, you can change this behavior to update only on file save. This can be accomplished by checking the **Apply XAML Hot Reload on document save** checkbox in the Hot Reload IDE settings available by selecting **Debug > Options> XAML Hot Reload** from the Visual Studio menu bar. Only updating on file save can sometimes be useful if you make bigger XAML updates and don't wish them to be displayed until they are complete.

<!-- XAML Hot Reload supports simultaneous debugging of multiple platforms in Visual Studio. You can deploy an Android, iOS, and WinUI target at the same time to see your changes reflected on all three platforms at once. To debug on multiple platforms, see [How To: Set multiple startup projects](/visualstudio/ide/how-to-set-multiple-startup-projects). -->

<!-- The above is commented out for now for the following reason: In MAUI if you have separate head projects, you could deploy to multiple platforms simultaneously and hot reload would work. But deploying to multiple platforms currently isn't possible with single project. -->

<!-- **Mac** [Set multiple startup projects](/visualstudio/mac/set-startup-projects?view=vsmac-2019) -->
By default, you don't need to save your XAML file to see the results of your edits. Instead, updates are applied immediately as you type. However, on Windows you can change this behavior to update only on file save. This can be accomplished by checking the **Apply XAML Hot Reload on document save** checkbox in the Hot Reload IDE settings available by selecting **Debug > Options> XAML Hot Reload** from the Visual Studio menu bar. Only updating on file save can sometimes be useful if you make bigger XAML updates and don't wish them to be displayed until they are complete.

> [!NOTE]
> If you're writing a native UWP or WPF app, without using .NET MAUI, see [What is XAML Hot Reload for WPF and UWP apps?](/visualstudio/xaml-tools/xaml-hot-reload).

<!-- XAML Hot Reload is available in both Visual Studio 2022 and Visual Studio 2022 for Mac. -->

On Windows, XAML Hot Reload is available on Android, iOS, and WinUI on emulators, simulators, and physical devices.
XAML Hot Reload is available in both Visual Studio 2022 and Visual Studio 2022 for Mac. On Windows, XAML Hot Reload is available on Android, iOS, and WinUI on emulators, simulators, and physical devices. On Mac, XAML Hot Reload is available on Android, iOS, and Mac Catalyst on emulators, simulators, and physical devices.

> [!IMPORTANT]
> XAML Hot Reload doesn't reload C# code, including event handlers.
Expand All @@ -32,18 +24,35 @@ On Windows, XAML Hot Reload is available on Android, iOS, and WinUI on emulators

## Enable XAML Hot Reload

<!-- markdownlint-disable MD025 -->
# [Visual Studio](#tab/vswin)
<!-- markdownlint-enable MD025 -->

XAML Hot Reload is enabled by default in Visual Studio 2022. If it's been previously disabled, it can be enabled by selecting **Debug > Options > XAML Hot Reload** from the Visual Studio menu bar. Next, in the **Options** dialog box, ensure that the **Enable XAML Hot Reload**, **WinUI (including .NET MAUI)**, and **Android and iOS (.NET MAUI)** options are checked:

:::image type="content" source="media/hot-reload/options.png" alt-text="XAML Hot Reload options for .NET MAUI.":::
:::image type="content" source="media/hot-reload/vs-options.png" alt-text="XAML Hot Reload options for .NET MAUI in Visual Studio.":::

Then, on iOS in your build settings, check that the Linker is set to "Don't Link".

<!-- On Mac, check the **Enable Xamarin Hot Reload** checkbox at **Visual Studio** > **Preferences** > **Tools for Xamarin** > **XAML Hot Reload**. -->
<!-- markdownlint-disable MD025 -->
# [Visual Studio for Mac](#tab/vsmac)
<!-- markdownlint-enable MD025 -->

XAML Hot Reload is enabled by default in Visual Studio 2022 for Mac. If it's been previously disabled, it can be enabled by selecting **Visual Studio > Preferences > Other > XAML Hot Reload** from the Visual Studio menu bar. Next, in the **Preferences** dialog box, ensure that the **Enable XAML Hot Reload**, and **.NET MAUI** options are checked:

:::image type="content" source="media/hot-reload/vsmac-preferences.png" alt-text="XAML Hot Reload options for .NET MAUI in Visual Studio for Mac":::

Then, on iOS in your build settings, check that the Linker is set to "Don't Link".

---

## Reload on multiple platforms

XAML Hot Reload supports simultaneous debugging of multiple platforms in Visual Studio and Visual Studio for Mac, provided that you have separate head projects per platform rather than a single project app. For example, you can deploy an Android and an iOS target at the same time to see your changes reflected on both platforms at once. To debug on multiple platforms on Windows, see [How To: Set multiple startup projects](/visualstudio/ide/how-to-set-multiple-startup-projects). To debug on multiple platforms on a Mac, see [Set multiple startup projects](/visualstudio/mac/set-startup-projects).

## Troubleshooting

The XAML Hot Reload output displays status messages that can help with troubleshooting. These can be displayed by selecting **View > Output** from the Visual Studio menu bar, and then selecting **Xamarin Hot Reload** in the **Show output from:** drop-down.
<!-- **Mac**: hover over **XAML Hot Reload** in the status bar to show that pad -->
The XAML Hot Reload output displays status messages that can help with troubleshooting. In Visual Studio, these can be displayed by selecting **View > Output** from the menu bar, and then selecting **Xamarin Hot Reload** in the **Show output from:** drop-down. In Visual Studio for Mac, these can be displayed by hovering your mouse cursor over **XAML Hot Reload** in the status bar.

If XAML Hot Reload fails to initialize you should ensure that you're using the latest version of .NET MAUI, the latest version of the IDE, and that your iOS linker settings are set to **Don't Link** in the project's build settings.

Expand Down
Binary file added docs/xaml/media/hot-reload/vsmac-preferences.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.