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또는 실험적 Reactor 템플릿(예: reactor 또는 reactor-mvu)) 런타임에 설치된 팩에 대해 유효성을 검사합니다. 실행 winapp new --list 하면 모든 항목이 표시됩니다. 기본값: winui (빈 XAML 앱)
• -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으로 서식 지정

템플릿:

이 팩에는 두 가지 스타일의 WinUI 앱이 제공됩니다. XAML 템플릿은 C# 코드 숨김을 사용하여 태그에서 UI를 정의합니다. Reactor 템플릿은 MVU(Model-View-Update) 패턴을 사용하여 XAML이 없는 순수 C#입니다. 템플릿 목록은 설치된 팩에서 실시간으로 읽혀지므로 항상 사용 중인 버전을 반영합니다. 현재 집합을 보려면 실행 winapp new --list 합니다. 일반적인 템플릿:

짧은 이름	설명
winui	최소 빈 XAML 앱(MSIX 패키징)
winui-navview	XAML NavigationView 시작 앱
winui-tabview	XAML TabView 시작 앱
winui-mvvm	XAML MVVM 앱(CommunityToolkit.Mvvm)
winui-lib	WinUI 3 클래스 라이브러리
winui-unittest	패키지된 MSTest 앱; 테스트가 시작될 때 실행됨
reactor	실험적인. 빈 Reactor 앱 - 순수 C#, XAML 없음
reactor-mvu	실험적인. MVU 패턴을 보여주는 Reactor 앱
reactor-navview	실험적인. Reactor NavigationView 시작 앱
reactor-tabview	실험적인. Reactor TabView 시작 앱

반응기 템플릿은 실험적입니다. 이후 릴리스에서 API를 변경하거나 제거할 수 있는 시험판 Microsoft.UI.Reactor 패키지를 참조합니다. winapp new대화형 선택기 및 대화형 선택기에서 --list(실험적)을 표시하고, 설정하고 "Experimental": true--json, 스캐폴딩한 후 경고를 출력합니다. 기본 템플릿으로 선택되지 않습니다. 또한 Reactor에는 .NET 10개 이상의 SDK가 필요합니다. 이전 SDK winapp new 에서는 빌드할 수 없는 프로젝트를 스캐폴딩하는 대신 필요한 버전으로 미리 실패합니다.

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

템플릿 팩 버전 관리:

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

첫 번째 실행은 더 오래 걸릴 수 있습니다. 템플릿 팩을 설치하거나 업데이트하거나 선택한 템플릿에서 사용하는 누락된 Windows 앱 SDK NuGet 패키지를 복원하려면 추가 다운로드가 필요할 수 있습니다. 이 문제는 새 Windows 앱 SDK 버전이 게시된 후에도 발생할 수 있습니다. 10초 winapp new 후에도 스캐폴딩이 계속 실행되는 경우 패키지가 다운로드 또는 복원 중일 수 있음을 나타내도록 상태 메시지를 업데이트합니다.

기능 설명:

• 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

# Experimental Reactor app (pure C#, no XAML) — requires the .NET 10 SDK
winapp new --name MyApp --template reactor-mvu

# 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 [base-directory] [options]

인수:

• base-directory - 복원할 디렉터리(기본값: 현재 디렉터리). 또한 재정의하지 않는 한 --config-dir 어디에서 winapp.yamlnuget.config 읽는지 선택합니다.

옵션:

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

기능 설명:

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

비고

.NET 프로젝트의 경우 SDK 버전이 winapp.yaml 항목 .csproj 으로 라이브 상태 PackageReference 이므로 winapp restore 실행됩니다dotnet restore.

예:

# Restore from winapp.yaml in current directory
winapp restore

# Restore a specific project directory (reads ./my-project/winapp.yaml)
winapp restore ./my-project

사용자 지정 및 프라이빗 NuGet 피드:

winapp init를 선택하고restoreupdate, NuGet을 통해 Windows SDK 및 Windows 앱 SDK 패키지를 다운로드하여 표준 nuget.config 계층 구조를 준수합니다. 프라이빗 피드 및 미러, 피드 자격 증명(자격 증명 공급자 포함) 및 사용자 지정 globalPackagesFolder 은 모두 다음과 같이 dotnet restore작동합니다. 고유한 미러 <clear /> 에서만 복원하려면 상속된 원본을 추가하고 사용자만 추가합니다.

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <packageSources>
    <clear />
    <add key="contoso" value="https://pkgs.dev.azure.com/contoso/_packaging/winsdk-mirror/nuget/v3/index.json" />
  </packageSources>
</configuration>

비고

네이티브 프로젝트의 경우 winapp이 nuget.config 작동하는 디렉터리에서 확인됩니다.restoreinit/디렉터리 인수( --config-dir 지정된 경우)이고, 그렇지 않으면 현재 디렉터리입니다. .NET 프로젝트의 경우 원본은 프로젝트 dotnet add packagedotnet restore 고유 nuget.config 의 계층 구조에서 가져오므로 프로젝트 디렉터리 또는 상위 항목에 프라이빗 피드의 구성을 배치합니다. --config-dir 프로젝트에서 복원할 수 없는 버전을 자동으로 선택하는 대신 해당 계층 구조 외부가 보고되고 무시됩니다. 신뢰할 수 있는 디렉터리에 대해서만 이러한 명령을 실행합니다. 동일한 주의가 적용됩니다 dotnet 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 만들려면)

단일 .csproj 프로젝트를 전달하여 프로젝트를 빌드하고 출력을 한 단계로 패키징합니다(프로젝트 모드, 바로 아래 프로젝트 패키징 참조). 여러 입력 폴더를 전달하여 다중 아키텍처 배포를 만듭니 .msixbundle 다(아래 다중 아키텍처 번들 참조).

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

인수:

• input-folder - 빌드 및 패키지할 단일 .csproj (프로젝트 모드) 또는 패키지할 애플리케이션 파일이 포함된 하나 이상의 디렉터리입니다. 여러 폴더(예: ./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 - 새 개발 인증서 생성
• --no-sign - 프로젝트 서명 구성(예: 스토어 제출 또는 외부 서명 파이프라인)을 재정의하여 서명되지 않은 패키지를 배달합니다. 또는 --cert.와 함께 --generate-cert 사용할 수 없습니다.
• --install-cert - 컴퓨터에 인증서 설치
• --publisher <name>- 인증서 생성을 위한 Publisher. 전체 X.500 고유 이름 또는 맨 이름(자동으로 로 CN=<name>래핑됨)을 허용합니다.
• --self-contained - 번들 Windows 앱 SDK 런타임
• --skip-pri - PRI 파일 생성 건너뛰기
• --executable <path> - 입력 폴더(또한 --exe)를 기준으로 실행 파일의 경로입니다. 매니페스트의 자리 표시자를 해결하는 $targetnametoken$ 데 사용됩니다.

Project 모드 옵션(입력 필요.csproj, 폴더/번들/매니페스트 입력에 대해 거부됨):

• --configuration <name> (-c) - 빌드 구성(기본값: Release)
• --arch <arch>- 대상 아키텍처: x64또는 arm64x86 (기본값: 현재 프로세스 아키텍처)
• --framework <tfm> (-f) - 다중 대상 프로젝트에 대한 대상 프레임워크 모니커
• --no-build - 다시 빌드하지 않고 기존 빌드 출력 패키지
• --no-restore - 빌드하기 전에 프로젝트 복원 건너뛰기
• --property <name=value> (-p) - 빌드 및 평가에 전달된 MSBuild 속성(반복 가능)

참고: WinUI/ EnableMsixTooling.csproj (MSIX 도구 프로젝트 모드)의 경우 Windows 앱 SDK 매니페스트, 진입점 및 PRI 생성을 소유하므로 --executable--manifest--skip-pri 프로젝트 자체에서 프로젝트 진입점 및 해당 리소스 빌드를 구성하고 거부<AppxManifest>됩니다. 이러한 세 가지 옵션은 폴더 입력 및 제네릭(비 MSIX 도구) .csproj 프로젝트 모드에도 계속 적용됩니다.

기능 설명:

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

직접 프로젝트 패키징

입력이 단일 .csprojwinapp pack 인 경우 위의 옵션을 사용하여 프로젝트를 빌드하고 결과 출력을 패키지합니다. 별도로 빌드하거나 출력 폴더를 먼저 찾을 필요가 없습니다. 이는 '프로젝트 모드'를 미러링합니다 winapp run.

# Build MyApp in Release for arm64 and package + sign it in one step
winapp pack ./MyApp.csproj -c Release --arch arm64 --cert ./devcert.pfx

# Package an existing build output without rebuilding
winapp pack ./MyApp.csproj --no-build

# Select the target architecture with an exact RID instead of --arch
winapp pack ./MyApp.csproj -p RuntimeIdentifier=win-x64

대상 아키텍처는 전달 --arch 하지 않을 때(정확한 RID가 유지되고 빌드를 구동하는) 고독 -p RuntimeIdentifier=<rid> 한 아키텍처에서 --arch비롯됩니다. 둘 다 --arch 전달하고 -p RuntimeIdentifier 충돌이며 거부됩니다.

프로젝트는 패키지된 앱(와 함께Package.appxmanifest)EnableMsixTooling=true으로 빌드해야 합니다. 패키지되지 않은 앱(WindowsPackageType=None)으로 빌드되는 프로젝트에는 패키지 winapp pack 에 대한 MSIX 매니페스트가 없으며 실행 가능한 오류를 보고합니다. 폴더, 번들 및 스파스 매니페스트 입력은 변경되지 않습니다.

Project 모드는 단일 .msix 또는 아키텍처 전용 .msixbundle 을 생성합니다(다중 아키텍처 번들 참조). 스토어 업로드 보관 파일 또는 리소스 분할(언어/규모) 번들을 생성하지 않습니다. 명시적이거나 -p UapAppxPackageBuildMode=StoreUpload-p AppxBundleAutoResourcePackageQualifiers=... 해당 흐름에 대해 직접 네이티브 SDK 패키징 명령을 실행하는 메모와 함께 거부됩니다.

스파스 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=<현재 사용자>). 단일 값의 쉼표로 구분된 구성 요소(다중값 + RDN 및 백슬라이시는 지원되지 않음)가 있는 X.500 DN을 허용합니다. 베어 이름은 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 파일은 원본 이미지로 완전히 지원됩니다. 각 대상 크기에서 직접 벡터로 렌더링되어 모든 해상도에서 픽셀에 완벽한 결과를 생성합니다. 파일은 특정 또는 절대 width 및 height 특성을 통해 viewBox 고유한 크기를 선언해야 합니다. 특정 크기를 설명하지 않는 viewBox 백분율 너비입니다. 둘 다 선언하는 원본은 빈 자산을 생성하는 대신 거부 SVG image has no usable dimensions 됩니다.

