Building a WinUI App With the New Windows App Development CLI

The corresponding C# code can handle the interaction:

private void RunButton_Click(
    object sender,
    RoutedEventArgs e)
{
    ContentDialog dialog = new ContentDialog
    {
        Title = "WinUI",
        Content = "The application is running.",
        CloseButtonText = "OK",
        XamlRoot = Content.XamlRoot
    };

    _ = dialog.ShowAsync();
}

The exact startup structure depends on the WinUI application template being used, but the principle remains the same.

XAML describes the UI.

C# implements the behavior.

The CLI provides the repeatable build and development workflow around them.

Use the CLI in a New Developer Setup

This is where command-line tooling becomes particularly useful.

Suppose a team maintains a WinUI application.

Without automation, the setup instructions may look like:

1. Install Visual Studio
2. Select workload A
3. Select component B
4. Install SDK C
5. Install package D
6. Open solution
7. Restore
8. Build

Some of these steps are easy to miss.

A scripted setup can reduce the manual work:

# Verify prerequisites
winapp --help

# Restore the application
dotnet restore

# Build the application
dotnet build -c Debug

The script can also validate versions and fail early when a required component is missing.

This makes onboarding more predictable.

Use the CLI in CI/CD

The strongest reason to use command-line tooling is automation.

A CI pipeline might follow this pattern:

Commit
  ↓
Build agent
  ↓
Install/verify Windows tooling
  ↓
Restore dependencies
  ↓
Build
  ↓
Run tests
  ↓
Package
  ↓
Publish artifact

For example:

$ErrorActionPreference = "Stop"

dotnet restore

dotnet build `
    -c Release `
    --no-restore

The important property is that the build does not depend on someone opening Visual Studio.

A failed build can be reproduced locally using the same commands.

Keep CLI Commands in Source Control

If the application requires specific setup commands, keep them in the repository.

For example:

scripts/
    setup.ps1
    build.ps1
    package.ps1

A build script might contain:

$ErrorActionPreference = "Stop"

dotnet restore

dotnet build `
    -c Release `
    --no-restore

The benefit is not the script itself.

The benefit is that the development process becomes part of the application source code.

When the build process changes, the change can be reviewed alongside the application change.

Build for Different Architectures

Windows applications can target different CPU architectures.

Common targets include:

x86
x64
ARM64

This matters because the application's native dependencies must match the architecture.

For example, a library compiled only for x64 cannot automatically be loaded into an ARM64 process.

A WinUI project may therefore define:

<PropertyGroup>
  <Platforms>x86;x64;ARM64</Platforms>
</PropertyGroup>

You should build and test each architecture you intend to support.

For example:

dotnet build -c Release -p:Platform=x64

The exact platform configuration depends on the project.

Do not advertise ARM64 support simply because the application compiles under one configuration. Test the actual application and its dependencies on the target architecture.

Package the Application

Building and packaging are different operations.

A build creates the application binaries.

Packaging creates the deployable application format required by your distribution strategy.

Conceptually:

Source code
    ↓
Build
    ↓
Application binaries
    ↓
Package
    ↓
Installable artifact

This distinction becomes important in CI.

A successful build does not necessarily mean that the application is ready for deployment.

The packaging stage should validate:

• Application identity

• Package metadata

• Version

• Architecture

• Dependencies

• Signing

• Required runtime

• Deployment configuration

Use MSBuild Where the Project Requires It

The .NET CLI is convenient, but Windows application packaging often relies on MSBuild properties and targets.

For example:

