diff --git a/build/cSpell.json b/build/cSpell.json index bbd1af5e256a..cd969053bf2c 100644 --- a/build/cSpell.json +++ b/build/cSpell.json @@ -62,6 +62,7 @@ "msbuild", "MVUX", "MVVM", + "MSIX", "NETSDK", "netstandard", "neumorphic", @@ -151,8 +152,11 @@ "odel", "pdate", "progressring", + "pwsh", "Ronica", "Serilog", + "Sideloading", + "sideload", "Singh", "slnf", "startscreen", diff --git a/doc/articles/toc.yml b/doc/articles/toc.yml index 0a0c0ca4c174..f9cc730889d7 100644 --- a/doc/articles/toc.yml +++ b/doc/articles/toc.yml @@ -231,6 +231,18 @@ 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 + 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: - 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-packaged-signed.md b/doc/articles/uno-publishing-windows-packaged-signed.md new file mode 100644 index 000000000000..2f921f2c3c41 --- /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 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). + +## 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, 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: + +- 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..c5424bc49c7f --- /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, 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: + +- 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 new file mode 100644 index 000000000000..14a2b88efa11 --- /dev/null +++ b/doc/articles/uno-publishing-windows.md @@ -0,0 +1,14 @@ +--- +uid: uno.publishing.windows +--- + +# Publishing Your App for Windows + +## Preparing For Publish + +## Building your app + +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)