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

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

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

# 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 — Обработка только операций файлов конфигурации, пропуск установки пакета
  • --exe <path> — Путь к исполняемому файлу приложения. Требует использования --sparse. Создает разреженный манифест только для удостоверений для exe вместо полной настройки пакета или пакета SDK.
  • --sparse — создание разреженного манифеста удостоверения (appxmanifest.xml) для существующего классического exe. Пропускает установку пакета SDK или пакета. Используйте с --exe.
  • --name <name> — переопределите имя пакета (только разреженное; значение по умолчанию: вывод из exe)
  • --publisher <CN> — переопределите cn издателя (только разреженный; значение по умолчанию: вывод из имени компании exe)
  • --output-dir <path> — Каталог для записи разреженного манифеста и Assets/ (разреженный только; по умолчанию: sparse/ папка в текущем каталоге)
  • --force — перезапись существующего appxmanifest.xml в целевом каталоге (только разреженный). Без него инициализация завершается ошибкой вместо замены существующего манифеста или ресурсов.
  • --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)

Разреженный режим идентификации (--exe + --sparse):

Создает манифест пакета только для удостоверений для существующего исполняемого файла рабочего стола — первый шаг разреженного процесса упаковки. В отличие от полного init потока, это пропускает все установки пакета SDK или пакета (разреженные пакеты удостоверений не имеют зависимостей ПАКЕТА SDK) и создает только ресурсы манифеста и заполнителя.

  • Выводит имя пакета, издателя, описание и версию из exe-файла FileVersionInfo (переопределяется с --nameпомощью , --publisherили интерактивно)
  • Записывает appxmanifest.xml (с именем exe, замененным Executableв ) плюс Assets/ папка в sparse/ папку в текущем каталоге (или --output-dir)
  • Используется --use-defaults/--no-prompt для пропуска интерактивных запросов переопределения (CI-friendly)
  • --exe без --sparse ошибки

Ресурсы являются внешними. Разреженный .msix — это только удостоверение: созданные Assets/ разрешены из каталога установки приложения (внешнего расположения содержимого) во время выполнения, а не в пакете .msix. Разверните их вместе с приложением.

Далее выполните следующие действия: winapp init --exe <exe> --sparsewinapp pack <appxmanifest.xml> чтобы создать удостоверение.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 после начальной установки