msbuild MyWinUIApp.csproj `
    /p:Configuration=Release

The exact command depends on the project and installed build tools.

The important idea is that Windows application development has multiple command-line layers:

winapp
   ↓
Windows app development tooling

dotnet
   ↓
.NET project/build tooling

msbuild
   ↓
Windows/MSBuild project targets

Windows SDK
   ↓
Platform build tools

A team should decide which tool owns each part of its build pipeline rather than mixing commands randomly.

Manage Configuration Separately From the Build

A common mistake is putting environment-specific settings directly into the application project.

For example:

Development API
Production API
Test API

should not be hard-coded into the source code.

A better approach is to keep configuration separate.

The application can use environment-specific configuration generated during packaging or deployment.

For example:

Build artifact
     ↓
Environment configuration
     ↓
Development deployment

or

Build artifact
     ↓
Environment configuration
     ↓
Production deployment

This is particularly important when the same WinUI application is distributed through multiple environments.

Sign the Application Properly

Windows application deployment may require code signing depending on the distribution method.

Signing allows Windows and users to verify the publisher identity associated with the package.

A production pipeline should treat signing as a controlled release step.

For example:

Build
  ↓
Test
  ↓
Package
  ↓
Sign
  ↓
Verify signature
  ↓
Publish

Do not place signing certificates directly in the source repository.

Use the CI/CD platform's secure secret or certificate storage mechanism.

The build agent should receive only the access required to sign the artifact.

Common Problems

CLI works on one machine but not another

Usually this means the tool versions or PATH configuration differ.

Check the installed SDKs and CLI version before investigating the application itself.

Build works in Visual Studio but fails in CI

The CI machine may be missing a Windows SDK component, workload, package, or MSBuild target.

Run the command-line build locally from a clean environment.

Wrong architecture

A native dependency may support x64 but not ARM64.

Check every native dependency before enabling a new architecture.

Package builds but does not install

Packaging metadata, signing, runtime dependencies, or architecture can cause installation failures.

Separate build validation from package validation.

CLI command has changed

Windows development tooling evolves.

Do not rely on a command copied from an older article without checking the help output of the installed version.

Hard-coded environment settings

A development API URL can accidentally end up in a production package.

Keep environment-specific configuration outside the shared application source where appropriate.

A Practical Project Workflow

For a small WinUI application, a practical workflow can look like this:

Create project
      ↓
Configure Windows App SDK
      ↓
Write XAML/C#
      ↓
dotnet restore
      ↓
dotnet build
      ↓
Run locally
      ↓
Run tests
      ↓
Package
      ↓
Sign
      ↓
Publish

For a team, turn this into scripts.

For example:

$ErrorActionPreference = "Stop"

Write-Host "Restoring..."
dotnet restore

Write-Host "Building..."
dotnet build -c Release --no-restore

Write-Host "Build complete."

As the application grows, the script can add tests, packaging, signing, artifact validation, and publishing.

When the CLI Is a Good Fit

The Windows App CLI is particularly useful when:

• Multiple developers need the same setup

• The application has a CI pipeline

• Builds must be reproducible

• Windows application tasks need automation

• Teams want fewer manual setup steps

• Packaging is part of an automated release

• Development environments are frequently recreated

• Build operations need to run without an IDE

Visual Studio remains useful for interactive development.

The CLI becomes more valuable around the development lifecycle.

Advantages and Disadvantages

The command-line approach has several advantages:

• Repeatable development workflow

• Easier CI/CD integration

• Scriptable setup

• Easier environment validation

• Less dependence on manual IDE operations

• Build commands can be stored with the source code

• Easier reproduction of build failures

There are also limitations:

• Windows application tooling can involve several command-line tools

• Some operations are still easier to understand through Visual Studio

• Version mismatches can cause confusing build failures

• Packaging and signing add additional complexity

• Preview tooling can change command behavior

The goal is not to eliminate Visual Studio.

The goal is to make the parts of the workflow that should be repeatable actually repeatable.

Production Checklist

Before adopting a CLI-based WinUI development workflow, verify:

• Windows development prerequisites are documented.

• .NET SDK version is known.

• Windows App SDK version is known.

• CLI version is controlled.

• Required Windows SDK components are installed.

• Project builds without Visual Studio.

• CI can reproduce the local build.

• Restore is deterministic.

• Target architectures are explicitly defined.

• Native dependencies support every target architecture.

• Packaging is tested separately from compilation.

• Signing is handled securely.

• Environment-specific configuration is not hard-coded.

• Build and packaging scripts are stored in source control.

• Developers can reproduce CI failures locally.

• Release artifacts are validated before publishing.

Summary

The Windows App Development CLI is useful when a WinUI application's development process needs to become repeatable and automatable.

WinUI itself still provides the application UI and Windows App SDK functionality, while .NET, MSBuild, Windows SDK tooling, and the Windows App CLI each handle different parts of the development workflow.

The biggest practical benefit is not that developers can avoid Visual Studio. It is that important operations such as environment setup, restore, build, packaging, and release preparation can be expressed as commands and scripts.

For individual development, Visual Studio may remain the most convenient environment. For teams and CI/CD systems, command-line workflows provide a much more predictable foundation.

Start by making the application build successfully from the command line. Then move packaging, testing, signing, and release operations into the same repeatable workflow. This gives the team a clear path from a developer's workstation to an automated Windows application delivery pipeline.