Windows App Development CLI 0.6: Automating WinUI 3 Builds from the Command Line

Building a Windows application usually involves an IDE, project configuration, SDKs, packaging tools, and a set of repeatable build commands. For individual developers, that workflow can be convenient. For CI/CD pipelines, however, reproducibility and command-line automation become much more important.

The Windows App Development CLI provides command-line tooling for Windows application development tasks. With the 0.6 release, developers can use the CLI as part of automated workflows for building and packaging Windows applications, including WinUI 3 projects.

For teams working with .NET and WinUI 3, command-line tooling can make local builds and CI pipelines easier to standardize. The key is to separate application compilation, packaging, signing, and deployment into explicit steps that can be automated and diagnosed independently.

What Is Windows App Development CLI?

The Windows App Development CLI is a command-line tool designed to simplify common Windows application development workflows.

Instead of relying exclusively on IDE actions, developers can use commands from a terminal or CI runner.

A simplified workflow looks like this:

Source Code
    |
    v
Windows App Development CLI
    |
    +--> Build
    +--> Package
    +--> Sign
    +--> Deploy

This is useful for teams because command-line operations can be versioned in scripts and executed consistently across developer machines and build agents.

The exact commands and capabilities should be verified against the Windows App Development CLI version installed in the environment because the CLI is evolving.

Why Command-Line Automation Matters

A WinUI 3 application can contain several moving parts:

WinUI 3 UI
   |
   +-- .NET
   +-- Windows App SDK
   +-- Project configuration
   +-- Assets
   +-- Package configuration
   +-- Signing configuration

Manually performing these steps can introduce differences between developers.

A CI pipeline should instead provide a repeatable process:

Checkout
   ↓
Restore
   ↓
Build
   ↓
Package
   ↓
Validate
   ↓
Publish Artifact

The command-line workflow becomes the source of truth for the automated build.

A Typical WinUI 3 Project

A simplified project structure might look like:

MyWinUIApp/
    |
    +-- App.xaml
    +-- MainWindow.xaml
    +-- MainWindow.xaml.cs
    +-- MyWinUIApp.csproj
    +-- Package.appxmanifest

A typical .NET project references the required Windows application framework packages and build configuration.

For example:

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <OutputType>WinExe</OutputType>
    <TargetFramework>net8.0-windows10.0.19041.0</TargetFramework>
    <TargetPlatformMinVersion>10.0.17763.0</TargetPlatformMinVersion>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>
  </PropertyGroup>

</Project>

The exact target framework and Windows App SDK version should match the versions supported by the project.

Build From the Command Line

Before introducing additional packaging automation, make sure the project builds using the .NET CLI.

For example:

dotnet restore

followed by:

dotnet build --configuration Release

This separates application compilation from later packaging operations.

If the build fails, there is little value in debugging packaging configuration at the same time.

A useful CI workflow therefore follows:

Restore
  ↓
Build
  ↓
Package

rather than attempting everything in one opaque command.

Automating the Build With a Script

Teams can place their build steps in a PowerShell script.

For example:

$ErrorActionPreference = "Stop"

dotnet restore

dotnet build `
    --configuration Release `
    --no-restore

The following command:

$ErrorActionPreference = "Stop"

is important because it causes the script to stop when a command produces an error that PowerShell treats as terminating.

Without appropriate error handling, a script can sometimes continue after an unsuccessful step and produce confusing downstream failures.

Building a WinUI Application in CI

A Windows CI runner needs the correct development environment.

At minimum, the build environment should be aligned with the application's:

.NET SDK
Windows SDK
Windows App SDK
Visual Studio Build Tools or required build components
MSBuild tooling
Architecture
Packaging dependencies

A conceptual pipeline is:

Windows Runner
      |
      +--> .NET SDK
      +--> Windows SDK
      +--> Windows App SDK
      +--> Build Tools
      |
      v
WinUI 3 Build

Version mismatches are a common reason why a project succeeds locally but fails on a build agent.

Architecture Matters

Windows applications may target different architectures:

x86
x64
ARM64

The selected architecture must be supported by the application's dependencies and packaging configuration.

For example:

dotnet build `
  --configuration Release `
  --arch x64

The exact command should be aligned with the project's SDK and build configuration.

If a native dependency supports only x64, an ARM64 build will not automatically become compatible simply because the application is written in .NET.

Packaging the Application

A Windows application intended for distribution may need to be packaged.

The packaging process can include:

Application binaries
       +
Dependencies
       +
Manifest
       +
Assets
       ↓
Windows application package

The package configuration defines important application metadata, capabilities, identity, and deployment information.

For example, a package manifest can contain identity information similar to:

<Identity
    Name="Contoso.MyWinUIApp"
    Publisher="CN=Contoso"
    Version="1.0.0.0" />

Production package identity and publisher values must match the actual signing and distribution configuration.

Do not copy example identities into a production application.

Build and Package Are Different Operations

It is useful to keep these concepts separate.

Operation	Purpose
Restore	Download project dependencies
Build	Compile application code
Package	Produce distributable application package
Sign	Establish package authenticity
Publish	Make the artifact available
Deploy	Install or release the application

This separation makes CI failures easier to diagnose.

For example:

Build failed

is an application compilation problem.

Whereas:

Package signing failed

is a packaging or certificate problem.

Automating Package Creation

