WinUI에서 winapp CLI 사용

이 가이드에서는 WinUI 3 앱의 전체 개발 내부 루프 과정에서 winapp CLI를 사용하는 방법을 보여 줍니다. 공식 템플릿에서 프로젝트를 만들고, 패키지 ID로 빌드 및 시작하고, 크래시를 디버그하고, 컨트롤 및 API를 찾고, UI를 자동화하고, 서명된 MSIX 패키지를 생성합니다. 모든 단계는 명령줄에서 실행되므로 모든 편집기, CI 및 AI 코딩 에이전트에서 작동합니다.

WinUI 프로젝트 템플릿에는 이미 Package.appxmanifest가 포함되어 있으므로 WinUI 앱에 대해 winapp init를 실행할 필요가 없습니다. WinUI를 사용하지 않는 기존 .NET 앱에 패키지 ID를 추가하는 경우 .NET에서 winapp CLI 사용을 대신 참조하세요.

Prerequisites

  • Windows 10 버전 1809 이상 또는 Windows 11.

  • .NET SDK 버전 8.0.100 이상 실험적 Reactor 템플릿에는 .NET 10 SDK가 필요합니다. winapp CLI는 도구 체인을 설치하지 않으므로 .NET SDK가 없으면 winapp new 및 winapp run가 안내와 함께 중지됩니다.

  • winapp CLI:

    winget install Microsoft.winappcli --source winget

  • Windows에서 빌드 출력의 앱을 등록하려면 개발자 모드가 필요합니다. 설정 > 시스템 > 개발자용에서 켜세요. 컴퓨터에서 변경되는 내용은 보안을 참조하세요.

WinUI 앱 만들기

winapp new 공식 Microsoft.WindowsAppSDK.WinUI.CSharp.Templates 팩에서 WinUI 앱을 스캐폴드합니다. 요청 시 템플릿 팩을 설치하거나 업데이트한 다음, dotnet new를 호출합니다.

# Pick a template and a name interactively
winapp new

# Or create a NavigationView app without prompts
winapp new --name MyApp --template winui-navview --use-defaults

winapp new --list을 실행하여 설치된 팩의 템플릿을 확인합니다. 팩에는 다음 템플릿이 포함됩니다.

Template Description
winui 최소 빈 XAML 앱(기본값). 스크린샷 참조
winui-navview NavigationView 셸이 있는 XAML 앱. 스크린샷 참조
winui-tabview TabView 셸이 있는 XAML 앱. 스크린샷을 확인하세요
winui-mvvm CommunityToolkit.Mvvm과 함께 MVVM 패턴을 사용하는 XAML 앱입니다. 스크린샷 참조
winui-lib WinUI 클래스 라이브러리
winui-unittest WinUI 단위 테스트를 위한 패키지된 MSTest 프로젝트
reactor, reactor-mvu, , reactor-navview, reactor-tabview 실험적인. XAML 없이 C#으로만 작성된 WinUI 앱

Note

Reactor 템플릿은 시험판 Microsoft.UI.Reactor 패키지를 참조합니다. 해당 API들은 향후 릴리스에서 변경되거나 제거될 수 있습니다.

모든 옵션에 대해서는 new명령 참조를 참조하세요.

ID를 사용하여 빌드 및 실행

프로젝트 폴더에서 winapp run가 프로젝트를 빌드하고, 해당 아키텍처와 일치하는 Windows 앱 SDK 런타임이 없으면 이를 설치하고, 패키지 ID로 앱을 등록하고, 시작합니다.

cd MyApp
winapp run

winapp run 는 프로젝트 파일, 솔루션 파일, 그 중 하나가 포함된 폴더 또는 빌드 출력 폴더를 허용합니다.

# A specific project and configuration
winapp run .\MyApp.csproj -c Release --arch arm64

# A solution: winapp CLI finds the single app project and skips libraries and tests
winapp run .\MySolution.sln

# A solution with more than one app project
winapp run .\MySolution.sln --project MyApp

# Build output that you produced yourself
winapp run .\bin\x64\Debug\net10.0-windows10.0.26100.0\win-x64

