From b2ea5a018c48a0f728e30d58d77ae8bafd87375a Mon Sep 17 00:00:00 2001 From: Jerome Laban Date: Fri, 10 May 2024 10:59:27 -0400 Subject: [PATCH 01/15] docs: Add windows publishing steps --- doc/articles/toc.yml | 7 ++ doc/articles/uno-publishing-overview.md | 18 +++++ doc/articles/uno-publishing-windows.md | 96 +++++++++++++++++++++++++ 3 files changed, 121 insertions(+) create mode 100644 doc/articles/uno-publishing-overview.md create mode 100644 doc/articles/uno-publishing-windows.md diff --git a/doc/articles/toc.yml b/doc/articles/toc.yml index 0a0c0ca4c174..53cd661564fb 100644 --- a/doc/articles/toc.yml +++ b/doc/articles/toc.yml @@ -231,6 +231,13 @@ topicHref: guides/silverlight-migration/silverlight-migration-landing.md href: guides/silverlight-migration/toc.yml + - name: Publishing + items: + - name: Overview + href: xref:uno.publishing.overview + - name: Publishing for Windows + href: xref:uno.publishing.windows + - name: Performance items: - name: Improving Build Times diff --git a/doc/articles/uno-publishing-overview.md b/doc/articles/uno-publishing-overview.md new file mode 100644 index 000000000000..561e05a2f4f9 --- /dev/null +++ b/doc/articles/uno-publishing-overview.md @@ -0,0 +1,18 @@ +--- +uid: uno.publishing.overview +--- + +# Publishing Your App + +## Preparing + +- [Configure the IL Linker](xref:uno.articles.features.illinker) +- [Improve Performance](xref:Uno.Development.Performance) + +## Packaging + +- [Packaging for Windows](xref:uno.publishing.windows) + +## Deploying + +_To be documented._ diff --git a/doc/articles/uno-publishing-windows.md b/doc/articles/uno-publishing-windows.md new file mode 100644 index 000000000000..80af62c1597b --- /dev/null +++ b/doc/articles/uno-publishing-windows.md @@ -0,0 +1,96 @@ +--- +uid: uno.publishing.windows +--- + +# Publishing Your App for Windows + +## Preparing For Publish + +## Building your app + +Building your app require using the msbuild command (`dotnet build` is not compatible as of WinAppSDK 1.5). + +### Side loading (without signing) + +#### Package the unsigned app + +Packaging the app without a code signature allows for installing the app on a machine without having to install the signer's certificate. This portion of the guide is derived from the [official Windows App SDK documentation](https://learn.microsoft.com/en-us/windows/msix/package/unsigned-package). + +To package your app: + +- Update the `Package.appxmanifest` file with the following `Identity` node to include the following `OID`: + + ```xml + + ``` + +- Build your app in the folder of the app's `.csproj` by using the following command: + + ```pwsh + msbuild /r /p:TargetFramework=net8.0-windows10.0.19041 /p:Configuration=Release /p:Platform=x64 /p:GenerateAppxPackageOnBuild=true /p:AppxBundle=Never /p:UapAppxPackageBuildMode=Sideloading /p:AppxPackageDir="C:/temp/output/" /p:AppxPackageSigningEnabled=false + ``` + +> [!IMPORTANT] +> Single package msix bundling is [not yet supported from msbuild the command line](https://learn.microsoft.com/en-us/windows/apps/windows-app-sdk/single-project-msix?tabs=csharp#automate-building-and-packaging-your-single-project-msix-app). + +#### Install unsigned the app + +To install the app, you'll need to use the following powershell command: + +```pwsh +Add-AppPackage -Path ".\MyApp.appx" -AllowUnsigned +``` + +For more information, see the [official documentation](https://learn.microsoft.com/en-us/windows/msix/package/unsigned-package#install-an-unsigned-package). + +### Side loading (with signing) + +#### Package signed the app + +This guide uses a self-signed certificate. + +To package your app: + +- Create a self-signed certificate: + - Open the solution in Visual Studio 2022 + - Double click on the `Package.appxmanifest` file + - Navigate to the `Packaging` tab + - Click the **Create** button, then set a **publisher common name**, then OK. Do not se password. + - Close the **Choose a Certificate** window by clicking OK. + - Click the **Save file** button in the Visual Studio toolbar +- Build the app on the command line in the folder of the app's `.csproj`, use the following command: + + ```cmd + msbuild /r /p:TargetFramework=net8.0-windows10.0.19041 /p:Configuration=Release /p:Platform=x64 /p:GenerateAppxPackageOnBuild=true /p:AppxBundlePlatforms="x86|x64|arm64" /p:AppxBundle=Never /p:UapAppxPackageBuildMode=Sideloading /p:AppxPackageDir="C:\temp\output\\" /p:AppxPackageSigningEnabled=true + ``` + +In order to build for additional platforms, change the `Platform` parameter to `x86` or `arm64` to create additional MSIX + +#### Install signed the app + +To install the app: + +- Install the certificate on the machine: + - In the file explorer, right click on the `.msix` file, then **Show More Options** on Windows 11, then **Properties** + - Open the **Digital signatures** tab + - Click on your certificate then **Details** + - Click the **View Certificate** button + - Click the **Install Certificate** button + - Select **Local Machine** then **Next** + - Click **Place all certificates in the following store** then **Browse** + - Select **Trusted People** then **OK** + - Click **Next**, then **Finish** + - Close all the opened properties windows. +- Install the `.msix` by double clicking on it + +The app will start automatically once installed. + +### Build your app for the Store + +_To be documented._ + +## Publish your app to the store + +_To be documented._ From 92a208e087f82686c2a3b157ba68693813c933d6 Mon Sep 17 00:00:00 2001 From: Jerome Laban Date: Fri, 10 May 2024 11:40:05 -0400 Subject: [PATCH 02/15] docs: Adjust for elevated promt --- doc/articles/uno-publishing-windows.md | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/doc/articles/uno-publishing-windows.md b/doc/articles/uno-publishing-windows.md index 80af62c1597b..f1f519bf8020 100644 --- a/doc/articles/uno-publishing-windows.md +++ b/doc/articles/uno-publishing-windows.md @@ -37,11 +37,14 @@ To package your app: #### Install unsigned the app -To install the app, you'll need to use the following powershell command: +To install the app: + +- Start an elevated powershell command prompt (Search for powershell in the start menu, right click on it then Run as administrator): +- In the folder contaning the `.msix` file, execute the following command : -```pwsh -Add-AppPackage -Path ".\MyApp.appx" -AllowUnsigned -``` + ```pwsh + Add-AppPackage -AllowUnsigned ".\MyApp.appx" + ``` For more information, see the [official documentation](https://learn.microsoft.com/en-us/windows/msix/package/unsigned-package#install-an-unsigned-package). From 584a5415f26778833a7a33d9b75a80e844d605d1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Laban?= Date: Fri, 10 May 2024 12:59:14 -0400 Subject: [PATCH 03/15] docs: Apply suggestions from code review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Agnès ZITTE <16295702+agneszitte@users.noreply.github.com> --- doc/articles/toc.yml | 2 +- doc/articles/uno-publishing-windows.md | 18 +++++++++--------- 2 files changed, 10 insertions(+), 10 deletions(-) diff --git a/doc/articles/toc.yml b/doc/articles/toc.yml index 53cd661564fb..6f0b7f049fe6 100644 --- a/doc/articles/toc.yml +++ b/doc/articles/toc.yml @@ -236,7 +236,7 @@ - name: Overview href: xref:uno.publishing.overview - name: Publishing for Windows - href: xref:uno.publishing.windows + href: xref:uno.publishing.windows - name: Performance items: diff --git a/doc/articles/uno-publishing-windows.md b/doc/articles/uno-publishing-windows.md index f1f519bf8020..d06f1002042c 100644 --- a/doc/articles/uno-publishing-windows.md +++ b/doc/articles/uno-publishing-windows.md @@ -8,7 +8,7 @@ uid: uno.publishing.windows ## Building your app -Building your app require using the msbuild command (`dotnet build` is not compatible as of WinAppSDK 1.5). +Building your app requires using the msbuild command (`dotnet build` is not compatible as of WinAppSDK 1.5). ### Side loading (without signing) @@ -39,8 +39,8 @@ To package your app: To install the app: -- Start an elevated powershell command prompt (Search for powershell in the start menu, right click on it then Run as administrator): -- In the folder contaning the `.msix` file, execute the following command : +- Start an elevated PowerShell command prompt (Search for PowerShell in the start menu, right-click on it then Run as administrator): +- In the folder containing the `.msix` file, execute the following command : ```pwsh Add-AppPackage -AllowUnsigned ".\MyApp.appx" @@ -58,15 +58,15 @@ To package your app: - Create a self-signed certificate: - Open the solution in Visual Studio 2022 - - Double click on the `Package.appxmanifest` file + - Double-click on the `Package.appxmanifest` file - Navigate to the `Packaging` tab - - Click the **Create** button, then set a **publisher common name**, then OK. Do not se password. + - Click the **Create** button, then set a **publisher common name**, then OK. Do not set a password. - Close the **Choose a Certificate** window by clicking OK. - Click the **Save file** button in the Visual Studio toolbar - Build the app on the command line in the folder of the app's `.csproj`, use the following command: - ```cmd - msbuild /r /p:TargetFramework=net8.0-windows10.0.19041 /p:Configuration=Release /p:Platform=x64 /p:GenerateAppxPackageOnBuild=true /p:AppxBundlePlatforms="x86|x64|arm64" /p:AppxBundle=Never /p:UapAppxPackageBuildMode=Sideloading /p:AppxPackageDir="C:\temp\output\\" /p:AppxPackageSigningEnabled=true +```cmd +msbuild /r /p:TargetFramework=net8.0-windows10.0.19041 /p:Configuration=Release /p:Platform=x64 /p:GenerateAppxPackageOnBuild=true /p:AppxBundlePlatforms="x86|x64|arm64" /p:AppxBundle=Never /p:UapAppxPackageBuildMode=Sideloading /p:AppxPackageDir="C:\temp\output\\" /p:AppxPackageSigningEnabled=true ``` In order to build for additional platforms, change the `Platform` parameter to `x86` or `arm64` to create additional MSIX @@ -76,7 +76,7 @@ In order to build for additional platforms, change the `Platform` parameter to ` To install the app: - Install the certificate on the machine: - - In the file explorer, right click on the `.msix` file, then **Show More Options** on Windows 11, then **Properties** + - In the file explorer, right-click on the `.msix` file, then **Show More Options** on Windows 11, then **Properties** - Open the **Digital signatures** tab - Click on your certificate then **Details** - Click the **View Certificate** button @@ -86,7 +86,7 @@ To install the app: - Select **Trusted People** then **OK** - Click **Next**, then **Finish** - Close all the opened properties windows. -- Install the `.msix` by double clicking on it +- Install the `.msix` by double-clicking on it The app will start automatically once installed. From efc70aa00441461a37010127f4e7b9eea70e3912 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Laban?= Date: Fri, 10 May 2024 13:01:19 -0400 Subject: [PATCH 04/15] docs: Adjust wording, alignment --- doc/articles/uno-publishing-windows.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/doc/articles/uno-publishing-windows.md b/doc/articles/uno-publishing-windows.md index d06f1002042c..12b028bd34a5 100644 --- a/doc/articles/uno-publishing-windows.md +++ b/doc/articles/uno-publishing-windows.md @@ -60,14 +60,15 @@ To package your app: - Open the solution in Visual Studio 2022 - Double-click on the `Package.appxmanifest` file - Navigate to the `Packaging` tab + - Click the **Choose certificate** button - Click the **Create** button, then set a **publisher common name**, then OK. Do not set a password. - Close the **Choose a Certificate** window by clicking OK. - Click the **Save file** button in the Visual Studio toolbar - Build the app on the command line in the folder of the app's `.csproj`, use the following command: -```cmd -msbuild /r /p:TargetFramework=net8.0-windows10.0.19041 /p:Configuration=Release /p:Platform=x64 /p:GenerateAppxPackageOnBuild=true /p:AppxBundlePlatforms="x86|x64|arm64" /p:AppxBundle=Never /p:UapAppxPackageBuildMode=Sideloading /p:AppxPackageDir="C:\temp\output\\" /p:AppxPackageSigningEnabled=true - ``` + ```cmd + msbuild /r /p:TargetFramework=net8.0-windows10.0.19041 /p:Configuration=Release /p:Platform=x64 /p:GenerateAppxPackageOnBuild=true /p:AppxBundlePlatforms="x86|x64|arm64" /p:AppxBundle=Never /p:UapAppxPackageBuildMode=Sideloading /p:AppxPackageDir="C:\temp\output\\" /p:AppxPackageSigningEnabled=true + ``` In order to build for additional platforms, change the `Platform` parameter to `x86` or `arm64` to create additional MSIX From aac91e815fd6f89b0cee026628a235d4ab0a9e99 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Laban?= Date: Fri, 10 May 2024 13:41:55 -0400 Subject: [PATCH 05/15] chore: Adjust msix spelling --- build/cSpell.json | 1 + 1 file changed, 1 insertion(+) diff --git a/build/cSpell.json b/build/cSpell.json index bbd1af5e256a..9bea0eca827f 100644 --- a/build/cSpell.json +++ b/build/cSpell.json @@ -62,6 +62,7 @@ "msbuild", "MVUX", "MVVM", + "MSIX", "NETSDK", "netstandard", "neumorphic", From 7055b510bfee4f370d5a7b2d525e0b6f6366fea6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Laban?= Date: Sun, 12 May 2024 22:47:43 -0400 Subject: [PATCH 06/15] chore: Adjust path --- doc/articles/uno-publishing-windows.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/articles/uno-publishing-windows.md b/doc/articles/uno-publishing-windows.md index 12b028bd34a5..86607cd553ee 100644 --- a/doc/articles/uno-publishing-windows.md +++ b/doc/articles/uno-publishing-windows.md @@ -67,7 +67,7 @@ To package your app: - Build the app on the command line in the folder of the app's `.csproj`, use the following command: ```cmd - msbuild /r /p:TargetFramework=net8.0-windows10.0.19041 /p:Configuration=Release /p:Platform=x64 /p:GenerateAppxPackageOnBuild=true /p:AppxBundlePlatforms="x86|x64|arm64" /p:AppxBundle=Never /p:UapAppxPackageBuildMode=Sideloading /p:AppxPackageDir="C:\temp\output\\" /p:AppxPackageSigningEnabled=true + msbuild /r /p:TargetFramework=net8.0-windows10.0.19041 /p:Configuration=Release /p:Platform=x64 /p:GenerateAppxPackageOnBuild=true /p:AppxBundlePlatforms="x86|x64|arm64" /p:AppxBundle=Never /p:UapAppxPackageBuildMode=Sideloading /p:AppxPackageDir="C:/temp/output/" /p:AppxPackageSigningEnabled=true ``` In order to build for additional platforms, change the `Platform` parameter to `x86` or `arm64` to create additional MSIX From 7ae559b2cb0cf635a7fde81015c98bbee727c088 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Laban?= Date: Tue, 14 May 2024 10:51:33 -0400 Subject: [PATCH 07/15] chore: Adjust build steps --- doc/articles/uno-publishing-windows.md | 31 ++++++++++++++++++++++---- 1 file changed, 27 insertions(+), 4 deletions(-) diff --git a/doc/articles/uno-publishing-windows.md b/doc/articles/uno-publishing-windows.md index 86607cd553ee..29ea90e024b7 100644 --- a/doc/articles/uno-publishing-windows.md +++ b/doc/articles/uno-publishing-windows.md @@ -32,8 +32,18 @@ To package your app: msbuild /r /p:TargetFramework=net8.0-windows10.0.19041 /p:Configuration=Release /p:Platform=x64 /p:GenerateAppxPackageOnBuild=true /p:AppxBundle=Never /p:UapAppxPackageBuildMode=Sideloading /p:AppxPackageDir="C:/temp/output/" /p:AppxPackageSigningEnabled=false ``` +In order to build for additional platforms, change the `Platform` parameter to `x86` or `arm64` to create additional MSIX files. + > [!IMPORTANT] -> Single package msix bundling is [not yet supported from msbuild the command line](https://learn.microsoft.com/en-us/windows/apps/windows-app-sdk/single-project-msix?tabs=csharp#automate-building-and-packaging-your-single-project-msix-app). +> IF your solution contains `net8.0` projects, you will need to split the above build command in two, one to restore NuGet packages, the other one to create the package. +> +> First run this command: +> +> ```pwsh +> msbuild /r /t:Restore /p:Configuration=Release +> ``` +> +> Then run the package creation command without the `/r` parameter. #### Install unsigned the app @@ -67,10 +77,23 @@ To package your app: - Build the app on the command line in the folder of the app's `.csproj`, use the following command: ```cmd - msbuild /r /p:TargetFramework=net8.0-windows10.0.19041 /p:Configuration=Release /p:Platform=x64 /p:GenerateAppxPackageOnBuild=true /p:AppxBundlePlatforms="x86|x64|arm64" /p:AppxBundle=Never /p:UapAppxPackageBuildMode=Sideloading /p:AppxPackageDir="C:/temp/output/" /p:AppxPackageSigningEnabled=true - ``` + msbuild /r /p:TargetFramework=net8.0-windows10.0.19041 /p:Configuration=Release /p:Platform=x64 /p:GenerateAppxPackageOnBuild=true /p:AppxBundle=Never /p:UapAppxPackageBuildMode=Sideloading /p:AppxPackageDir="C:/temp/output/" /p:AppxPackageSigningEnabled=true -In order to build for additional platforms, change the `Platform` parameter to `x86` or `arm64` to create additional MSIX +> [!IMPORTANT] +> IF your solution contains `net8.0` projects, you will need to split the above build command in two, one to restore NuGet packages, the other one to create the package. +> +> First run this command: +> +> ```pwsh +> msbuild /r /t:Restore /p:Configuration=Release +> ``` +> +> Then run the package creation command without the `/r` parameter. + +In order to build for additional platforms, change the `Platform` parameter to `x86` or `arm64` to create additional MSIX files. + +> [!IMPORTANT] +> Single package msix bundling is [not yet supported from msbuild the command line](https://learn.microsoft.com/en-us/windows/apps/windows-app-sdk/single-project-msix?tabs=csharp#automate-building-and-packaging-your-single-project-msix-app). #### Install signed the app From 9ed5e30a28aa90e6b5ff53246aa6640de053bd3b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Laban?= Date: Tue, 14 May 2024 15:50:12 -0400 Subject: [PATCH 08/15] docs: Apply suggestions from code review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Agnès ZITTE <16295702+agneszitte@users.noreply.github.com> --- doc/articles/uno-publishing-windows.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/doc/articles/uno-publishing-windows.md b/doc/articles/uno-publishing-windows.md index 29ea90e024b7..4c5350e8a2cd 100644 --- a/doc/articles/uno-publishing-windows.md +++ b/doc/articles/uno-publishing-windows.md @@ -35,7 +35,7 @@ To package your app: In order to build for additional platforms, change the `Platform` parameter to `x86` or `arm64` to create additional MSIX files. > [!IMPORTANT] -> IF your solution contains `net8.0` projects, you will need to split the above build command in two, one to restore NuGet packages, the other one to create the package. +> IF your solution contains `net8.0` projects, you will need to split the above build command in two, one to restore NuGet packages, and the other one to create the package. > > First run this command: > @@ -45,7 +45,7 @@ In order to build for additional platforms, change the `Platform` parameter to ` > > Then run the package creation command without the `/r` parameter. -#### Install unsigned the app +#### Install the unsigned app To install the app: @@ -80,7 +80,7 @@ To package your app: msbuild /r /p:TargetFramework=net8.0-windows10.0.19041 /p:Configuration=Release /p:Platform=x64 /p:GenerateAppxPackageOnBuild=true /p:AppxBundle=Never /p:UapAppxPackageBuildMode=Sideloading /p:AppxPackageDir="C:/temp/output/" /p:AppxPackageSigningEnabled=true > [!IMPORTANT] -> IF your solution contains `net8.0` projects, you will need to split the above build command in two, one to restore NuGet packages, the other one to create the package. +> IF your solution contains `net8.0` projects, you will need to split the above build command in two, one to restore NuGet packages, and the other one to create the package. > > First run this command: > @@ -95,7 +95,7 @@ In order to build for additional platforms, change the `Platform` parameter to ` > [!IMPORTANT] > Single package msix bundling is [not yet supported from msbuild the command line](https://learn.microsoft.com/en-us/windows/apps/windows-app-sdk/single-project-msix?tabs=csharp#automate-building-and-packaging-your-single-project-msix-app). -#### Install signed the app +#### Install the signed app To install the app: From 1808e8b0f0da88e5ee91f62bce43e91f2dcbadd0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Laban?= Date: Tue, 14 May 2024 15:53:29 -0400 Subject: [PATCH 09/15] docs: Adjust signed procedure for workaround --- doc/articles/uno-publishing-windows.md | 1 + 1 file changed, 1 insertion(+) diff --git a/doc/articles/uno-publishing-windows.md b/doc/articles/uno-publishing-windows.md index 4c5350e8a2cd..007a35765130 100644 --- a/doc/articles/uno-publishing-windows.md +++ b/doc/articles/uno-publishing-windows.md @@ -68,6 +68,7 @@ To package your app: - Create a self-signed certificate: - Open the solution in Visual Studio 2022 + - Ensure that the active debugging target framework is `net8.0-windows10.xxx` (Please upvote [this Visual Studio issue](https://developercommunity.visualstudio.com/t/Double-clicking-on-a-PackageAppxmanifes/10658683)) - Double-click on the `Package.appxmanifest` file - Navigate to the `Packaging` tab - Click the **Choose certificate** button From 1c04f79825eb6d72295ab84cb7864104f81f2928 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Laban?= Date: Tue, 14 May 2024 20:56:31 -0400 Subject: [PATCH 10/15] chore: Adjust spelling --- build/cSpell.json | 2 ++ 1 file changed, 2 insertions(+) diff --git a/build/cSpell.json b/build/cSpell.json index 9bea0eca827f..213c37c88033 100644 --- a/build/cSpell.json +++ b/build/cSpell.json @@ -152,8 +152,10 @@ "odel", "pdate", "progressring", + "pwsh", "Ronica", "Serilog", + "Sideloading", "Singh", "slnf", "startscreen", From 821bf7664e84ed4f79f54d3f71e484001107ef52 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Laban?= Date: Wed, 15 May 2024 09:51:16 -0400 Subject: [PATCH 11/15] docs: Adjust casing --- doc/articles/uno-publishing-windows.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/articles/uno-publishing-windows.md b/doc/articles/uno-publishing-windows.md index 007a35765130..2307f69d94e6 100644 --- a/doc/articles/uno-publishing-windows.md +++ b/doc/articles/uno-publishing-windows.md @@ -35,7 +35,7 @@ To package your app: In order to build for additional platforms, change the `Platform` parameter to `x86` or `arm64` to create additional MSIX files. > [!IMPORTANT] -> IF your solution contains `net8.0` projects, you will need to split the above build command in two, one to restore NuGet packages, and the other one to create the package. +> If your solution contains `net8.0` projects, you will need to split the above build command in two, one to restore NuGet packages, and the other one to create the package. > > First run this command: > @@ -81,7 +81,7 @@ To package your app: msbuild /r /p:TargetFramework=net8.0-windows10.0.19041 /p:Configuration=Release /p:Platform=x64 /p:GenerateAppxPackageOnBuild=true /p:AppxBundle=Never /p:UapAppxPackageBuildMode=Sideloading /p:AppxPackageDir="C:/temp/output/" /p:AppxPackageSigningEnabled=true > [!IMPORTANT] -> IF your solution contains `net8.0` projects, you will need to split the above build command in two, one to restore NuGet packages, and the other one to create the package. +> If your solution contains `net8.0` projects, you will need to split the above build command in two, one to restore NuGet packages, and the other one to create the package. > > First run this command: > From de8e9c4f1d6882cc1f00d57fb19cc97796631365 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Laban?= Date: Wed, 15 May 2024 12:07:23 -0400 Subject: [PATCH 12/15] chore: Update source folder --- doc/articles/uno-publishing-windows.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/doc/articles/uno-publishing-windows.md b/doc/articles/uno-publishing-windows.md index 2307f69d94e6..868783b54df6 100644 --- a/doc/articles/uno-publishing-windows.md +++ b/doc/articles/uno-publishing-windows.md @@ -26,7 +26,8 @@ To package your app: Version="1.0.0.0" /> ``` -- Build your app in the folder of the app's `.csproj` by using the following command: +- Navigate to the folder of the app's `.csproj` (Building at the solution level is not supported) +- Build your app using the following command: ```pwsh msbuild /r /p:TargetFramework=net8.0-windows10.0.19041 /p:Configuration=Release /p:Platform=x64 /p:GenerateAppxPackageOnBuild=true /p:AppxBundle=Never /p:UapAppxPackageBuildMode=Sideloading /p:AppxPackageDir="C:/temp/output/" /p:AppxPackageSigningEnabled=false @@ -75,7 +76,8 @@ To package your app: - Click the **Create** button, then set a **publisher common name**, then OK. Do not set a password. - Close the **Choose a Certificate** window by clicking OK. - Click the **Save file** button in the Visual Studio toolbar -- Build the app on the command line in the folder of the app's `.csproj`, use the following command: +- Navigate to the folder of the app's `.csproj` (Building at the solution level is not supported) +- Build the app on the command line with the following command: ```cmd msbuild /r /p:TargetFramework=net8.0-windows10.0.19041 /p:Configuration=Release /p:Platform=x64 /p:GenerateAppxPackageOnBuild=true /p:AppxBundle=Never /p:UapAppxPackageBuildMode=Sideloading /p:AppxPackageDir="C:/temp/output/" /p:AppxPackageSigningEnabled=true From 0de9a627c3b41cdbb3774aa159dd41cfb187fc1e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Laban?= Date: Wed, 15 May 2024 16:05:16 -0400 Subject: [PATCH 13/15] chore: Adjust for multi-project, reflow docs --- doc/articles/toc.yml | 7 +- .../uno-publishing-windows-packaged-signed.md | 87 +++++++++++++ ...no-publishing-windows-packaged-unsigned.md | 77 ++++++++++++ doc/articles/uno-publishing-windows.md | 117 +----------------- 4 files changed, 173 insertions(+), 115 deletions(-) create mode 100644 doc/articles/uno-publishing-windows-packaged-signed.md create mode 100644 doc/articles/uno-publishing-windows-packaged-unsigned.md diff --git a/doc/articles/toc.yml b/doc/articles/toc.yml index 6f0b7f049fe6..f9cc730889d7 100644 --- a/doc/articles/toc.yml +++ b/doc/articles/toc.yml @@ -236,7 +236,12 @@ - name: Overview href: xref:uno.publishing.overview - name: Publishing for Windows - href: xref:uno.publishing.windows + topicHref: xref:uno.publishing.windows + items: + - name: Build Packaged Unsigned Apps + href: xref:uno.publishing.windows.sideload.packaged.unsigned + - name: Build Packaged Signed Apps + href: xref:uno.publishing.windows.sideload.packaged.signed - name: Performance items: diff --git a/doc/articles/uno-publishing-windows-packaged-signed.md b/doc/articles/uno-publishing-windows-packaged-signed.md new file mode 100644 index 000000000000..5227d55da429 --- /dev/null +++ b/doc/articles/uno-publishing-windows-packaged-signed.md @@ -0,0 +1,87 @@ +--- +uid: uno.publishing.windows.sideload.packaged.signed +--- + +# Build a signed packaged app + +This guide will show how to create an signed packaged app using Windows App SDK. + +> [!IMPORTANT] +> Building your app requires using the msbuild command (`dotnet build` is not compatible as of WinAppSDK 1.5). + +## Package signed the app + +This guide uses a self-signed certificate. + +To package your app: + +- Create a self-signed certificate: + - Open the solution in Visual Studio 2022 + - Ensure that the active debugging target framework is `net8.0-windows10.xxx` (Please upvote [this Visual Studio issue](https://developercommunity.visualstudio.com/t/Double-clicking-on-a-PackageAppxmanifes/10658683)) + - Double-click on the `Package.appxmanifest` file + - Navigate to the `Packaging` tab + - Click the **Choose certificate** button + - Click the **Create** button, then set a **publisher common name**, then OK. Do not set a password. + - Close the **Choose a Certificate** window by clicking OK. + - Click the **Save file** button in the Visual Studio toolbar +- Navigate to the folder of the app's `.csproj` (Building at the solution level is not supported) +- Build the app on the command line with the following command: + + ```shell + msbuild /r /p:TargetFramework=net8.0-windows10.0.19041 /p:Configuration=Release /p:Platform=x64 /p:GenerateAppxPackageOnBuild=true /p:AppxBundle=Never /p:UapAppxPackageBuildMode=Sideloading /p:AppxPackageDir="C:/temp/output/" /p:AppxPackageSigningEnabled=true + ``` + +In order to build for additional platforms, change the `Platform` parameter to `x86` or `arm64` to create additional MSIX files. + +> [!IMPORTANT] +> Single package msix bundling is [not yet supported from msbuild the command line](https://learn.microsoft.com/en-us/windows/apps/windows-app-sdk/single-project-msix?tabs=csharp#automate-building-and-packaging-your-single-project-msix-app). + +## Considerations for solutions with class library projects + +If your app references multiple library projects projects, you will need to split the above build command in two parts, one to restore NuGet packages, and the other one to create the package. + +To build your solution: + +- Add the following to your app's csproj: + + ```xml + + true + Never + Sideloading + true + + ``` + +- Run this command to restore the nuget packages: + + ```shell + msbuild /r /t:Restore /p:Configuration=Release + ``` + +- Then run this command: + + ```shell + msbuild /p:TargetFramework=net8.0-windows10.0.19041 /p:Configuration=Release /p:Platform=x64 /p:PublishSignedPackage=true /p:AppxPackageDir="C:/temp/output/" + ``` + + Notice that this command does not contain the `/r`. + +## Install the signed app + +To install the app: + +- Install the certificate on the machine: + - In the file explorer, right-click on the `.msix` file, then **Show More Options** on Windows 11, then **Properties** + - Open the **Digital signatures** tab + - Click on your certificate then **Details** + - Click the **View Certificate** button + - Click the **Install Certificate** button + - Select **Local Machine** then **Next** + - Click **Place all certificates in the following store** then **Browse** + - Select **Trusted People** then **OK** + - Click **Next**, then **Finish** + - Close all the opened properties windows. +- Install the `.msix` by double-clicking on it + +The app will start automatically once installed. diff --git a/doc/articles/uno-publishing-windows-packaged-unsigned.md b/doc/articles/uno-publishing-windows-packaged-unsigned.md new file mode 100644 index 000000000000..9364c782d7e9 --- /dev/null +++ b/doc/articles/uno-publishing-windows-packaged-unsigned.md @@ -0,0 +1,77 @@ +--- +uid: uno.publishing.windows.sideload.packaged.unsigned +--- + +# Build an unsigned packaged app + +This guide will show how to create an unsigned packaged app using Windows App SDK. + +> [!IMPORTANT] +> Building your app requires using the msbuild command (`dotnet build` is not compatible as of WinAppSDK 1.5). + +## Package the unsigned app + +Packaging the app without a code signature allows for installing the app on a machine without having to install the signer's certificate. This portion of the guide is derived from the [official Windows App SDK documentation](https://learn.microsoft.com/en-us/windows/msix/package/unsigned-package). + +To package your app: + +- Update the `Package.appxmanifest` file with the following `Identity` node to include the following `OID`: + + ```xml + + ``` + +- Navigate to the folder of the app's `.csproj` (Building at the solution level is not supported) +- Build your app using the following command: + + ```pwsh + msbuild /r /p:TargetFramework=net8.0-windows10.0.19041 /p:Configuration=Release /p:Platform=x64 /p:GenerateAppxPackageOnBuild=true /p:AppxBundle=Never /p:UapAppxPackageBuildMode=Sideloading /p:AppxPackageDir="C:/temp/output/" /p:AppxPackageSigningEnabled=false + ``` + +In order to build for additional platforms, change the `Platform` parameter to `x86` or `arm64` to create additional MSIX files. + +## Considerations for solutions with class library projects + +If your app references multiple library projects projects, you will need to split the above build command in two parts, one to restore NuGet packages, and the other one to create the package. + +To build your solution: + +- Add the following to your app's csproj: + + ```xml + + true + Never + Sideloading + false + + ``` + +- Run this command to restore the nuget packages: + + ```pwsh + msbuild /r /t:Restore /p:Configuration=Release + ``` + +- Then run this command: + + ```pwsh + msbuild /p:TargetFramework=net8.0-windows10.0.19041 /p:Configuration=Release /p:Platform=x64 /p:PublishUnsignedPackage=true /p:AppxPackageDir="C:/temp/output/" + ``` + + Notice that this command does not contain the `/r`. + +## Install the unsigned app + +To install the app: + +- Start an elevated PowerShell command prompt (Search for PowerShell in the start menu, right-click on it then Run as administrator): +- In the folder containing the `.msix` file, execute the following command : + + ```pwsh + Add-AppPackage -AllowUnsigned ".\MyApp.appx" + ``` + +For more information, see the [official documentation](https://learn.microsoft.com/en-us/windows/msix/package/unsigned-package#install-an-unsigned-package). diff --git a/doc/articles/uno-publishing-windows.md b/doc/articles/uno-publishing-windows.md index 868783b54df6..4b235be139a9 100644 --- a/doc/articles/uno-publishing-windows.md +++ b/doc/articles/uno-publishing-windows.md @@ -8,119 +8,8 @@ uid: uno.publishing.windows ## Building your app -Building your app requires using the msbuild command (`dotnet build` is not compatible as of WinAppSDK 1.5). +Using the Windows App SDK, it's possible to side-load an app using the following: -### Side loading (without signing) +- [Build an unsigned packaged app](xref:uno.publishing.windows.sideload.packaged.unsigned) +- [Build a signed packaged app](xref:uno.publishing.windows.sideload.packaged.signed) -#### Package the unsigned app - -Packaging the app without a code signature allows for installing the app on a machine without having to install the signer's certificate. This portion of the guide is derived from the [official Windows App SDK documentation](https://learn.microsoft.com/en-us/windows/msix/package/unsigned-package). - -To package your app: - -- Update the `Package.appxmanifest` file with the following `Identity` node to include the following `OID`: - - ```xml - - ``` - -- Navigate to the folder of the app's `.csproj` (Building at the solution level is not supported) -- Build your app using the following command: - - ```pwsh - msbuild /r /p:TargetFramework=net8.0-windows10.0.19041 /p:Configuration=Release /p:Platform=x64 /p:GenerateAppxPackageOnBuild=true /p:AppxBundle=Never /p:UapAppxPackageBuildMode=Sideloading /p:AppxPackageDir="C:/temp/output/" /p:AppxPackageSigningEnabled=false - ``` - -In order to build for additional platforms, change the `Platform` parameter to `x86` or `arm64` to create additional MSIX files. - -> [!IMPORTANT] -> If your solution contains `net8.0` projects, you will need to split the above build command in two, one to restore NuGet packages, and the other one to create the package. -> -> First run this command: -> -> ```pwsh -> msbuild /r /t:Restore /p:Configuration=Release -> ``` -> -> Then run the package creation command without the `/r` parameter. - -#### Install the unsigned app - -To install the app: - -- Start an elevated PowerShell command prompt (Search for PowerShell in the start menu, right-click on it then Run as administrator): -- In the folder containing the `.msix` file, execute the following command : - - ```pwsh - Add-AppPackage -AllowUnsigned ".\MyApp.appx" - ``` - -For more information, see the [official documentation](https://learn.microsoft.com/en-us/windows/msix/package/unsigned-package#install-an-unsigned-package). - -### Side loading (with signing) - -#### Package signed the app - -This guide uses a self-signed certificate. - -To package your app: - -- Create a self-signed certificate: - - Open the solution in Visual Studio 2022 - - Ensure that the active debugging target framework is `net8.0-windows10.xxx` (Please upvote [this Visual Studio issue](https://developercommunity.visualstudio.com/t/Double-clicking-on-a-PackageAppxmanifes/10658683)) - - Double-click on the `Package.appxmanifest` file - - Navigate to the `Packaging` tab - - Click the **Choose certificate** button - - Click the **Create** button, then set a **publisher common name**, then OK. Do not set a password. - - Close the **Choose a Certificate** window by clicking OK. - - Click the **Save file** button in the Visual Studio toolbar -- Navigate to the folder of the app's `.csproj` (Building at the solution level is not supported) -- Build the app on the command line with the following command: - - ```cmd - msbuild /r /p:TargetFramework=net8.0-windows10.0.19041 /p:Configuration=Release /p:Platform=x64 /p:GenerateAppxPackageOnBuild=true /p:AppxBundle=Never /p:UapAppxPackageBuildMode=Sideloading /p:AppxPackageDir="C:/temp/output/" /p:AppxPackageSigningEnabled=true - -> [!IMPORTANT] -> If your solution contains `net8.0` projects, you will need to split the above build command in two, one to restore NuGet packages, and the other one to create the package. -> -> First run this command: -> -> ```pwsh -> msbuild /r /t:Restore /p:Configuration=Release -> ``` -> -> Then run the package creation command without the `/r` parameter. - -In order to build for additional platforms, change the `Platform` parameter to `x86` or `arm64` to create additional MSIX files. - -> [!IMPORTANT] -> Single package msix bundling is [not yet supported from msbuild the command line](https://learn.microsoft.com/en-us/windows/apps/windows-app-sdk/single-project-msix?tabs=csharp#automate-building-and-packaging-your-single-project-msix-app). - -#### Install the signed app - -To install the app: - -- Install the certificate on the machine: - - In the file explorer, right-click on the `.msix` file, then **Show More Options** on Windows 11, then **Properties** - - Open the **Digital signatures** tab - - Click on your certificate then **Details** - - Click the **View Certificate** button - - Click the **Install Certificate** button - - Select **Local Machine** then **Next** - - Click **Place all certificates in the following store** then **Browse** - - Select **Trusted People** then **OK** - - Click **Next**, then **Finish** - - Close all the opened properties windows. -- Install the `.msix` by double-clicking on it - -The app will start automatically once installed. - -### Build your app for the Store - -_To be documented._ - -## Publish your app to the store - -_To be documented._ From 183b6fe55d293629ac62bc7b27664d4874eba171 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Laban?= Date: Thu, 16 May 2024 09:22:39 -0400 Subject: [PATCH 14/15] chore: Update spelling --- build/cSpell.json | 1 + doc/articles/uno-publishing-windows.md | 1 - 2 files changed, 1 insertion(+), 1 deletion(-) diff --git a/build/cSpell.json b/build/cSpell.json index 213c37c88033..cd969053bf2c 100644 --- a/build/cSpell.json +++ b/build/cSpell.json @@ -156,6 +156,7 @@ "Ronica", "Serilog", "Sideloading", + "sideload", "Singh", "slnf", "startscreen", diff --git a/doc/articles/uno-publishing-windows.md b/doc/articles/uno-publishing-windows.md index 4b235be139a9..14a2b88efa11 100644 --- a/doc/articles/uno-publishing-windows.md +++ b/doc/articles/uno-publishing-windows.md @@ -12,4 +12,3 @@ Using the Windows App SDK, it's possible to side-load an app using the following - [Build an unsigned packaged app](xref:uno.publishing.windows.sideload.packaged.unsigned) - [Build a signed packaged app](xref:uno.publishing.windows.sideload.packaged.signed) - From e633306c13ed09d93f3bbea7b89dacaba818e961 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Laban?= Date: Tue, 28 May 2024 08:23:31 -0400 Subject: [PATCH 15/15] docs: Apply suggestions from code review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Agnès ZITTE <16295702+agneszitte@users.noreply.github.com> --- doc/articles/uno-publishing-windows-packaged-signed.md | 6 +++--- doc/articles/uno-publishing-windows-packaged-unsigned.md | 4 ++-- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/doc/articles/uno-publishing-windows-packaged-signed.md b/doc/articles/uno-publishing-windows-packaged-signed.md index 5227d55da429..2f921f2c3c41 100644 --- a/doc/articles/uno-publishing-windows-packaged-signed.md +++ b/doc/articles/uno-publishing-windows-packaged-signed.md @@ -4,7 +4,7 @@ uid: uno.publishing.windows.sideload.packaged.signed # Build a signed packaged app -This guide will show how to create an signed packaged app using Windows App SDK. +This guide will show how to create a signed packaged app using Windows App SDK. > [!IMPORTANT] > Building your app requires using the msbuild command (`dotnet build` is not compatible as of WinAppSDK 1.5). @@ -38,7 +38,7 @@ In order to build for additional platforms, change the `Platform` parameter to ` ## Considerations for solutions with class library projects -If your app references multiple library projects projects, you will need to split the above build command in two parts, one to restore NuGet packages, and the other one to create the package. +If your app references multiple library projects, you will need to split the above build command into two parts, one to restore NuGet packages, and the other one to create the package. To build your solution: @@ -53,7 +53,7 @@ To build your solution: ``` -- Run this command to restore the nuget packages: +- Run this command to restore the NuGet packages: ```shell msbuild /r /t:Restore /p:Configuration=Release diff --git a/doc/articles/uno-publishing-windows-packaged-unsigned.md b/doc/articles/uno-publishing-windows-packaged-unsigned.md index 9364c782d7e9..c5424bc49c7f 100644 --- a/doc/articles/uno-publishing-windows-packaged-unsigned.md +++ b/doc/articles/uno-publishing-windows-packaged-unsigned.md @@ -34,7 +34,7 @@ In order to build for additional platforms, change the `Platform` parameter to ` ## Considerations for solutions with class library projects -If your app references multiple library projects projects, you will need to split the above build command in two parts, one to restore NuGet packages, and the other one to create the package. +If your app references multiple library projects, you will need to split the above build command into two parts, one to restore NuGet packages, and the other one to create the package. To build your solution: @@ -49,7 +49,7 @@ To build your solution: ``` -- Run this command to restore the nuget packages: +- Run this command to restore the NuGet packages: ```pwsh msbuild /r /t:Restore /p:Configuration=Release