Документация и использование ИНТЕРФЕЙСА командной строки

Завершение оболочки

Включите завершение вкладки для команд, параметров и значений. Инструкции по настройке см. в руководстве по завершению оболочки .

# 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

инициализация

Инициализируйте каталог с Windows SDK, Windows App SDK и необходимыми ресурсами для современной разработки Windows.

winapp init [base-directory] [options]

Аргументы:

  • base-directory — базовый или корневой каталог для приложения или рабочей области (по умолчанию: текущий каталог)

Варианты.

  • --config-dir <path> — каталог для чтения и хранения конфигурации (по умолчанию: текущий каталог)
  • --setup-sdks — режим установки пакета SDK: "стабильный" (по умолчанию), "предварительная версия", "экспериментальный" или "нет" (пропустить установку пакета SDK)
  • --ignore-config, --no-config — не используйте файл конфигурации для управления версиями
  • --no-gitignore — Не обновляйте файл gitignore
  • --use-defaults, --no-prompt — не запрашивайте и используйте по умолчанию все запросы.
  • --config-only — Обработка только операций файлов конфигурации, пропуск установки пакета
  • --add-js-bindings (только npm) — добавление winapp.jsBindings в package.json и создание привязок JS/TypeScript без запроса (несовместимо с --setup-sdks none)

Что он делает:

  • Создает winapp.yaml файл конфигурации (только если пакеты SDK управляются; пропускаются с --setup-sdks noneпомощью )
  • Скачивает пакет Windows SDK и пакеты Windows App SDK
  • Создает заголовки и двоичные файлы C++/WinRT
  • Создает Package.appxmanifest
  • Настройка средств сборки и включение режима разработчика
  • Обновляет .gitignore, чтобы исключить созданные файлы
  • Хранит общие файлы в каталоге глобального кэша
  • Создает привязки JS для Windows App SDK API при включении (только npm)

Автоматическое обнаружение проектов:

При init выполнении без аргумента каталога выполняется первый поиск текущего дерева каталогов для поиска совместимых проектов (до 10). Поддерживаемые типы проектов:

  • Tauri — tauri.conf.json найден один уровень ниже каталога
  • Electron — package.json с electron зависимостями или 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 на TFM, совместимый с Windows (например, net10.0-windows10.0.26100.0)
  • Добавляет Microsoft.WindowsAppSDK и Microsoft.Windows.SDK.BuildTools как записи NuGet PackageReference непосредственно в .csproj
  • Создает Package.appxmanifest, ресурсы и сертификат разработки
  • Не создает winapp.yaml или загружает проекции на C++ (используйте dotnet restore для пакетов NuGet)

Примеры:

# 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 после начальной установки

Если вы выполнили (или пропустили init--setup-sdks none установку пакета SDK), а затем потребуется пакеты SDK:

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

Используйте --setup-sdks preview или для предварительных и --setup-sdks experimental экспериментальных версий пакета SDK.

Восстановление

Восстановите пакеты и повторно создайте файлы на основе существующей winapp.yaml конфигурации.

winapp restore [options]

Варианты.

  • --config-dir <path> — Каталог, содержащий winapp.yaml (по умолчанию: текущий каталог)

Что он делает:

  • Считывает существующую winapp.yaml конфигурацию
  • Скачивание и обновление пакетов SDK для указанных версий
  • Повторно создает заголовки и двоичные файлы C++/WinRT
  • Хранит общие файлы в каталоге глобального кэша

Замечание

Для проектов .NET, инициализированных с помощью winapp init, нет winapp.yaml. Вместо этого используется dotnet restore для восстановления пакетов NuGet.

Примеры:

# Restore from winapp.yaml in current directory
winapp restore

update

Обновите пакеты до последних версий и обновите файл конфигурации.

winapp update [options]

