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

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

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

# 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 — Обработка только операций файлов конфигурации, пропуск установки пакета

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

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

Автоматическое обнаружение проекта .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 создание манифеста)

winapp pack <input-folder> [options]

Аргументы:

  • input-folder — каталог, содержащий файлы приложения для упаковки

Варианты.

  • --output <filename> — Выходное имя ФАЙЛА MSIX (по умолчанию: <name>_<version>_<arch>.msix, возвращающееся в <name>_<version>.msix, <name>_<arch>.msixили <name>.msix когда не удается определить версию или арку)
  • --name <name> — Имя пакета (по умолчанию: из манифеста)
  • --manifest <path> — Путь к файлу манифеста (Package.appxmanifest предпочтительный, appxmanifest.xml также поддерживаемый; по умолчанию: автоматическое обнаружение)
  • --cert <path> — Путь к сертификату подписывания (включает автоматическую подпись)
  • --cert-password <password> — пароль сертификата (по умолчанию: "пароль")
  • --generate-cert — создание нового сертификата разработки
  • --install-cert — установка сертификата на компьютер
  • --publisher <name> — имя Publisher для создания сертификатов
  • --self-contained — среда выполнения пакета Windows App SDK
  • --skip-pri — пропустить создание файла PRI
  • --executable <path> — Путь к исполняемому файлу относительно входной папки (также --exe). Используется для разрешения $targetnametoken$ плейсхолдеров в манифесте.

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

  • Проверяет и обрабатывает файлы Package.appxmanifest
  • $placeholder$ Разрешает маркеры в манифесте (см. заполнители манифеста ниже)
  • Обеспечивает корректность зависимостей фреймворка
  • Обновляет параллельные манифесты с регистрацией
  • Автоматически обнаруживает сторонние компоненты 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

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

Создайте удостоверение приложения для отладки с помощью разреженной упаковки. 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> — cn Publisher (по умолчанию: CN=<current user>)
  • --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) происходит сбой отображения имен и смещения модулей. Одновременно использовать другие отладчики (Visual Studio, VS Code) нельзя одновременно использовать только один отладчик. Используйте --no-launch вместо этого, если необходимо подключить другой отладчик. Не удается объединить с --no-launch. Не удается объединить с --json.
  • --symbols — скачивание символов PDB из сервера символов Microsoft для более полного анализа аварийного сбоя с именами разрешенных функций. Используется только с --debug-output. Если опущено и происходит сбой в собственном коде, выходные данные предполагают добавление этого флага. Сначала запускается скачивание символов и кэширует их локально; последующие запуски используют кэш.
  • --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 сертификата
  • --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 рабочей области
  • Каталоги установки пакетов
  • Созданные расположения заголовков

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.

ui

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

winapp ui [command] [options]

Команды:

  • status — Подключение к приложению и отображение сведений
  • inspect — Представление дерева элементов
  • search — Поиск элементов по селектору
  • get-property — чтение свойств элемента
  • get-text / get-value — чтение значения и текста из элемента (TextPattern, ValuePattern или Name)
  • screenshot — запись окна или элемента в формате PNG (диалоговые окна автоматического захвата отдельно)
  • invoke — Активировать элемент (щелчок, переключатель, развернуть)
  • click — Щелкните элемент с помощью имитации мыши (для элементов управления, которые не поддерживают вызов)
  • set-value — Задать значение для редактируемого элемента (текст, число)
  • focus — Перемещение фокуса клавиатуры
  • scroll-into-view — видимый элемент scroll
  • wait-for — ожидание состояния элемента
  • list-windows — Вывод списка всех окон для приложения
  • get-focused — Сообщите об элементе, ориентированном на данный момент

Варианты.

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

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

  • Last updated on