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 - 구성 파일 작업만 처리하고 패키지 설치를 건너뜁니다.

기능 설명:

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

자동 .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 사용).

예:

# 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

팁: 초기 설정 후 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 사용합니다.

복원

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

winapp restore [options]

옵션:

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

기능 설명:

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

예:

# 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 만들려면)

winapp pack <input-folder> [options]

인수:

• input-folder - 패키지할 애플리케이션 파일이 포함된 디렉터리

옵션:

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

기능 설명:

• Package.appxmanifest 파일의 유효성을 검사하고 처리합니다.
• 매니페스트에서 토큰을 확인합니다 $placeholder$ (아래 매니페스트 자리 표시자 참조).
• 적절한 프레임워크 종속성을 보장합니다.
• 나란히 배치된 매니페스트를 등록과 함께 업데이트합니다.
• 타사 WinRT 구성 요소를 자동으로 검색하고 활성화 가능한 클래스를 등록합니다(아래 WinRT 구성 요소 검색 참조).
• 자체 포함된 WinAppSDK 배포 처리
• 인증서가 제공된 경우 패키지 서명

WinRT 구성 요소 검색

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

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

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

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

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

디버그 아이덴티티 생성

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

이 대winapp run: exe가 앱 코드(예: 있는 Electron 앱 electron.exenode_modules)에서 분리된 경우 또는 특히 스파스 패키지 동작을 테스트할 때 사용합니다create-debug-identity. 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

나타나다

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

매니페스트 생성

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

winapp manifest generate [directory] [options]

인수:

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

옵션:

• --package-name <name> - 패키지 이름(기본값: 폴더 이름)
• --publisher-name <name> - Publisher CN(기본값: CN=< 동시 사용자>)
• --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$

이는 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를 반환합니다.

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

winapp run <input-folder> [options]

인수:

• input-folder - 실행할 앱이 포함된 디렉터리(필수)

옵션:

• --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) 크래시가 모듈 이름 및 오프셋을 표시합니다. 한 번에 하나의 디버거만 프로세스에 연결할 수 있으므로 다른 디버거(Visual Studio, VS Code)를 동시에 사용할 수 없습니다. 다른 디버거를 연결해야 하는 경우 대신 사용합니다 --no-launch . 와 함께 --no-launch사용할 수 없습니다. 와 함께 --json사용할 수 없습니다.
• --symbols - 확인된 함수 이름으로 보다 풍부한 네이티브 크래시 분석을 위해 Microsoft 기호 서버에서 PDB 기호를 다운로드합니다. 와 함께 --debug-output만 사용됩니다. 생략하고 네이티브 크래시가 발생하면 출력에서 이 플래그를 추가하는 것이 좋습니다. 먼저 실행은 기호를 다운로드하고 로컬로 캐시합니다. 후속 실행에서는 캐시를 사용합니다.
• --unregister-on-exit - 애플리케이션이 종료된 후 개발 패키지의 등록을 취소합니다. 개발 모드에 등록된 패키지만 제거합니다. 와 함께 --no-launch사용할 수 없습니다.
• --detach - 애플리케이션을 시작하고 종료할 때까지 기다리지 않고 즉시 반환합니다. 시작 후 앱과 상호 작용해야 하는 CI/자동화에 유용합니다. PID를 stdout(또는 JSON 포함)으로 --json인쇄합니다. , --debug-output또는 --with-alias--unregister-on-exit.와 함께 --no-launch사용할 수 없습니다.
• --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

MSBuild 속성(NuGet 패키지):

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

<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}.debug 패키지를 모두 {name} 검색합니다(디버그 변형은 에 의해 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 이름
• --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

create-external-catalog

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

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

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 작업 영역 디렉터리의 경로
• 패키지 설치 디렉터리
• 생성된 헤더 위치

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

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

npx winapp node create-addon [options]

옵션:

• --name <name> - Addon 이름(기본값: "nativeWindowsAddon")
• --template - 추가 기능 유형을 선택합니다. 옵션은 다음과 cpp 같습니다cs(기본값: 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 manifest generate 없는 경우 만들기winapp init).

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

옵션:

기능 설명:

• 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]

옵션:

기능 설명:

• 에서 만든 백업에서 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실행할 때 자동으로 이 디렉터리를 만듭니다.

ui

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

winapp ui [command] [options]

명령을:

• status - 앱에 연결하고 정보 표시
• inspect - 요소 트리 보기
• search - 선택기로 요소 찾기
• get-property - 요소 속성 읽기
• get-text / get-value - 요소(TextPattern, ValuePattern 또는 Name)에서 값/텍스트를 읽습니다.
• screenshot - PNG로 창/요소 캡처(대화 자동 캡처 별도로)
• invoke - 요소 활성화(클릭, 토글, 확장)
• click - 마우스 시뮬레이션을 통해 요소 클릭(호출을 지원하지 않는 컨트롤의 경우)
• set-value - 편집 가능한 요소에 값 설정(텍스트, 숫자)
• focus - 키보드 포커스 이동
• scroll-into-view - 스크롤 요소 표시
• wait-for - 요소 상태 대기
• list-windows - 앱의 모든 창 나열
• get-focused - 현재 포커스가 있는 요소 보고

옵션:

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

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