Варианты.

  • --setup-sdks <stable|preview|experimental|none>— режим установки пакета SDK: stable (по умолчанию), previewexperimentalили none (пропустить установку пакета 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 App SDK
  • --skip-pri — пропустить создание файла PRI
  • --executable <path> — Путь к исполняемому файлу относительно входной папки (также --exe). Используется для разрешения $targetnametoken$ плейсхолдеров в манифесте.

Что он делает:

  • Проверяет и обрабатывает файлы Package.appxmanifest
  • $placeholder$ Разрешает маркеры в манифесте (см. заполнители манифеста ниже)
  • Обеспечивает корректность зависимостей фреймворка
  • Обновляет параллельные манифесты с регистрацией
  • Автоматически обнаруживает и упаковает все файлы, не связанные с изображением, на которые ссылается манифест (например, AppExtension manifest.json, файлы конфигурации) из каталога манифеста или папки ввода, если они отсутствуют в промежуточном режиме.
  • Автоматически обнаруживает сторонние компоненты WinRT и регистрирует их активируемые классы (см. сведения об обнаружении компонентов WinRT ниже).
  • Обрабатывает автономное развертывание WinAppSDK
  • Подписывает пакет, если предоставлен сертификат

Обнаружение компонентов WinRT

При упаковке автоматически сканирует пакеты NuGet, winapp pack определенные в winapp.yaml компонентах WinRT сторонних *.csproj производителей (например, Win2D). Он анализирует .winmd файлы для извлечения имен активируемых классов и находит их библиотеки DLL реализации. Обнаруженные записи регистрируются следующим образом:

  • Зависящие от платформы (по умолчанию): активируемые классы добавляются в качестве <InProcessServer> записей в Package.appxmanifest
  • Автономные (--self-contained): активируемые классы внедрены в параллельные манифесты (SxS) в исполняемый файл.

Разрешение заполнителей во время упаковки:

Если манифест содержится $targetnametoken$ в атрибуте Executable :

  1. Если --executable указан (путь относительно входной папки), заполнитель заменяется указанным значением.
  2. winapp pack В противном случае проверяет корневой каталог входной папки для .exe файлов— если он найден, он используется автоматически.
  3. Если найдено ноль или несколько .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 первичного исполняемого файла, проверяет согласованность между срезами (удостоверения, возможности, зависимости) и создает .<Name>_<Version>_<arch1>_<arch2>.msixbundle

Разрешение манифеста для пакетов:

Каждый срез в пакете нуждается в манифесте. Команда разрешает манифесты в следующем порядке:

  1. --manifest <path> — Если указано, этот один манифест используется для всех срезов. Автоматически ProcessorArchitecture обновляется на срез для соответствия обнаруженной архитектуре.

  2. Манифест для каждой папки— если каждая входная папка содержит Package.appxmanifest манифест (или appxmanifest.xml), этот манифест используется для его среза.

  3. Текущая резервная версия каталога — если папка не имеет манифеста, команда ищет Package.appxmanifest в текущем рабочем каталоге и использует ее (с автоматической меткой архитектуры).

Во всех случаях манифест автоматически обновляется: заполнители разрешаются, добавляются зависимости, а ProcessorArchitecture для обнаруженной архитектуры задано принудительное значение. После разрешения проверка перекрестного среза гарантирует согласованность удостоверений (имя, версия, 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

создать-отладочный-идентификатор

Создайте удостоверение приложения для отладки с помощью разреженной упаковки. Exe остается в исходном расположении— Windows связывает удостоверение с ним через Add-AppxPackage -ExternalLocation.

Если использовать это vswinapp run: используйтеcreate-debug-identity, если exe-файл отделен от кода приложения (например, приложения Electron, где electron.exe находится), node_modulesили при тестировании разреженного поведения пакета. Для большинства платформ, где exe находится в выходной папке сборки, используйте winapp run вместо этого — он регистрирует полный свободный пакет макета и запускает приложение. Полный сравнение см. в руководстве по отладке .

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

Аргументы:

  • entrypoint — Путь к исполняемому файлу (.exe) или скрипту, которому требуется удостоверение

Варианты.

  • --manifest <path> — Путь к файлу манифеста приложения либо Package.appxmanifest (по appxmanifest.xml умолчанию: автоматическое обнаружение Package.appxmanifest или appxmanifest.xml в текущем каталоге)
  • --no-install — Не устанавливайте пакет после создания
  • --keep-identity — Сохраняйте удостоверение манифеста as-is, не добавляя .debug к имени пакета и идентификатору приложения.

Что он делает:

  • Изменяет параллельный манифест исполняемого файла
  • Регистрирует разреженный пакет для идентичности
  • Активирует отладку 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

manifest

Создание файлов Package.appxmanifest и управление ими.

Генерация манифеста

Создайте Package.appxmanifest из шаблонов.

winapp manifest generate [directory] [options]

Аргументы:

  • directory — каталог для создания манифеста в (по умолчанию: текущий каталог)

Варианты.

  • --package-name <name> — Имя пакета (по умолчанию: имя папки)
  • --publisher-name <name>— Publisher различающееся имя (по умолчанию: CN=<current user>). Принимает любое допустимое DN X.500; имена обнажены автоматически в виде CN=<name>.
  • --version <version> — версия (по умолчанию: "1.0.0.0".0")
  • --description <text> — Описание (по умолчанию: "Мое приложение")
  • --entrypoint <path> — исполняемый файл или скрипт точки входа
  • --template <type> — тип шаблона: packaged (по умолчанию) или sparse
  • --logo-path <path> — Путь к файлу изображения логотипа
  • --if-exists <Error|Overwrite|Skip> — Поведение, когда файл манифеста уже существует в целевом пути (по умолчанию: Error)

Шаблоны:

  • packaged — Стандартный манифест упаковаемого приложения
  • sparse — Манифест приложения с использованием разреженного/внешнего расположения упаковки

Заполнители для манифеста

Созданные манифесты используют $placeholder$ токены (ограниченные знаками доллара), которые обрабатываются автоматически в процессе упаковки.

Заполнитель Решено Пример
$targetnametoken$ Имя исполняемого файла без расширения Executable="$targetnametoken$.exe" → Executable="MyApp.exe"
$targetentrypoint$ Windows.FullTrustApplication Всегда решается автоматически

Это следует тому же соглашению, используемому шаблонами проектов Visual Studio, поэтому манифесты переносятся между инструментами.

Как обрабатываются заполнители:

  • winapp pack — Во время упаковки $targetnametoken$ разрешается с помощью --executable параметра или автоматического обнаружения одного .exe в входной папке. Если найдено несколько (или ноль) .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

Псевдоним надстройки манифеста

Добавьте псевдоним выполнения (uap5:AppExecutionAlias) в Package.appxmanifest. Это позволяет запустить упаковаемое приложение из командной строки, введя имя псевдонима.

winapp manifest add-alias [options]

Варианты.

  • --name <alias> — имя псевдонима (например, myapp.exe). По умолчанию: вывод из атрибута Executable в манифесте.
  • --manifest <path> — Путь к Package.appxmanifest (по умолчанию: поиск текущего каталога)
  • --app-id <id> — Идентификатор приложения для добавления псевдонима в (по умолчанию: первый элемент Application)

Что он делает:

  • Считывает манифест и выводит псевдоним из Executable атрибута (сохраняя заполнители, например $targetnametoken$.exe)
  • Добавляет объявление пространства имен, uap5 если оно еще отсутствует
  • <Extensions> Добавляет блок внутри <uap5:AppExecutionAlias> целевого элемента Application
  • Если псевдоним уже существует, сообщает об этом и завершает работу успешно.

Примеры:

# 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> — Путь к отдельному исходному изображению для вариантов светлой темы

Description:

Принимает один исходный образ и создает полный набор ресурсов образов MSIX на основе ссылок на ресурсы манифеста:

Для каждого ресурса, на который ссылается манифест:

  • 5 вариантов масштабирования — база (без суффикса), .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

Additionally:

  • 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 с помощью API Windows.Management.Deployment.PackageManager и запустите приложение— имитацию полной установки MSIX для отладки. Возвращает идентификатор процесса для вложения отладчика.

This — предпочтительная команда для отладки с удостоверением пакета для большинства платформ (.NET, C++, Rust, Flutter, Tauri). В отличие от create-debug-identity того, что регистрирует разреженный пакет для одного exe-файла, 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 — Только создайте удостоверение отладки и зарегистрируйте пакет без запуска приложения.
  • --with-alias — Запустите приложение с помощью псевдонима выполнения вместо активации AUMID. Приложение выполняется в текущем терминале с унаследованным stdin/stdout/stderr. Требуется uap5:ExecutionAlias в манифесте (используется winapp manifest add-alias для добавления). Не удается объединить с --no-launch. Не удается объединить с --json.
  • --debug-output — захват OutputDebugString сообщений и исключений первого шанса из запущенного приложения. Шум платформы (WinUI, COM, DirectX) фильтруется из выходных данных консоли; Полный файл журнала записывает все. Если приложение завершится сбоем, автоматически фиксирует мини-dump и анализирует его, чтобы отобразить тип исключения, сообщение и трассировку стека с исходными номерами файла:строки (разрешены из PDF-файлов в папке выходных данных сборки). Управляемые (.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 — скачивание символов PDB из сервера символов Microsoft для более полного анализа аварийного сбоя с именами разрешенных функций. Используется только с --debug-output. Если опущено и происходит сбой в собственном коде, выходные данные предполагают добавление этого флага. Этот флаг также улучшает стек трех исключений WinUI для приложений WinUI 3. Сначала запускается скачивание символов и кэширует их локально; последующие запуски используют кэш.
  • --unregister-on-exit — Отмена регистрации пакета разработки после завершения работы приложения. Удаляет только пакеты, зарегистрированные в режиме разработки. Не удается объединить с --no-launch.
  • --detach — Запустите приложение и вернитесь немедленно, не ожидая выхода. Полезно для ci/automation, где необходимо взаимодействовать с приложением после запуска. Выводит piD в stdout (или в ФОРМАТЕ JSON).--json Не удается объединить с --no-launch, --debug-outputили --with-alias--unregister-on-exit.
  • --clean — Удалите данные приложения существующего пакета (LocalState, параметры и т. д.) перед повторной развертыванием. По умолчанию данные приложения сохраняются во время повторного развертывания.
  • --json — форматируйте выходные данные в формате JSON для программного использования (например, CI/automation). Полезно для --detach записи ИДЕНТИФИКАТОРА. Нельзя объединить с --with-alias или --debug-output.

Сохраняемость данных приложения:

По умолчанию winapp run сохраняет данные приложения (LocalState, RoamingStateи Settingsт. д.) при повторном развертывании. Если приложение записывает данные в ApplicationData.Current.LocalFolder контекст пакета или Environment.GetFolderPath(SpecialFolder.LocalApplicationData) в контексте пакета, эти данные будут выжить в разных winapp run вызовах.

Используйте --clean при необходимости нового запуска (например, для сброса поврежденного состояния или тестирования поведения первого запуска).

Что он делает:

  • Находит или создает Package.appxmanifest
  • Создает и регистрирует удостоверение отладки с помощью свободного пакета макета
  • Вычисляет идентификатор пользовательской модели приложения (AUMID)
  • Запускает приложение с помощью зарегистрированного удостоверения (если --no-launch не указано)
  • Выводит идентификатор процесса (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):

При использовании пакета NuGet Microsoft.Windows.SDK.BuildTools.WinAppdotnet run автоматически вызывает winapp run. Следующие свойства MSBuild можно задать в .csproj поведении элемента управления:

Недвижимость По умолчанию Описание
EnableWinAppRunSupport true Включение и отключение функции поддержки запуска
WinAppLaunchArgs (пусто) Аргументы для передачи приложению при запуске
WinAppRunUseExecutionAlias false Запуск с помощью псевдонима выполнения вместо активации AUMID
WinAppRunNoLaunch false Только регистрация удостоверения без запуска
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 Создайте файл каталога, содержащий хэши исполняемых файлов из указанных каталогов. Этот каталог используется с флагом TrustedLaunch в манифестах разреженных пакетов MSIX (AllowExternalContent), чтобы разрешить выполнение внешних файлов, не включенных в сам пакет.

Это похоже на создание signtool.exeAppxMetadata\CodeIntegrity.cat при подписи пакета MSIX, но создает внешний каталог для использования с упаковкой разреженных и внешних расположений.

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) с хэшами всех найденных исполняемых файлов
  • Использует API-интерфейсы CryptoCAT Windows для создания файла каталога .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

Когда следует использовать:

Используйте эту команду при создании разреженного пакета MSIX, использующего TrustedLaunch для проверки внешних исполняемых файлов. Типичный рабочий процесс:

  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 — утилита манифеста для сборок, выполняемых бок о бок
  • И другие средства пакета SDK Windows из Microsoft.Windows. SDK. BuildTools

Примеры:

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

store

Выполните команду Developer CLI в Microsoft Store. Эта команда скачивает Microsoft Store CLI разработчика, если он еще не скачан. Дополнительные сведения о интерфейсе командной строки разработчика Microsoft Store.

winapp store [args...]

Аргументы:

Что он делает:

  • Гарантирует, что Microsoft Store CLI разработчика (msstore) скачан и доступен в системе.
  • Перенаправит все аргументы в ИНТЕРФЕЙС командной 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

Получите пути к установленным компонентам пакета SDK для Windows.

winapp get-winapp-path [options]

Возвращаемая функция:

  • Пути к каталогу .winapp рабочей области
  • Каталоги установки пакетов
  • Созданные расположения заголовков

создание привязок узла

(Доступно только в пакете NPM) Создайте привязки JS для Windows App SDK API. Привязки объявляются пространством "winapp": { "jsBindings": {...} } имен и записываются в package.json.winapp/bindings/.

npx winapp node generate-bindings [options]

Варианты.

  • --verbose, -v — включение подробных выходных данных кода файла
  • --quiet, -q — подавление хода выполнения и информационных выходных данных

Что он делает:

  • Считывает winapp.jsBindings блок из package.json и winmds.lock.json записанный последним winapp restore, а затем выдает типизированные .js + .d.ts привязки в .winapp/bindings/
  • Не изменяет package.json — это пассивный регенератор. winapp.jsBindings Добавление блока и @microsoft/dynwinrt зависимости среды выполнения происходит во время winapp init включения привязок JS. Эта команда выполняется быстро, если блок отсутствует.
  • Предупреждает (но не записывает), если @microsoft/dynwinrt отсутствует из зависимостей — выполните его npm install после init добавления.

Замечание

Привязки являются только npm - они требуют вызова через npx winapp ( @microsoft/winappcli пакет npm); автономный интерфейс командной строки winget не отображает их. Выполните winapp init интерактивный запуск и согласие или использование winapp init . --use-defaults --add-js-bindingsперед использованием этой команды для повторного создания привязок. При изменении winapp.yamlвыполните обновление npx winapp restore Windows зависимостей перед повторной созданием.

Примеры:

# 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 создать-дополнение

(доступно только в пакете NPM) Создание собственных шаблонов надстроек C++ или C# с помощью пакета SDK Windows и интеграции Windows App SDK.

npx winapp node create-addon [options]

Варианты.

  • --name <name> — имя надстройки (по умолчанию : nativeWindowsAddon)
  • --template — выберите тип надстройки. Параметры или cscpp (по умолчанию: cpp)
  • --verbose — включение подробных выходных данных

Что он делает:

  • Создает каталог надстройки с файлами шаблонов
  • Создает binding.gyp и addon.cc с примерами пакета SDK Windows
  • Устанавливает необходимые зависимости 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

node add-electron-debug-identity

(Доступно только в пакете NPM) Добавьте удостоверение приложения в процесс разработки Electron с помощью разреженной упаковки. Требуется 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]

Варианты.

Опция Описание
--manifest <path> Путь к пользовательскому package.appxmanifest (по умолчанию: Package.appxmanifest в текущем каталоге)
--no-install Не устанавливайте и не изменяйте зависимости; настраивайте только идентификатор отладки в Electron
--keep-identity Сохраните идентичность манифеста в неизменном виде, без добавления .debug к имени пакета или идентификатору приложения.
--verbose Включите подробный вывод

Что он делает:

  • Регистрирует удостоверение отладки для процесса electron.exe
  • Включает тестирование api-интерфейсов, требующих идентификации, в разработке Electron
  • Использует существующий 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 путем восстановления исходного electron.exe из резервной копии.

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

Варианты.

Опция Описание
--verbose Включите подробный вывод

Что он делает:

  • Восстанавливает electron.exe из резервной копии, созданной add-electron-debug-identity
  • Удаляет файлы резервной копии после восстановления
  • Возвращает Значение 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 периодически проверяет наличие новых версий и отображает однострочный уведомление о доступности обновления. Эта проверка выполняется в фоновом режиме и не добавляет задержку в команды.

Проверки обновлений автоматически отключаются в средах 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

Проверьте и взаимодействуйте с запущенными пользовательскими интерфейсами приложений Windows с помощью модель автоматизации пользовательского интерфейса (UIA).

winapp ui [command] [options]

Команды:

  • status — Подключение к приложению и отображение сведений
  • inspect — Представление дерева элементов
  • search — Поиск элементов по селектору
  • get-property — чтение свойств элемента
  • get-text / get-value — чтение значения и текста из элемента (TextPattern, ValuePattern или Name)
  • screenshot — запись окна или элемента в формате PNG (диалоговые окна автоматического захвата отдельно)
  • record— Запись области окна или элемента в видео H.264 MP4 (Windows запись графики + Media Foundation)
  • invoke — Активировать элемент (щелчок, переключатель, развернуть)
  • click — Щелкните элемент с помощью имитации мыши (для элементов управления, которые не поддерживают вызов)
  • hover — Переместите мышь на элемент, чтобы активировать всплывающие подсказки, всплывающие элементы и состояния наведения указателя мыши (по умолчанию: 800 мс)
  • drag — Перетащите мышь из одной точки в другую, по селектору элементов или координатам экрана x,y (переупорядочение, изменение размера, ползунки, перетаскивание)
  • touch— Внедрение искусственных сенсорных жестов (касание, двойное касание, длинное нажатие, пальцем, сцепление, растяжение) в центре элементов или координатах экрана x,y
  • pen — Ввод искусственных пера и пера пера и пера — касания и росчерки рукописного ввода с настраиваемым давлением, наклоном и режимом ластика
  • send-keys — Отправка искусственных вводов клавиатуры (именованные клавиши, combos, необработанный vk=0xNN или литеральный текст) в окно
  • set-value — задайте значение для редактируемого элемента (текст, число); возвращается к элементу управления LegacyIAccessible put_accValue для элементов управления с расширенным доступом для TextPattern.
  • focus — Перемещение фокуса клавиатуры
  • scroll-into-view — видимый элемент scroll
  • wait-for — ожидание состояния элемента
  • list-windows — Вывод списка всех окон для приложения
  • get-focused — Сообщите об элементе, ориентированном на данный момент

Варианты.

  • -a, --app <app> — Целевое приложение (имя, название или PID)
  • -w, --window <hwnd> — Целевое окно по HWND (стабильная)

запись пользовательского интерфейса

Запишите целевое окно (или регион одного элемента) в видео 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 — Запись с экрана, поэтому включены наложения или всплывающие окна (может записывать окна occluding).
  • -o, --output <path> — выходной .mp4recording-<timestamp>-<guid>.mp4путь (по умолчанию — ).

С --jsonпомощью , выдает UiRecordResult конверт, включая выходные данныеpath, frames, widthheight, , fileSize(codec"h264") и mode — путь захвата фактически используемый (wgc, printwindowилиscreen).

Известное ограничение: запись определенного элемента внутри всплывающего окна, отображающегося в собственном окне верхнего уровня (всплывающее меню WinUI/XAML, подсказка обучения, подсказка) может записать базовое главное окно. Запишите все окно или используйте ui screenshot --capture-screen для всплывающих окон. Отслеживается в #646.

Полная документация см. в документации по docs/ui-automation.md.

  • Last updated on