CLI 설명서 및 사용 현황

셸 완성

명령, 옵션 및 값에 대해 탭 완성을 사용하도록 설정합니다. 설치 지침은 셸 완성 가이드 를 참조하세요.

# Quick setup for PowerShell (permanent — add to profile)
winapp complete --setup powershell >> $PROFILE

# Or try it in the current session only
winapp complete --setup powershell | Out-String | Invoke-Expression

초기화 (init)

최신 Windows 개발을 위해 Windows SDK, Windows 앱 SDK 및 필수 자산을 사용하여 디렉터리를 초기화합니다.

winapp init [base-directory] [options]

인수:

• base-directory - 앱/작업 영역의 기본/루트 디렉터리(기본값: 현재 디렉터리)

옵션:

• --config-dir <path> - 읽기/저장 구성을 위한 디렉터리(기본값: 현재 디렉터리)
• --setup-sdks - SDK 설치 모드: 'stable'(기본값), '미리 보기', '실험적' 또는 '없음'(SDK 설치 건너뛰기)
• --ignore-config, --no-config - 버전 관리에 구성 파일을 사용하지 마세요.
• --no-gitignore - .gitignore 파일을 업데이트하지 않음
• --use-defaults, --no-prompt - 프롬프트를 표시하지 않고 모든 프롬프트의 기본값을 사용합니다.
• --config-only - 구성 파일 작업만 처리하고 패키지 설치를 건너뜁니다.
• --exe <path> - 애플리케이션 실행 파일의 경로입니다. --sparse가 필요합니다. 전체 패키지/SDK 설정 대신 exe에 대한 ID 전용 스파스 매니페스트를 생성합니다.
• --sparse - 기존 데스크톱 exe에 대한 스파스 ID 매니페스트(appxmanifest.xml)를 생성합니다. SDK/패키지 설치를 건너뜁니다. --exe를 사용합니다.
• --name <name> - 패키지 이름 재정의(스파스만, 기본값: exe에서 유추됨)
• --publisher <CN> - 게시자 CN 재정의(스파스만 해당, 기본값: exe의 회사 이름에서 유추됨)
• --output-dir <path> - 스파스 매니페스트를 작성하는 디렉터리( Assets/ 스파스만 해당, 기본값: sparse/ 현재 디렉터리의 폴더)
• --force - 대상 디렉터리에 있는 기존 appxmanifest.xml 항목을 덮어씁니다(스파스만 해당). 이 항목이 없으면 기존 매니페스트/자산을 바꾸는 대신 init가 실패합니다.
• --add-js-bindings (npm에만 해당) - 메시지를 표시하지 않고 package.json 추가하고 winapp.jsBindings JS/TypeScript 바인딩을 생성합니다(호환되지 않음 --setup-sdks none).

기능 설명:

• 구성 파일을 만듭니다 winapp.yaml (SDK 패키지가 관리되고 건너뛰는 --setup-sdks none경우에만)
• Windows SDK 및 Windows 앱 SDK 패키지 다운로드
• C++/WinRT 헤더 및 이진 파일을 생성합니다.
• Package.appxmanifest를 만듭니다.
• 빌드 도구 설정 및 개발자 모드 사용
• 생성된 파일을 제외하도록 .gitignore를 업데이트합니다.
• 공유 가능한 파일을 전역 캐시 디렉터리에 저장합니다.
• 사용하도록 설정된 경우 Windows 앱 SDK API에 대한 JS 바인딩을 생성합니다(npm만 해당).

자동 프로젝트 검색:

디렉터리 인수 없이 실행되는 경우 init 현재 디렉터리 트리의 폭 우선 검색을 수행하여 호환되는 프로젝트(최대 10개)를 찾습니다. 지원되는 프로젝트 유형:

• Tauri — tauri.conf.json 디렉터리 아래의 한 수준 발견
• 전자 - package.jsonelectron 종속성 또는 devDependencies 사용
• Flutter - pubspec.yaml 프로젝트 루트
• .NET — .csproj 프로젝트 루트
• Rust - Cargo.toml 프로젝트 루트
• C++ - CMakeLists.txt 프로젝트 루트

검색은 일반적으로 무시되는 디렉터리(node_modules, bin, obj, .git 등)를 건너뜁니다. 호환되는 프로젝트가 발견되면 아래의 하위 디렉터리가 검색되지 않습니다.

• 디렉터리 인수가 제공된 경우(예: winapp init . 또는 winapp init path/to/project) 검색을 건너뛰고 init 해당 디렉터리에서 호환되는 프로젝트만 확인합니다.
• (또는--use-defaults)가 디렉터리 인수 --no-prompt 없이 설정된 경우 init 검색을 건너뛰고 현재 디렉터리를 비대화형으로 초기화합니다. 알려진 프로젝트 형식이 검색되지 않은 경우 먼저 경고합니다(예: winapp init --use-defaults).
• 비대화형 환경(파이프된 stdin, CI, 리디렉션된 입력) init 에서 자동으로 동작을 사용하고 --use-defaults 경고를 내보냅니다. Non-interactive environment detected. Using default values.
• 현재 디렉터리가 호환되는 프로젝트 init 인 경우 즉시 진행합니다.
• 정확히 하나의 프로젝트가 다른 곳에서 발견되면 확인하라는 메시지가 표시됩니다.
• 여러 프로젝트가 발견되면 초기화할 프로젝트를 선택할 수 있습니다. 현재 디렉터리를 항상 대체 옵션으로 사용할 수 있습니다.
• 프로젝트를 찾을 수 없으면 경고를 받고 계속 진행할지 묻는 메시지가 표시됩니다.
• 검색이 10 프로젝트 제한에 도달하면 디렉터리 인수 제공을 제안하는 경고가 표시됩니다.

자동 .NET 프로젝트 흐름:

대상 디렉터리에 .csproj 파일이 있으면 init 간소화된 .NET 관련 흐름을 사용합니다.

• TargetFramework 유효성을 검사하고 Windows 호환되는 TFM(예: net10.0-windows10.0.26100.0)으로 업데이트합니다.
• Microsoft.WindowsAppSDK와 Microsoft.Windows.SDK.BuildTools를 PackageReference 내에서 NuGet .csproj 항목으로 직접 추가합니다.
• Package.appxmanifest, 자산 및 개발 인증서 생성
• C++ 프로젝션을 생성하지 않거나 다운로드winapp.yaml 않습니다 (NuGet 패키지에dotnet restore 사용).

스파스 ID 모드(--exe + --sparse):

스파스 패키징 워크플로의 첫 번째 단계인 기존 데스크톱 실행 파일에 대한 ID 전용 스파스 패키지 매니페스트를 생성합니다. 전체 init 흐름과 달리 모든 SDK/패키지 설치 (스파스 ID 패키지에는 SDK 종속성이 없음)를 건너뛰고 매니페스트 및 자리 표시자 자산만 생성합니다.

• exe FileVersionInfo 에서 패키지 이름, 게시자, 설명 및 버전을 유추합니다(또는 대화형으로 --name--publisher재정의).
• appxmanifest.xml 현재 디렉터리의 폴더(또는--output-dir)에 Executable폴더를 더한 sparse/ 쓰기(exe 이름이 대체됨)Assets/
• 대화형 재정의 프롬프트를 건너뛰는 데 사용 --use-defaults/--no-prompt (CI 친화적)
• --exe오류가 없으면 --sparse

자산은 외부에 있습니다. 스파스는 .msix ID 전용입니다. 생성된 Assets/ 내용은 런타임에 앱의 설치 디렉터리(외부 콘텐츠 위치)에서 확인되며 번들로 묶.msix이지 않습니다. 애플리케이션과 함께 배포합니다.

다음 단계: winapp init --exe <exe> --sparsewinapp pack <appxmanifest.xml> ID.msix를 빌드하려면 .winapp embed-identity <exe> 전체 연습 은 스파스 패키징 가이드 를 참조하세요.

예:

# Initialize current directory
winapp init

# Initialize with experimental packages
winapp init --setup-sdks experimental

# Initialize specific directory without prompts
winapp init ./my-project --use-defaults

# Initialize a .NET project (auto-detected from .csproj)
cd my-dotnet-app
winapp init

# Generate a sparse identity manifest for an existing exe (no SDK install)
winapp init --exe ./bin/Release/net8.0-windows/MyApp.exe --sparse --use-defaults

팁: 초기 설정 후 SDK 설치

SDK 설치를 건너 init--setup-sdks none 뛰고 나중에 SDK가 필요한 경우:

# Re-run init to install SDKs - preserves existing files (manifest, etc.)
winapp init . --use-defaults --setup-sdks stable

미리 보기/실험적 SDK 버전을 사용 --setup-sdks preview 하거나 --setup-sdks experimental 사용합니다.

---

새로운

공식 Windows 앱 SDK dotnet new 템플릿에서 새 WinUI 앱을 만듭니다. 기본적으로 대화형; 는 비대화형 환경에서 기본값을 자동으로 사용합니다.

winapp new [options]

옵션:

• -t, --template <short-name>- 템플릿의 짧은 이름(예: winui, , winui-navviewwinui-mvvm, winui-libwinui-unittest). 런타임에 설치된 팩에 대해 유효성을 검사합니다. 실행 winapp new --list 하면 모든 항목이 표시됩니다. 기본값: winui (빈 앱).
• -n, --name <name> - 새 앱/프로젝트의 이름(기본값: 파생됨 --output, 기타 WinUIApp)
• -o, --output <path> - 앱을 만드는 디렉터리(기본값: ./<name>)
• --use-defaults, --no-prompt - 프롬프트를 표시하지 마세요. 기본값을 사용합니다(빈 템플릿, 이름 및 --output/--name설치된 템플릿 팩을 업데이트하는 대신 유지)
• --force - 출력 디렉터리에 파일이 이미 포함된 경우에도 스캐폴드
• --template-version <latest|installed|version> - WinUI 템플릿 팩 버전: latest 최신 게시된 팩을 설치하거나, installed 이미 다운로드한 항목(네트워크 없음)을 유지하거나, 명시적 버전(예: 1.2.3.)을 고정합니다. 기본값: 팩이 없을 때 최신 버전을 설치합니다. 그렇지 않으면 부실 팩을 업데이트하라는 메시지가 표시됩니다(as-is 유지 --use-defaults됨).
• --list - 사용 가능한 WinUI 템플릿을 나열하고 종료합니다(설치되지 않은 경우 먼저 최신 팩 설치)
• --json - 출력을 JSON으로 서식 지정

템플릿:

템플릿 목록은 설치된 팩에서 실시간으로 읽혀지므로 항상 사용 중인 버전을 반영합니다. 현재 집합을 보려면 실행 winapp new --list 합니다. 일반적인 템플릿:

짧은 이름	설명
winui	빈 WinUI 3 앱 최소(MSIX 패키징)
winui-navview	NavigationView 시작 앱
winui-tabview	TabView 시작 앱
winui-mvvm	MVVM 앱(CommunityToolkit.Mvvm)
winui-lib	WinUI 3 클래스 라이브러리
winui-unittest	패키지된 MSTest 앱; 테스트가 시작될 때 실행됨

각 템플릿의 정식 짧은 이름은 첫 번째 별칭 dotnet new 목록입니다. 나열된 별칭(예: winui3) wasdk-single도 허용됩니다. 기존 WinUI 프로젝트 내에서 실행하는 경우 새 프로젝트를 만드는 대신 현재 프로젝트에 dotnet new 추가되는 winapp new항목 템플릿(예: 빈 페이지)도 표시합니다.

템플릿 팩 버전 관리:

winapp new 더 이상 특정 템플릿 팩 버전을 고정하지 않습니다. 설치된 팩이 없으면 최신 팩을 설치합니다. 이전 팩이 이미 설치된 경우 피드를 확인하고, 최신 팩이 있는 경우 비대화형/--use-defaults실행을 제외하고 업데이트할지 여부를 묻는 메시지를 표시합니다. 이 팩은 설치된 팩을 유지합니다. 항상 프롬프트 없이 최신 항목을 사용하거나 --template-version installed 네트워크 검사 없이 다운로드한 팩을 항상 사용하는 데 사용합니다--template-version latest. 명시적 버전(예: --template-version 1.2.3)을 전달하면 항상 해당 버전이 정확하게 설치되므로 최신 팩이 이미 있는 경우에도 다시 설치되므로 머신 간에 스캐폴딩을 재현할 수 있습니다.

기능 설명:

• SDK가 설치된 .NET 확인합니다(누락된 경우 지침에 따라 빠르게 실패함 - winapp 도구 체인을 설치하지 않음)
• 요청 시 공식 WinUI 템플릿 팩(Microsoft.WindowsAppSDK.WinUI.CSharp.Templates)을 설치하거나 업데이트합니다.
• 설치된 팩에서 사용 가능한 템플릿을 열거하고 스캐폴딩을 위임합니다. dotnet new <short-name>

WinUI 앱 템플릿에는 이미 Windows 패키징 및 ID(Package.appxmanifest)가 포함되어 있으므로 별도의 winapp init 단계가 필요하지 않습니다. 앱 템플릿의 경우 앱을 빌드하고 시작하는 데 사용합니다 winapp run . 템플릿은 winui-lib 앱 프로젝트에서 참조할 클래스 라이브러리를 생성합니다(앱 매니페스트가 없음). 템플릿은 winui-unittest패키지된 MSTest 앱으로, 앱을 시작할 때 테스트가 실행됩니다 (winapp run을 통해 dotnet test서가 아님). winapp new설치된 .NET SDK의 대상 프레임워크에 대해 스캐폴딩하고 선택한 템플릿에 적합한 다음 단계를 인쇄합니다.

템플릿 팩 또는 스캐폴딩 문제를 진단하는 dotnet 데 유용한 전체 출력과 함께 모든 기본 호출(팩 쿼리, 업데이트 검사, 설치, dotnet new list스캐폴드)을 에코하도록 전역 --verbose (-v) 플래그를 전달합니다.

예:

# Interactive: pick a template, then a name (output defaults to ./<name>)
winapp new

# List the available templates without scaffolding
winapp new --list

# One-shot with a specific template
winapp new --name MyApp --template winui-navview

# Always use the newest template pack, no prompts
winapp new --name MyApp --template-version latest --use-defaults

# Show the underlying dotnet commands and their output
winapp new --name MyApp --verbose

# Non-interactive (agent) with machine-readable output
winapp new --use-defaults --name MyApp --json

---

복원

패키지를 복원하고 기존 구성에 따라 파일을 다시 생성합니다 winapp.yaml .

winapp restore [options]

옵션:

• --config-dir <path> - winapp.yaml을 포함하는 디렉터리(기본값: 현재 디렉터리)

기능 설명:

• 기존 구성을 읽습니다.winapp.yaml
• SDK 패키지를 지정된 버전으로 다운로드/업데이트
• C++/WinRT 헤더 및 이진 파일을 다시 생성합니다.
• 공유 가능한 파일을 전역 캐시 디렉터리에 저장합니다.

비고

winapp init 사용하여 초기화된 .NET 프로젝트의 경우 winapp.yaml 없습니다. 대신 NuGet 패키지를 복원하는 데 사용합니다 dotnet restore .

예:

# Restore from winapp.yaml in current directory
winapp restore

---

업데이트

패키지를 최신 버전으로 업데이트하고 구성 파일을 업데이트합니다.

winapp update [options]

옵션:

• --setup-sdks <stable|preview|experimental|none>- SDK 설치 모드: stable (기본값), preview또는 experimentalnone (SDK 설치 건너뛰기)

기능 설명:

• 현재 디렉터리에서 기존 winapp.yaml 구성을 읽습니다.
• 모든 패키지를 사용 가능한 최신 버전으로 업데이트합니다.
• winapp.yaml 파일을 새 버전 번호로 업데이트합니다.
• C++/WinRT 헤더 및 이진 파일을 다시 생성합니다.

예:

# Update packages to latest versions
winapp update

# Update including experimental packages
winapp update --setup-sdks experimental

---

pack

준비된 애플리케이션 디렉터리에서 MSIX 패키지를 만듭니다. 매니페스트 파일(Package.appxmanifest 기본 설정, appxmanifest.xml 지원됨)이 대상 디렉터리, 현재 디렉터리 또는 옵션과 함께 --manifest 전달되어야 합니다. (매니페스트를 실행 init 하거나 manifest generate 만들려면)

여러 입력 폴더를 전달하여 다중 아키텍처 배포를 만듭니 .msixbundle 다(아래 다중 아키텍처 번들 참조).

winapp pack <input-folder> [input-folder...] [options]

인수:

• input-folder - 패키지할 애플리케이션 파일을 포함하는 하나 이상의 디렉터리입니다. 여러 폴더(예: ./publish/x64 ./publish/arm64)를 전달하여 MSIX 번들을 만듭니다. 스파스 ID 패키지의 경우 폴더 대신 스파스 appxmanifest.xml 파일을 직접 전달합니다(아래 스파스 ID 패키지 참조).

옵션:

• --output <filename> - 출력 파일 이름입니다. 단일 패키지의 경우: <name>_<version>_<arch>.msix (또는 )로 <name>_<version>.msix<name>_<arch>.msix<name>.msix대체합니다. 번들의 경우: <name>_<version>_<arch1>_<arch2>.msixbundle.
• --name <name> - 패키지 이름(기본값: 매니페스트에서)
• --manifest <path> - 매니페스트 파일 경로(Package.appxmanifest 기본 설정, appxmanifest.xml 지원됨, 기본값: 자동 검색)
• --cert <path> - 서명 인증서 경로(자동 서명 사용)
• --cert-password <password> - 인증서 암호(기본값: "암호")
• --generate-cert - 새 개발 인증서 생성
• --install-cert - 컴퓨터에 인증서 설치
• --publisher <name>- 인증서 생성을 위한 Publisher. 전체 X.500 고유 이름 또는 맨 이름(자동으로 로 CN=<name>래핑됨)을 허용합니다.
• --self-contained - 번들 Windows 앱 SDK 런타임
• --skip-pri - PRI 파일 생성 건너뛰기
• --executable <path> - 입력 폴더(또한 --exe)를 기준으로 실행 파일의 경로입니다. 매니페스트의 자리 표시자를 해결하는 $targetnametoken$ 데 사용됩니다.

기능 설명:

• Package.appxmanifest 파일의 유효성을 검사하고 처리합니다.
• 매니페스트에서 토큰을 확인합니다 $placeholder$ (아래 매니페스트 자리 표시자 참조).
• 적절한 프레임워크 종속성을 보장합니다.
• 나란히 배치된 매니페스트를 등록과 함께 업데이트합니다.
• 매니페스트 디렉터리 또는 입력 폴더에서 매니페스트에서 참조되는 이미지가 아닌 파일(예: AppExtension manifest.json, 구성 파일)을 스테이징에서 누락된 경우 자동으로 검색하고 번들로 묶습니다.
• 타사 WinRT 구성 요소를 자동으로 검색하고 활성화 가능한 클래스를 등록합니다(아래 WinRT 구성 요소 검색 참조).
• 자체 포함된 WinAppSDK 배포 처리
• 인증서가 제공된 경우 패키지 서명

스파스 ID 패키지

입력이 폴더 winapp pack 가 아닌 스파스 appxmanifest.xml 파일(아래 <Properties>선언<uap10:AllowExternalContent>true</uap10:AllowExternalContent>)인 경우 ID 전용.msix을 빌드합니다. 애플리케이션 이진 파일이나 자산이 없는 매니페스트만 패키지합니다. 스파 스 패키징 워크플로의 2단계입니다.

# Build a signed identity package from a sparse manifest
winapp pack ./sparse/appxmanifest.xml --cert ./devcert.pfx