이 명령은 가로 세로 비율을 유지하면서 이미지를 비례적으로 조정하여 필요할 때 투명한 배경으로 가운데에 배치합니다. 자산은 매니페스트 위치를 기준으로 디렉터리에 저장 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 모드를 참조하세요.
• 단일 파일 모드 - 입력은 .NET 파일 기반 앱입니다.cs. winapp run 빌드하고, 지시 #:property 문에서 매니페스트를 생성하고, 패키지 ID를 사용하여 시작합니다.

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- 실행할 앱: 빌드 출력 폴더(폴더 모드), .cs .NET 파일 기반 앱(단일 파일 모드), .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를 사용하여 현재 터미널에서 실행됩니다. 거의 필요하지 않습니다. 이미 있는 OutputType=Exe 앱이 기본적으로 이 방식으로 시작됩니다. winapp은 AppX 레이아웃에서 단계별로 구성된 매니페스트에 필수 uap5:ExecutionAlias 항목을 추가하므로 체크 인 매니페스트를 변경할 필요가 없습니다. 앱에서 자체 선언하는 별칭은 as-is사용됩니다. , --no-launch또는 --detach--without-alias.와 함께 --json사용할 수 없습니다.
• --without-alias - 실행 별칭을 통해 실행될 앱에 대해 AUMID 활성화를 강제 적용합니다. 그런 다음 콘솔 앱이 콘솔 없이 실행되고 이 터미널에 아무것도 인쇄하지 않습니다. 와 함께 --with-alias사용할 수 없습니다.
• --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를 인쇄합니다. 대상 실행은 범위가 지정된 UI 대상을 인쇄합니다. JSON에는 PID 및 대상 범위가 포함됩니다. , --no-launch또는 --debug-output--with-alias.와 함께 --unregister-on-exit사용할 수 없습니다.
• --clean - 다시 배포하기 전에 기존 패키지의 애플리케이션 데이터(LocalState, 설정 등)를 제거합니다. 기본적으로 애플리케이션 데이터는 다시 배포에서 유지됩니다.
• --json - 프로그래밍 방식 사용을 위해 출력을 JSON으로 서식 지정합니다(예: CI/자동화). --detach PID를 캡처하는 데 유용합니다. 또는 --with-alias.와 함께 --debug-output 사용할 수 없습니다.
• --on <target> - 호스트에서 빌드한 다음, 대상에서 등록하고 실행합니다. 현재는 로컬 실행에 대한 대체 없이 지원합니다 sandbox. 후속 UI 명령 전에 사용합니다 --detach . 샌드박스 --debug-output 에는 패키지된 앱이 필요합니다. 설치, 런타임 지원 및 분리된 앱 수명은 Windows 샌드박스 실행을 참조하세요.

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

기본적으로 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의 경우)이 필요합니다.

네이티브 AOT: project 파일 요소 <Project> 내에 이 속성 그룹을 추가한 다음, 다음을 추가합니다--aot.

<PropertyGroup>
  <PublishAot>true</PublishAot>
</PropertyGroup>

winapp run . --aot
winapp run . --aot -c Release

--aot는 x64 및 ARM64 프로젝트를 지원하며 .NET SDK 8.0.300 이상이 필요합니다. 프로젝트의 AOT 구성으로 실행 dotnet publish 된 다음, 해당 출력을 실행합니다. 일회성 재정의에 사용합니다 -p PublishAot=true . 별도의 런타임 인증을 수행하지 않으며 결합하거나 --manifest결합 --no-build 할 수 없습니다.

