Unpackaged app deployment (#2607)

* Unpackaged apps by default on Win. * Edit. * Edit. * Edit. * Edits. * Fix linting error. * Fix identation. * Edit. * Fix moniker range. * Add image.
dotnet · Nov 7, 2024 · 86fa5c5 · 86fa5c5
1 parent 2f5df77
commit 86fa5c5
Show file tree

Hide file tree

Showing 10 changed files with 138 additions and 21 deletions.
diff --git 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
@@ -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
@@ -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
+<PropertyGroup>
+    <WindowsPackageType>None</WindowsPackageType>
+</PropertyGroup>
+```
+
+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
@@ -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 `<WindowsPackageType>None</WindowsPackageType>` 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
@@ -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
diff --git a/docs/windows/media/setup/packaged-app-unchecked.png b/docs/windows/media/setup/packaged-app-unchecked.png
diff --git a/docs/windows/media/setup/vs-target-windows-net7.png b/docs/windows/media/setup/vs-target-windows-net7.png
diff --git a/docs/windows/media/setup/vs-target-windows-net9.png b/docs/windows/media/setup/vs-target-windows-net9.png
diff --git 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
 
 <!--
 ## Start Menu entry