A build script can provide a clear structure:

$ErrorActionPreference = "Stop"

dotnet restore

dotnet build `
    --configuration Release `
    --no-restore

# Invoke the configured Windows packaging step here.

The packaging command should come from the Windows App SDK / Windows application build configuration used by the project.

This is preferable to embedding environment-specific paths and developer-machine assumptions into the script.

Handling Build Artifacts

A CI pipeline should publish only the artifacts that are required.

For example:

artifacts/
    |
    +-- MyWinUIApp.msix
    +-- checksums.txt

Avoid publishing intermediate build directories unless they are needed for diagnostics.

A clean artifact structure makes release automation easier.

Versioning the Package

Windows package versions need to be managed carefully.

For example:

1.0.0.0
1.0.1.0
1.1.0.0

The version should come from a controlled source rather than being manually changed on individual developer machines.

A CI pipeline can pass a version value into the build process.

For example:

$version = "1.2.0.0"

dotnet build `
    --configuration Release `
    -p:PackageVersion=$version

The exact MSBuild property supported by the packaging project should be confirmed for the application's packaging configuration.

Signing Is a Separate Security Step

A package can be built successfully and still fail during installation or distribution because it is not signed correctly.

The signing process involves a certificate and private key.

Conceptually:

Package
   |
   v
Signing Certificate
   |
   v
Signed Package

The private key should never be committed to the source repository.

In CI/CD, certificates and signing credentials should be stored using the organization's approved secret-management mechanism.

CI Pipeline Example

A simplified GitHub Actions workflow could look like:

name: WinUI Build

on:
  push:
  pull_request:

jobs:
  build:
    runs-on: windows-latest

    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Setup .NET
        uses: actions/setup-dotnet@v4
        with:
          dotnet-version: '8.0.x'

      - name: Restore
        run: dotnet restore

      - name: Build
        run: dotnet build --configuration Release --no-restore

For an actual WinUI 3 project, the runner must also have the Windows SDK, Windows App SDK, and other required build components.

The pipeline should therefore be validated against the application's actual build requirements rather than assuming that a generic Windows runner contains every dependency.

Making Builds Reproducible

A reproducible build should minimize dependencies on a developer's local machine.

Avoid:

C:\Users\Developer\Desktop\Tools\

inside scripts.

Prefer:

Repository
    |
    +-- Configuration
    +-- Build script
    +-- Project
    +-- CI workflow

Environment-specific values should be supplied by the CI system.

This makes it easier to create a new build agent without manually reproducing someone's workstation.

Troubleshooting Build Failures

When a WinUI build fails in CI but succeeds locally, start with the environment.

Check the SDK Versions

Run:

dotnet --info

Compare the local and CI environments.

Check Windows SDK Availability

Verify that the Windows SDK required by the project is installed.

Check Windows App SDK Dependencies

Ensure the build agent has the version required by the project.

Check Architecture

Confirm that the selected architecture matches all native dependencies.

Check Packaging Configuration

If compilation succeeds but packaging fails, inspect the package manifest and packaging project separately.

Check Signing

If the package is generated but cannot be distributed or installed, inspect the certificate, publisher identity, and signing configuration.

Common Mistakes

Building Only on a Developer Machine

A project that works locally is not automatically CI-ready.

Mixing Build and Deployment Logic

Keep compilation, packaging, signing, and deployment as separate pipeline stages.

Hardcoding Paths

Absolute developer-machine paths make CI migration unnecessarily difficult.

Committing Signing Certificates

Private signing material should never be stored directly in source control.

Ignoring Architecture

x64, x86, and ARM64 can have different native dependency requirements.

Using Floating Tool Versions Without Testing

Automatically picking arbitrary SDK versions can introduce unexpected build changes.

Best Practices

Keep the command-line build reproducible.
Pin or centrally manage important SDK versions.
Separate build, package, sign, and deployment stages.
Use Windows CI runners with the required SDK components.
Validate all target architectures independently.
Keep signing credentials outside source control.
Publish only required build artifacts.
Fail the pipeline immediately when a critical build step fails.
Test the exact CI build process locally where practical.
Keep environment-specific configuration outside application source code.

Advantages and Disadvantages

Advantages

Enables repeatable command-line builds.
Works well with CI/CD automation.
Reduces dependence on manual IDE operations.
Makes build steps easier to document and version.
Helps separate compilation, packaging, and signing concerns.
Supports automated artifact generation.

Disadvantages

Windows application builds require a correctly configured Windows environment.
SDK and Windows App SDK compatibility must be maintained.
Packaging adds additional configuration complexity.
Architecture-specific dependencies can complicate builds.
Signing requires secure certificate management.

Conclusion

The Windows App Development CLI can be useful for teams that want to move Windows application development workflows from manual IDE operations toward repeatable command-line automation.

For a .NET WinUI 3 project, the most maintainable approach is to keep the workflow explicit:

Restore
   ↓
Build
   ↓
Package
   ↓
Sign
   ↓
Publish Artifact
   ↓
Deploy

Each stage has a different responsibility and a different failure mode.

The CLI should complement the existing .NET, MSBuild, Windows SDK, and Windows App SDK tooling rather than hide those dependencies. Once the build environment is reproducible and the pipeline clearly separates compilation from packaging and signing, WinUI 3 applications become much easier to build consistently across developer machines and CI/CD environments.