winapp CLI는 프로젝트의 WindowsPackageType 속성을 읽어 이를 실행할 방법을 결정합니다. 패키지된 프로젝트는 패키지 ID를 사용하여 실행됩니다. None를 WindowsPackageType로 설정하는 프로젝트는 ID 없이 패키지되지 않은 앱으로 실행됩니다. 패키지된 프로젝트를 패키지되지 않은 프로젝트로 실행하려면 명령줄에서 속성을 전달하세요:

winapp run -p WindowsPackageType=None

다른 유용한 옵션으로는 새로 처음 실행할 수 있도록 이전 등록과 앱의 저장된 데이터(LocalState 및 설정)를 제거하는 --clean, 앱을 시작하지 않고 등록하는 --no-launch, 그리고 앱이 실행되는 동안 스크립트와 에이전트가 계속 작동할 수 있도록 프로세스 ID를 반환하고 종료하는 --detach --json가 포함됩니다. 전체 목록은 Project 모드(.NET SDK 프로젝트)를 참조하세요.

대신 dotnet run을 사용하세요

dotnet run를 선호하는 경우 Microsoft.Windows.SDK.BuildTools.WinApp NuGet 패키지를 사용하세요. 패키지는 dotnet run를 후크하여 winapp run를 호출하고 ID를 사용해 앱을 시작합니다. dotnet run로 만든 프로젝트는 이미 패키지를 참조하므로 winapp new는 추가 설정 없이 작동합니다. 다른 프로젝트의 경우 먼저 패키지를 추가하세요:

dotnet add package Microsoft.Windows.SDK.BuildTools.WinApp --prerelease
dotnet run

dotnet run -p:WinAppRunDebugOutput=true 옵션을 WinAppRun* MSBuild 속성으로 전달할 수 있습니다. 예를 들어 winapp run. 통합을 해제하려면 프로젝트 파일에서 EnableWinAppRunSupport를 false로 설정합니다. 자세한 내용은 dotnet 실행 지원을 참조하세요.

충돌 디버깅

앱이 실행되는 동안 --debug-output 메시지와 첫 번째 기회 예외를 캡처하려면 OutputDebugString을(를) 추가합니다. WinUI 앱이 stowed exception으로 실패하면 winapp CLI는 크래시 덤프를 분석하고 일반 오류 코드 대신 원래 오류 및 호출 스택을 출력합니다.

winapp run --debug-output

--symbols을 추가하여 전체 네이티브 함수 이름용 기호를 다운로드합니다. --debug-output winapp CLI를 디버거로 연결하므로 Visual Studio 또는 다른 디버거를 동일한 프로세스에 연결할 수 없습니다. 대신 IDE로 디버그하려면 winapp CLI로 디버깅을 참조하세요. Stowed-exception 분석에 대한 자세한 내용은 WinUI stowed-exception 분류를 참조하세요.

컨트롤 및 API 찾기

winapp find-ui는 의도에 따라 WinUI 갤러리 및 Windows Community Toolkit에서 XAML 및 C# 샘플을 검색하고 선택한 시나리오에 대한 코드를 반환합니다. winapp find-api는 Windows 앱 SDK 및 Windows SDK 형식, 멤버 및 열거형과 같이 프로젝트에서 참조하는 Windows 및 WinRT API 범위를 검색합니다.

# Find a control by what you want to build
winapp find-ui "tabbed layout"

# Get the XAML and C# for one of the returned scenarios
winapp find-ui --id gallery-tabview-1

# Look up an API
winapp find-api NavigationView

두 명령 모두 --json를 지원하므로 AI 코딩 에이전트는 이를 사용하여 컨트롤을 선택하고 API 이름을 확인할 수 있습니다. 자세한 내용은 find-api 및 find-ui 참조하세요.

UI를 자동화하고 확인하세요

winapp ui는 Microsoft UI 자동화을 통해 실행 중인 앱을 제어합니다. 이를 사용하여 요소 트리를 검사하고, 컨트롤을 호출하고, 상태 변경을 기다린 후 스크린샷을 찍습니다. 에이전트는 동일한 명령을 사용하여 자신이 변경한 내용을 확인할 수 있습니다.