생성된 MSIX 레이아웃 없이 패키지 ID를 사용하는 앱의 경우 프로젝트의 게시 출력을 포함 Package.appxmanifest 하거나 appxmanifest.xml 포함합니다. Winapp은 게시된 파일을 해당 매니페스트와 함께 단계별로 지정합니다. 두 이름이 모두 있는 경우 winapp은 하나를 선택하는 대신 중지됩니다. 부실 매니페스트를 제거하고 의도한 매니페스트만 게시하도록 프로젝트를 구성합니다.

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 되고 필요한 게시 프로필을 선택할 수 있습니다. (또한 단일 파일 모드에서 적용되며, 파일에서 선언된 파일을 재정의합니다 #:property RuntimeIdentifier .)
• -f, --framework <tfm> - 다중 대상 프로젝트(예: net10.0-windows10.0.26100.0)에 대한 대상 프레임워크 모니커입니다. (단일 파일 모드에서 거부됨 - .)#:property TargetFramework=...
• --project <name-or-path> - 입력이 솔루션(.sln/.slnx) 또는 실행 가능한 앱 프로젝트가 여러 개 있는 디렉터리인 경우 프로젝트 이름 또는 경로별로 실행할 프로젝트를 선택합니다. (단일 파일 모드에서 거부됨 - .cs 파일 기반 앱 자체는 프로젝트입니다.)
• --no-build - 빌드를 건너뛰고 기존 빌드 출력을 실행합니다(출력 속성은 계속 평가됨). (단일 파일 모드에서도 적용됩니다.)
• --no-restore - 빌드 또는 네이티브 AOT 게시 전에 복원을 건너뜁니다. (단일 파일 모드에서도 적용됩니다.)
• --aot- 프로젝트의 구성된 .NET 네이티브 AOT 게시를 실행합니다. 유효 PublishAot=true해야 합니다. 폴더 및 단일 파일 모드에서 거부되었습니다.
• -p, --property <Name=Value> - 빌드 및 속성 평가 모두에 전달되는 MSBuild 속성입니다. 여러 속성에 대해 반복 -p 합니다. 값에서 리터럴 세미콜론 또는 쉼표로 사용하거나 %2C 사용합니다%3B. (또한 단일 파일 모드에서 적용됩니다. 여기서는 설정할 TargetFramework수 있는 유일한 방법입니다.)

빌드 출력 및 세부 정보: 일반 프로젝트 실행에서 사용한 dotnet build다음, 빌드된 출력을 평가합니다. 인증된 피드 URL의 자격 증명을 수정하여 출력 스트림을 라이브로 복원하고 빌드합니다. 와 함께 --aotwinapp 사용 dotnet publish; --verbose 게시 명령 및 확인 된 경로를 표시 합니다. 아래의 세부 정보 표시 옵션을 사용하여 표시되는 내용을 제어합니다.

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

네이티브 AOT는 도착 시 출력 스트림을 게시합니다. 아래에서 --json복원/빌드 호출 및 자식 출력은 stderr로 이동하므로 stdout은 순수 JSON을 유지합니다. 아래에서 --quiet호출은 표시되지 않으며 dotnet의 조용한 복원/빌드 출력은 stderr로 라우팅되므로 stdout은 깨끗하게 유지됩니다. 네이티브 AOT 게시 출력도 두 옵션 중 하나에서 stderr로 이동합니다.

옵션 적용 가능성: 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

# Publish and run the Release configuration with Native AOT
winapp run . --aot -c Release

# 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

단일 파일 모드(.NET 파일 기반 앱)

.NET 10을 사용하면 프로젝트 파일이 없는 단일 .cs 파일을 실행하여 맨 위에 지시문을 사용하여 #: 구성할 수 있습니다. 해당 파일을 가리키 winapp run 면 앱을 빌드하고, 앱에 대한 appxmanifest를 생성하고, 패키지 ID를 사용하여 시작합니다. 따라서 Windows.ApplicationModel.Package.Current 앱이 실제 AUMID 및 시작 메뉴 항목을 가져오고 ID(앱 알림, ApplicationData디바이스 내 AI)가 단순히 필요한 API가 작동합니다.

프로토콜 처리기, 파일 연결, 공유 대상 및 시작 작업과 같은 셸 통합에는 생성된 매니페스트에 포함되지 않은 선언된 <Extensions> 항목이 필요합니다. 매니페스트를 추가하려면 사용자 고유의 매니페스트를 작성합니다. 아래의 고유한 매니페스트 가져오기 를 참조하세요.

winapp run counter.cs

또는 일반 dotnet run 으로 실행합니다. 아래와 함께 dotnet run실행을 참조하세요.

매니페스트를 작성하지 않습니다. 대신 지시문을 사용하여 패키지를 #:property 설명합니다.

#:package Microsoft.UI.Reactor@0.1.0-preview.13
#:property OutputType=WinExe
#:property TargetFramework=net10.0-windows10.0.22621.0
#:property UseWinUI=true
#:property RuntimeIdentifier=win-x64

#:property WinAppPackageName=com.contoso.counter
#:property WinAppDisplayName=Contoso Counter
#:property WinAppDescription=Counts things, one click at a time
#:property Version=1.2.3

using static Microsoft.UI.Reactor.Factories;
ReactorApp.Run<MyApp>("Hello");

매니페스트 속성입니다. 모두 선택 사항입니다. 각각은 합리적인 기본값으로 돌아갑니다.

재산	설정	Default
WinAppPackageName	Identity/@Name (패키지 ID)	삭제된 [-.A-Za-z0-9]파일 이름과 파일 경로의 짧은 해시(counter.cs → counter-a1b2c3d4)
WinAppDisplayName	시작 및 설정에 표시된 이름	확장명을 사용하지 않는 파일 이름
WinAppPublisher	Identity/@Publisher	CN=<your Windows user name>; 맨손 이름은 .로 CN=<name>래핑됩니다.
WinAppVersion	Identity/@Version	$(Version), 정규화됨(아래 참조)
WinAppDescription	설치 중 및 설정에 표시되는 설명	표시 이름
WinAppCapabilities	선언, 구분 ; 또는 ,	none

Version. 패키지 버전은 각각 0~65535의 정확히 4개의 숫자여야 합니다. WinAppVersion (또는, 설정하지 않으면 표준 Version 속성)이 다음 항목에 맞게 -preview/-rc 정규화됩니다. 접미사가 삭제되고 누락된 구성 요소가 0으로 채워지므로 #:property Version=1.2.3-preview.4 어셈블리 버전과 패키지 버전이 함께 만들어 1.2.3.0 집니다. 65535 이상의 구성 요소 또는 4개 이상의 구성 요소에 맞게 만들 수 없는 값은 자동으로 변경되지 않고 오류로 거부 됩니다.

Capabilities

앱은 ID로 완전 신뢰를 실행하며 패키지된 앱만 필요한 API를 충족합니다. 그러나 일부 API는 선언된 기능에 관계없이 제어됩니다. Windows AI API가 일반적인 경우입니다. (프로토콜 처리기 및 파일 연결과 같은 셸 통합은 세 번째 사례입니다. 이러한 경우는 기능이 아닌 작성된 <Extensions> 항목이 필요하므로 사용자 고유의 매니페스트 를 사용합니다.)

#:property WinAppCapabilities=systemAIModels

즉, 매니페스트에서 필요한 모든 Phi Silica 및 기타 디바이스 모델 API입니다. 여러 항목을 구분하여 선언합니다.

#:property WinAppCapabilities=systemAIModels;internetClient;microphone

winapp은 실제로 필요한 요소 및 XML 네임스페이스에 각 네임스페이스를 쓰고, 해당 네임스페이스를 선언하고, 기능에 최신 네임스페이스가 필요할 때 발생합니다 MaxVersionTested . 이는 소리보다 더 중요합니다. 기능은 여러 다른 요소에 분산되고 위의 동일한 목록은 세 가지 모양이 됩니다.

<systemai:Capability Name="systemAIModels" />
<Capability Name="internetClient" />
<DeviceCapability Name="microphone" />

winapp이 알고 있는 이름은 당신을 위해 작성되었습니다. 시간이 지남에 따라 제한된 집합이 증가하는 다른 항목의 경우 네임스페이스 접두사를 사용하여 직접 한정합니다.

프리픽스	내보내기
rescap:	<rescap:Capability> — 제한된 기능
uap:, uap6:, , uap7:, uap11:	<uap*:Capability>
systemai:	<systemai:Capability>
device:	<DeviceCapability>
app:	<Capability> 기본 네임스페이스에서

#:property WinAppCapabilities=rescap:broadFileSystemAccess

인식할 수 없는 맨 이름은 추측하지 않고 이러한 접두사 이름을 지정하는 오류로 거부됩니다. 잘못된 네임스페이스에 내보낸 기능은 자동으로 부여하지 않으면서 등록을 거부하거나 수락할 Windows 매니페스트를 생성합니다.

사용자 고유의 매니페스트 가져오기

프로토콜 처리기, 파일 연결, 실행 별칭 등 속성에서 다루지 않는 항목이 필요한 경우 매니페스트를 작성하고 매니페스트 winapp run 를 생성하는 대신 그대로 사용합니다. 순서대로 선택됩니다.

1. --manifest <path> 명령줄에 있는 입니다.
2. #:property WinAppManifestPath=<path> 파일에 있습니다 .cs .
3. 파일 옆에 .cs 있는 매니페스트(예counter.appxmanifest: 옆에 counter.cs있는)입니다 <filename>.appxmanifest .

파일당 이름만 자동으로 선택됩니다. A Package.appxmanifest 또는 appxmanifest.xml 동일한 폴더에서 의도적으로 무시됩니다. 여러 .cs 파일이 폴더를 공유할 수 있으며 공유 이름을 채택하면 한 앱이 다른 사용자의 ID로 자동으로 실행됩니다. 여러 파일에 하나의 매니페스트를 사용하려면 명시적으로 이름을 지정 --manifest 하거나 WinAppManifestPath.

그렇지 않으면 Package.appxmanifest 기본 이미지 자산과 함께 빌드 출력에 생성되고 모든 실행에서 새로 고쳐집니다.

Options. 모든 폴더 모드 옵션은 다음과 -c/--configuration--unregister-on-exit--symbols--debug-output--args/--executable--json--manifest----output-appx-directory--clean-p/--property--with-alias--no-restore--without-alias--no-build--detach같이 작동합니다. --no-launch

Tip

콘솔 앱은 기본적으로 터미널에 인쇄됩니다. AUMID를 통해 시작된 패키지된 앱에는 콘솔이 없으므로 콘솔 전용 앱이 올바르게 실행되고 아무것도 인쇄하지 않습니다. winapp은 이 터미널의 stdin/stdout/stderr를 상속하는 실행 별칭을 통해 앱이 시작되는 것을 OutputType=Exe 방지합니다. 패키지 ID가 계속 표시되므로 다음을 요청할 필요가 없습니다.

winapp run counter.cs

대신 AUMID 활성화를 강제로 전달 --without-alias 합니다. 그러면 앱이 콘솔 없이 실행되고 여기에 아무것도 인쇄하지 않습니다. 창이 있는 앱(WinExe)은 창을 표시하므로 AUMID 활성화를 유지합니다. 이 터미널에서 원하는 경우 전달 --with-alias 합니다. 모든 명령줄이 아닌 파일에서 선택을 수정하려면 사용하는 것과 동일한 속성을 .csproj 설정합니다.

#:property WinAppRunUseExecutionAlias=false

winapp 선언 별칭은 접두사를 사용하여 패키지 패밀리 이름 이름을winapp- 따서 명명되므로 com.contoso.counter gets에 의해 CN=You 게시됩니다winapp-com.contoso.counter_gspb8g6x97k2t.exe. 그 후행 부분은 게시자 해시 Windows 파생되므로 다른 게시자에서 이름을 공유하는 두 개의 앱은 여전히 다른 별칭을 얻습니다. 접두사는 실제 명령의 이름을 지워 줍니다. 앱은 python.cs 별칭을 winapp-… 가져오지 않습니다 python.exe. 사용자 고유의 매니페스트를 작성하는 경우 선언한 별칭은 as-is 사용되고 winapp은 아무 것도 추가하지 않습니다.

별칭에만 적용됩니다. 등록 자체는 패키지 이름에 키가 지정되므로 다른 게시자에서 동일한 WinAppPackageName 항목을 선언하는 두 번째 앱을 실행하면 첫 번째 등록이 함께 앉지 않고 바뀝니다. 둘 다 한 번에 등록하려면 각 앱에 고유한 이름을 지정합니다.

winapp run 는 등록된 별칭을 인쇄하므로 해시를 계산하여 찾을 필요가 없습니다.

별칭은 패키지가 등록된 상태로 유지되는 동안 지속되는 PATH의 명령입니다. 일부 다른 패키지가 이미 이름을 소유하고 있는 경우 winapp은 그렇게 말합니다. 별칭을 유추하면 잘못된 앱을 시작하는 대신 AUMID를 통해 시작됩니다. 다른 작업을 조용히 수행하는 대신 명시적으로 --with-alias 또는 다른 작업을 수행하도록 #:property WinAppRunUseExecutionAlias=true 요청하면 실패합니다.

파일 기반 앱이 자체 구성되므로 두 가지 프로젝트 모드 옵션이 적용되지 않습니다 . 대신 사용할 지시문의 이름을 지정하는 메시지와 함께 거부됩니다.

Option	대신 사용
-f/--framework	#:property TargetFramework=net10.0-windows10.0.22621.0
--project	nothing - .cs 파일이 프로젝트 입니다 .

--arch 프로젝트 -r/--runtime 모드에서와 같이 작동합니다. 둘 중 하나를 전달하지 않으면 winapp은 컴퓨터의 아키텍처를 위해 빌드됩니다. 이 아키텍처는 SDK가 빌드 AnyCPU 되고 실패하기 때문에 자체 포함된 Windows 앱 SDK 앱에 WindowsAppSDKSelfContained requires a supported Windows architecture필요합니다. 파일의 A #:property RuntimeIdentifier=win-arm64 가 적용되며 명시적 --arch/--runtime 재정의가 적용됩니다.

패키지된 작업과 패키지되지 않은 두 작업 모두 프로젝트 모드에서 WindowsPackageType 정확하게 검색됩니다. 기본값은 느슨한 레이아웃을 등록하고 ID로 시작하고, 앱을 빌드하는 동안#:property WindowsPackageType=None, 일치하는 Windows 앱 런타임을 설치하고, 직접 시작합니다.exe. (패키지된 앱은 실행 별칭을 통해 또는 AUMID 활성화를 통해 시작됩니다. 위의 콘솔 참고를 참조하세요. 패키지 여부와는 별개입니다.) ID 옵션(--no-launch,, --with-alias, --without-alias, --clean, --unregister-on-exit, --manifest--output-appx-directory)은 패키지된 앱에만 적용됩니다.

다음을 사용하여 실행 dotnet run

입력 winapp 할 필요가 없습니다. Microsoft.Windows.SDK.BuildTools.WinApp 파일에서 패키지를 참조하고 일반 dotnet run 은 동일한 패키지 시작을 제공합니다.

#:package Microsoft.Windows.SDK.BuildTools.WinApp@*
#:property OutputType=Exe
#:property TargetFramework=net10.0-windows10.0.19041.0

System.Console.WriteLine(Windows.ApplicationModel.Package.Current.Id.FamilyName);

dotnet run counter.cs

패키지의 MSBuild 대상은 실행을 winapp으로 리디렉션합니다. 그러면 방금 빌드한 앱을 dotnet run 패키지, 등록 및 시작하며 다시 빌드되지 않습니다. 매니페스트 처리는 변경되지 않습니다 winapp run. winapp은 그대로 확인하므로 #:property WinAppManifestPath=…<filename>.appxmanifest 두 항목 옆에 .cs 모두 영광이 있으며( 사용자 매니페스트 가져오기 참조), 디렉터리 전체 Package.appxmanifest 는 여전히 무시되고, 그렇지 않으면 지시문에서 #:property 생성되고 실행될 때마다 새로 고쳐집니다.

리디렉션이 수행되려면 다음 두 가지 조건을 유지해야 합니다.

지시	이유
#:package Microsoft.Windows.SDK.BuildTools.WinApp@*	이 패키지에서 리디렉션 배송을 수행하는 대상
#:property TargetFramework=net10.0-windows…	일반 net10.0 파일은 단독으로 남아 있으므로 패키지되지 않은 상태로 실행됩니다.

또한 추가 #:property WindowsPackageType=None 하면 파일만 dotnet run 남게 됩니다. 그런 다음 ID 없이 직접 실행 .exe 합니다. 일치하는 Windows 앱 런타임을 먼저 설치하려면 패키지되지 않은 경로에 사용합니다winapp run.

리디렉션을 완전히 WinAppRun* 옵트아웃하도록 설정하고 #:property EnableWinAppRunSupport=falseConfiguration 아래에 설명된 속성을 설정하여 시작을 셰이프합니다. 예를 들면 다음과 같습니다.

#:property WinAppRunUnregisterOnExit=true

ID를 예상할 때 패키지되지 않은 앱을 실행하는 경우 dotnet run MSBuild에 이유를 물어보십시오. 다음을 통해 파일 기반 앱이 컴파일되는 가상 프로젝트를 합성하는 것뿐만 dotnet build 아니라 dotnet msbuild 다음을 사용합니다dotnet build.

dotnet build counter.cs -t:WinAppRunSupportInfo

단일 파일 모드에는 .NET SDK 10.0.300 이상이 필요합니다.

등록은 실행보다 오래 실행됩니다. winapp run counter.cs 는 앱이 종료된 후 폴더 및 프로젝트 모드와 똑같이 등록된 패키지를 유지하므로 LocalState 유지되고 동일한 파일을 다시 실행하면 등록을 쌓는 대신 동일한 ID가 다시 사용됩니다. winapp은 앱을 winapp unregister 처음 등록하고 그 자체를 취 .cs 한다고 말합니다.

# Remove the registration (resolves the same identity `winapp run` registered)
winapp unregister counter.cs

# Or remove it as soon as the app exits
winapp run counter.cs --unregister-on-exit

winapp unregister counter.cs매니페스트 경로가 필요하지 않습니다. 동일한 방식으로 run 파일의 #:property 값을 평가하고 해당 파일의 빌드 출력에서 등록된 패키지만 제거합니다. 다른 폴더에서 등록된 동일한 이름의 앱은 통과 --force하지 않는 한 거부됩니다. 실행에서 ID 또는 레이아웃을 셰이프하는 옵션을 사용한 경우 동일한 옵션을 다음으로 전달합니다 unregister.

winapp run counter.cs -p WinAppPackageName=com.contoso.alt
winapp unregister counter.cs -p WinAppPackageName=com.contoso.alt

winapp run counter.cs -c Release --arch arm64
winapp unregister counter.cs -c Release --arch arm64

-p 는 파일의 고유한 지시문과 Directory.Build.props.cs can 키 WinAppPackageName 오프 $(Configuration) 또는 $(RuntimeIdentifier) 옆에 재정의하므로 각 패키지가 등록되는 패키지를 변경할 수 있습니다.

SDK의 임시 출력이 정리되면 winapp unregister counter.cs 더 이상 등록이 해당 파일에서 온 것을 확인할 수 없으며 건너뜁니다. 파일이 사라진 등록을 지우거나 --force 특정 파일을 제거하는 데 사용합니다winapp unregister --prune. 실행이 사용된 --output-appx-directory경우 레이아웃을 인식할 unregister 수 있도록 동일한 디렉터리를 전달합니다.

사용자 지정 출력 경로에도 동일하게 적용됩니다. 소유권은 SDK의 표준 <root>\bin\<configuration> 레이아웃에서 확인되므로 빌드된 실행은 원본 파일과 -p OutputPath=<somewhere-else> 일치시킬 수 없습니다. unregister 는 더 넓은 디렉터리에서 추측하지 않고 레이아웃 이름을 --output-appx-directory지정하거나 사용합니다 --force.

단일 파일 예제:

# Build and run a file-based app with package identity
winapp run counter.cs

# Register identity without launching (e.g. to attach Visual Studio)
winapp run counter.cs --no-launch

# Release build, detached, printing the PID as JSON
winapp run counter.cs -c Release --detach --json

# Capture OutputDebugString output and crash diagnostics
winapp run counter.cs --debug-output

# Forward arguments to the app
winapp run counter.cs -- --verbose --input data.json

# Wipe the app's LocalState and start fresh
winapp run counter.cs --clean

# Remove the package it registered
winapp unregister counter.cs

비고

기본 ID에는 파일 경로 counter.cs 의 짧은 해시가 포함되므로 counter-a1b2c3d4 서로 다른 폴더에 있는 두 counter.cs 개의 파일은 서로 다른 앱이며 자체 설정을 LocalState유지하고 있습니다. 해시는 경로에서 파생되므로 편집 및 다시 실행이 유지되며 파일을 이동하는 경우에만 변경됩니다. 안정적인 ID를 직접 선택하도록 설정합니다#:property WinAppPackageName=<name>. 즉, 외부 [-.A-Za-z0-9] 문자가 Identity/@Name 삭제되고, 3자 미만의 이름이 패딩1되고, 결과가 50자로 제한되므로 My App 다음과 같이 MyApp등록됩니다. 시작 메뉴와 설정에 ID가 아닌 (기본값: 파일 이름)이 표시됩니다 WinAppDisplayName . ID는 항상 사용자 계정으로 범위가 지정되므로 동일한 컴퓨터에서 다른 사용자와 충돌하지 않습니다.

MSBuild 속성(NuGet 패키지):

Microsoft.Windows.SDK.BuildTools.WinApp NuGet 패키지를 사용하는 경우 dotnet run 자동으로 winapp run 호출합니다.

이후에 dotnet run 작성된 모든 항목은 패키지가 없는 것처럼 애플리케이션에 전달됩니다. 아래 MSBuild 속성을 사용하여 시작 관리자를 구성합니다.

# Goes to your app. `--` is optional here, but required when the flag is also a
# `dotnet run` option (--configuration, --framework, --project, -c, -f, -r, ...),
# otherwise the SDK claims it and your app never sees it.
dotnet run --devtools
dotnet run -- --devtools
dotnet run -- --configuration Release

# Configures WinApp; --devtools still reaches your app
dotnet run -p:WinAppRunDetach=true --devtools

다음 MSBuild 속성을 컨트롤 동작에 .csproj 설정할 수 있습니다.

재산	Default	설명
EnableWinAppRunSupport	true	실행 지원 기능 사용/사용 안 함
WinAppLaunchArgs	(비어 있음)	시작할 때 앱에 전달할 인수
WinAppRunUseExecutionAlias	앱에서 유추	AUMID 활성화 대신 실행 별칭을 통해 시작합니다. 설정되지 않은 상태로 두면 winapp에서 유추합니다. 콘솔 앱은 별칭을 사용하여 출력이 터미널에 도달하고 창이 있는 앱은 AUMID를 사용합니다. 직접 설정 true 하거나 false 결정합니다.
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, WinAppRunDebugOutput, WinAppRunUnregisterOnExit
WinAppRunDetach	WinAppRunNoLaunch, WinAppRunDebugOutput, WinAppRunUnregisterOnExit

WinAppRunUseExecutionAlias 는 의도적으로 어느 방향으로든 해당 목록에 없습니다 . false 시작 안 됨 및 분리에서 이미 사용하는 AUMID 활성화를 요청합니다. true 는 실행 별칭에 추적된 실행 중인 프로세스가 필요하기 때문에 둘 중 하나가 설정될 때 적용되지 않습니다. 따라서 체크 인 <WinAppRunUseExecutionAlias>true</WinAppRunUseExecutionAlias> 하는 프로젝트는 실패하지 않고 AUMID를 통해 시작하여 계속 깔끔하게 dotnet run -p:WinAppRunDetach=true실행됩니다.

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 [input] [options]

인수:

• input- 패키지를 등록 취소해야 하는 .NET 파일 기반 앱(단일.cs)의 경로입니다. 해당 ID는 앱 #:property 에 해당 값이 있는 경우 작성된 매니페스트에서 확인하는 것과 동일한 방식으로 winapp run 확인되므로 매니페스트 경로가 필요하지 않습니다. 현재 디렉터리에서 매니페스트를 사용 --manifest 하거나 자동으로 검색하지 않습니다. 패키지 이름을 다른 방식으로 지정하고 다른 방법으로 확인할 수 있는 와 --manifest결합할 수 없습니다.

옵션:

• --manifest <path> - Package.appxmanifest 경로(기본값: 현재 디렉터리에서 자동 검색)
• --force - 로컬 등록 취소 전용의 경우 설치 위치 디렉터리 검사를 건너뛰고 패키지가 다른 프로젝트 트리에서 등록된 경우에도 등록을 취소합니다. 대상 소유권 검사를 바이패스할 수 없으므로 거부 --on됩니다.
• --on <target> - 이 컴퓨터가 아니라 일치하는 winapp 소유 개발 등록을 sandbox제거합니다. 매니페스트가 필요하고 지원하지 --force않습니다. 샌드박스 앱 정리를 참조하세요.
• --prune - 파일이 사라진 모든 개발 모드 등록을 제거합니다. 입력, , --manifest, --property--configuration, --arch--runtime또는 --output-appx-directory.와 함께 사용할 수 없습니다.
• -p, --property <Name=Value> - 파일 기반 앱의 ID를 .cs 확인할 때 사용되는 MSBuild 속성입니다. 반복. 명령줄 속성이 파일의 지시 #:property 문을 재정의하기 때문에 실행에서 사용한 것과 동일한 ID 영향을 주는 속성(예-p WinAppPackageName=...: )을 전달합니다. 입력에 .cs 만 적용됩니다.
• -c, --configuration <name> - 파일 기반 앱의 ID를 .cs 확인할 때 사용되는 빌드 구성입니다. 기본값: Debug. 실행에서 사용한 Directory.Build.props 것과 동일한 구성을 전달합니다. 옆에 .cs 는 설정할 수 있거나 WinAppManifestPath 조건부로 설정합니다 WinAppPackageName$(Configuration). 입력에 .cs 만 적용됩니다.
• --arch <x64|arm64|x86> - 파일 기반 앱의 ID를 .cs 확인할 때 사용되는 대상 아키텍처입니다. 기본값: 현재 프로세스 아키텍처입니다. ID를 키오프 $(RuntimeIdentifier)할 수도 있으므로 실행에서 사용한 것과 동일한 아키텍처를 전달합니다. 입력에 .cs 만 적용됩니다.
• -r, --runtime <rid>- 파일 기반 앱의 ID를 .cs 확인할 때 사용되는 대상 .NET 런타임 식별자(예win-x64: )입니다. 해당 아키텍처만 사용되며 재정의됩니다 --arch. 입력에 .cs 만 적용됩니다.
• --output-appx-directory <path> - 패키지가 등록된 AppX 레이아웃 디렉터리입니다. 실행 옵션이 레이아웃을 생성한 패키지 레코드에는 아무것도 없기 때문에 실행이 사용된 --output-appx-directory경우에만 필요합니다.
• --json - 출력을 JSON으로 서식 지정

기능 설명:

• 파일의 확인된 ID에서 또는 매니페스트를 .cs 읽어 패키지 이름을 확인합니다.
• 패키지와 {name} 패키지를 모두 {name}.debug 검색합니다(디버그 변형은 에 의해 create-debug-identity생성됨).
• 각 패키지가 개발 모드로 등록되었는지 확인합니다(IsDevelopmentMode == true)
• 패키지가 사용자가 지정한 앱에 속하는지 확인합니다(예 --force: 해당 설치 위치는 사용자가 식별한 .cs 디렉터리 아래에 있어야 합니다. 파일의 빌드 출력, 매니페스트의 디렉터리, 현재 디렉터리 또는 명시적 --output-appx-directory). ID만으로는 소유권 증명이 아니므로 설치 위치를 확인할 수 없는 패키지(파일 삭제됨)를 건너뜁니다. 두 앱이 모두 다른 #:property WinAppPackageName=counter 폴더에서 동일한 ID를 등록합니다. 파일이 사라진 등록을 지우는 데 사용합니다 --prune .
• 일치하는 패키지 등록 취소

죽은 등록 정리(--prune):

등록은 파일보다 오래 깁니다. 빌드 출력, 프로젝트 트리 또는 파일 기반 앱의 경우 삭제하면 Windows 정리%LOCALAPPDATA%\Temp되고 패키지가 등록된 상태로 유지됩니다. Windows ID 및 시작 메뉴 항목을 유지하지만 활성화는 자동으로 아무 작업도 수행하지 않습니다. 이러한 내용은 보이지 않게 누적됩니다.

# List dev registrations whose files are gone, then confirm before removing
winapp unregister --prune

# Skip the prompt (required for non-interactive/CI use)
winapp unregister --prune --force

개발 모드 등록만 고려되며 각 등록은 전체 패키지 이름으로 제거되므로 라이브 위치에서 동일한 이름의 패키지가 여전히 설치되지 않습니다. 누락된 설치 위치는 일반적으로 삭제된 폴더이지만 연결이 끊긴 네트워크 공유 또는 이동식 드라이브에서 등록된 패키지에 대해서도 설명하므로 확인 전에 목록을 검토하세요.

예:

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

# Unregister a .NET file-based app by its source file
winapp unregister counter.cs

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

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

# Remove every dev registration whose files are gone
winapp unregister --prune

# JSON output for scripting
winapp unregister --json

---

cert

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

인증서 생성

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

winapp cert generate [options]

옵션:

• --manifest <Package.appxmanifest>- 매니페스트에서 인증서 publisher 추출합니다Identity/@Publisher. 게시자만 필요하므로 부분적으로 완성된 매니페스트는 여전히 작동합니다. 매니페스트에 사용할 수 있는 게시자가 없으면 기본값을 대체하는 대신 명령이 실패하므로 인증서가 매니페스트와 자동으로 일치하지 않을 수 있습니다.
• --publisher <name>- 인증서에 대한 Publisher. 인증서를 생성할 때 이 옵션이 우선 --manifest합니다. 매니페스트 게시자를 사용하는 대신 명시적으로 빈 값이 실패합니다. 전체 X.500 고유 이름(예: CN=Contoso, O=Contoso Ltd, C=US) 또는 자동으로 로 래핑 CN=<name>되는 bare 이름을 허용합니다. 구성 요소는 단일 값과 쉼표로 구분되어야 합니다. MSIX 매니페스트 게시자가 표시할 수 없으므로 다중값 RDN(CN=Foo+OU=Bar) 및 백슬라이시는 지원되지 않습니다. 매니페스트 게시자와 일치시킬 수 없는 인증서를 생성하는 대신 잘못된 형식의 고유 이름(예: CN= 또는 CN=A,,O=B)이 0이 아닌 종료 및 문제 이름을 지정하는 오류로 인해 거부됩니다.
• --output <path> - 출력 인증서 파일 경로(절대 및 상대 경로 지원)
• --password <password> - 인증서 암호(기본값: password공개적으로 알려진 - JSON 출력 및 보안 참조)
• --valid-days <valid-days> - 인증서가 유효한 일 수(기본값: 365)
• --install - 생성 후 로컬 컴퓨터 저장소에 인증서 설치
• --if-exists <Error|Overwrite|Skip> - 인증서 파일이 이미 있는 경우 동작 설정(기본값: 오류)
• --export-cer - 파일(공개 키만 해당)을 함께 내 .cer 보냅니다 .pfx. 신뢰 설치를 위해 공용 인증서를 별도로 배포하는 데 유용합니다.
• --json - 프로그래밍 방식으로 사용할 수 있는 JSON으로 출력 형식을 지정합니다. 오류도 JSON({"error": "..."})으로 반환됩니다.

JSON 출력:

{
  "certificatePath": "C:\\app\\devcert.pfx",
  "password": "password",
  "defaultPasswordIsPublic": true,
  "publisher": "Contoso",
  "subjectName": "CN=Contoso",
  "warnings": [
    "Protected with the default password ('password'), which is public. Treat this certificate as development-only: anyone who obtains the .pfx can sign as you. Pass --password to choose your own, and use a CA-issued certificate or Azure Trusted Signing to ship."
  ]
}

publisher 는 인증서가 발급된 전체 고유 이름 및 subjectName 표시 이름입니다. defaultPasswordIsPublic 는 항상 존재합니다. 이 true.pfx 경우 누구나 추측할 수 있는 암호로 보호되므로 인증서는 사용자 컴퓨터에 남아 있는 빌드에만 서명해야 합니다. 스크립트가 인증서를 다른 항목에 전달하기 전에 확인합니다. warnings 는 텍스트와 동일한 공개를 수행하며 보고할 항목이 없으면 생략됩니다. publicCertificatePath 는 .와 함께 --export-cer만 나타납니다.

인증서 정보

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

winapp cert info <cert-path> [options]

인수:

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

옵션:

• --password <password> - 공용 CER에 대해 무시된 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> <cert-path> [options]

인수:

• file-path - 서명할 MSIX 패키지 또는 실행 파일의 경로
• cert-path - 서명 인증서 경로(.pfx)

옵션:

• --password <password> - 인증서 암호(기본값: "암호")
• --timestamp <url> - RFC 3161 타임스탬프 서버 URL

예:

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

# Sign executable with a non-default certificate password
winapp sign ./bin/MyApp.exe ./mycert.pfx --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

서명 확인

빌드 도구는 NuGet에서 다운로드한 다음 실행되므로 winapp은 실행 직전에 유효한 Microsoft Authenticode 서명을 확인합니다. 인증서는 Microsoft Corporation을 서명 조직으로 지정해야 합니다. 이는 SDK 도구에 셸 아웃되는 모든 명령(예 : < a0/> 및 )에 적용됩니다. 검사에 실패한 도구가 실행되지 않습니다.

'mt.exe' is not validly signed by Microsoft, so it was not run (C:\...\mt.exe).

여기서 오류가 발생한다는 것은 디스크의 파일이 게시된 Microsoft 아니라는 것을 의미합니다. 가장 자주는 손상되거나 부분적으로 다운로드됩니다. NuGet 캐시에서 패키지를 삭제하고 명령을 다시 실행하여 winapp에서 다시 다운로드합니다.

그런 다음 winapp은 실행되는 동안 도구를 열어 두므로 선택한 파일은 로드할 Windows 파일입니다. 도구를 제자리에 고정할 수 없는 경우 다음 중 하나가 실행되지 않습니다.

'mt.exe' could not be held open for verification, so it was not run (C:\...\mt.exe).

바이러스 백신 검사 또는 열린 편집기가 일반적인 원인인 파일을 사용 중인 항목을 닫고 명령을 다시 실행합니다. 도구가 사용되지 않고 사라진 경우 Winapp이 다시 다운로드되도록 NuGet 캐시에서 패키지를 삭제합니다.

---

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

---

target

명령을 실행하거나, 파일을 복사하거나, 상태를 검사하거나, 전체 게스트 데스크톱을 캡처합니다.

모든 동사는 첫 번째 인수로 사용합니다 sandbox . 제외하면 snapshot이러한 명령은 샌드박스를 준비하거나 시작할 수 있습니다. 필수 구성 요소, 권한, 수명 주기 및 복구에 대한 Windows 샌드박스 실행을 참조하세요.

target exec

게스트 사용자로 명령을 실행합니다.

winapp target exec <target> [--cwd <path>] [--json] -- <executable> [arguments...]
winapp target exec sandbox -- dotnet --info

경계를 유지한 후 -- 의 인수입니다. 표준 스트림 및 게스트 프로세스의 종료 코드가 전달됩니다. 전체 터미널이 아닙니다. --json 자식 명령의 stdout을 변경하지 않고 stderr에서 winapp 오류의 형식을 지정합니다. 구조적 error.code 개체를 사용하여 대상 오류를 애플리케이션의 자체 종료 상태와 구분합니다.

명시적 WINAPP_UI_WORKFLOW_ID 또한 명령에 의해 수행된 게스트 UI 호출을 그룹화 합니다. 샌드박스 UI 조정을 참조하세요.

대상 푸시 및 대상 끌어오기

동사로 명명된 방향으로 파일 또는 디렉터리를 복사합니다.

winapp target push <target> <host-source> <target-destination> [--json]
winapp target pull <target> <target-source> <host-destination> [--json]
winapp target push sandbox .\setup.ps1 Setup\setup.ps1
winapp target pull sandbox Results .\results

대상 경로는 대상의 관리되는 작업 영역을 기준으로 합니다. 절대, 루트 및 UNC 대상 경로가 거부됩니다. 파일 대상에는 해당 파일 이름이 포함됩니다. 디렉터리 레이아웃, 링크 처리 및 복사된 스크립트 실행에 대한 명령 실행 및 파일 복사 를 참조하세요.

대상 스냅샷

샌드박스를 시작하지 않고 준비 상태, 배포 및 게스트 창을 보고합니다.

winapp target snapshot <target> [--json]
winapp target snapshot sandbox

클라이언트를 다시 연결하거나 에이전트를 복구하지 않습니다. 샌드박스를 실행하는 것은 오류가 아니라 성공적인 결과입니다. 준비 상태 및 프로세스 ID 해석에 대한 샌드박스 검사를 참조하세요.

대상 스크린샷

앱 선택기 또는 호스트 창 테두리 없이 네이티브 픽셀 크기로 게스트 데스크톱을 호스트 PNG로 캡처합니다. --json 는 게스트 좌표 원본을 보고합니다.

winapp target screenshot <target> [-o <host-path>] [--json]
winapp target screenshot sandbox -o .\sandbox.png

대신 앱 창에 사용합니다 ui screenshot --on sandbox -a <app> . 클라이언트 요구 사항, 포커스 제한 사항 및 출력 처리에 대한 스크린샷 및 기록을 참조하세요.

대상 레코드

H.264 MP4에 게스트 데스크톱을 기록합니다. 녹화가 완료된 후 호스트 비디오 및 프레임 파일이 도착합니다. JSON 및 프레임 매니페스트는 크기 조정 또는 안쪽 여백을 설명합니다.

winapp target record <target> [-o <host-path>] [--duration-sec <n>] [--fps <n>] [--max-edge <px>] [--frames] [--overwrite] [--json]
winapp target record sandbox -o .\sandbox.mp4 --duration-sec 20 --fps 15

기간, 프레임, 덮어쓰기 및 결과 옵션을 ui record사용하지만 앱 하나가 아닌 데스크톱을 캡처합니다. 무인 CLI 사용에 대해 긍정 --duration-sec 을 선호합니다. npm 도우미에는 다음이 durationSec필요합니다. 부분 증거 및 캡처 준비 오류는 샌드박스 캡처 를 참조하세요.

---

find-ui

에이전트 우선. find-ui 는 주로 AI 코딩 에이전트를 위해 빌드됩니다. 에이전트가 실제로 끌어오고, 이를 발명하는 대신 배송 갤러리에서 WinUI 태그를 컴파일하고 --json , 모든 결과(및 모든 실패)를 컴퓨터에서 읽을 수 있도록 합니다. 그것은 손으로 입력뿐만 아니라 작동합니다.

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

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

갤러리, 도구 키트 및 Reactor corpora는 CLI 내부에 제공되므로 find-ui 에이전트 샌드박스에서 처음 실행하거나 차단하는 raw.githubusercontent.com회사 프록시 뒤에 있는 것을 포함하여 네트워크 액세스 없이 작동합니다. GitHub 연결할 수 있으면 CLI가 새로 고쳐지고 사용자별 결과를 아래에 <global .winapp>/cache/find-ui캐시합니다. 기본 제공 코퍼스는 바닥일 뿐이며 천장은 없습니다. 캐시된 데이터는 최대 24시간마다 또는 요청 시 새로 고쳐집니다 --refresh.

안정적인 릴리스가 빌드될 때마다 기본 제공 코퍼스가 GitHub 다시 가져오고, 실패하는 새로 고침은 오래된 데이터를 조용히 전달하지 않고 릴리스 빌드를 중지합니다. 베이커는 동일한 코드 경로를 --refresh 사용하여 페치하므로 오류가 발생하면 라이브 새로 고침도 끊어지고 배송 전에 조사할 가치가 있습니다. 릴리스는 이전에 커밋된 모음에 대해 계속 잘라낼 수 있지만 명시적 재정의로만 가능합니다. 갤러리/도구 키트/Reactor corpora find-ui 의 기본 제공 복사본에서 결과가 제공되면 stderr 및 --json 출력에 "corpus": "embedded" 대해 이렇게 말합니다(다른 값: "network" 새 인출의 경우, "cache" 로컬 캐시의 경우). 큐레이팅된 코어 패턴은 CLI로 컴파일되고 가져오지 않으므로 코어 전용 요청 --source core또는 --id 모든 핵심 패턴인 집합도 보고 "embedded" 합니다. 변경될 수 없으므로 부실 알림 --refresh 이 인쇄되지 않습니다. 이 corpus 필드는 결과가 제공될 때마다 보고되며, 코퍼스를 전혀 로드할 수 없는 경우에만 이 필드가 없습니다.

옵션:

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

관련:find-ui 는 WinUI 샘플을 검색합니다. 프로젝트 참조의 API 화면(형식, 멤버, 열거형)을 검색하고 winapp ui search실행 중인 앱의 UI 트리를 검색하는 데 사용합니다find-api.

---

find-api

에이전트 우선. find-api 는 주로 AI 코딩 에이전트를 위해 빌드됩니다. 즉, 프로젝트가 모델의 기억 대신 실제로 참조하는 API 표면에서 생성된 코드를 근거로 하고 --json 누락된 기호에 대한 0이 아닌 종료 코드는 에이전트 게이트 코드 생성을 답변에 허용합니다. 그것은 손으로 입력뿐만 아니라 작동합니다.

참조된 .winmd/.dll 메타데이터에서 확인된 프로젝트에서 사용할 수 있는 Windows/WinRT API 표면(형식, 멤버, 열거형, 네임스페이스)을 검색하고 검사합니다. 맨손으로 검색합니다. 하위 동사는 특정 형식, 네임스페이스 또는 인덱스 자체를 드릴합니다.

winapp find-api "<query>" [options]
winapp find-api [command] [options]

인덱스는 처음 사용할 때 프로젝트의 복원된 NuGet/SDK 패키지(통해 project.assets.json)에서 빌드되고 프로젝트가 복원될 때 자동으로 새로 고쳐집니다. 전역 .winapp 캐시(cache/find-api/)에 있으며 프로젝트 간에 공유됩니다. 프로젝트를 먼저 복원합니다(winapp restore 또는 dotnet restore).

각 일치 항목은 해당 네임스페이스 아래에 해당 항목을 제공하는 패키지와 해당 항목에 대한 한 줄 요약이 나열되므로 두 번째 members 호출 없이 결과를 사용할 수 있습니다.

[40] Microsoft.UI.Xaml.Media
    Class Microsoft.UI.Xaml.Media.AcrylicBrush  [Microsoft.WindowsAppSDK.WinUI 1.8.260224000]
        Paints an area with a semi-transparent material that uses multiple effects including blur and a noise texture.

또한 부 --verbose 실 또는 예기치 않은 인덱스를 진단할 때 유용한 각 네임스페이스를 지원하는 디스크 캐시 파일을 인쇄합니다.

쿼리 없이 실행 winapp find-api 하면 짧은 사용 요약이 인쇄되고 종료됩니다 0 . 이는 아무 것도 찾지 못한 검색이 아니라 도움말 요청입니다.

범위. 모든 답변은 텍스트 출력의 메모로 scope 보고되는 --json 정확히 하나의 범위에서 제공됩니다.

• project - 현재 디렉터리(또는 --project / --project-dir)의 프로젝트입니다. Windows SDK, Windows 앱 SDK 및 프로젝트 고유의 NuGet 패키지를 다룹니다. Windows 앱 SDK 메타데이터는 프로젝트에서 참조하는 릴리스입니다. 머신에 최신 Windows 앱 런타임이 설치된 find-api 경우 프로젝트에서 컴파일할 수 없는 형식을 확인하는 대신 경고하고 제외합니다.
• sdk- 현재 디렉터리에 프로젝트가 없고 솔루션이 없을 때 자동으로 사용되는 컴퓨터 전체 Windows SDK + Windows 앱 SDK 메타데이터입니다. 이렇게 하면 find-api 프로젝트가 존재하기 전에 API를 탐색하는 데 사용할 수 있으며 네트워크 액세스가 필요하지 않습니다. 의도적으로 타사 NuGet 패키지를 포함하지 않으므로 커뮤니티 도구 키트의 형식은 이 범위에서 찾을 수 없습니다.

프로젝트가 없고 솔루션이 없는 디렉터리의 쿼리는 항상 범위에 의해 sdk 응답됩니다. 즉, 공유 캐시에서 인덱싱되는 프로젝트가 없습니다. 따라서 결과는 관련 없는 전역 상태에 의존하지 않습니다. 프로젝트 winapp find-api refresh --project sdk 내에서 SDK 범위를 명시적으로 선택하고 새 Windows SDK를 설치한 후 다시 빌드하도록 전달 --project sdk 합니다.

솔루션 디렉터리. 프로젝트 파일이 없는 디렉터리 .sln/.slnx 에서 솔루션이 범위 대신 sdk 답변을 빌드하는 프로젝트는 요청 시 인덱싱되므로 NuGet 패키지가 포함됩니다. 솔루션이 둘 이상의 인덱싱된 프로젝트를 빌드할 때 쿼리는 인덱싱된 프로젝트를 나열하고 하나를 선택하지 않고 요청 --project <name> 합니다.

명령을:

• (bare)find-api "<query>" ["<query>"...] - 검색 유형 및 멤버 이름, 문서화된 요약으로 대체, 네임스페이스별로 그룹화
• members <type> [<type>...] [--filter <text>] - 형식의 속성, 이벤트 및 메서드 나열(서명이 있는 선언된 멤버, 형식을 선언하여 요약된 상속된 멤버)
• check-property <type> <property> [<property>...] - 형식에 속성이 있는지 확인합니다(누락된 경우 0이 아닌 경우 종료됨). 읽기 전용 속성은 일반 ✅속성이 아닌 ️ 및 "읽기 전용, 할당할 수 없음"으로 보고⚠되므로 설정할 수 있는 속성으로 ActualWidth 오인되지 않습니다. C# 및 XAML은 0이 아닌 종료되고 실제로 작성할 수 없는 이름을 보고하는 대신 거의 일치하는 것으로 제공 Background 되므로 check-property Button background 속성 이름은 대/소문자를 구분하여 일치합니다.
• enums <type> [<type>...] [--filter <text>] - 열거형의 값을 나열합니다(형식이 열거형이 아닌 경우 0이 아닌 경우 종료됨)
• packages - 패키지별 형식/멤버 수를 사용하여 인덱싱된 메타데이터 패키지 나열
• stats - 집계 인덱스 통계 표시(패키지, 네임스페이스, 형식, 멤버, .winmd 파일)
• refresh [--scan] - 프로젝트의 인덱스를 다시 작성합니다(--scan 디렉터리 아래의 모든 프로젝트를 인덱싱). 현재 --project <name>디렉터리를 인덱싱하는 대신 인덱싱된 단일 프로젝트와 일치하는 이름이 실패합니다.

Batching.search, members, enums및 check-property 한 호출 에서 여러 주체를 허용합니다. AI 에이전트의 경우 이는 단일 가장 큰 비용 레버입니다. 조회의 한계 비용은 페이로드 크기가 아니라 왕복(각 통화가 전체 대화를 다시 전송)에 의해 지배되므로 10개의 질문에 대답하는 한 통화는 10개의 호출보다 훨씬 저렴합니다.

• 단일 제목은 텍스트와 --json.
• 두 개 이상의 주체가 봉투 { "count": N, "results": [ ... ] }--json를 반환하며 각 요소는 일반 단일 주체 페이로드 check-propertymissingCount가 됩니다. 텍스트 출력은 각 제목을 하나의 범위 머리글 아래에 순서대로 렌더링합니다.
• check-property 한 형식에 속성을 일괄 처리합니다. 첫 번째 인수는 속성이 된 후의 모든 인수인 형식입니다. 일괄 처리 모드에서 존재하는 속성은 한 ✅ 줄로 인쇄되고, 누락에 가까운 전체 세부 정보는 그렇지 않은 속성에 대해서만 인쇄됩니다.
• 일괄 처리는 모든 주체가 0확인되고 발견된 경우에만 종료되므로 일괄 처리는 codegen을 제어하는 데 여전히 안전합니다.

검색 순위입니다. 형식 이름과 정확히 일치하는 쿼리는 부분 일치보다 먼저 순위가 지정되며, 여러 네임스페이스에서 짧은 이름을 공유하는 경우 정확한 이름 충돌만 모호한 것으로 나열됩니다. 이와 같은 NavigationView 쿼리는 비슷한 이름의 기호를 포함하는 모든 네임스페이스가 아닌 정확한 형식을 정의하는 소수의 네임스페이스를 보고합니다. 모호성 목록은 준수 --max하고, 일반 결과는 여전히 그 아래에 인쇄됩니다.

이름을memberscheck-property 입력하고 enums 짧은 이름() 또는 정규화된 이름(NavigationViewMicrosoft.UI.Xaml.Controls.NavigationView)을 허용합니다. 최신 Microsoft.* 형식과 해당 레거시 Windows.* UWP 쌍 Microsoft.* 에서 짧은 이름을 공유하는 경우 형식은 Windows 앱 SDK 앱에서 사용하는 프로젝션인 응답이며 확인된 정규화된 이름은 항상 표시됩니다. 다른 충돌은 0이 아닌 상태로 종료되고 추측하는 대신 후보를 나열합니다.

메서드 서명입니다. 호출을 작성하는 방식으로 서명이 인쇄됩니다. 인스턴스가 아닌 형식에서 호출하는 메서드가 표시static되고 참조 매개 변수가 실제로 필요한 outinref키워드와 함께 표시됩니다. 따라서 TryGetValue 쓰기로 컴파일되는 읽기 Boolean TryGetValue(String key, out String value)입니다.

옵션:

• --max <n> - 네임스페이스로 그룹화된 검색 결과의 최대 수(기본값 5, 검색 전용). 또한 모호성 목록의 한도를 지정하므로 여러 네임스페이스에서 충돌하는 짧은 쿼리를 읽을 수 있습니다.
• --filter <text> - 목록 members 범위를 좁히고 enums멤버/값 이름 에서 대/소문자를 구분하지 않는 부분 문자열 일치 항목입니다. 수백 명의 멤버가 있는 형식에 가장 적합합니다. 대부분의 열거형은 전체( Symbol197개 값에서 WinUI에서 가장 큰 값)를 덤프할 수 있을 만큼 작으므로 일반적으로 두 번째 추측을 고려하면 저장하는 것보다 더 많은 비용이 듭니다. 다른 필터 텍스트를 사용하여 동일한 명령을 다시 실행하지 마세요. 한 번 덤프하고 읽습니다.
• --all members- 전체 표면을 나열합니다. 상속된 멤버에 대한 전체 서명과 종속성 속성 식별자 정적 및 멤버별 설명이 모두 필터링되지 않은 목록이 생략됩니다(아래 목록 크기 참조). --verbose는 이를 의미합니다. 을 사용하려면 --json.--all와 --verbose함께 사용할 수 없습니다.
• --scan - 디렉터리 아래의 모든 프로젝트를 재귀적으로 검색하고 인덱싱합니다(refresh 전용).
• --project <name>- 쿼리(이름과 일치.csproj/.vcxproj) 또는 sdk 컴퓨터 전체 Windows SDK 범위를 쿼리하는 Project
• --project-dir <path>- 쿼리할 디렉터리를 Project(현재 디렉터리의 기본값) 존재하지 않는 경로는 오류입니다. 범위에서 sdk 자동으로 응답되지 않습니다.
• --json - stdout에서 컴퓨터에서 읽을 수 있는 페이로드를 내보낸다(모든 동사에서 지원됨). 쿼리 페이로드는 (또는 ) 및 (SDK 범위에 대해 없음)을 통해 scope 응답한 인덱스를 식별합니다. 프로젝트 이름은 디렉터리 간에 고유하지 않으므로 projectDir 신뢰할 수 있는 ID도 마찬가지입니다.projectDirprojectNamesdkproject --json 정수가 아닌 오류와 같은 인수/파서 오류를 비롯한 모든 오류에서 --max 0이 아닌 종료 코드가 있는 stdout의 플랫 {"error": "..."} 개체로 내보내지므로 출력은 컴퓨터에서 읽을 수 있게 유지됩니다.

예:

# Search
winapp find-api "acrylic brush"
winapp find-api NavigationView --max 10

# Inspect and validate
winapp find-api members Microsoft.UI.Xaml.Controls.NavigationView
winapp find-api check-property Button Background
winapp find-api enums Symbol

# Batch — one call instead of one per subject
winapp find-api check-property InfoBar Severity IsOpen Message Title
winapp find-api members InfoBar TeachingTip ContentDialog
winapp find-api enums InfoBarSeverity Visibility
winapp find-api "acrylic brush" "teaching tip" --max 5

# Narrow a large type instead of dumping it and grepping
winapp find-api members Button --filter background

# Full member surface: inherited signatures, dependency-property statics, descriptions
winapp find-api members Button --all

# Manage the index
winapp find-api refresh

# Explore the Windows SDK with no project at all (e.g. before scaffolding an app)
winapp find-api "acrylic brush"          # from an empty directory -> scope: sdk
winapp find-api members Button --project sdk

적용된 경우 --filter 출력은 필터링되지 않은 합계(totalValues또는totalEvents//totalPropertiestotalMethods 내부--json)를 계속 보고하므로 좁은 보기는 작은 API로 오인되지 않습니다. 아무것도 일치하지 않는 필터는 여전히 종료 0 되고 명시적으로 말합니다. 즉, "필터와 일치하는 항목이 없습니다"가 아니라 "그러한 형식 없음"입니다.

목록 크기입니다. 필터링 members 되지 않은 목록은 비용이 많이 드는 하나의 셰이프 members Button 이며, 288개의 멤버를 포함하며, 그 중 280개는 6가지 기본 형식에서 상속됩니다. 필터링되지 않은 호출은 방향 쿼리("이 형식은 무엇인가요, 대략 무엇을 할 수 있습니까?")이므로 응답하고 기록되지 않은 부분을 생략합니다.

• 상속된 멤버 서명 - 상속된 멤버는 형식을 선언하여 그룹화되고 이름으로만 나열되므로 상속된 표면의 모양은 280개의 전체 서명 없이 계속 표시됩니다.
• 종속성 속성 식별자 정적 (BackgroundProperty) - 일반적인 WinUI 컨트롤의 속성 중 28개%. 할당되지 않고 전달되어야 합니다 GetValue/SetValue.
• 멤버별 설명 - XML-doc 산문으로, 페이로드의 약 16%.
• (포함events/properties/methods 배열에 --jsonkind 의해 암시됨), (포함되는 배열에 의해 암시됨) returnType 및 inherited false(암시적)인 signature경우의 주변 영역에서 암시된 declaringType필드입니다.

생략된 항목은 항상 보고되며(hiddenDependencyPropertiesdescriptionsOmitted및 hint in--json; 텍스트의 "생략됨:" 줄) 합계는 여전히 전체 형식을 설명합니다. 둘 다 --filter 전체 서명 및 설명이 포함된 전체 표면을 확인하므로 members Button --filter BackgroundProperty 여전히 식별자를 찾고 members Button --filter Click 상속된 서명을 반환 Click--all 합니다. 측정한 samples/winui-app값은 91,954자에서 10,567자(-88.5자%)--filter까지 소요 members Button --json 되며 --all 바이트는 동일합니다.

쿼리 일치 방법 winapp find-api "language model" 위의 순위는 LanguageModel 형식이 인덱싱될 때 프로젝트 외부를 포함하여 네임스페이스 및 멤버에 단어가 분산된 단어와 일치합니다. 검색은 의미 체계가 아닌 어휘입니다. 즉, 문자가 실행되지 않고 전체 식별자 단어와 일치하므로 llm 검색하지만 찾을 IImageLLMAdapterSession 수는 없습니다 ScrollMode. 쿼리가 이름과 일치하지 않는 경우 형식 및 멤버의 문서화된 요약에 대해 시도됩니다. 이 요약을 통해 찾을 IRandomAccessStream수 있습니다"random-access stream". 설명은 모든 이름과 일치할 때마다 순위가 매겨지고 실제로 제공되는 패키지의 요약만 검색할 수 있습니다. XML 설명서가 없는 패키지는 설명 텍스트를 제공하지 않습니다.

MSBuild 프로젝트 파일이 없는 프로젝트입니다. Electron 앱(또는 다른 비 .NET 앱winapp.yaml)에는 없습니다.csproj.project.assets.json find-api .winapp/winmds.lock.json 는 해결된 각 패키지, 해당 winapp restore 버전 및 해당 패키지가 기여하는 파일과 같은 것을 기록하는 쓰기에서 .winmd 인덱싱합니다. 이러한 프로젝트의 이름은 해당 디렉터리의 이름을 따서 지정되며 lockfile을 다시 작성하면 인덱스가 부실합니다. a와 a .csprojwinapp.yaml 를 모두 포함하는 디렉터리가 인덱싱됩니다 .csproj. 이는 프로젝트가 컴파일하는 내용에 대한 보다 정확한 설명입니다.

인덱스가 불완전하면 부정 답변이 한정됩니다. 패키지의 메타데이터를 읽을 수 없는 경우 "이러한 형식 없음"과 "해당 패키지가 인덱싱되지 않음"은 동일하게 표시되며, 실제로 두 번째 항목이 API에 대한 코드를 생성할 때 첫 번째 항목에서 동작하는 작업은 존재하지 않는다고 들었습니다. 따라서 0개의 결과를 반환하는 것을 포함하여 search 모든 음수 답변은 인덱스가 부분적이고 을 가리 winapp find-api refresh킨다는 메모를 전달합니다. 긍정적인 답변은 영향을 받지 않습니다.

제네릭 형식 이름입니다. 메타데이터는 제네릭 형식을 arity 접미사(IAsyncOperation`1)로 저장하며, 이는 다른 사용자가 작성하는 방법이 아닙니다. members, enums및 check-property 모든 형식을 적용합니다 IAsyncOperation. , IAsyncOperation<StorageFile>및 IAsyncOperation`1 모두 동일한 형식으로 확인됩니다. 맨손 이름은 모든 arity와 일치합니다. 명시된 arity(두 표기법 중 하나)는 일치해야 하므로 Holder<A, B> 단일 매개 변수 Holder<T>로 확인되지 않습니다.

--json 페이로드는 진단을 생략합니다. 캐시 파일 경로는 아래에만 --verbose 나타나고(일치하는 텍스트 출력, 이미 자세한 정보만 표시됨) 빈 제안 배열은 직렬화되지 []않고 생략됩니다.

종료 코드:search 적수 없음, check-property 누락된 속성 및 enums 열거형이 아닌 형식에서는 모두 0이 아닌 종료(게이트 코드 생성 및 CI 검사)가 있습니다. 주체가 실패하면 일괄 처리된 호출이 0이 아닌 상태로 종료됩니다. 읽기 전용 속성은 오류가 아니므로 check-property 출력에서 종료 0 하고 플래그를 지정합니다(writable: false--json). 속성은 init 같은 이유로 보고 writable: false 합니다. 개체 이니셜라이저에서 설정할 수 있으며 해당 서명은 표시되지 { get; init; }만 나중에 할당해도 컴파일되지 않습니다.

관련:find-api 는 "이 API가 존재하며 해당 멤버는 무엇인가요?"라고 대답합니다. 컨트롤에 대해 작동하는 WinUI 샘플을 찾는 데 사용합니다 find-ui .

---

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 워크플로 ID

winapp ui 물리적 데스크톱을 구동하는 명령은 항상 협조적인 회전을 수행하므로 한 번에 실행되는 두 워크플로는 서로의 포커스를 훔치거나 서로의 메뉴를 해제할 수 없습니다. 해당 중재는 설정이 필요하지 않으며 해제할 수 없습니다.

선택 사항인 것은 연속성입니다. 기본적으로 각 명령은 데스크톱이 완료되는 즉시 릴리스되는 자체 포함 원샷입니다. 여러 명령에서 데스크톱을 유지하려면 동일한 워크플로 ID를 모두 제공합니다.

$env:WINAPP_UI_WORKFLOW_ID = [guid]::NewGuid().ToString()

협력 프로세스에 동일한 값(예: 기록 및 캡처해야 하는 클릭)과 독립적인 워크플로에 대해 다른 값을 사용합니다. ID가 없는 모든 명령은 하나의 셸에서 여러 명령을 시작한 경우에도 고유한 원샷 워크플로이므로 명령당 새 셸을 시작하는 호스트는 각 셸에 동일한 명시적 값을 삽입해야 합니다. 값은 불투명하고 자격 증명으로 처리되지 않으며 SHA-256 해시로만 유지됩니다. UI 자동화 → 동시 UI 워크플로 조정을 참조하세요.

ui

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

winapp ui [command] [options]

명령을:

• status - 앱에 연결하고 정보 표시
• inspect - 요소 트리 보기
• search - 선택기로 요소 찾기
• get-property - 요소 속성 읽기
• get-text / get-value - 요소(TextPattern, ValuePattern 또는 Name)에서 값/텍스트를 읽습니다.
• screenshot - PNG로 창/요소 캡처(여러 창이 하나의 레이블이 지정된 복합 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 - 현재 포커스가 있는 요소 보고
• yield - 현재 워크플로의 UI 턴을 해제합니다. 요구 사항 WINAPP_UI_WORKFLOW_ID

옵션:

• -a, --app <app> - 대상 앱(이름, 제목 또는 PID)
• -w, --window <hwnd> - HWND별 대상 창(안정)
• --on <target>- 이름, PID 및 창 핸들에서 sandbox동 ui 사를 실행하면 게스트가 참조됩니다. 출력은 호스트에 전달됩니다. 설치, 워크플로 조정 및 클라이언트 요구 사항은 샌드박스 UI 자동화 를 참조하세요.

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 evidence.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).
• --overwrite - 새 테이크가 완료된 후 기존 기록 출력을 바꿉니다. 기존 출력은 기본적으로 거부됩니다. 이전 프레임 번들은 유지됩니다. 출력 복구 기록을 참조하세요.
• --frames- 타임스탬프가 지정된 JPEG frames.ndjsonmanifest.json<output-name>.frames를 작성하고 1GiB 프레임 데이터 한도를 사용하여 1-30fps 및 --max-edge 64-4096(기본값 1280)을 지원합니다.

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

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

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