Windows 앱 개발 CLI(winapp CLI)

중요합니다

Windows 앱 개발 CLI는 현재 공개 미리 보기 있습니다. 기능 및 명령은 최종 릴리스 전에 변경될 수 있습니다. 의견을 문제를 작성하여 공유하세요.

winapp CLI(Windows 앱 개발 CLI)는 선택한 프레임워크를 사용하여 Windows 앱을 빌드하기 위한 명령줄 도구입니다. 터미널, 선호하는 편집기 또는 AI 코딩 에이전트에서 작동합니다.

• WinUI 앱: Visual Studio 열지 않고 WinUI 앱을 만들고, 실행하고, 디버그하고, 테스트하고, 패키지합니다.
• 플랫폼 간 및 기타 프레임워크: 프레임워크를 변경하지 않고 기존 Electron, Flutter, Tauri, Rust, .NET 또는 C++ 앱에 Windows 기능을 제공합니다. winapp CLI는 Windows 앱 SDK를 설정하고 Windows SDK를 설정하고, 알림 및 디바이스 내 AI와 같은 API를 호출할 수 있도록 앱에 패키지 식별 정보를 부여하고, Microsoft Store 또는 사용자 고유의 배포를 위해 MSIX로 패키지합니다.

winapp CLI의 주요 이점

터미널에서 WinUI 앱 만들기 및 실행
winapp new 는 빈, NavigationView, TabView 및 MVVM 스타터를 포함하여 공식 템플릿에서 WinUI 앱을 만듭니다. winapp run는 프로젝트를 빌드하고, 일치하는 Windows 앱 런타임을 설치하고, 패키지된 앱이든 패키지되지 않은 앱이든 관계없이 앱을 시작합니다.
첫 번째 WinUI 앱 빌드

패키지 ID 및 크래시 진단을 사용하여 디버그
패키지 ID를 사용하여 앱을 실행하여 ID가 필요한 알림, 디바이스 내 AI 및 기타 API를 테스트할 수 있습니다. 디버그 메시지 및 크래시 덤프를 캡처하기 위해 --debug-output을 추가합니다. WinUI 충돌의 경우 winapp은 실패한 XAML 이벤트 처리기를 가리키도록 stowed 예외를 디코딩합니다.
패키지 ID를 사용하여 디버깅

실제 WinUI 코드에 기반한 AI 코딩 에이전트
winapp find-ui는 WinUI 3 갤러리 및 Windows Community Toolkit에서 작동하는 XAML 및 C#을 반환합니다. winapp find-api는 프로젝트에서 참조하는 Windows 런타임 API를 검사합니다. 에이전트는 추측하는 대신 이를 사용해 실제 샘플 및 메타데이터에서 코드를 생성합니다.
AI 에이전트와 함께 winapp CLI 사용

앱의 UI 자동화 및 테스트
winapp ui는 UI 자동화 통해 실행 중인 앱을 검사하고 상호 작용하며 스크린샷 및 녹화를 캡처합니다. Windows 샌드박스에서 앱을 실행하여 깨끗한 환경에서 테스트하세요.
UI 자동화

패키징하고, 서명하고, 배송
winapp pack 는 프로젝트를 빌드하고, MSIX로 패키지하고, 한 단계로 서명합니다. 개발 인증서를 로컬로 생성하고, Azure 신뢰할 수 있는 서명 사용하여 릴리스 빌드에 서명하고, GitHub Actions 또는 Azure DevOps 실행기에서 winapp CLI를 설치합니다.
앱을 패키징하세요

모든 프레임워크에 Windows 기능 가져오기
빌드 시스템을 변경하지 않고 .NET, C++, Electron, Flutter, Rust 또는 Tauri로 빌드된 앱에 Windows SDK 및 Windows 앱 SDK, 패키지 식별 및 MSIX 패키징을 추가합니다.
지원되는 프레임워크 보기

WinUI 시작하기

winapp CLI 및 .NET SDK를 설치한 후 WinUI 앱을 만들고 실행합니다.

winapp new --name MyWinUIApp --template winui-navview --use-defaults
cd MyWinUIApp
winapp run

패키지를 로컬로 테스트할 준비가 되면 개발 인증서를 생성하고 서명된 MSIX 패키지를 만듭니다.

winapp cert generate --manifest ./Package.appxmanifest
winapp pack ./MyWinUIApp.csproj -c Release --cert ./devcert.pfx

개발 인증서는 기본 암호를 사용하며 로컬 테스트 전용입니다. 앱을 배포하기 전에 신뢰할 수 있는 인증서로 서명합니다(예: winapp az-sign). 자세한 내용은 보안을 참조하세요.

설치 및 첫 번째 UI 변경 내용을 포함하는 단계별 안내는 첫 번째 WinUI 앱 빌드를 참조하세요. 사용 가능한 모든 템플릿을 보려면 다음을 실행 winapp new --list합니다. 디버깅, UI 자동화 및 패키징을 비롯한 전체 워크플로는 WinUI와 함께 winapp CLI 사용을 참조하세요.

설치

WinGet

CLI를 설치하는 가장 쉬운 방법은 WinGet(Windows 패키지 관리자)을 통해서입니다.

winget install Microsoft.winappcli --source winget

WinGet PowerShell 모듈을 사용하는 경우 대신 Install-WinGetPackage Microsoft.winappcli를 실행합니다.

NPM

Electron 프로젝트의 경우 NPM을 통해 설치합니다.

npm install @microsoft/winappcli --save-dev

GitHub Actions/Azure DevOps

CI/CD pipelines 경우 setup-WinAppCli 작업을 사용하여 실행기/에이전트에 CLI를 자동으로 설치합니다.

