WinUI 3 Deployment

This document provides comprehensive guidance on deploying your Windows App SDK (WinUI 3) applications. Learn about the different deployment methods, packaging options, and best practices to ensure a smooth and reliable distribution of your application.

On this page

Introduction

Deploying your WinUI 3 application involves packaging your app and its dependencies in a way that is easily installable and manageable on Windows devices. The Windows App SDK provides flexible deployment options to suit various application scenarios.

Deployment Methods

Packaged Apps

Packaged apps are deployed using the MSIX format. This is the recommended approach for modern Windows applications as it offers features like:

  • Reliable installation and uninstallation.
  • Automatic updates.
  • App isolation for better system stability.
  • Access to Windows features like background tasks and notifications.

When you create a WinUI 3 project in Visual Studio, you can choose to create a packaged app directly.

Unpacked (MSIX) Apps

Unpacked apps, also known as "loose" or "folder" deployments, are typically used for development and testing. While it's possible to deploy applications this way, it's generally not recommended for production releases due to the lack of robust installation and update management features inherent in MSIX.

For more advanced deployment scenarios or specific distribution needs, consider exploring options like traditional Win32 deployment or containerization.

Packaging Options

MSIX Container

MSIX is the modern packaging format for Windows apps. It's built on the best of MSI, AppX, and UWP, and it's designed to address the challenges developers face with app distribution. When you create an MSIX package for your WinUI 3 app, you are leveraging the full power of the Windows Store or direct distribution.

To create an MSIX package, you can use Visual Studio's "Create App Packages" wizard or the msbuild command-line tool with the appropriate project configuration.

Note: Ensure your project is configured for MSIX packaging in the project properties within Visual Studio.

Folder Deployment

Folder deployment is primarily for development and debugging. It allows you to run your application directly from its output folder without creating a formal package. This is useful for quick iteration during the development cycle.

To enable folder deployment, ensure your project's output is set to a deployable location and that all necessary runtime components are present.

Dependencies

Your WinUI 3 application depends on the Windows App SDK runtime. When deploying your application, you need to ensure that the correct version of the Windows App SDK runtime is installed on the target machine. This can be achieved in several ways:

  • Bundling with your app: If you are creating an unpackaged app, you might need to include the runtime redistributables.
  • Framework Package: For MSIX packaged apps, the Windows App SDK runtime is typically deployed as a framework package, which can be pre-installed or downloaded from the Microsoft Store.

Refer to the WinUI 3 Runtime Dependencies documentation for detailed information on managing these dependencies.

Deployment Tools

Several tools and technologies can assist you in deploying your WinUI 3 applications:

  • Visual Studio: Provides built-in tools for creating MSIX packages and deploying applications.
  • MSIX Packaging Tool: A standalone tool for converting existing desktop applications into MSIX packages.
  • Azure DevOps / GitHub Actions: For continuous integration and continuous deployment (CI/CD) pipelines, automating the build and deployment process.
  • Microsoft Store: The primary channel for distributing packaged WinUI 3 applications to a wide audience.

Best Practices

  • Always use MSIX for production releases: Leverage the benefits of robust installation, updates, and uninstallation.
  • Target the correct runtime versions: Ensure your application targets a compatible version of the Windows App SDK.
  • Thoroughly test deployments: Test your application on various Windows versions and configurations before releasing.
  • Manage dependencies carefully: Understand how the Windows App SDK runtime will be delivered to your users.
  • Consider localization: If your app supports multiple languages, ensure your deployment process handles localized resources correctly.
Tip: For enterprise deployments, explore options like provisioning packages or sideloading MSIX apps.