diff --git a/docs/whats-new/dotnet-9.md b/docs/whats-new/dotnet-9.md index 44bb2fe73..0b7f0a5ec 100644 --- a/docs/whats-new/dotnet-9.md +++ b/docs/whats-new/dotnet-9.md @@ -1,7 +1,7 @@ --- title: What's new in .NET MAUI for .NET 9 description: Learn about the new features introduced in .NET MAUI for .NET 9. -ms.date: 11/06/2024 +ms.date: 11/07/2024 --- # What's new in .NET MAUI for .NET 9 @@ -420,6 +420,10 @@ Full trimming is now supported by setting the `$(TrimMode)` MSBuild property to [!INCLUDE [Trimming feature switches](../deployment/includes/feature-switches.md)] +## Windows app deployment + +When debugging and deploying a new .NET MAUI project to Windows, the default behavior in .NET MAUI 9 is to deploy an unpackaged app. For more information, see [Deploy and debug your .NET MAUI app on Windows](~/windows/setup.md). + ## XAML compiler In .NET MAUI 9, the XAML compiler error codes have changed their prefix from `XFC` to `XC`. Ensure that you update the `$(WarningsAsErrors)`, `$(WarningsNotAsErrors)`, and `$(NoWarn)` build properties in your app's project files, if used, to reference the new prefix. diff --git a/docs/windows/includes/configure-packaged.md b/docs/windows/includes/configure-packaged.md new file mode 100644 index 000000000..d19ded1ef --- /dev/null +++ b/docs/windows/includes/configure-packaged.md @@ -0,0 +1,28 @@ +--- +ms.topic: include +ms.date: 11/07/2024 +--- + +## Configure Windows for packaged app deployment + +You'll need to enable Developer Mode in Windows to be able to deploy a packaged .NET MAUI Windows app. Both Windows 10 and Windows 11 are supported. + +:::image type="content" source="../media/setup/developer-mode-win11.png" alt-text="Developer mode settings in Windows 11 for MAUI .NET Windows app."::: + +### Windows 11 + +Developer Mode is enabled in **Settings** app, under **Privacy & security** > **For developers**. To enable Developer Mode in Windows 11: + +01. Open the Start Menu. +01. Type **Developer settings** in the search box and select it. +01. Turn on **Developer Mode**. +01. If you receive a warning message about Developer Mode, read it, and select **Yes** if you understand the warning. + +### Windows 10 + +Developer Mode is enabled in **Settings** app, under **Update & Security** > **For developers**. To enable Developer Mode in Windows 10: + +01. Open the Start Menu. +01. Search for **Developer settings**, select it. +01. Turn on **Developer Mode**. +01. If you receive a warning message about Developer Mode, read it, and select **Yes** if you understand the warning. diff --git a/docs/windows/includes/convert-packaged-to-unpackaged.md b/docs/windows/includes/convert-packaged-to-unpackaged.md new file mode 100644 index 000000000..cc20cf5eb --- /dev/null +++ b/docs/windows/includes/convert-packaged-to-unpackaged.md @@ -0,0 +1,36 @@ +--- +ms.topic: include +ms.date: 11/07/2024 +--- + +## Convert a packaged .NET MAUI Windows app to unpackaged + +To convert an existing .NET MAUI Windows packaged app to an unpackaged app in Visual Studio: + +1. In **Solution Explorer**, right-click on your .NET MAUI app project and select **Properties**. Then, navigate to the **Application > Windows Targets** tab and ensure that **Create a Windows MSIX package** is unchecked: + + :::image type="content" source="../media/setup/packaged-app-unchecked.png" alt-text="Screenshot of Create a Windows MSIX package unchecked in Visual Studio."::: + +Visual Studio will modify your app's project file (*.csproj) to set the `$(WindowsPackageType)` build property to `None`: + +```xml + + None + +``` + +In addition, your app's *Properties/launchSettings.json* file will have the `commandName` value changed from `MsixPackage` to `Project`: + +```json +{ + "profiles": { + "Windows Machine": { + "commandName": "Project", + "nativeDebugging": false + } + } +} +``` + +> [!IMPORTANT] +> If your app defines multiple launch setting profiles you'll have to manually update the `commandName` value from `MsixPackage` to `Project` for each profile. diff --git a/docs/windows/includes/convert-unpackaged-to-packaged.md b/docs/windows/includes/convert-unpackaged-to-packaged.md new file mode 100644 index 000000000..4b2898f53 --- /dev/null +++ b/docs/windows/includes/convert-unpackaged-to-packaged.md @@ -0,0 +1,30 @@ +--- +ms.topic: include +ms.date: 11/07/2024 +--- + +## Convert an unpackaged .NET MAUI Windows app to packaged + +If your app needs to use APIs that are only available with Windows packaged apps and you plan on distributing your app through the Microsoft Store, you'll need to convert your unpackaged app to a packaged app. This can be achieved in Visual Studio: + +1. In **Solution Explorer**, right-click on your .NET MAUI app project and select **Properties**. Then, navigate to the **Application > Windows Targets** tab and ensure that **Create a Windows MSIX package** is checked: + + :::image type="content" source="../media/setup/packaged-app-checked.png" alt-text="Screenshot of Create a Windows MSIX package checked in Visual Studio."::: + +Visual Studio will modify your app's project file (*.csproj*) to remove the `None` line. In addition, your app's *Properties/launchSettings.json* file will have the `commandName` value changed from `Project` to `MsixPackage`: + +```json +{ + "profiles": { + "Windows Machine": { + "commandName": "MsixPackage", + "nativeDebugging": false + } + } +} +``` + +> [!IMPORTANT] +> If your app defines multiple launch setting profiles you'll have to manually update the `commandName` value from `Project` to `MsixPackage` for each profile. + +When deploying a packaged .NET MAUI Windows app, you'll need to enable Developer Mode in Windows. For more information, see [Configure Windows for packaged app deployment](#configure-windows-for-packaged-app-deployment). diff --git a/docs/windows/includes/target-windows.md b/docs/windows/includes/target-windows.md new file mode 100644 index 000000000..142d1b041 --- /dev/null +++ b/docs/windows/includes/target-windows.md @@ -0,0 +1,22 @@ +--- +ms.topic: include +ms.date: 11/07/2024 +--- + +## Target Windows + +::: moniker range="=net-maui-8.0" + +In Visual Studio, set the **Debug Target** to **Framework (...)** > **net8.0-windows**. There is a version number in the item entry, which may or may not match the following screenshot: + +:::image type="content" source="../media/setup/vs-target-windows-net8.png" alt-text="Visual Studio debug target set to Windows for .NET MAUI 8 app."::: + +::: moniker-end + +::: moniker range="=net-maui-9.0" + +In Visual Studio, set the **Debug Target** to **Framework (...)** > **net9.0-windows**. There is a version number in the item entry, which may or may not match the following screenshot: + +:::image type="content" source="../media/setup/vs-target-windows-net9.png" alt-text="Visual Studio debug target set to Windows for .NET MAUI 9 app."::: + +::: moniker-end diff --git a/docs/windows/media/setup/packaged-app-checked.png b/docs/windows/media/setup/packaged-app-checked.png new file mode 100644 index 000000000..76bb6de59 Binary files /dev/null and b/docs/windows/media/setup/packaged-app-checked.png differ diff --git a/docs/windows/media/setup/packaged-app-unchecked.png b/docs/windows/media/setup/packaged-app-unchecked.png new file mode 100644 index 000000000..a2ad6fe50 Binary files /dev/null and b/docs/windows/media/setup/packaged-app-unchecked.png differ diff --git a/docs/windows/media/setup/vs-target-windows-net7.png b/docs/windows/media/setup/vs-target-windows-net7.png deleted file mode 100644 index 221996ab9..000000000 Binary files a/docs/windows/media/setup/vs-target-windows-net7.png and /dev/null differ diff --git a/docs/windows/media/setup/vs-target-windows-net9.png b/docs/windows/media/setup/vs-target-windows-net9.png new file mode 100644 index 000000000..376a42c42 Binary files /dev/null and b/docs/windows/media/setup/vs-target-windows-net9.png differ diff --git a/docs/windows/setup.md b/docs/windows/setup.md index b29e54ec8..5edaf44ac 100644 --- a/docs/windows/setup.md +++ b/docs/windows/setup.md @@ -1,43 +1,40 @@ --- title: "Debugging on Windows" description: "This article explains how to configure Windows 10 and Windows 11 for .NET MAUI app deployment and debugging." -ms.date: 02/28/2022 -ms.custom: updateeachrelease +ms.date: 11/07/2024 --- # Deploy and debug your .NET MAUI app on Windows You can use your local Windows development computer to deploy and debug a .NET Multi-platform App UI (.NET MAUI) app. This article describes how to configure Windows to debug a .NET MAUI app. -## Configure Windows +::: moniker range="=net-maui-8.0" -You must enable Developer Mode in Windows. Both Windows 10 and Windows 11 are supported. +When debugging and deploying a new .NET MAUI project to Windows, the default behavior is to deploy a packaged app. For information about packaged apps, see [Windows apps: packaging, deployment, and process](/windows/apps/get-started/intro-pack-dep-proc). -:::image type="content" source="media/setup/developer-mode-win11.png" alt-text="Developer mode settings in Windows 11 for MAUI .NET Windows app."::: +[!INCLUDE [Configure Windows for packaged app deployment](includes/configure-packaged.md)] -### Windows 11 +[!INCLUDE [Target Windows](includes/target-windows.md)] -Developer Mode is enabled in **Settings** app, under **Privacy & security** > **For developers**. To enable Developer Mode in Windows 11: +[!INCLUDE [Convert a packaged .NET MAUI Windows app to unpackaged](includes/convert-packaged-to-unpackaged.md)] -01. Open the Start Menu. -01. Type **Developer settings** in the search box and select it. -01. Turn on **Developer Mode**. -01. If you receive a warning message about Developer Mode, read it, and select **Yes** if you understand the warning. +[!INCLUDE [Convert an unpackaged .NET MAUI Windows app to packaged](includes/convert-unpackaged-to-packaged.md)] -### Windows 10 +::: moniker-end -Developer Mode is enabled in **Settings** app, under **Update & Security** > **For developers**. To enable Developer Mode in Windows 10: +::: moniker range=">=net-maui-9.0" -01. Open the Start Menu. -01. Search for **Developer settings**, select it. -01. Turn on **Developer Mode**. -01. If you receive a warning message about Developer Mode, read it, and select **Yes** if you understand the warning. +When debugging and deploying a new .NET MAUI project to Windows, the default behavior is to deploy an unpackaged app. For information about unpackaged apps, see [Windows apps: packaging, deployment, and process](/windows/apps/get-started/intro-pack-dep-proc). -## Target Windows +[!INCLUDE [Target Windows](includes/target-windows.md)] -In Visual Studio, set the **Debug Target** to **Framework (...)** > **net8.0-windows**. There is a version number in the item entry, which may or may not match the following screenshot: +[!INCLUDE [Convert an unpackaged .NET MAUI Windows app to packaged](includes/convert-unpackaged-to-packaged.md)] -:::image type="content" source="media/setup/vs-target-windows-net8.png" alt-text="Visual Studio debug target set to Windows for .NET MAUI app."::: +[!INCLUDE [Convert a packaged .NET MAUI Windows app to unpackaged](includes/convert-packaged-to-unpackaged.md)] + +[!INCLUDE [Configure Windows for packaged app deployment](includes/configure-packaged.md)] + +::: moniker-end