수동 다운로드

GitHub 릴리스 최신 빌드를 다운로드합니다.

설치 확인

설치되면 CLI를 호출하여 설치를 확인합니다.

winapp --help

또는 Electron/Node.js사용하는 경우:

npx winapp --help

AI 에이전트와 함께 winapp CLI 사용

winapp CLI는 AI 코딩 에이전트와 잘 작동하도록 설계되었습니다. find-api 및 --json 같은 명령은 find-ui를 사용해 컴퓨터에서 읽을 수 있는 출력을 반환하므로 에이전트는 코드를 작성하기 전에 실제 WinUI 샘플과 Windows 런타임 API를 조회할 수 있습니다.

winapp CLI 워크플로에 대한 에이전트 기능을 제공하려면 winapp 플러그인을 설치합니다.

# GitHub Copilot CLI
copilot plugin install microsoft/WinAppCli

# Claude Code
claude plugin marketplace add microsoft/WinAppCli
claude plugin install winappcli@winappcli

Visual Studio Code에서 작업하는 경우 WinApp VS Code 확장은 편집기에서 winapp CLI 명령을 실행하고 F5 키를 누르면 패키지 ID로 앱을 시작합니다. Visual Studio Marketplace에서 설치합니다.

지원되는 프레임워크

winapp CLI는 WinUI 및 기타 앱 프레임워크와 호환됩니다.

프레임워크	가이드
WinUI	WinUI 시작하기
.NET / WPF / WinForms	.NET으로 시작하십시오
.NET MAUI	.NET MAUI 시작하기
C++(CMake)	C++ 시작하기
전자	Electron 사용 시작하기
러스트	Rust 시작하기
타우리 주	타우리를 시작하세요
떨림	Flutter 시작하기

추가 가이드:

• EXE/CLI 패키징: 기존 EXE/CLI를 MSIX로 패키징하기 위한 단계별 가이드
• 스파스 패키징: ID 전용(스파스) MSIX와 외부 콘텐츠를 사용해 패키지되지 않은 앱에 앱 패키지 식별자 부여
• 셸 완성: PowerShell, bash, zsh 및 fish의 명령, 옵션 및 값에 대한 탭 완성 사용
• 보안 지침: 머신에서 변경되는 개발 인증서 및 개발자 모드, 처리 devcert.pfx방법 및 프로덕션에 서명하는 방법

명령 개요

카테고리	Commands
생성 및 설정	new, init, restore, update
실행 및 디버그	run, create-debug-identity, embed-identity, unregister
패키징	pack
매니페스트	매니페스트 생성, 매니페스트 업데이트 자산, 매니페스트 추가 별칭
인증서 및 서명	cert generate, cert install, sign, az-sign, create-external-catalog
에이전트에 대한 코드 검색	find-ui, find-api
UI 자동화 및 샌드박스	ui, target
유틸리티	tool, store, get-winapp-path, complete
Node.js/Electron	node create-addon, node generate-bindings, node add-electron-debug-identity, node clear-electron-debug-identity

전체 CLI 참조는 CLI 참조를 참조하세요.

Samples

GitHub 샘플 폴더에는 지원되는 각 프레임워크에 대해 실행 가능한 프로젝트가 있습니다.

Sample	Description
WinUI 앱	패키지된 WinUI 앱이 winapp run로 등록되고 시작됨
패키지되지 않은 WinUI 앱	winapp run를 사용하여 시작된 패키지되지 않은 WinUI 앱
WinUI 솔루션	winapp run가 앱 프로젝트를 선택하는 방법을 보여 주는 다중 프로젝트 솔루션(앱 및 테스트 프로젝트)
C++ WinUI 앱	XAML 또는 MSBuild 없이 CMake를 사용하여 C++로 빌드된 WinUI 창
WPF 앱	WPF 데스크톱 앱
.NET MAUI 앱	winapp CLI로 패키지 및 서명된 .NET MAUI Windows 프로젝트
C++ 앱	CMake를 사용하여 빌드된 네이티브 C++ Win32 앱
Electron	매니페스트, 자산 및 네이티브 C++ 및 C# 추가 기능이 있는 Electron Forge 앱
Rust 앱	Windows API를 호출하는 Rust 앱
Tauri 앱	Rust 백 엔드가 있는 Tauri 앱
Flutter 앱	패키지 ID 및 Windows 앱 SDK가 있는 Flutter 데스크톱 앱
스파스 앱	스파스 패키징(ID 전용 MSIX) 및 설치 관리자가 있는 WPF 앱

패키지 ID를 지정하는 이유는 무엇인가요?

많은 Windows API를 사용하려면 앱에 패키지 ID가 있어야 합니다. ID를 사용하면 앱이 알림, OS 통합 및 디바이스 내 AI와 같은 기능에 access 얻을 수 있습니다. WinUI 앱 템플릿에는 패키지 매니페스트가 포함되어 있으므로 기본적으로 ID가 부여됩니다. 패키지 ID의 잠금을 해제하고 올바른 패키징 모델을 선택하는 데 도움이 되는 전체 목록은 패키징 개요를 참조하세요.

오픈 소스

winapp CLI가 오픈 소스. 소스 코드, 파일 문제를 찾고 GitHub 기여할 수 있습니다. 도움이 필요하면 지원을 참조하세요.

관련 토픽

• 첫 번째 WinUI 앱 빌드
• WinUI 개요
• CLI 참조
• 패키지 ID를 사용하여 디버깅
• 보안 지침
• UI 자동화
• Windows 샌드박스 실행
• NPM 프로그래밍 API
• 프레임워크 가이드
• Windows 앱 SDK 설명서
• MSIX 패키징 설명서