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 - 구성 파일 작업만 처리하고 패키지 설치를 건너뜁니다.
  • --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 해당 디렉터리에서 호환되는 프로젝트만 확인합니다.
  • (또는--no-prompt)가 디렉터리 인수 init 없이 설정된 경우 --use-defaults 검색을 건너뛰고 현재 디렉터리를 비대화형으로 초기화합니다. 알려진 프로젝트 형식이 검색되지 않은 경우 먼저 경고합니다(예: 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 사용).

예:

# 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 헤더 및 이진 파일을 다시 생성합니다.
  • 공유 가능한 파일을 전역 캐시 디렉터리에 저장합니다.

비고

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 번들을 만듭니다.

옵션:

  • --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 배포 처리
  • 인증서가 제공된 경우 패키지 서명

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 아키텍처당 하나의 .msix 입력 폴더를 만듭니다.msixbundle.

# 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

나타나다

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)

템플릿:

매니페스트 자리 표시자

생성된 매니페스트는 패키징 시 자동으로 해결되는 토큰(달러 기호로 구분된)을 사용합니다. $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를 반환합니다.

이 명령은 대부분의 프레임워크(.NET, C++, Rust, Flutter, Tauri)에 대해 패키지 ID를 사용하여 디버깅하기 위한 기본 명령입니다. 단일 exe create-debug-identity 에 대해 스파스 패키지를 등록하는 것과 달리 winapp run 실제 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) 크래시가 모듈 이름 및 오프셋을 표시합니다. 충돌된 앱이 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

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 . 
<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

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]

사용 가능한 도구:

예:

# 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 generate-bindings

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

npx winapp node generate-bindings [options]

옵션:

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

기능 설명:

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

비고

바인딩은 npm 전용이며(npm 패키지)@microsoft/winappcli를 통해 npx winapp 호출해야 합니다. 독립 실행형 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 비디오에 기록합니다. 프레임은 Windows 그래픽 캡처(PrintWindow 대체)를 통해 캡처되고 Media Foundation으로 증분 방식으로 인코딩되므로 긴 녹음은 메모리에 버퍼링되지 않습니다.

# 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

레코드 옵션:

  • --duration-sec <n> - 기록 길이(초)입니다. 0 는 Ctrl+C(기본값 0)까지 레코드를 기록합니다.
  • --fps <n> - 캡처할 초당 프레임(기본값 15)입니다.
  • --max-edge <px> - 다운스케일이므로 가장 긴 가장자리는 대부분의 픽셀(0 = 다운스케일 없음)입니다.
  • --capture-screen - 오버레이/팝업이 포함되도록 화면에서 캡처합니다(폐색 창을 캡처할 수 있음).
  • -o, --output <path> - 출력 .mp4 경로(기본값: recording-<timestamp>-<guid>.mp4).

를 사용하면 출력, , widthheightfileSizeframescodec () 및 mode 캡처 경로가"h264" 실제로 사용된(wgc또는screenprintwindow)를 포함한 봉투를 내 UiRecordResult 보냅니다.path--json

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

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

  • Last updated on