• 출력은 <PackageName>.identity.msix 기본적으로 현재 디렉터리(재정의) --output로 설정됩니다.
• 서명은 (또는--generate-cert) 제공된 경우에만 --cert 발생합니다.
• 대신 매니페스트가 선언AllowExternalContent된 폴더를 전달하는 경우 기존 폴더 패키징 동작이 적용되지만 winapp pack 자산() 또는 이진 파일(///.so.jpg.png.exe.dll.ico/)을 찾으면 경고합니다. 스파스 패키지는 내부.msix가 아닌 외부 위치에 속합니다.

압축 후 설치 관리자Add-AppxPackage -Path <msix> -ExternalLocation <install-dir>에서 패키지를 실행하고 winapp embed-identity <exe> 등록합니다. 스파스 패키징 가이드를 참조하세요.

WinRT 구성 요소 검색

패키징할 winapp pack 때 타 winapp.yaml 사 WinRT 구성 요소(예: Win2D)에 정의된 *.csproj NuGet 패키지를 자동으로 검색합니다. 파일을 구문 분석 .winmd 하여 활성화 가능한 클래스 이름을 추출하고 구현 DLL을 찾습니다. 검색된 항목은 다음과 같이 등록됩니다.

• 프레임워크 종속 (기본값): 활성화 가능한 클래스는 에 항목으로 <InProcessServer> 추가됩니다. Package.appxmanifest
• 자체 포함 (--self-contained): 활성화 가능한 클래스는 실행 파일 내의 SxS(Side-by-Side) 매니페스트에 포함됩니다.

패키징 중 자리 표시자 확인:

매니페스트가 특성에 $targetnametoken$ 포함된 Executable 경우:

1. 제공된 경우 --executable (입력 폴더에 상대적인 경로) 자리 표시자가 지정된 값으로 대체됩니다.
2. 그렇지 않으면 winapp pack 입력 폴더 루트에서 .exe 파일을 검색합니다. 정확히 하나가 발견되면 자동으로 사용됩니다.
3. 파일이 0개 또는 여러 .exe 개 있으면 지정하라는 오류가 표시됩니다. --executable

예:

# Package directory with auto-detected manifest
winapp pack ./dist

# Package with custom output name and certificate
winapp pack ./dist --output MyApp.msix --cert ./cert.pfx

# Package with generated and installed certificate and self-contained WinAppSDK runtime
winapp pack ./dist --generate-cert --install-cert --self-contained

# Package with explicit executable (resolves $targetnametoken$ in manifest)
winapp pack ./dist --executable MyApp.exe

다중 아키텍처 번들

여러 입력 폴더가 전달되면 winapp pack 아키텍처당 하나의 .msixbundle 입력 폴더를 만듭니다.msix.

# Create unsigned bundle for Microsoft Store submission
winapp pack ./publish/x64 ./publish/arm64

# Create signed bundle for sideloading
winapp pack ./publish/x64 ./publish/arm64 --cert ./devcert.pfx

# Self-contained bundle
winapp pack ./publish/x64 ./publish/arm64 --self-contained --generate-cert

이 명령은 기본 실행 파일의 PE 헤더에서 각 폴더의 아키텍처를 자동으로 검색하고, 조각(ID, 기능, 종속성)에서 일관성의 유효성을 검사하고, 생성합니다 <Name>_<Version>_<arch1>_<arch2>.msixbundle.

번들에 대한 매니페스트 확인:

번들 내의 각 조각에는 매니페스트가 필요합니다. 이 명령은 다음 순서대로 매니페스트를 확인합니다.

1. --manifest <path> — 지정된 경우 이 단일 매니페스트는 모든 조각에 사용됩니다. ProcessorArchitecture 검색된 아키텍처와 일치하도록 조각당 자동으로 업데이트됩니다.

2. 폴더별 매니페스트 - 각 입력 폴더에 Package.appxmanifestappxmanifest.xml해당 폴더의 매니페스트가 포함된 경우 해당 조각에 사용됩니다.

3. 현재 디렉터리 대체 — 폴더에 매니페스트가 없는 경우 명령은 현재 작업 디렉터리에서 검색 Package.appxmanifest 하여 사용(아키텍처 자동 스탬프 사용)합니다.

모든 경우에 매니페스트는 자동으로 업데이트됩니다. 자리 표시자가 확인되고, 종속성이 주입되고 ProcessorArchitecture , 검색된 아키텍처에 강제 설정됩니다. 확인 후 교차 조각 유효성 검사를 통해 ID(이름, 버전, Publisher), 기능 및 종속성이 모든 조각 ProcessorArchitecture 에서 일관되도록 합니다. 조각에 정의된 패키지 버전은 MSIX 번들 버전(있는 경우 0.0.0.0제외)에 해당하며, 이 경우 타임스탬프 기반 버전이 자동으로 생성됩니다.

# Option 1: Single shared manifest (simplest for most projects)
# Place Package.appxmanifest in your project root and run from there
winapp pack ./publish/x64 ./publish/arm64

# Option 2: Explicit manifest path
winapp pack ./publish/x64 ./publish/arm64 --manifest ./src/Package.appxmanifest

# Option 3: Per-folder manifests (useful if slices have different app extensions)
# Each folder already contains its own Package.appxmanifest
winapp pack ./publish/x64 ./publish/arm64

---

디버그 아이덴티티 생성

스파스 패키징을 사용하여 디버깅을 위한 앱 ID를 만듭니다. exe는 원래 위치에 유지됩니다. Windows Add-AppxPackage -ExternalLocation 통해 ID를 연결합니다.

이 대winapp run: exe가 create-debug-identity(예: 있는 Electron 앱 electron.exe)에서 분리된 경우 또는 특히 스파스 패키지 동작을 테스트할 때 사용합니다node_modules. exe가 빌드 출력 폴더 winapp run 에 있는 대부분의 프레임워크의 경우 대신 전체 느슨한 레이아웃 패키지를 등록하고 앱을 시작합니다. 전체 비교는 디버깅 가이드 를 참조하세요.

winapp create-debug-identity [entrypoint] [options]

인수:

• entrypoint - 실행 파일 경로(.exe) 또는 ID가 필요한 스크립트

옵션:

• --manifest <path> - 앱 매니페스트 파일의 경로( Package.appxmanifestappxmanifest.xml 기본값: 자동 검색 Package.appxmanifest 또는 appxmanifest.xml 현재 디렉터리)
• --no-install - 만든 후 패키지를 설치하지 마세요.
• --keep-identity - 패키지 이름 및 애플리케이션 ID에 추가 .debug 하지 않고 매니페스트 ID as-is유지

기능 설명:

• 실행 파일의 병렬 매니페스트를 수정합니다.
• 정체성을 위한 스파스 패키지를 등록합니다.
• ID가 필요한 API의 디버깅을 사용하도록 설정

예:

# Add identity to executable using local manifest
winapp create-debug-identity ./bin/MyApp.exe

# Add identity with custom manifest location
winapp create-debug-identity ./dist/app.exe --manifest ./custom-manifest.xml

# Create identity for hosted app script
winapp create-debug-identity app.py

---

embed-identity

요소를 앱의 병렬(fusion) 매니페스트에 포함시켜 <msix> 데스크톱 애플리케이션을 스파스 ID 패키지에 연결합니다. 이는 스파스 패키징 워크플로의 3단계로, 실행 중인 exe가 속한 ID 패키지를 Windows 알려줍니다.

winapp embed-identity <target> [options]

인수:

• target - 업데이트할 파일입니다. 확장별로 자동 검색됨:
  • .exe (EXE 모드) - 을 <msix> 사용하여 mt.exeexe의 side-by-side 매니페스트에 요소를 직접 포함합니다.
  • .xml / .manifest (XML 모드) - 외부 SxS 매니페스트 파일의 요소를 삽입하거나 바꿉 <msix> 니다(없는 경우 생성됨). 업데이트된 매니페스트가 이진 파일에 포함되도록 나중에 앱을 다시 빌드합니다.

옵션:

• --manifest <path> - ID(packageName, publisher, applicationId)를 읽을 스파스의 appxmanifest.xml 경로입니다. 생략하면 명령은 대상 옆에 있는 sparse/ 폴더를 먼저 검색한 다음 현재 디렉터리, 대상의 디렉터리 및 현재 디렉터리에서 검색합니다 appxmanifest.xml.

예:

# EXE mode — embed identity straight into the built exe
winapp embed-identity ./bin/Release/net8.0-windows/MyApp.exe

# XML mode — update a checked-in side-by-side manifest, then rebuild
winapp embed-identity ./app.manifest --manifest ./appxmanifest.xml

이 명령은 idempotent입니다. 다시 실행하면 기존 요소를 복제하지 않고 대체 <msix> 합니다.

---

나타나다

Package.appxmanifest 파일을 생성하고 관리합니다.

매니페스트 생성

템플릿에서 Package.appxmanifest를 생성합니다.

winapp manifest generate [directory] [options]

인수:

• directory - 매니페스트를 생성하는 디렉터리(기본값: 현재 디렉터리)

옵션:

• --package-name <name> - 패키지 이름(기본값: 폴더 이름)
• --publisher-name <name>- 고유 이름 Publisher(기본값: CN=<현재 사용자>). 유효한 X.500 DN을 허용합니다. bare name은 CN=<name>으로 자동 래핑됩니다.
• --version <version> - 버전(기본값: "1.0.0.0")
• --description <text> - 설명(기본값: "내 애플리케이션")
• --entrypoint <path> - 진입점 실행 파일 또는 스크립트
• --template <type> - 템플릿 유형: packaged (기본값) 또는 sparse
• --logo-path <path> - 로고 이미지 파일 경로
• --if-exists <Error|Overwrite|Skip> - 매니페스트 파일이 대상 경로에 이미 있는 경우의 동작(기본값: Error)

템플릿:

• packaged - 표준 패키지 앱 매니페스트
• sparse- 스파스/외부 위치 패키징을 사용하는 앱 매니페스트

매니페스트 자리 표시자

생성된 매니페스트는 패키징 시 자동으로 해결되는 토큰(달러 기호로 구분된)을 사용합니다. $placeholder$

Placeholder	해결됨	예시
$targetnametoken$	확장명 없는 실행 파일 이름	Executable="$targetnametoken$.exe" → Executable="MyApp.exe"
$targetentrypoint$	Windows.FullTrustApplication	항상 자동으로 해결됨

이는 Visual Studio 프로젝트 템플릿에서 사용하는 것과 동일한 규칙을 따르므로 매니페스트는 도구 전체에서 이식 가능합니다.

자리 표시자를 해결하는 방법:

• winapp pack - 패키징하는 $targetnametoken$ 동안 옵션을 사용 --executable 하거나 입력 폴더에서 단일 .exe 을 자동으로 검색하여 확인합니다. 여러 파일(또는 0) .exe 을 찾아 --executable 지정하지 않으면 오류가 표시됩니다.
• winapp create-debug-identity — 진입점 인수가 제공되면 $targetnametoken$ 해당 인수에서 확인됩니다. 진입점이 없으면 매니페스트에서 실행 가능한 자리 표시자를 이미 확인해야 합니다.
• winapp manifest generate --executable --executable— 제공되면 매니페스트 메타데이터(버전, 설명) 및 아이콘이 실행 파일에서 추출되지만 생성된 매니페스트는 여전히 사용합니다$targetnametoken$.exe. 이 자리 표시자는 나중에 확인됩니다(예: winapp pack 또는winapp create-debug-identity).

PS: 체크 인 매니페스트에서 $targetnametoken$ 유지하면 실행 파일 이름이 하드 코딩되는 것을 방지하고 winapp pack 및 Visual Studio 빌드 모두에서 작동합니다.

예:

# Generate standard manifest interactively
winapp manifest generate

# Generate with all options specified
winapp manifest generate ./src --package-name MyApp --publisher-name "CN=My Company" --if-exists overwrite

매니페스트 추가 별칭

Package.appxmanifest에 실행 별칭(uap5:AppExecutionAlias)을 추가합니다. 이렇게 하면 별칭 이름을 입력하여 명령줄에서 패키지된 앱을 시작할 수 있습니다.

winapp manifest add-alias [options]

옵션:

• --name <alias> - 별칭 이름(예: myapp.exe). 기본값: 매니페스트의 Executable 특성에서 유추됩니다.
• --manifest <path> - Package.appxmanifest 경로(기본값: 현재 디렉터리 검색)
• --app-id <id> - 별칭을 추가할 애플리케이션 ID(기본값: 첫 번째 Application 요소)

기능 설명:

• 매니페스트를 읽고 특성에서 Executable 별칭을 유추합니다(예: $targetnametoken$.exe자리 표시자 유지).
• uap5 아직 없는 경우 네임스페이스 선언을 추가합니다.
• <Extensions> 대상 Application 요소 내부에 블록을 <uap5:AppExecutionAlias> 추가합니다.
• 별칭이 이미 있는 경우 별칭을 보고하고 성공적으로 종료합니다.

예:

# Add alias inferred from Executable attribute (e.g. $targetnametoken$.exe)
winapp manifest add-alias

# Add alias with explicit name
winapp manifest add-alias --name myapp.exe

# Add alias to specific manifest
winapp manifest add-alias --manifest ./dist/Package.appxmanifest

매니페스트 자산 업데이트

단일 원본 이미지에서 필요한 모든 MSIX 이미지 자산을 생성합니다.

winapp manifest update-assets <image-path> [options]

인수:

• image-path - 원본 이미지 파일 경로(PNG, JPG, SVG, ICO, GIF, BMP 등)

옵션:

• --manifest <path> - Package.appxmanifest 파일의 경로(기본값: 현재 디렉터리 검색)
• --light-image <path> - 밝은 테마 변형에 대한 별도의 원본 이미지 경로

설명:

단일 원본 이미지를 사용하고 매니페스트의 자산 참조에 따라 포괄적인 MSIX 이미지 자산 집합을 생성합니다.

매니페스트에서 참조되는 각 자산에 대해 다음을 수행합니다.

• 5 배율 변형 - base(접미사 없음), .scale-125, .scale-150, .scale-200.scale-400

앱 아이콘의 경우(Square44x44Logo / AppList, 44×44 base):

• 14개의 도금된 대상 크기 조정 변형 — .targetsize-{16,20,24,30,32,36,40,48,60,64,72,80,96,256}
• 14개의 분리된 대상 크기 조정 변형 — .targetsize-{size}_altform-unplated

추가적으로:

• app.ico — 셸 통합을 위한 다중 해상도 ICO 파일(16, 24, 32, 48, 256)입니다. .ico 기존 파일이 자산 디렉터리(예: AppIcon.ico 프로젝트 템플릿)에 있는 경우 중복 파일을 만드는 대신 현재 위치로 바뀝니다.

--light-image 사용함:

• 밝은 테마 대상 변형 — .targetsize-{size}_altform-lightunplated (앱 아이콘)
• 밝은 테마 배율 변형 - .scale-{factor}_altform-colorful_theme-light (타일, 스토어 로고)

SVG 지원: SVG 파일은 원본 이미지로 완전히 지원됩니다. 각 대상 크기에서 직접 벡터로 렌더링되어 모든 해상도에서 픽셀에 완벽한 결과를 생성합니다.

이 명령은 가로 세로 비율을 유지하면서 이미지를 비례적으로 조정하여 필요할 때 투명한 배경으로 가운데에 배치합니다. 자산은 매니페스트 위치를 기준으로 디렉터리에 저장 Assets 됩니다.

예:

# Generate assets with auto-detected manifest
winapp manifest update-assets mylogo.png

# Use an SVG source for best quality at all sizes
winapp manifest update-assets mylogo.svg

# Specify manifest location explicitly
winapp manifest update-assets mylogo.png --manifest ./dist/Package.appxmanifest

# Generate light theme variants from a separate image
winapp manifest update-assets mylogo.png --light-image mylogo-light.png

# Use the same image for both (generates all MRT light theme qualifiers)
winapp manifest update-assets mylogo.png --light-image mylogo.png

# With verbose output
winapp manifest update-assets mylogo.png --verbose

---

run

빌드 출력 폴더에서 느슨한 레이아웃 패키지를 만들고, Windows.Management.Deployment.PackageManager API를 사용하여 Windows 등록하고, 애플리케이션을 시작합니다. 디버깅을 위해 전체 MSIX 설치를 시뮬레이션합니다. 디버거 첨부 파일의 프로세스 ID를 반환합니다.

winapp run 는 입력에서 자동으로 선택된 두 가지 모드 중 하나로 작동합니다.

• 폴더 모드 - 입력은 빌드 출력 폴더(포함) Package.appxmanifest/AppxManifest.xml입니다.
• Project 모드 - 입력은 하나의 솔루션 또는 하나를 포함하는 디렉터리입니다.csproj/.sln.slnx. winapp run 는 프로젝트를 빌드하고 실행하여 패키지된 WinUI 앱과 패키지되지 않은 WinUI 앱을 모두 지원합니다. 아래 Project 모드를 참조하세요.

Tip

모드 선택은 기본적으로 자동입니다. 디렉터리가 프로젝트로 빌드될 것으로 예상할 때 빌드 출력 폴더로 처리된 경우 폴더 모드를 사용하여 다시 실행 --verbose 하면 디렉터리가 선택된 이유를 보고합니다(No .csproj/.sln/.slnx with a runnable app found in '<path>' — running it as a build-output folder.). 디렉터리는 실행 가능한 앱이 최상위 수준에 있을 때만.slnx.csproj/.sln/프로젝트로 빌드되며 재귀적으로 검색되지 않습니다.

이 명령은 대부분의 프레임워크(.NET, C++, Rust, Flutter, Tauri)에 대해 패키지 ID를 사용하여 디버깅하기 위한 기본 명령입니다. 단일 exe create-debug-identity 에 대해 스파스 패키지를 등록하는 것과 달리 winapp run 실제 MSIX 설치와 마찬가지로 전체 폴더를 느슨한 레이아웃 패키지로 등록합니다. 일반적인 디버깅 워크플로는 디버깅 가이드 를 참조하세요.

winapp run [<input>] [options]

인수:

• input - 실행할 앱: 빌드 출력 폴더(폴더 모드), .csproj 프로젝트, .sln/.slnx 솔루션 또는 최상위 수준(프로젝트 모드, 디렉터리가 재귀적으로 검색되지 않음) 중 하나가 포함된 디렉터리입니다. 현재 디렉터리에서 프로젝트를 빌드/실행하는 데 사용합니다 . . 선택 사항 - 생략할 때 현재 디렉터리 (일치)로 기본값이 지정 dotnet run됩니다.

옵션:

• --manifest <path> - Package.appxmanifest 경로(기본값: 입력 폴더 또는 현재 디렉터리에서 자동 검색)
• --output-appx-directory <path> - 느슨한 레이아웃 패키지의 출력 디렉터리(기본값: AppX 입력 폴더 디렉터리 내부)
• --args <string> - 애플리케이션에 전달할 명령줄 인수입니다. 또는 인수 뒤에 인수를 사용하여 -- 이스케이프를 방지합니다(예: winapp run . -- --flag value).
• --no-launch - 애플리케이션을 시작하지 않고 디버그 ID만 만들고 패키지를 등록합니다.
• --with-alias - AUMID 활성화 대신 실행 별칭을 사용하여 앱을 시작합니다. 앱은 상속된 stdin/stdout/stderr를 사용하여 현재 터미널에서 실행됩니다. 매니페스트에 있어야 uap5:ExecutionAlias 합니다(매니페스트를 추가하는 데 사용 winapp manifest add-alias ). 와 함께 --no-launch사용할 수 없습니다. 와 함께 --json사용할 수 없습니다.
• --debug-output - 시작된 애플리케이션에서 메시지 및 첫 번째 예외를 캡처 OutputDebugString 합니다. 프레임워크 노이즈(WinUI, COM, DirectX)는 콘솔 출력에서 필터링됩니다. 전체 로그 파일은 모든 것을 캡처합니다. 앱이 충돌하는 경우 자동으로 미니덤프를 캡처하고 분석하여 소스 파일:줄 번호(빌드 출력 폴더의 PDB에서 확인됨)를 사용하여 예외 유형, 메시지 및 스택 추적을 표시합니다. 관리되는(.NET) 크래시는 외부 도구 없이 즉시 분석됩니다. 네이티브(C++/WinRT) 크래시가 모듈 이름 및 오프셋을 표시합니다. 충돌된 앱이 WinUI 3 앱(Microsoft.UI.Xaml.dll 로드됨)인 경우 추가 저장 예외 심사 패스가 자동으로 실행되어 원래 HRESULT, ErrorContext 체인 및 전체 네이티브 XAML 디스패치 스택을 표시합니다. 필요한 디버거 구성 요소는 처음 사용할 때 다운로드됩니다(디 버깅 참조, 환경 변수를 통해 WINAPP_DBGTOOLS_DIR 재정의 가능). 한 번에 하나의 디버거만 프로세스에 연결할 수 있으므로 다른 디버거(Visual Studio, VS Code)를 동시에 사용할 수 없습니다. 다른 디버거를 연결해야 하는 경우 대신 사용합니다 --no-launch . 와 함께 --no-launch사용할 수 없습니다. 와 함께 --json사용할 수 없습니다.
• --symbols - 확인된 함수 이름으로 보다 풍부한 네이티브 크래시 분석을 위해 Microsoft 기호 서버에서 PDB 기호를 다운로드합니다. 와 함께 --debug-output만 사용됩니다. 생략하고 네이티브 크래시가 발생하면 출력에서 이 플래그를 추가하는 것이 좋습니다. 이 플래그는 WinUI 3 앱에 대한 WinUI 수납 예외 심사 스택도 향상시킵니다. 먼저 실행은 기호를 다운로드하고 로컬로 캐시합니다. 후속 실행에서는 캐시를 사용합니다.
• --unregister-on-exit - 애플리케이션이 종료된 후 개발 패키지의 등록을 취소합니다. 개발 모드에 등록된 패키지만 제거합니다. 와 함께 --no-launch사용할 수 없습니다.
• --detach - 애플리케이션을 시작하고 종료할 때까지 기다리지 않고 즉시 반환합니다. 시작 후 앱과 상호 작용해야 하는 CI/자동화에 유용합니다. PID를 stdout(또는 JSON 포함)으로 --json인쇄합니다. , --no-launch또는 --debug-output--with-alias.와 함께 --unregister-on-exit사용할 수 없습니다.
• --clean - 다시 배포하기 전에 기존 패키지의 애플리케이션 데이터(LocalState, 설정 등)를 제거합니다. 기본적으로 애플리케이션 데이터는 다시 배포에서 유지됩니다.
• --json - 프로그래밍 방식 사용을 위해 출력을 JSON으로 서식 지정합니다(예: CI/자동화). --detach PID를 캡처하는 데 유용합니다. 또는 --with-alias.와 함께 --debug-output 사용할 수 없습니다.

애플리케이션 데이터 지속성:

기본적으로 winapp run 다시 배포할 때 애플리케이션의 데이터(LocalState, RoamingState등 Settings)를 유지합니다. 앱이 패키지 컨텍스트에 ApplicationData.Current.LocalFolder 또는 Environment.GetFolderPath(SpecialFolder.LocalApplicationData) 패키지 컨텍스트 내에서 데이터를 쓰는 경우 해당 데이터는 호출에서 winapp run 유지됩니다.

새 시작이 필요한 경우(예: 손상된 상태를 다시 설정하거나 첫 실행 동작을 테스트하는 경우) 사용합니다 --clean .

기능 설명:

• Package.appxmanifest를 찾거나 생성합니다.
• 느슨한 레이아웃 패키지를 사용하여 디버그 ID를 만들고 등록합니다.
• AUMID(애플리케이션 사용자 모델 ID)를 계산합니다.
• 등록된 ID를 사용하여 애플리케이션을 시작합니다(지정되지 않은 경우 --no-launch ).
• 디버거 첨부 파일의 프로세스 ID(PID)를 인쇄합니다.

예:

# Register debug identity and launch app from build output
winapp run ./bin/Debug

# Launch with custom manifest and arguments
winapp run ./dist --manifest ./out/Package.appxmanifest --args "--my-flag value"

# Pass arguments after -- to avoid escaping (equivalent to --args)
winapp run ./bin/Debug -- --my-flag value

# Specify output directory for loose layout package
winapp run ./bin/Release --output-appx-directory ./AppXDebug

# Register identity without launching
winapp run ./bin/Debug --no-launch

# Launch via execution alias (console apps run in current terminal)
winapp run ./bin/Debug --with-alias

# Launch and capture OutputDebugString messages and crash diagnostics
winapp run ./bin/Debug --debug-output

# Download native symbols for richer crash analysis (C++/WinRT crashes)
winapp run ./bin/Debug --debug-output --symbols

# Combine with execution alias to debug console apps inline
winapp run ./bin/Debug --with-alias --debug-output

# Run and automatically clean up registration on exit
winapp run ./bin/Debug --with-alias --unregister-on-exit

# Launch and detach immediately (useful for CI/automation)
winapp run ./bin/Debug --detach

# Detach with JSON output (returns PID for scripting)
winapp run ./bin/Debug --detach --json

# Wipe application data (LocalState, settings) and start fresh
winapp run ./bin/Debug --clean

Project 모드(.NET SDK 프로젝트)

입력이 .csproj하나(포함.) winapp run 를 포함하는 디렉터리, .sln.slnx/솔루션 또는 디렉터리인 경우 프로젝트를dotnet build 빌드한 다음 시작합니다. 패키지된 WinUI 앱과 패키지되지 않은 WinUI 앱을 모두 지원하고, 앱이 시작하기 전에 필요한 런타임에 일치하는 아키텍처 Windows 앱 설치합니다.

솔루션 입력: (또는 하나의 디렉터리를 포함하는 디렉터리를 가리키 winapp run.sln.slnx/고, 솔루션은 느슨한 .csproj 파일보다 선호됨) 실행 가능한 앱 프로젝트를 확인한 다음, 정의된 형제 Solution* 속성을 사용하여 빌드 $(SolutionDir) 하므로 종속된 프로젝트는 Visual Studio 빌드됩니다. 해결 규칙:

• 테스트 프로젝트는 자동 선택 시 건너뛰므로 앱과 해당 테스트를 포함하는 솔루션이 필요 없이 --project 앱으로 확인됩니다. (WinUI 테스트 프로젝트 자체는 패키지된 앱이므로 출력 형식만으로는 구별할 수 없습니다.)
• 실행 가능한 유일한 프로젝트가 테스트 프로젝트인 경우 실행됩니다.
• 실행 가능한 앱 프로젝트가 두 개 이상 있는 경우 시작 프로젝트를 추측하지 않습니다. 즉, winapp run 후보를 나열하는 데 오류가 발생합니다. 테스트 프로젝트를 선택하는 것을 포함하여 항상 적용되는 옵션을 선택하는 데 사용합니다 --project <name> .

패키지된 항목과 패키지되지 않은 항목은 프로젝트의 유효 WindowsPackageType MSBuild 속성에서 자동으로 검색됩니다(매니페스트가 없음).

• 패키지됨 (WindowsPackageType=MSIXWinUI 패키지 기본값) - 빌드한 다음 빌드 출력을 느슨한 레이아웃 패키지로 등록하고 AUMID(폴더 모드와 동일한 파이프라인)를 통해 시작합니다.
• 패키지 해제(WindowsPackageType=None) - 빌드하고, 프레임워크 종속 Windows 앱 런타임이 설치되었는지 확인하고, 빌드 .exe 를 직접 시작합니다. 를 사용하여 패키지된 프로젝트에 대해 이 작업을 강제 적용 -p WindowsPackageType=None합니다.

Project 모드에는 .NET SDK 8.0.100 이상(MSBuild--getProperty의 경우)이 필요합니다.

Project 모드 옵션(폴더 모드에서는 무시됨):

• -c, --configuration <name> - 빌드 구성. 기본값: Debug.
• --arch <x64|arm64|x86> - 대상 아키텍처입니다. 기본값: 현재 프로세스 아키텍처입니다. 빌드 RID와 설치되는 Windows 앱 런타임의 아키텍처를 모두 결정합니다.
• -r, --runtime <rid>- 대상 .NET 런타임 식별자(예: win-x64). Project 모드는 RID의 아키텍처만 사용하고 항상 정식 win-<arch>모드를 빌드하며 Windows 없는 RID(예: linux-x64)를 거부합니다. 아키텍처가 재정의합니다.--arch
• -f, --framework <tfm> - 다중 대상 프로젝트(예: net10.0-windows10.0.26100.0)에 대한 대상 프레임워크 모니커입니다.
• --project <name-or-path> - 입력이 솔루션(.sln/.slnx) 또는 실행 가능한 앱 프로젝트가 여러 개 있는 디렉터리인 경우 프로젝트 이름 또는 경로별로 실행할 프로젝트를 선택합니다.
• --no-build - 빌드를 건너뛰고 기존 빌드 출력을 실행합니다(출력 속성은 계속 평가됨).
• --no-restore - 빌드하기 전에 프로젝트 복원을 건너뜁니다.
• -p, --property <Name=Value> - 빌드 및 속성 평가 모두에 전달되는 MSBuild 속성입니다. 반복 가능(예: -p WindowsPackageType=None).

빌드 출력 및 세부 정보: 프로젝트는 두 단계로 dotnet build 빌드됩니다. 즉, 출력 스트림이 콘솔에 상주 하고 빠른 속성 평가 패스가 붙습니다. winapp은 출력 전에 정확한 dotnet build … 호출을 출력하고 성공적인 빌드에서도 경고를 스트리밍합니다. 세부 정보 표시:

Flag	dotnet 세부 정보 표시	추가
(기본값)	minimal	—
--verbose	minimal	winapp의 빌드 결정 추적
--quiet	quiet	—

아래 --json 또는 --quiet 호출 및 빌드 출력이 stderr로 이동하므로 stdout은 순수 JSON/클린 상태를 유지합니다.

옵션 적용 가능성: ID/느슨한 레이아웃 옵션(--manifest, , --output-appx-directory, --no-launch--with-alias, --unregister-on-exit, --clean--executable)은 패키지된 앱에만 적용됩니다. 패키지되지 않은 앱(MSIX 패키지가 없음)에 대한 명확한 오류와 함께 거부됩니다. 시작/디버그 옵션(--args/--, , --debug-output--detach, --symbols--json)은 둘 다에서 작동합니다.

Project 모드 예제:

# Build and run the project in the current directory (input defaults to ".")
winapp run

# Run a specific project
winapp run ./src/MyApp/MyApp.csproj

# Build and run from a solution (resolves the runnable app project, defines $(SolutionDir))
winapp run ./MyApp.sln

# Pick a startup project when the solution has more than one runnable app
winapp run ./MyApp.sln --project MyApp

# Release build for arm64
winapp run . -c Release --arch arm64

# Force an unpackaged run of a packaged project
winapp run . -p WindowsPackageType=None

# Run the existing build output without rebuilding, and capture crash diagnostics
winapp run . --no-build --debug-output

# Show winapp's build decision traces (dotnet build stays at minimal verbosity)
winapp run . --verbose

# Launch and detach (prints PID), forwarding args to the app
winapp run . --detach -- --my-flag value

MSBuild 속성(NuGet 패키지):

Microsoft.Windows.SDK.BuildTools.WinApp NuGet 패키지를 사용하는 경우 dotnet run 자동으로 winapp run 호출합니다. 다음 MSBuild 속성을 컨트롤 동작에 .csproj 설정할 수 있습니다.

재산	Default	설명
EnableWinAppRunSupport	true	실행 지원 기능 사용/사용 안 함
WinAppLaunchArgs	(비어 있음)	시작할 때 앱에 전달할 인수
WinAppRunUseExecutionAlias	false	AUMID 활성화 대신 실행 별칭을 통해 시작
WinAppRunNoLaunch	false	시작하지 않고 ID만 등록
WinAppRunDebugOutput	false	메시지 및 첫 번째 예외를 캡처 OutputDebugString 합니다. 한 번에 하나의 디버거만 연결할 수 있습니다(VS/VS Code 방지). 대신 다른 디버거를 연결하는 데 사용합니다 WinAppRunNoLaunch .
WinAppRunDetach	false	앱이 종료되는 것을 기다리지 않고 실행 후 즉시 반환합니다. PID를 인쇄합니다.
WinAppRunUnregisterOnExit	false	앱이 종료된 후 개발 패키지 등록 취소
WinAppRunClean	false	다시 배포하기 전에 기존 패키지의 애플리케이션 데이터(LocalState, 설정)를 제거합니다.
WinAppRunSymbols	false	더 풍부한 네이티브 크래시 분석을 위해 Microsoft 기호 서버에서 기호를 다운로드합니다. 에만 효과가 있습니다 WinAppRunDebugOutput.
WinAppRunExecutable	(비어 있음)	빌드 출력 폴더를 기준으로 하는 실행 경로입니다. 매니페스트에 포함 $targetnametoken$ 되고 출력 폴더에 둘 .exe이상이 있는 경우 사용합니다.
WinAppRunArgs	(비어 있음)	전용 속성이 없는 옵션(예--verbose: )의 경우 명령줄에 원시 인수가 추가 winapp run 되었습니다. 위의 모든 속성에 추가됩니다.

상호 배타적인 설정입니다. WinAppRunNoLaunch 각각 WinAppRunDetach 다른 시작 동작을 설명하므로 다른 시작 속성과 서로 충돌합니다. 충돌하는 쌍을 설정하면 다음을 사용하여 실행 --X and --Y cannot be used together이 실패합니다.

재산	와 함께 사용할 수 없습니다.
WinAppRunNoLaunch	WinAppRunDetach, WinAppRunUseExecutionAlias, , WinAppRunDebugOutput, WinAppRunUnregisterOnExit
WinAppRunDetach	WinAppRunNoLaunch, WinAppRunUseExecutionAlias, , WinAppRunDebugOutput, WinAppRunUnregisterOnExit

WinAppRunUseExecutionAlias를 사용하여 WinAppRunDebugOutputWinAppRunUnregisterOnExit 서로 결합할 수 있습니다. WinAppRunClean, WinAppRunSymbols, WinAppRunExecutable및 WinAppLaunchArgs 제한 사항이 없습니다. WinAppRunArgs 는 자체 제한 사항을 추가하지 않지만 통과된 스위치는 다른 스위치와 같이 확인되므로 WinAppRunArgs="--detach" 여전히 충돌합니다 WinAppRunNoLaunch.

<PropertyGroup>
  <WinAppRunUseExecutionAlias>true</WinAppRunUseExecutionAlias>
  <WinAppRunDebugOutput>true</WinAppRunDebugOutput>
</PropertyGroup>

---

등록

테스트용으로 로드된 개발 패키지의 등록을 취소합니다. 개발 모드(예: 통해 winapp run 또는 create-debug-identity)에 등록된 패키지만 제거합니다. 스토어 설치 또는 MSIX 설치 패키지는 제거되지 않습니다.

winapp unregister [options]

옵션:

• --manifest <path> - Package.appxmanifest 경로(기본값: 현재 디렉터리에서 자동 검색)
• --force - 다른 프로젝트 트리에서 패키지를 등록한 경우에도 설치 위치 디렉터리 검사를 건너뛰고 등록을 취소합니다.
• --json - 출력을 JSON으로 서식 지정

기능 설명:

• 매니페스트에서 패키지 이름을 읽습니다.
• 패키지와 {name} 패키지를 모두 {name}.debug 검색합니다(디버그 변형은 에 의해 create-debug-identity생성됨).
• 각 패키지가 개발 모드로 등록되었는지 확인합니다(IsDevelopmentMode == true)
• 패키지의 설치 위치가 현재 디렉터리 트리 아래에 있는지 확인합니다(다음이 아닌 경우 --force).
• 일치하는 패키지 등록 취소

예:

# Unregister from current directory (auto-detects manifest)
winapp unregister

# Unregister with explicit manifest
winapp unregister --manifest ./Package.appxmanifest

# Force unregister even if registered from a different project tree
winapp unregister --force

# JSON output for scripting
winapp unregister --json

---

cert

개발 인증서를 생성, 검사 및 설치합니다.

인증서 생성

패키지 서명에 대한 개발 인증서를 생성합니다.

winapp cert generate [options]

옵션:

• --manifest <Package.appxmanifest> - Package.appxmanifest에서 게시자 정보 추출
• --publisher <name>- 인증서에 대한 Publisher. 전체 X.500 고유 이름(예: CN=Contoso, O=Contoso Ltd, C=US)을 허용하거나 자동으로 로 래핑되는 베어 이름을 허용합니다. CN=<name>
• --output <path> - 출력 인증서 파일 경로(절대 및 상대 경로 지원)
• --password <password> - 인증서 암호(기본값: "암호")
• --valid-days <valid-days> - 인증서가 유효한 일 수(기본값: 365)
• --install - 생성 후 로컬 컴퓨터 저장소에 인증서 설치
• --if-exists <Error|Overwrite|Skip> - 인증서 파일이 이미 있는 경우 동작 설정(기본값: 오류)
• --export-cer - 파일(공개 키만 해당)을 함께 내 .cer 보냅니다 .pfx. 신뢰 설치를 위해 공용 인증서를 별도로 배포하는 데 유용합니다.
• --json - 프로그래밍 방식으로 사용할 수 있는 JSON으로 출력 형식을 지정합니다. 오류도 JSON({"error": "..."})으로 반환됩니다.

인증서 정보

PFX 파일의 인증서 세부 정보를 표시합니다. 서명하기 전에 인증서가 매니페스트와 일치하는지 확인하는 데 유용합니다.

winapp cert info <cert-path> [options]

인수:

• cert-path - 인증서 파일 경로(PFX)

옵션:

• --password <password> - PFX 파일의 암호(기본값: "암호")
• --json - 출력을 JSON으로 서식 지정

인증서 설치

컴퓨터 인증서 저장소에 인증서를 설치합니다.

winapp cert install <cert-path> [options]

인수:

• cert-path - 설치할 인증서 파일 경로

예:

# Generate certificate for specific publisher
winapp cert generate --publisher "CN=My Company" --output ./mycert.pfx

# Generate certificate and export public key .cer file
winapp cert generate --publisher "CN=My Company" --export-cer

# Generate certificate with JSON output (for scripting)
winapp cert generate --publisher "CN=My Company" --json

# View certificate details
winapp cert info ./mycert.pfx

# View certificate details as JSON
winapp cert info ./mycert.pfx --json

# Install certificate to machine
winapp cert install ./mycert.pfx

---

서명

인증서를 사용하여 MSIX 패키지 및 실행 파일에 서명합니다.

winapp sign <file-path> [options]

인수:

• file-path - 서명할 MSIX 패키지 또는 실행 파일의 경로

옵션:

• --cert <path> - 서명 인증서 경로
• --cert-password <password> - 인증서 암호(기본값: "암호")

예:

# Sign MSIX package
winapp sign MyApp.msix --cert ./mycert.pfx

# Sign executable
winapp sign ./bin/MyApp.exe --cert ./mycert.pfx --cert-password mypassword

---

az-sign

클라우드 관리 서명 ID인 Azure 신뢰할 수 있는 서명 사용하여 파일(exe, MSIX 또는 MSIX 번들)을 코드 서명하므로 PFX(프라이빗 키)가 로컬 컴퓨터에 존재하지 않습니다.

winapp az-sign <file-path> [options]

인수:

• file-path - 서명할 파일의 경로(exe, msix 또는 msixbundle)

옵션:

• --subscription, -s - 사용할 구독 ID를 Azure. 제공되지 않고 여러 구독이 있는 경우 메시지가 표시됩니다.
• --resource-group, -r - 로그인 계정의 범위를 좁히는 리소스 그룹
• --account - 서명 계정 이름입니다. 다음을 사용해야 합니다. --resource-group
• --profile, -p - 인증서 프로필 이름입니다. 다음을 사용해야 합니다. --account
• --metadata-file, -m - 기존 metadata.json경로입니다. 리소스 검색 및 계정/프로필 선택 프롬프트를 건너뛰고 직접 서명합니다. 비대화형 Azure 자격 증명을 이미 사용할 수 있어야 합니다. CLI는 대화형 테넌트 프롬프트로 대체하거나 az loginnpm 프로그래밍 방식 API는 항상 비대화형이며 프롬프트 대신 실패합니다.

인증:

az-sign는 Azure 표준 자격 증명 체인(DefaultAzureCredential)을 사용합니다. CI/CD의 경우, 설정 AZURE_TENANT_IDAZURE_CLIENT_ID및 AZURE_CLIENT_SECRET (또는 GitHub Actions OIDC/관리 ID 사용). 기존 Azure CLI 세션(az loginGitHub 작업 포함 azure/login )도 모든 환경에서 적용됩니다. 자격 증명을 찾을 수 없고 세션이 대화형인 경우에만 시작 az login 됩니다az-sign.

사전 요구 사항:

• Azure 코드 서명 계정 및 인증서 프로필(ID 유효성 검사 후 Azure 포털에서 생성됨) 및 ID에 할당된 코드 서명 인증서 프로필 서명자 역할. 자세한 지침은 Azure 아티팩트 서명 빠른 시작 문서를 참조하세요.
• 컴퓨터 전체 x64 .NET 8 이상 런타임이 설치되었습니다. Azure 서명 클라이언트 라이브러리는 별도의 프로세스에서 로드되는 signtool.exe 관리되는 어셈블리입니다. winapp의 자체 포함 런타임은 이를 충족하지 않습니다. 런타임 로드 오류로 서명이 실패하는 경우 설치 https://dotnet.microsoft.com/download 합니다.
• Microsoft Visual C++ 재배포 가능 패키지(x64)입니다. Azure 서명 클라이언트 라이브러리는 VC++ 런타임에 따라 달라지고 winapp은 공식 클라이언트 도구 설치 관리자가 아닌 원시 NuGet 패키지를 다운로드하므로 이 종속성이 자동으로 설치되지 않습니다. 클린 머신은 .NET SignTool이 있는 경우에도 로드 실패할 수 있습니다. "애플리케이션을 올바르게 시작할 수 없습니다." 또는 dlib에서 누락된 DLL 오류로 0xc000007b서명이 실패하는 경우부터 https://aka.ms/vs/17/release/vc_redist.x64.exe 최신 x64 재배포 가능 파일을 설치합니다.

최소 권한 CI: 자동 검색(구독, 리소스 그룹, 계정 및 프로필 나열)에는 부모 범위에서 읽기 권한이 필요합니다. 모든 컬렉션 목록 호출을 방지하려면 부모 컬렉션을 열거하는 대신 직접 리소스 읽기(각 명명된 리소스의 GET)를 사용하여 계정 및 프로필의 유효성을 검사 --subscription--profile--resource-group--accountaz-sign 하므로 해당 계정 및 프로필로 범위가 지정된 보안 주체로 충분합니다. 그 중 하나를 생략하면 목록 호출이 다시 도입됩니다. 예를 들어 --subscription , 제외하면 ID가 액세스할 수 있는 구독 목록이 만들어지며 az-sign , 범위가 좁은 보안 주체는 이를 허용하지 않을 수 있습니다. 단일 인증서 프로필로만 범위가 지정된 보안 주체는 미리 생성된 --metadata-file (계정 엔드포인트 및 프로필을 직접 지정)을 전달하여 유효성 검사를 완전히 건너뛸 수 있습니다.

예:

# Interactive — discover/select subscription, account, and profile
winapp az-sign ./app.msix

# Fully specified — no prompting (ideal for CI/CD)
winapp az-sign ./app.msix --subscription <sub-id> --resource-group <rg> --account <account> --profile <profile>

# Reuse an existing metadata.json (skips resource discovery and selection; authentication may still prompt)
winapp az-sign ./app.msix --metadata-file ./metadata.json

---

create-external-catalog

CodeIntegrityExternal.cat 지정된 디렉터리에서 실행 파일의 해시가 포함된 카탈로그 파일을 생성합니다. 이 카탈로그는 패키지 자체에 포함되지 않은 외부 파일의 실행을 허용하기 위해 MSIX 스파스 패키지 매니페스트(AllowExternalContent)의 TrustedLaunch 플래그와 함께 사용됩니다.

이는 MSIX 패키지에 서명할 때 만드는 signtool.exe 방법과 AppxMetadata\CodeIntegrity.cat 비슷하지만 스파스/외부 위치 패키징에 사용할 외부 카탈로그를 생성합니다.

winapp create-external-catalog <input-folder> [options]

인수:

• input-folder - 처리할 실행 파일이 포함된 하나 이상의 디렉터리입니다. 여러 디렉터리를 세미콜론으로 구분(예: "dir1;dir2")

옵션:

• --recursive, -r - 하위 디렉터리의 파일 포함
• --use-page-hashes - 카탈로그를 생성할 때 페이지 해시 포함(페이지별 해시 데이터를 사용하여 더 큰 카탈로그 생성)
• --compute-flat-hashes - 카탈로그를 생성할 때 플랫 파일 해시 포함
• --if-exists <Error|Overwrite|Skip> - 출력 파일이 이미 있는 경우의 동작(기본값: Error)
• --output, -o - 출력 카탈로그 파일 경로입니다. 지정 CodeIntegrityExternal.cat 하지 않으면 현재 디렉터리에 만들어집니다. 디렉터리를 지정하면 기본 파일 이름이 추가됩니다.

기능 설명:

• 지정된 디렉터리에서 실행 파일(코드 섹션이 있는 PE 이진 파일)을 검색합니다.
• 찾은 모든 실행 파일의 해시를 사용하여 CDF(카탈로그 정의 파일)를 생성합니다.
• Windows CryptoCAT API를 사용하여 .cat 카탈로그 파일을 생성합니다.
• 실행 불가능한 파일(예: .txt.dll 코드 섹션 없음)은 자동으로 건너뜁니다.

예:

# Generate catalog for all executables in a directory
winapp create-external-catalog ./bin

# Include files in subdirectories
winapp create-external-catalog ./bin --recursive

# Specify a custom output path
winapp create-external-catalog ./bin --output ./dist/CodeIntegrityExternal.cat

# Overwrite existing catalog
winapp create-external-catalog ./bin --if-exists Overwrite

# Skip generation if catalog already exists
winapp create-external-catalog ./bin --if-exists Skip

# Include page hashes (for stricter code integrity validation)
winapp create-external-catalog ./bin --use-page-hashes

# Process multiple directories
winapp create-external-catalog "./bin;./lib" --recursive

# Combine multiple options
winapp create-external-catalog ./bin --recursive --use-page-hashes --compute-flat-hashes --output ./dist/CodeIntegrityExternal.cat --if-exists Overwrite

사용 시기:

TrustedLaunch를 사용하여 외부 실행 파일을 확인하는 스파스 MSIX 패키지를 빌드할 때 이 명령을 사용합니다. 일반적인 워크플로는 다음과 같습니다.

1. winapp manifest generate --template sparse — 다음을 사용하여 스파스 매니페스트 만들기 AllowExternalContent
2. winapp create-external-catalog ./bin — 앱의 실행 파일에 대한 코드 무결성 카탈로그 생성
3. winapp pack — 매니페스트, 자산 및 카탈로그를 MSIX에 패키지

---

도구

Windows SDK 도구에 직접 액세스하세요. Microsoft.Windows 사용할 수 있는 도구를 사용합니다. Sdk. BuildTools

winapp tool <tool-name> [tool-arguments]

사용 가능한 도구:

• makeappx - 앱 패키지 만들기 및 조작
• signtool - 파일 서명 및 서명 확인
• mt - 병렬 어셈블리에 대한 매니페스트 도구
• Microsoft.Windows 기타 Windows SDK 도구도 있습니다. Sdk. BuildTools

예:

# Use signtool to verify signature
winapp tool signtool verify /pa MyApp.msix

---

store

Microsoft Store 개발자 CLI 명령을 실행합니다. 이 명령은 아직 다운로드하지 않은 경우 Microsoft Store Developer CLI를 다운로드합니다. Microsoft Store 개발자 CLI 대해 자세히 알아봅니다.

winapp store [args...]

인수:

• args... – CLI에 직접 전달할 인수입니다 msstore . 사용 가능한 명령 및 옵션은 MSStore CLI 설명서를 참조하세요.

기능 설명:

• Microsoft Store 개발자 CLI(msstore)가 다운로드되어 시스템에서 사용할 수 있는지 확인합니다.
• 모든 인수를 CLI에 msstore 전달합니다.
• 터미널에서 직접 출력을 보여 주는 명령을 실행합니다.

예:

# List all apps in your Microsoft Partner Center account
winapp store app list

# Publish a package to the Microsoft Store
winapp store publish ./myapp.msix --appId <your-app-id>

---

get-winapp-path

설치된 Windows SDK 구성 요소에 대한 경로를 가져옵니다.

winapp get-winapp-path [options]

반환되는 내용:

• .winapp 작업 영역 디렉터리의 경로
• 패키지 설치 디렉터리
• 생성된 헤더 위치

---

find-ui

WinUI 컨트롤 및 샘플에서 작업 코드 예제를 검색합니다. WinUI 전용: 코퍼스는 WinUI 3 갤러리 및 Windows 커뮤니티 도구 키트(및 몇 가지 큐레이팅된 핵심 패턴)이며 WPF, WinForms 또는 기타 UI 프레임워크를 다루지 않습니다. 세 번째 소스인 microsoft-ui-reactor ReactorGallery는 옵트인입니다. 일반 검색에서 제외되고 전달 --source reactor 될 때만 검색됩니다(C#전용 선언적 샘플은 표준 XAML 앱에 붙여넣지 않으므로 Reactor/MVU 프로젝트를 빌드할 때만 도달함).

winapp find-ui "<query>" [options]

코퍼스는 처음 사용할 때 GitHub 가져와 사용자<global .winapp>/cache/find-ui별로 캐시되므로 첫 번째 실행에는 네트워크 액세스가 필요합니다. 후속 실행은 로컬 캐시에서 제공됩니다(최대 7일마다 또는 요청 시 --refresh새로 고침됨).

옵션:

• --id <id> - 코드를 가져옵니다(Gallery/Toolkit은 XAML 및/또는 C#을 반환합니다. Reactor는 C#전용이며 이전 검색에서 하나 이상의 시나리오 ID(예: gallery-tabview-1)에 대한 필수 구성 요소 노트를 추가합니다. 반복. ID는 대/소문자를 구분GALLERY-TABVIEW-1 하지 않습니다.gallery-tabview-1
• --list - 검색하는 대신 검색 가능한 모든 컨트롤/샘플 ID를 나열합니다(갤러리 + 도구 키트 + 코어, 옵트인 Reactor 원본은 제외됨).
• --source <gallery|toolkit|reactor|core> - 검색 결과를 단일 원본으로 제한합니다. (검색 전용 - .으로 --list/--id는 유효하지 않음) Reactor는 옵트인(opt-in )이며 일반 검색에서 제외되므로 --source reactor 검색하는 유일한 방법입니다.
• --max <N> - 반환할 일치 컨트롤의 최대 수(기본값: 3). 검색에만 적용됩니다. 을 사용하여 무시됩니다 --list/--id.
• --refresh- 로컬 캐시를 우회하고 GitHub WinUI 모음을 다시 가져옵니다.
• --json - 구조화된 JSON(에이전트 친화적)을 내보냅니다. 검색의 경우 각 일치 항목은 sourcescoredescriptioncontrol시나리오 idheader별 및 전체 코드에 대해 ;를 포함하는 배열, , 및 scenarios 배열을 --id전달합니다. --json 정수가 아닌 오류와 같은 인수/파서 오류를 비롯한 모든 오류에서 --max 0이 아닌 종료 코드가 있는 stdout의 플랫 {"error": "..."} 개체로 내보내지므로 출력은 컴퓨터에서 읽을 수 있게 유지됩니다.

워크플로: 압축적으로 검색하여 올바른 컨트롤과 해당 시나리오 ID를 찾은 다음, 가장 일치하는 --id전체 코드를 가져옵니다.

예:

# Find a control by intent (compact results with scenario ids)
winapp find-ui "tabbed layout"

# Restrict to the Windows Community Toolkit
winapp find-ui "settings card" --source toolkit

# Restrict to Reactor (opt-in; C#-only declarative WinUI — Reactor projects only)
winapp find-ui "flex layout" --source reactor

# Fetch the full XAML + C# for a specific scenario
winapp find-ui --id gallery-tabview-1

# Agent-friendly structured output
winapp find-ui "color picker" --json

# Browse everything, or force a corpus refresh
winapp find-ui --list
winapp find-ui "navigation view" --refresh

---

node generate-bindings

(NPM 패키지에서만 사용 가능) Windows 앱 SDK API에 대한 JS 바인딩을 생성합니다. 바인딩은 네임스페이스에 "winapp": { "jsBindings": {...} } 의해 package.json 선언되고 에 기록.winapp/bindings/됩니다.

npx winapp node generate-bindings [options]

옵션:

• --verbose, -v - 파일별 자세한 코드 생성 출력 사용
• --quiet, -q - 진행률 및 정보 출력 표시 안 함

기능 설명:

• 마지막에 의해 작성된 블록 과 블록을 읽은 다음 형식화된 바인딩을
• 수정 package.json 않습니다. 수동 다시 생성자입니다. winapp.jsBindings 블록 추가 및 @microsoft/dynwinrt 런타임 종속성은 JS 바인딩을 사용하는 동안 winapp init 발생합니다. 블록이 없으면 이 명령이 빠르게 실패합니다.
• 종속성에서 누락된 경우 @microsoft/dynwinrt 경고(하지만 작성하지 않음) - 추가한 후 npm install 실행 init

비고

바인딩은 npm 전용이며(npm 패키지)npx winapp를 통해 @microsoft/winappcli 호출해야 합니다. 독립 실행형 winget CLI는 이를 표시하지 않습니다. 이 명령을 사용하여 바인딩을 다시 생성하기 전에 대화형으로 실행하고 winapp init 옵트인하거나 사용합니다 winapp init . --use-defaults --add-js-bindings. 편집winapp.yaml하는 경우 다시 생성하기 전에 Windows 종속성을 새로 고치려면 실행 npx winapp restore 합니다.

예:

# Regenerate JS bindings in the current project
npx winapp node generate-bindings

# Regenerate after editing winapp.jsBindings, with verbose output
npx winapp node generate-bindings --verbose

엔드 투 엔드 워크플로 및 구성 옵션에 대한 JS 바인딩 가이드 를 winapp.jsBindings 참조하세요.

---

node create-addon (노드 추가 기능 생성)

(NPM 패키지에서만 사용 가능) Windows SDK 및 Windows 앱 SDK 통합을 사용하여 네이티브 C++ 또는 C# 추가 기능 템플릿을 생성합니다.

npx winapp node create-addon [options]

옵션:

• --name <name> - Addon 이름(기본값: "nativeWindowsAddon")
• --template - 추가 기능 유형을 선택합니다. 옵션은 다음과 cs 같습니다cpp(기본값: cpp).
• --verbose - 자세한 정보 표시 출력 사용

기능 설명:

• 템플릿 파일을 사용하여 추가 기능 디렉터리를 만듭니다.
• Windows SDK 예제를 사용하여 binding.gyp 및 addon.cc 생성합니다.
• 필요한 npm 종속성(nan, node-addon-api, node-gyp)을 설치합니다.
• package.json 빌드 스크립트 추가

예:

# Generate addon with default name
npx winapp node create-addon

# Generate custom named addon
npx winapp node create-addon --name myWindowsAddon

---

노드 add-electron-debug-identity 명령어 실행

(NPM 패키지에서만 사용 가능) 스파스 패키징을 사용하여 Electron 개발 프로세스에 앱 ID를 추가합니다. Package.appxmanifest가 필요합니다(패키지가 있거나 winapp init 없는 경우 만들기winapp manifest generate).

중요합니다

웹 콘텐츠를 렌더링할 때 앱이 충돌하거나 렌더링되지 않는 스파스 패키징 Electron 애플리케이션에 알려진 문제가 있습니다. 이 문제는 Windows 해결되었지만 아직 외부 Windows 디바이스로 전파되지 않았습니다. 호출 add-electron-debug-identity후 이 문제가 표시되는 경우 플래그를 사용하여 디버그 목적으로 Electron 앱에서 샌드박싱 을 --no-sandbox 사용하지 않도록 설정할 수 있습니다. 이 문제는 전체 MSIX 패키징에 영향을 주지 않습니다.

Electron 디버그 정체성을 실행 취소하려면 winapp node clear-electron-debug-identity를 사용합니다.

npx winapp node add-electron-debug-identity [options]

옵션:

Option	설명
--manifest <path>	사용자 지정 Package.appxmanifest에 대한 경로(기본값: 현재 디렉터리의 Package.appxmanifest)
--no-install	종속성을 설치하거나 수정하지 마세요. Electron 디버그 ID만 구성
--keep-identity	매니페스트 ID를 그대로 유지하고, 패키지 이름 및 애플리케이션 ID에 .debug를 추가하지 마십시오.
--verbose	자세한 정보 출력 사용

기능 설명:

• electron.exe 프로세스에 대한 디버그 ID를 등록합니다.
• Electron 개발에서 ID가 필요한 API 테스트 사용
• ID 구성에 기존 Package.appxmanifest 사용

예:

# Add identity to Electron development process
npx winapp node add-electron-debug-identity

# Use a custom manifest file
npx winapp node add-electron-debug-identity --manifest ./custom/Package.appxmanifest

---

node clear-electron-debug-identity

(NPM 패키지에서만 사용 가능) 백업에서 원래 electron.exe 복원하여 Electron 디버그 프로세스에서 패키지 ID를 제거합니다.

npx winapp node clear-electron-debug-identity [options]

옵션:

Option	설명
--verbose	자세한 정보 출력 사용

기능 설명:

• 에서 만든 백업에서 electron.exe 복원합니다. add-electron-debug-identity
• 복원 후 백업 파일을 제거합니다.
• 패키지 ID 없이 Electron을 원래 상태로 반환합니다.

예:

# Remove identity from Electron development process
npx winapp node clear-electron-debug-identity

---

전역 옵션

모든 명령은 다음과 같은 전역 옵션을 지원합니다.

• --verbose, -v - 자세한 로깅에 자세한 정보 표시 출력 사용
• --quiet, -q - 진행률 메시지 표시 안 함
• --help, -h - 명령 도움말 표시

---

전역 캐시 디렉터리

Winapp은 여러 프로젝트 간에 공유할 수 있는 파일을 캐시하는 디렉터리를 만듭니다.

기본적으로 winapp은 전역 캐시 디렉터리 $UserProfile/.winapp 로 디렉터리를 만듭니다.

다른 위치를 사용하려면 환경 변수를 WINAPP_CLI_CACHE_DIRECTORY 설정합니다.

cmd:

REM Set a custom location for winapp's global cache
set WINAPP_CLI_CACHE_DIRECTORY=d:\temp\.winapp

PowerShell 및 pwsh에서:

# Set a custom location for winapp's global cache
$env:WINAPP_CLI_CACHE_DIRECTORY=d:\temp\.winapp

Winapp은 같은 init 명령을 restore실행할 때 자동으로 이 디렉터리를 만듭니다.

업데이트 검사

winapp CLI는 주기적으로 새 버전을 확인하고 업데이트를 사용할 수 있는 경우 한 줄로 알림을 표시합니다. 이 검사는 백그라운드에서 실행되며 명령에 대기 시간을 추가하지 않습니다.

업데이트 검사는 CI 환경(GitHub Actions, Azure Pipelines 등)에서 자동으로 비활성화됩니다.

업데이트 검사를 수동으로 사용하지 않도록 설정하려면 환경 변수를 WINAPP_CLI_UPDATE_CHECK .로 0설정합니다.

cmd:

set WINAPP_CLI_UPDATE_CHECK=0

PowerShell 및 pwsh에서:

$env:WINAPP_CLI_UPDATE_CHECK = "0"

이 영구를 만들려면 다음을 수행합니다.

[System.Environment]::SetEnvironmentVariable('WINAPP_CLI_UPDATE_CHECK', '0', 'User')

ui

UIA(UI 자동화)를 사용하여 실행 중인 Windows 앱 UI를 검사하고 상호 작용합니다.

winapp ui [command] [options]

명령을:

• status - 앱에 연결하고 정보 표시
• inspect - 요소 트리 보기
• search - 선택기로 요소 찾기
• get-property - 요소 속성 읽기
• get-text / get-value - 요소(TextPattern, ValuePattern 또는 Name)에서 값/텍스트를 읽습니다.
• screenshot - PNG로 창/요소 캡처(대화 자동 캡처 별도로)
• record- H.264 MP4 비디오에 창/요소 영역 녹화(그래픽 캡처 + 미디어 파운데이션 Windows)
• invoke - 요소 활성화(클릭, 토글, 확장)
• click - 마우스 시뮬레이션을 통해 요소 클릭(호출을 지원하지 않는 컨트롤의 경우)
• hover - 마우스를 요소로 이동하여 도구 설명, 플라이아웃 및 호버 상태 트리거(기본 연산: 800ms)
• drag - 요소 선택기 또는 화면 x,y 좌표(순서 변경, 크기 조정, 슬라이더, 끌어서 놓기)를 사용하여 마우스를 한 지점에서 다른 지점으로 끕니다.
• touch - 요소 중심 또는 화면 x,y 좌표에 가상 터치 제스처 삽입(탭, 두 번 탭, 긴 누름, 살짝 밀기, 손가락 모으기, 스트레치)
• pen - 가상 펜/스타일러스 입력 삽입 - 구성 가능한 압력, 기울기 및 지우개 모드로 탭 및 잉크 스트로크
• send-keys - 가상 키보드 입력(명명된 키, 콤보, 원시 vk=0xNN 또는 리터럴 텍스트)을 창으로 보내기
• set-value - 편집 가능한 요소(텍스트, 숫자)에 값을 설정합니다. 는 TextPattern 전용 리치 편집 컨트롤에 대한 LegacyIAccessible put_accValue 로 대체됩니다.
• focus - 키보드 포커스 이동
• scroll-into-view - 스크롤 요소 표시
• wait-for - 요소 상태 대기
• list-windows - 앱의 모든 창 나열
• get-focused - 현재 포커스가 있는 요소 보고

옵션:

• -a, --app <app> - 대상 앱(이름, 제목 또는 PID)
• -w, --window <hwnd> - HWND별 대상 창(안정)

ui 레코드

H.264 MP4에 창 또는 요소 영역을 기록합니다.

# Record a window for 10 seconds at 15 fps
winapp ui record -a Calculator --duration-sec 10 --fps 15 -o demo.mp4

# Record until Ctrl+C, downscaled so the longest edge is 1280px
winapp ui record -a "My App" --duration-sec 0 --max-edge 1280 -o capture.mp4

# Record just one element's region
winapp ui record -a "My App" btn-save-1234 -o button.mp4

# Keep an agent-readable timeline alongside the MP4
winapp ui record -a Calculator --frames --duration-sec 10 --fps 10 -o demo.mp4

레코드 옵션:

• --duration-sec <n> - 기록 길이(초)입니다. 0 는 Ctrl+C(기본값 0)까지 레코드를 기록합니다.
• --fps <n> - 캡처할 초당 프레임(기본값 15)입니다.
• --max-edge <px> - 다운스케일이므로 가장 긴 가장자리는 대부분의 픽셀(0 = 다운스케일 없음)입니다.
• --capture-screen - 오버레이/팝업이 포함되도록 화면에서 캡처합니다(폐색 창을 캡처할 수 있음).
• -o, --output <path> - 출력 .mp4 경로(기본값: recording-<timestamp>-<guid>.mp4).
• --frames- 타임스탬프가 지정된 JPEG frames.ndjsonmanifest.json<output-name>.frames를 작성하고 1GiB 프레임 데이터 한도를 사용하여 1-30fps 및 --max-edge 64-4096(기본값 1280)을 지원합니다.

최종 --json결과에는 출력 경로, 차원, 코덱, 캡처 모드, 주기, 중지 이유, 선택 사항 frameArtifacts및 경고가 포함됩니다.

알려진 제한 사항: 자체 최상위 창(WinUI/XAML 플라이아웃, 교육 팁, 도구 설명)에서 렌더링되는 팝업 내에 특정 요소를 기록하면 대신 기본 주 창을 캡처할 수 있습니다. 전체 창을 기록하거나 팝업 스틸에 사용합니다 ui screenshot --capture-screen . #646에서 추적됩니다.

전체 설명서는 docs/ui-automation.md를 참조하세요.