winapp run --detach
winapp ui inspect -a MyApp
winapp ui search Button -a MyApp
winapp ui invoke PART_PaneToggleButton -a MyApp
winapp ui screenshot -a MyApp

PART_PaneToggleButton 선택기는 winui-navview 템플릿의 메뉴 단추를 대상으로 합니다. 자신의 컨트롤의 경우 winapp ui inspect 또는 winapp ui search의 출력에서 선택기를 복사합니다.

데스크톱 대신 Windows 샌드박스에서 앱을 실행하려면 --on sandbox를 winapp run 및 winapp ui에 추가합니다. 자세한 내용은 UI 자동화 및 샌드박스 실행을 참조하세요.

패키징 및 서명하기

패키지를 로컬로 테스트할 준비가 되면 게시자가 매니페스트와 일치하는 개발 인증서를 생성한 다음, 한 단계에서 프로젝트를 빌드하고 패키지합니다.

winapp cert generate --manifest .\Package.appxmanifest
winapp pack .\MyApp.csproj -c Release --arch x64 --cert .\devcert.pfx

winapp pack는 프로젝트를 빌드하고 서명된 .msix를 생성합니다. 여러 아키텍처에 대한 빌드를 하나로 .msixbundle결합하려면 다중 아키텍처 번들을 참조하세요. 프로젝트를 패키징해야 하므로 WindowsPackageType를 None로 설정한 프로젝트는 패키지할 수 없습니다. WinUI 프로젝트의 경우 Windows 앱 SDK 빌드는 매니페스트, 진입점 및 리소스 생성을 관리하므로 --manifest, --executable 및 --skip-pri는 허용되지 않습니다.

개발 인증서는 로컬 테스트 전용이며 기본 암호를 사용합니다. 앱을 배포하기 전에 winapp az-sign 및 Azure 신뢰할 수 있는 서명과 같은 신뢰할 수 있는 인증서로 서명합니다. 자세한 내용은 프로젝트 직접 패키징 및 보안을 참조하세요.

기존 WinUI 프로젝트

winapp CLI는 Visual Studio에서 만든 WinUI 프로젝트와 함께 작동합니다. winapp run 프로젝트 파일, 솔루션 파일 또는 해당 파일이 포함된 폴더를 가리키세요. winapp pack의 경우 .csproj를 전달합니다. Visual Studio 빌드 및 디버깅을 계속하고 스크립트, CI 및 에이전트 워크플로에 winapp CLI를 사용할 수 있습니다.

C++를 사용하여 WinUI

winapp run또한 Visual Studio WinUI Blank App (Packaged) 템플릿에서 만든 C++/WinRT WinUI 프로젝트(.vcxproj)를 빌드하고 실행합니다. Visual Studio MSBuild를 사용하여 프로젝트를 빌드하고, 앱에 패키지 ID를 부여하고, 시작합니다.

winapp run .\MyApp.vcxproj

# Or from the folder that contains the project
winapp run .

C++ 프로젝트에는 Desktop development with C++ 워크로드 및 C++ WinUI app development tools가 포함된 Visual Studio 또는 Visual Studio용 Build Tools가 필요합니다. winapp pack는 .vcxproj 프로젝트를 빌드하지 않으므로 Visual Studio에서 MSIX 패키지를 만드세요. 필수 구성 요소 및 옵션은 C++ 프로젝트(.vcxproj)를 참조하세요. WinUI를 사용하지 않는 C++ 앱의 경우 C++와 함께 winapp CLI 사용을 참조하세요.

Samples

  • winui-app: winapp ui 자동화용으로 설정된 컨트롤이 있는 패키지된 WinUI 앱
  • winui-unpackaged-app: 패키지 ID 없이 실행되는 WinUI 앱
  • winui-solution: winapp run가 앱 프로젝트를 선택하는 방식을 보여 주는 다중 프로젝트 솔루션
  • cpp-winui-app: winapp run와 함께 실행되는 패키지된 C++/WinRT WinUI 앱(XAML을 사용하는 Visual Studio .vcxproj)

다음 단계

  • 에 마지막으로 업데이트됨