Если вы выполнили (или пропустили 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.

новый

Создайте новое приложение WinUI из официального шаблона Windows App SDKdotnet new. Интерактивный по умолчанию; автоматически использует значения по умолчанию в неинтерактивных средах.

winapp new [options]

Варианты.

  • -t, --template <short-name>— короткое имя шаблона (напримерwinui, , winui-navview, winui-mvvm, winui-lib). winui-unittest Проверено на установленный пакет во время выполнения; Выполните команду winapp new --list , чтобы просмотреть все. Значение по умолчанию: winui (пустое приложение).
  • -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

Шаблоны:

Список шаблонов считывается в режиме реального времени из установленного пакета, поэтому он всегда отражает версию, которую у вас есть , чтобы winapp new --list просмотреть текущий набор. Общие шаблоны:

Короткое имя Описание
winui Минимальное пустое приложение WinUI 3 (упаковка MSIX)
winui-navview Начальная версия приложения NavigationView
winui-tabview Начальная версия tabView
winui-mvvm Приложение MVVM (CommunityToolkit.Mvvm)
winui-lib Библиотека классов WinUI 3
winui-unittest Упакованое приложение MSTest; тесты выполняются при запуске

Каноническое короткое имя каждого шаблона является первым списком псевдонимов dotnet new для него; также принимается любой указанный псевдоним (например winui3, wasdk-single). При запуске внутри существующего проекта WinUI также отображает шаблоны элементов (например, dotnet new пустую страницу), которая winapp new добавляется в текущий проект, а не создает новый.

Управление версиями пакета шаблонов:

winapp new больше не закрепляет определенную версию пакета шаблонов. Если пакет не установлен, он устанавливает последнюю версию. Если старый пакет уже установлен, он проверяет веб-канал и, когда он существует, запрашивает обновление, за исключением неинтерактивных или--use-defaults запусков, которые сохраняют установленный пакет. Используйте --template-version latest всегда принимать новейшие без запроса или --template-version installed всегда использовать скачанный пакет без проверки сети. Передача явной версии (например --template-version 1.2.3, всегда устанавливает именно ту версию— переустановку, даже если новый пакет уже присутствует), поэтому шаблон воспроизводим на разных компьютерах.

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

  • Проверяет установку пакета SDK .NET (сбой с рекомендациями, если отсутствует — winapp не устанавливает цепочку инструментов)
  • Устанавливает или обновляет официальный пакет шаблонов WinUI (Microsoft.WindowsAppSDK.WinUI.CSharp.Templates) по запросу
  • Перечисляет доступные шаблоны из установленного пакета и делегирование шаблонов в dotnet new <short-name>

Шаблоны приложений WinUI уже включают Windows упаковку и удостоверение (Package.appxmanifest), поэтому отдельный winapp init шаг не требуется. Для шаблонов приложений используйте winapp run для создания и запуска приложения. Шаблон winui-lib создает библиотеку классов для ссылки из проекта приложения (он не имеет манифеста приложения). Шаблон winui-unittest — это упаковаемое приложение MSTest, тесты которого выполняются при запуске приложения (winapp run) — не через dotnet test. winapp newшаблонов для установленной платформы пакета SDK .NET и выводит соответствующий следующий шаг для выбранного шаблона.

Передайте глобальный --verbose флаг (-v) для передачи каждого базового dotnet вызова (запрос пакета, проверка обновления, установка, dotnet new listшаблон) вместе со своими полными выходными данными, полезными для диагностики проблем с шаблонным пакетом или шаблонами.

Примеры:

# 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

# 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 [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). Для разреженных пакетов удостоверений передайте разреженный appxmanifest.xml файл непосредственно вместо папки (см. раздел "Разреженные пакеты удостоверений ниже").

Варианты.

  • --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
  • Подписывает пакет, если предоставлен сертификат

Разреженные пакеты удостоверений

Если входные данные — это разреженный appxmanifest.xml файл (один объявленный <uap10:AllowExternalContent>true</uap10:AllowExternalContent> в <Properties>) вместо папки, создает только.msix удостоверение — winapp pack он упаковает только манифест без двоичных файлов или ресурсов приложения. Это шаг 2 рабочего процесса разреженной упаковки.

# Build a signed identity package from a sparse manifest
winapp pack ./sparse/appxmanifest.xml --cert ./devcert.pfx
  • Выходные <PackageName>.identity.msix данные по умолчанию в текущем каталоге (переопределяются с --output).
  • Подписывание происходит только в том случае, если --cert предоставляется (или --generate-cert)
  • Если вместо этого передать папку, манифест которой объявляетсяAllowExternalContent, применяется существующее поведение упаковки папок, но winapp pack предупреждает, находит ли ресурсы (.ico//.jpg.png) или двоичные файлы (.exe.dll//.so) для разреженных пакетов, которые принадлежат во внешнем расположении, а не внутри..msix

После упаковки запустите winapp embed-identity <exe> и зарегистрируйте пакет в установщике Add-AppxPackage -Path <msix> -ExternalLocation <install-dir>. См. руководство по разреженной упаковке.

Обнаружение компонентов 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

внедрение удостоверения

Подключите классическое приложение к его разреженный пакет удостоверений , встраивая <msix> элемент в параллельный манифест приложения (fusion). Это шаг 3 рабочего процесса упаковки разреженной упаковки. Он сообщает Windows, к какой пакет удостоверений принадлежит запущенный exe.

winapp embed-identity <target> [options]

Аргументы:

  • target — файл для обновления. Автоматическое обнаружение по расширению:
    • .exe (режим EXE) — внедряет <msix> элемент непосредственно в параллельный манифест exe с помощью mt.exe.
    • .xml / .manifest (РЕЖИМ XML) — вставляет или заменяет <msix> элемент во внешнем файле манифеста SxS (создается, если он не существует). Перестройте приложение после этого, чтобы обновленный манифест внедрен в двоичный файл.

Варианты.

  • --manifest <path> — Путь к разрежению appxmanifest.xml для чтения удостоверения (packageName, издателя, applicationId) из. При опущении команда выполняет поиск 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

Эта команда является идемпотентной: повторное выполнение заменяет любой существующий <msix> элемент, а не дедупликацию.

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 для отладки. Возвращает идентификатор процесса для вложения отладчика.

winapp run работает в одном из двух режимов, выбранных автоматически из входных данных:

  • Режим папки — входные данные — это папка выходных данных сборки (содержит a Package.appxmanifest/AppxManifest.xml).
  • Project режиме — входные данные — это .csproj.sln/.slnx решение или каталог, содержащий один. winapp run создает проект и запускает его, поддерживая как упакованные , так и распакованные приложения WinUI. См. Project режим ниже.

Tip

Выбор режима по умолчанию безмолвный. Если каталог рассматривается как папка выходных данных сборки, когда ожидается, что она будет создана как проект, повторно запустите его с --verbose помощью — режим папки сообщает, почему он был выбран (No .csproj/.sln/.slnx with a runnable app found in '<path>' — running it as a build-output folder.). Каталог создается только в качестве проекта, если .csproj/.slnx/.slnприложение с запущенным приложением находится на верхнем уровне; он не выполняется рекурсивно.

This — предпочтительная команда для отладки с удостоверением пакета для большинства платформ (.NET, C++, Rust, Flutter, Tauri). В отличие от create-debug-identity того, что регистрирует разреженный пакет для одного exe-файла, winapp run регистрирует всю папку как свободный пакет макета, как и реальную установку MSIX. См. руководство по отладке распространенных рабочих процессов отладки.

winapp run [<input>] [options]

Аргументы:

  • input — Приложение для запуска: папка вывода сборки (режим папки), .csproj проект, .sln/.slnx решение или каталог, содержащий один из них на верхнем уровне (режим проекта; каталог не выполняется рекурсивно). Используется . для сборки и запуска проекта в текущем каталоге. Необязательный — по умолчанию используется текущий каталог при опущении (совпадения dotnet run).

Варианты.

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

режим Project (проекты пакета SDK .NET)

Если входные данные являются решением или каталогом.csproj.slnx/.sln, содержащим один (включая.),winapp run создает проект и dotnet build запускает его. Он поддерживает как упакованные, так и распакованные приложения WinUI, а также устанавливает соответствующую архитектуру приложение для Windows среды выполнения, необходимые приложению перед запуском.

Входные данные решения: точка winapp run на/.slnx.sln(или каталог, содержащий один — решение предпочтительнее по сравнению с свободными .csproj файлами) и разрешает проект запускаемого приложения, а затем создает его с определенными $(SolutionDir) свойствами, Solution* чтобы проекты, которые зависят от них, как и в Visual Studio. Правила разрешения:

  • Тестовые проекты пропускаются при автоматическом выборе, поэтому решение, содержащее приложение, а также тесты разрешаются приложению без --project необходимости. (Тестовый проект WinUI — это упакованое приложение, поэтому один тип вывода не может его различать.)
  • Если единственным запускаемым проектом является тестовый проект, он запускается.
  • Если существует несколько проектов запускаемых приложений, winapp run не угадывает проект запуска — это ошибки, которые перечисляют кандидатов. Используется --project <name> для выбора, который всегда учитывается, включая выбор тестового проекта.

Упакованный и распакованный объект обнаруживается автоматически из эффективного WindowsPackageType свойства MSBuild проекта (никогда не из присутствия манифеста):

  • Упаковано (WindowsPackageType=MSIXпакет WinUI по умолчанию) — сборки, а затем регистрирует выходные данные сборки в виде пакета свободного макета и запускается через AUMID (тот же конвейер, что и режим папки).
  • Распаковка (WindowsPackageType=None) — сборки, гарантирует установку приложение для Windows среды выполнения, зависящей от платформы, а затем запускает встроенную .exe напрямую. Принудительное применение для упаковаемого проекта с -p WindowsPackageType=Noneпомощью .

для режима Project требуется пакет SDK .NET версии 8.0.100 или более поздней версии (для MSBuild--getProperty).

параметры Project режима (игнорируются в режиме папки):

  • -c, --configuration <name> — конфигурация сборки. По умолчанию: Debug.
  • --arch <x64|arm64|x86> — целевая архитектура. По умолчанию: текущая архитектура процесса. Определяет как сборку RID, так и архитектуру установленной среды выполнения приложение для Windows.
  • -r, --runtime <rid>— целевой идентификатор среды выполнения .NET (например, win-x64). Project режим использует только архитектуру RID, всегда создает каноническую win-<arch>сборку и отклоняет не Windows идентификаторы (например, linux-x64). Его архитектура переопределяет --arch.
  • -f, --framework <tfm> — Моникер целевой платформы для многоцеловых проектов (например, net10.0-windows10.0.26100.0).
  • --project <name-or-path> — Если входные данные являются решением (.sln/.slnx) или каталогом с несколькими запускаемыми проектами приложений, выбирает проект для запуска (по имени проекта или пути).
  • --no-build — Пропустить сборку и запустить существующие выходные данные сборки (по-прежнему вычисляет выходные свойства).
  • --no-restore — Пропустить восстановление проекта перед сборкой.
  • -p, --property <Name=Value> — свойство MSBuild, переадресованное как в сборку, так и в оценку свойств. Повторяемый (например, -p WindowsPackageType=None).

Выходные данные сборки и детализация: проект построен на двух шагах — dotnet build выходные потоки, входящие в консоль, за которым следует быстрый проход оценки свойств. Winapp печатает точный dotnet build … вызов перед выходными данными и передает предупреждения даже в успешной сборке. Детализация:

Flag детализация dotnet Добавляет
(Значение по умолчанию.) minimal —
--verbose minimal Трассировки решений сборки winapp
--quiet quiet —

В --json разделе или --quiet вызове и выходные данные сборки переходят к stderr, чтобы stdout оставался чистым JSON/clean.

Применимость параметров: параметры удостоверений и свободного макета (--manifest, --output-appx-directory, --no-launch--with-alias, --unregister-on-exit, --clean--executable) применяются только к упакованным приложениям. Они отклоняются с явной ошибкой для распакованных приложений (у которых нет пакета MSIX). Параметры запуска и отладки (--args/--, --detach, --debug-output, --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

# 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

Свойства 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 для подключения другого отладчика.
WinAppRunDetach false Вернитесь сразу после запуска вместо ожидания завершения работы приложения. Выводит идентификатор идентификатора.
WinAppRunUnregisterOnExit false Отмена регистрации пакета разработки после завершения работы приложения
WinAppRunClean false Удалите данные приложения существующего пакета (LocalState, параметры) перед повторной развертыванием
WinAppRunSymbols false Скачайте символы из сервера символов Microsoft для более полного анализа аварийного сбоя. Действует только с WinAppRunDebugOutput.
WinAppRunExecutable (пусто) Путь к исполняемому файлу относительно папки выходных данных сборки. Используется, если манифест содержит $targetnametoken$ и выходную папку имеет несколько .exe.
WinAppRunArgs (пусто) Необработанные аргументы, добавленные в командную winapp run строку, для параметров без выделенного свойства (например --verbose). Добавлено после каждого приведенного выше свойства.

Взаимоисключающие параметры. WinAppRunNoLaunch и WinAppRunDetach каждый из них описывает другое поведение запуска, поэтому они конфликтуют с другими свойствами запуска и друг с другом. Установка конфликтующей пары завершается сбоем выполнения с помощью --X and --Y cannot be used together:

Недвижимость Не удается объединить с
WinAppRunNoLaunch WinAppRunDetach, , WinAppRunUseExecutionAliasWinAppRunDebugOutputWinAppRunUnregisterOnExit
WinAppRunDetach WinAppRunNoLaunch, , WinAppRunUseExecutionAliasWinAppRunDebugOutputWinAppRunUnregisterOnExit

WinAppRunUseExecutionAlias, WinAppRunDebugOutputи WinAppRunUnregisterOnExit может сочетаться друг с другом. WinAppRunClean, , WinAppRunSymbolsWinAppRunExecutableи WinAppLaunchArgs не имеют ограничений. WinAppRunArgs добавляет никаких ограничений, но переключение, переданное через него, проверяется как любой другой, так что WinAppRunArgs="--detach" по-прежнему конфликтует с 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

az-sign

Подписывание файла (exe, MSIX или пакета MSIX) с помощью Azure Trusted Signing — управляемого облаком удостоверения подписи, поэтому закрытый ключ (PFX) никогда не находится на локальном компьютере.

winapp az-sign <file-path> [options]

Аргументы:

  • file-path — Путь к файлу для подписания (exe, msix или msixbundle)

Варианты.

  • --subscription— -s Azure идентификатор подписки для использования. Если не указано и существует несколько подписок, вам будет предложено
  • --resource-group— -r группа ресурсов для сузки учетных записей подписывания
  • --account — имя учетной записи подписывания. Необходимо использовать с --resource-group
  • --profile— -p имя профиля сертификата. Необходимо использовать с --account
  • --metadata-file, -m — путь к существующему metadata.json. Пропускает обнаружение ресурсов и запросы на выбор учетной записи или профиля и подписывается напрямую. Учетные данные, не являющиеся интерактивными Azure, уже должны быть доступны; интерфейс командной строки может в противном случае вернуться к интерактивному запросу клиента илиaz login, но программный API npm всегда неактивен и завершается ошибкой, а не запрашивать запрос.

Проверка подлинности:

az-signиспользует стандартную цепочку учетных данных Azure (DefaultAzureCredential). Для CI/CD, задайте AZURE_TENANT_IDAZURE_CLIENT_IDи (или AZURE_CLIENT_SECRET используйте GitHub Actions OIDC / управляемое удостоверение). Существующий сеанс Azure CLI (az loginвключая azure/login действие GitHub) также учитывается в любой среде. Только если учетные данные не найдены, и сеанс будет запущен az login для вас интерактивнымaz-sign.

Prerequisites:

  • Учетная запись подписывания кода Azure и профиль сертификата (созданный на портале Azure после проверки удостоверения), а также роль подписывания сертификата для подписывания кода, назначенная вашему удостоверению. Дополнительные сведения см. в документации по Azure кратком руководстве по подписи артефактов.
  • Установленная среда выполнения x64 на уровне компьютера .NET 8 (или более поздней версии). Клиентская библиотека подписывания Azure — это управляемая сборка, signtool.exe которая загружается в отдельном процессе. Собственная локальная среда выполнения winapp не удовлетворяет ей. Установите его из-за https://dotnet.microsoft.com/download сбоя подписи с ошибкой загрузки среды выполнения.
  • Распространяемый Microsoft Visual C++ (x64). Клиентская библиотека подписывания Azure зависит от среды выполнения VC++ и поскольку winapp загружает необработанный пакет NuGet, а не официальный установщик клиентских средств, эта зависимость не устанавливается автоматически. Чистая машина может загрузить сбой даже с .NET и SignTool. Установите последнюю распространяемую версию x64, https://aka.ms/vs/17/release/vc_redist.x64.exe если сбой подписи с 0xc000007bсообщением "Приложение не удалось запустить правильно" или отсутствует ошибка DLL из dlib.

Ci с наименьшими привилегиями: Автоматическое обнаружение (перечисление подписок, групп ресурсов, учетных записей и профилей) требует доступа на чтение в родительской области. Чтобы избежать каждого вызова перечисления коллекции, передайте все четыре --subscriptionиз , --resource-group--accountа az-sign--profileзатем проверяет учетную запись и профиль с помощью прямых операций чтения ресурсов (GET на каждом именованном ресурсе), а не перечисляет родительскую коллекцию, поэтому субъект, ограниченный только этой учетной записью и профилем, достаточно. Опущение любого из них повторно вводит вызов перечисления , например, выход --subscriptionaz-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 Создайте файл каталога, содержащий хэши исполняемых файлов из указанных каталогов. Этот каталог используется с флагом 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 рабочей области
  • Каталоги установки пакетов
  • Созданные расположения заголовков

Find-ui

Поиск элементов управления WinUI и примеров для примера рабочего кода. Только WinUI: корпус является коллекцией WinUI 3 и набором средств сообщества Windows (плюс несколько курированных основных шаблонов) — он не охватывает WPF, WinForms или другие платформы пользовательского интерфейса. Третий источник, microsoft-ui-reactor ReactorGallery, является согласием: он исключается из обычного поиска и выполняется только при прохождении --source reactor (его декларативные образцы только C#не вставляются в стандартное приложение XAML, поэтому достигается только при создании проекта Reactor/MVU).

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

Корпус извлекается из GitHub при первом использовании и кэшируется для каждого пользователя<global .winapp>/cache/find-ui, поэтому для первого запуска требуется доступ к сети. Последующие запуски выполняются из локального кэша (обновляются не более 7 дней или по запросу).--refresh

Варианты.

  • --id <id> — получение кода (коллекция/набор средств возвращает XAML и/или C#; Реактор является C#-only) плюс заметки о предварительных требованиях для одного или нескольких идентификаторов сценария из предыдущего поиска (например, gallery-tabview-1). Повторяемые. Идентификаторы являются нечувствительными к регистру — GALLERY-TABVIEW-1 разрешает то же самое, что gallery-tabview-1и .
  • --list — Вывод списка всех обнаруженных элементов управления или образца идентификатора вместо поиска (коллекция + набор средств + ядро; источник opt-in Reactor исключен).
  • --source <gallery|toolkit|reactor|core> — ограничить результаты поиска одним источником. (Только поиск — недопустимый с --list/--id.) Реактор включен — он исключен из нормального поиска, поэтому --source reactor единственный способ поиска.
  • --max <N> — максимальное количество возвращаемых элементов управления (по умолчанию: 3). Применяется только к поиску; игнорируется с --list/--id.
  • --refresh— обходить локальный кэш и повторно получить корпус WinUI из GitHub.
  • --json — выдающий структурированный JSON (с поддержкой агента). Для поиска каждое совпадение содержит source, controlscoredescriptionи scenarios массив, записи которого хранятся в каждом сценарии id и header; для --idполного кода. При --jsonкаждом сбое , включая ошибки аргумента или синтаксического анализа, такие как не целочисленное число --max , создается как неструктурированный {"error": "..."} объект на stdout с кодом выхода без нуля, поэтому выходные данные остаются доступны для чтения компьютером.

Рабочий процесс: выполните компактный поиск, чтобы найти правильный элемент управления и его идентификаторы сценария, а затем получить полный код для оптимального соответствия --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

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

(Доступно только в пакете 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.

# 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 demo.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путь (по умолчанию — ).
  • --frames — запись меток времени JPEG, frames.ndjsonа также manifest.json в <output-name>.frames. Поддерживает 1-30 fps и --max-edge 64-4096 (по умолчанию 1280) с ограничением кадров 1 ГиБ.

Окончательный --jsonрезультат включает выходной путь, измерения, кодек, режим записи, периодичность, причину остановки, необязательные frameArtifactsи предупреждения.

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

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

  • Last updated on