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

Version

Печать установленной версии winapp с --version помощью или ее короткой формы -V:

winapp -V

Нижний регистр -v — это короткая форма --verbose команд (например, winapp restore -v).

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

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

# 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
  • Использует новейший выпуск Windows App SDK в выбранном --setup-sdks канале. Если этот выпуск по-прежнему публикуется, а некоторые из его пакетов пока недоступны, init использует предыдущий выпуск и выводит заметку, которая говорит так. Чтобы перейти к новому выпуску позже, запустите winapp updateили для проекта .NET. dotnet add package Microsoft.WindowsAppSDK --version <new version>
  • Создает заголовки и двоичные файлы 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-libwinui-mvvm, winui-unittestили экспериментальный шаблон реактора, например reactor или reactor-mvu). Проверено на установленный пакет во время выполнения; Выполните команду winapp new --list , чтобы просмотреть все. Значение по умолчанию: winui (пустое приложение XAML).
  • -n, --name <name> — Имя нового приложения или проекта (по умолчанию: производное от --output, иначе WinUIApp)
  • -o, --output <path> — Каталог для создания приложения в (по умолчанию: ./<name>)
  • --use-defaults, --no-prompt — не запрашивайте; используйте значения по умолчанию (пустой шаблон, имя из --output/--nameи не обновляйте его)
  • --force — шаблон, даже если выходной каталог уже содержит файлы
  • --template-version <latest|installed|version> — Версия пакета шаблонов WinUI: latest обновления до нового опубликованного пакета без запроса (установленный пакет, который уже более новый, например локальная предварительная сборка, хранится; завершается ошибкой, если веб-канал не может быть проверен), installed хранит все, что уже загружено (нет сети) или закрепляет явную версию, например 1.2.3. По умолчанию: установите последнюю версию, если пакет отсутствует, в противном случае запрос на обновление устаревшего пакета (хранится as-is в разделе --use-defaults).
  • --list — вывод списка доступных шаблонов WinUI и выхода (сначала устанавливается последний пакет, если он не установлен)
  • --json — формат выходных данных в формате JSON

Шаблоны:

Пакет поставляет два стиля приложения WinUI. Шаблоны XAML определяют пользовательский интерфейс в разметке с помощью кода C#. Шаблоны реакторов являются чистыми C# без XAML, используя шаблон MVU (модель-View-Update) . Список шаблонов считывается в режиме реального времени из установленного пакета, поэтому он всегда отражает версию, которую у вас есть , чтобы winapp new --list просмотреть текущий набор. Интерактивный средство выбора и --list отображение шаблонов WinUI сначала, а затем все остальные— каждая группа в алфавитном порядке. Общие шаблоны:

Короткое имя Описание
winui Минимальное пустое приложение XAML (упаковка MSIX)
winui-navview Начальная версия приложения XAML NavigationView
winui-tabview Начальная версия ПРИЛОЖЕНИЯ XAML TabView
winui-mvvm Приложение XAML MVVM (CommunityToolkit.Mvvm)
winui-lib Библиотека классов WinUI 3
winui-unittest Упакованое приложение MSTest; тесты выполняются при запуске
reactor Экспериментальный. Пустое приложение Reactor — чистое C#, нет XAML
reactor-mvu Экспериментальный. Приложение Реактора, демонстрирующее шаблон MVU
reactor-navview Экспериментальный. Начальная версия Приложения Reactor NavigationView
reactor-tabview Экспериментальный. Начальная версия приложения Reactor TabView

Шаблоны реакторов являются экспериментальными. Они ссылаются на пакеты предварительной версии Microsoft.UI.Reactor , API-интерфейсы которых могут изменяться или удаляться в будущем выпуске. winapp new помечает их (экспериментальный) в --list интерактивном элементе выбора, задает "Experimental": true и --jsonвыводит предупреждение после формирования шаблонов. Они никогда не выбираются в качестве шаблона по умолчанию. Для реактора также требуется пакет SDK для .NET 10 или более поздних версий. В более старой версии пакет SDK winapp new не требуется, а не шаблон проекта, который невозможно построить.

Каноническое короткое имя каждого шаблона — это первые списки псевдонимовdotnet new. Также принимается любой указанный псевдоним (напримерwinui3, wasdk-single, ). winui-reactor Если другой установленный пакет шаблонов регистрирует то же короткое имя (например, reactor из Microsoft.UI.Reactor.Templates), winapp new по-прежнему создает шаблон пакета WinUI с помощью одного из других псевдонимов. Если другой пакет регистрирует каждый псевдоним шаблона, winapp new останавливается и имена этого пакета. Удалите его с dotnet new uninstall <package> помощью и повторно запустите его. При запуске внутри существующего проекта WinUI также отображает шаблоны элементов (например, dotnet new пустую страницу), которая winapp new добавляется в текущий проект, а не создает новый.

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

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

Первое выполнение может занять больше времени: Установка или обновление пакета шаблона или восстановление отсутствующих Windows App SDK пакетов NuGet, используемых выбранным шаблоном, может потребовать дополнительных скачивание. Это также может произойти после публикации новой версии Windows App SDK. Если формирование шаблонов по-прежнему выполняется через 10 секунд, обновляет его сообщение о состоянии, winapp new чтобы указать, что пакеты могут загружать или восстанавливаться.

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

  • Проверяет установку пакета 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

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

# Always use the newest template pack, no prompts
winapp new --name MyApp --template-version latest --use-defaults

# Show the underlying dotnet commands and their output
winapp new --name MyApp --verbose

# Non-interactive (agent) with machine-readable output
winapp new --use-defaults --name MyApp --json

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

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

winapp restore [base-directory] [options]

Аргументы:

  • base-directory — каталог для восстановления (по умолчанию: текущий каталог). Кроме того, выбирает место winapp.yaml и nuget.config считывается, если --config-dir он не переопределяется.

Варианты.

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

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

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

Замечание

Для .NET проектов нет winapp.yaml — версии ПАКЕТА SDK живут в качестве PackageReference записей в приложении .csproj , поэтому winapp restore выполняется dotnet restore для вас.

Примеры:

# Restore from winapp.yaml in current directory
winapp restore

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

Пользовательские и частные веб-каналы NuGet:

winapp init, restoreи update скачайте пакет SDK Windows и Windows App SDK через NuGet, учитывая стандартную nuget.config иерархию. Частные веб-каналы и зеркальные отображения, учетные данные веб-канала (включая поставщики учетных данных) и настраиваемые globalPackagesFolder все работают так, как они выполняются dotnet restore. Чтобы восстановить только из собственного зеркала, <clear /> унаследованные источники и добавить только ваши:

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

Замечание

Для собственных проектов winapp разрешается nuget.config из каталога, на который он работает: init/restore аргумент каталога, --config-dir если он указан, в противном случае — текущий каталог. Для .NET проектов источники исходят из собственной nuget.config иерархии проекта, так как это то, что dotnet add package и dotnet restore используется, поэтому поместите конфигурацию частного веб-канала в каталог проекта или предку. Вне --config-dir этой иерархии сообщается и игнорируется, а не автоматически выбирает версии проекта. Выполните эти команды только для каталогов, которым вы доверяете, то же внимание, к которому относится dotnet restore. При настройке нескольких источников используйте сопоставление источников пакетов для привязки каждого пакета к веб-каналу.

update

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

winapp update [options]

Варианты.

  • --setup-sdks <stable|preview|experimental|none>— режим установки пакета SDK: stable (по умолчанию), previewexperimentalили none (пропустить установку пакета SDK)

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

  • Считывает существующую winapp.yaml конфигурацию в текущем каталоге
  • Обновляет все пакеты до последних доступных версий. Выпуск Windows App SDK, который по-прежнему публикуется, пропускается до тех пор, пока не будут доступны все его пакеты, и update выводит заметку, именующую его выпуск, который он использовал вместо этого. Запустите winapp update еще раз позже, чтобы перейти к новому выпуску.
  • winapp.yaml Обновляет файл с новыми номерами версий
  • Повторно создает заголовки и двоичные файлы C++/WinRT

Примеры:

# Update packages to latest versions
winapp update

# Update including experimental packages
winapp update --setup-sdks experimental

pack

Создайте пакеты MSIX из проекта или подготовленных каталогов приложений. Требуется, чтобы файл манифеста (Package.appxmanifest предпочтительный, appxmanifest.xml также поддерживаемый) присутствовал в целевом каталоге, в текущем каталоге или передан с параметром --manifest . (запуск init или manifest generate создание манифеста)

Передайте один объект .csproj для сборки проекта и упаковайте его выходные данные на одном шаге (режим проекта см. в разделе "Упаковка проекта" непосредственно ниже). Передайте несколько входных папок, чтобы создать .msixbundle распределение с несколькими архитектурами (см. следующие пакеты с несколькими архитектурами ).

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

Аргументы:

  • input-folder — один для .csproj сборки и пакета (режим проекта) или одного или нескольких каталогов, содержащих файлы приложения для пакета. Передайте несколько папок (например, ./publish/x64 ./publish/arm64для создания пакета MSIX). Для разреженных пакетов удостоверений передайте разреженный 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 — создание нового сертификата разработки
  • --no-sign — Доставляете пакет без знака, переопределяя любую конфигурацию подписи проекта (например, для отправки Магазина или внешнего конвейера подписывания). Нельзя объединить с --cert или --generate-cert.
  • --install-cert — установка сертификата на компьютер
  • --publisher <name>— Publisher для создания сертификатов. Принимает полное различающееся имя X.500 или голое имя (автоматически упаковано как CN=<name>)
  • --self-contained — среда выполнения пакета Windows App SDK
  • --skip-pri — пропустить создание файла PRI
  • --executable <path> — Путь к исполняемому файлу относительно входной папки (также --exe). Используется для разрешения $targetnametoken$ плейсхолдеров в манифесте.

параметры Project режима (требуют .csproj ввода; отклонены для входных данных папки или пакета или манифеста):

  • --configuration <name> (-c) — конфигурация сборки (по умолчанию: Release)
  • --arch <arch> — целевая архитектура: x64, arm64или x86 (по умолчанию: текущая архитектура процесса)
  • --framework <tfm> (-f) — моникер целевой платформы для многоцеловых проектов
  • --no-build — Упаковать существующие выходные данные сборки без перестроения
  • --no-restore — пропуск восстановления проекта перед сборкой
  • --property <name=value> (-p) — свойство MSBuild, переадресованное в сборку и оценку (повторяемое)

Примечание. Для winUI / EnableMsixTooling.csproj (режим проекта MSIX-tooling) Windows App SDK владеет манифестом, точкой входа и поколением PRI, поэтому --executable--manifest, и --skip-pri отклоняются — настраиваются<AppxManifest>, точка входа проекта и ее сборка ресурсов в самом проекте. Эти три варианта по-прежнему применяются к входным данным папок и к универсальному (не MSIX-tooling) .csproj режиму проекта.

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

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

Упаковка проекта напрямую

Если входные данные являются одним .csproj, winapp pack создает проект (используя приведенные выше параметры) и упаковает полученные выходные данные— не нужно создавать отдельно или сначала находить выходную папку. Этот режим проекта зеркального winapp runотображения.

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

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

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

Целевая архитектура исходит от или от --archодинокого -p RuntimeIdentifier=<rid> , если вы не проходите --arch (точный RID сохраняется и управляет сборкой). Передача обоих --arch и -p RuntimeIdentifier является конфликтом и отклоняется.

Проект должен создаваться как упаковаемое приложение (EnableMsixTooling=true с Package.appxmanifest); проект, который строится как распаковываемое приложение (WindowsPackageType=None) не имеет манифеста MSIX для упаковки и winapp pack сообщает об ошибке с действиями. Входные данные папки, пакета и разреженного манифеста не изменяются.

Project режим создает один .msix или только .msixbundle архитектуру (см. пакеты с несколькими архитектурами). Он не создает архивы для отправки в Магазин или пакеты с разделением ресурсов (язык или масштабирование): явным -p UapAppxPackageBuildMode=StoreUpload или -p AppxBundleAutoResourcePackageQualifiers=... отклонен с заметкой для запуска команды упаковки собственного пакета SDK непосредственно для этих потоков.

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

Если входные данные — это разреженный 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 с одним значением, разделенными запятыми компонентами (многозначные + RDN и обратные косые строки не поддерживаются). Имена без запятой автоматически упаковываются как 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 полностью поддерживаются в качестве исходных образов. Они отрисовываются как векторы непосредственно на каждом целевом размере, создавая идеальные результаты пикселей во всех разрешениях. Файл должен объявлять собственный размер с помощью либо абсолютной viewBox или абсолютной и height атрибутовwidth; процентная ширина без viewBox описания определенного размера. Источник, объявляющий ни о чем не отклонен SVG image has no usable dimensions , вместо создания пустых активов.

Команда масштабирует изображения пропорционально при сохранении пропорций, центрируя их с прозрачными фонами при необходимости. Ресурсы сохраняются в Assets каталоге относительно расположения манифеста.

Примеры:

# Generate assets with auto-detected manifest
winapp manifest update-assets mylogo.png

# Use an SVG source for best quality at all sizes
winapp manifest update-assets mylogo.svg

# Specify manifest location explicitly
winapp manifest update-assets mylogo.png --manifest ./dist/Package.appxmanifest

# Generate light theme variants from a separate image
winapp manifest update-assets mylogo.png --light-image mylogo-light.png

# Use the same image for both (generates all MRT light theme qualifiers)
winapp manifest update-assets mylogo.png --light-image mylogo.png

# With verbose output
winapp manifest update-assets mylogo.png --verbose

run

Создайте свободный пакет макета из выходной папки сборки, зарегистрируйте его в Windows с помощью API Windows.Management.Deployment.PackageManager и запустите приложение— имитацию полной установки MSIX для отладки. Возвращает идентификатор процесса для вложения отладчика.

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

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

Tip

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

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

winapp run [<input>] [options]

Аргументы:

  • input— Приложение для запуска: папка вывода сборки (режим папки), .cs .NET файловое приложение (однофайловой режим), .csproj проект или проект C++.vcxproj, .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. Редко требуется: приложение с OutputType=Exe уже запущенным способом по умолчанию. Winapp добавляет необходимый uap5:ExecutionAlias для манифеста этапы в макет AppX, поэтому никаких изменений в манифесте проверки не требуется; псевдоним приложения объявляет себя as-is. Не удается объединить с --no-launch, --detachили --without-alias--json.
  • --without-alias — принудительное активацию AUMID для приложения, которое в противном случае запускается с помощью псевдонима выполнения. Затем консольное приложение запускается без консоли и не выводит ничего в этот терминал. Не удается объединить с --with-alias.
  • --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. Если вы работаете без него, а приложение выходит из ненулевого кода, winapp выводит подсказку для повторного запуска с --debug-outputпомощью.
  • --symbols — скачивание символов PDB из сервера символов Microsoft для более полного анализа аварийного сбоя с именами разрешенных функций. Используется только с --debug-output. Если опущено и происходит сбой в собственном коде, выходные данные предполагают добавление этого флага. Этот флаг также улучшает стек трех исключений WinUI для приложений WinUI 3. Сначала запускается скачивание символов и кэширует их локально; последующие запуски используют кэш.
  • --unregister-on-exit — Отмена регистрации пакета разработки после завершения работы приложения. Удаляет только пакеты, зарегистрированные в режиме разработки. Не удается объединить с --no-launch.
  • --detach — Запустите приложение и вернитесь немедленно, не ожидая выхода. Полезно для ci/automation, где необходимо взаимодействовать с приложением после запуска. Локальные запуски печатают идентификатор пин-код; Целевой объект запускает печать целевого объекта пользовательского интерфейса с областью действия. JSON включает piD и целевую область. Не удается объединить с --no-launch, --debug-outputили --with-alias--unregister-on-exit.
  • --clean — Удалите данные приложения существующего пакета (LocalState, параметры и т. д.) перед повторной развертыванием. По умолчанию данные приложения сохраняются во время повторного развертывания.
  • --json — форматируйте выходные данные в формате JSON для программного использования (например, CI/automation). Полезно для --detach записи ИДЕНТИФИКАТОРА. Нельзя объединить с --with-alias или --debug-output.
  • --on <target> — Создание узла, регистрация и запуск в целевом объекте. В настоящее время поддерживается sandboxбез резервного выполнения локального выполнения. Используйте --detach перед выполнением команд пользовательского интерфейса. Для песочницы --debug-output требуется упакованое приложение. См. Windows выполнение песочницы для установки, поддержки среды выполнения и времени существования отсоединяемого приложения.

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

По умолчанию 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).

Native AOT: добавьте эту группу свойств внутри элемента project файла<Project>, а затем добавьте--aot:

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

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

--aotподдерживает проекты x64 и ARM64 и требуется пакет SDK для .NET версии 8.0.300 или более поздней версии. Он выполняется dotnet publish с конфигурацией AOT проекта, а затем запускает выходные данные; используется -p PublishAot=true для однократного переопределения. Он не выполняет отдельную сертификацию среды выполнения и не может сочетаться с --no-build ней или --manifest.

Для приложений, использующих удостоверение пакета без созданного макета MSIX, включите Package.appxmanifest или appxmanifest.xml в выходные данные публикации проекта. Winapp этапов опубликованных файлов с этим манифестом. Если оба имени присутствуют, winapp останавливается вместо выбора одного; Удалите устаревший манифест и настройте проект для публикации только предполагаемого манифеста.

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

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

Выходные данные сборки и детализация: обычное выполнение проекта используется dotnet build, а затем вычисляет встроенные выходные данные. Восстановление и сборка потока выходных данных в реальном времени с учетными данными из URL-адресов веб-канала, прошедших проверку подлинности. С --aotпомощью winapp используется dotnet publish; --verbose отображает команду публикации и разрешенные пути. Используйте приведенные ниже параметры детализации, чтобы управлять отображаемыми сведениями:

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

Собственные потоки AOT публикуют выходные потоки по мере поступления. В разделе --json" Восстановление и сборка вызовов и дочерних выходных данных перейдите в stderr, чтобы stdout оставался чистым JSON. В разделе --quietвызовы подавляются, а выходные данные восстановления и сборки dotnet направляются в stderr, чтобы stdout оставался чистым. Выходные данные публикации в собственном коде AOT также переходили к stderr в любом из вариантов.

Применимость параметров: параметры удостоверений и свободного макета (--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

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

# Force an unpackaged run of a packaged project
winapp run . -p WindowsPackageType=None

# Run the existing build output without rebuilding, and capture crash diagnostics
winapp run . --no-build --debug-output

# Show winapp's build decision traces (dotnet build stays at minimal verbosity)
winapp run . --verbose

# Launch and detach (prints PID), forwarding args to the app
winapp run . --detach -- --my-flag value

Проекты C++ (.vcxproj)

Наведите указатель winapp run на .vcxproj папку или решение, единственное запускаемое приложение которого является одним из них, и он создает проект с помощью MSBuild Visual Studio, а затем запускает его так же, как и проект .NET:

winapp run .\MyApp.vcxproj
winapp run . -c Release --arch arm64
winapp run . --no-build --detach --json
  • Приложение WinUI 3 C++/WinRT из шаблона Visual Studio запускается пустое приложение WinUI (упаковано). Другие проекты приложений, такие как консольное приложение или приложение WinUI, созданное с -p WindowsPackageType=Noneпомощью , запускайте распаковку из их сборки .exe.
  • Сборки для текущей архитектуры Debug по умолчанию. --arch x64|arm64|x86 или -p Platform=x64|ARM64|Win32 выбирает архитектуру (передача обоих с разными архитектурами является ошибкой); пользовательское -p Platform имя передается.
  • packages.config Восстанавливает пакеты NuGet сначала (пропустить с--no-restore) и устанавливает версию среды выполнения приложение для Windows, закрепленную. Упакованные приложения также получают пакеты платформы, ссылки на сборку, такие как среда выполнения Отладки VC++, установленная при отсутствии.
  • --frameworkи --aot применяется только к проектам .NET.
  • Выходные данные сборки показывают только предупреждения и ошибки MSBuild с спиннером во время сборки; --verbose отображает полные выходные данные MSBuild и точную команду.
  • В папке или решении с запущенным приложением C# выбрано приложение C#; используется --project <name> для запуска приложения C++ . Библиотеки C# и тестовые проекты рядом с приложением C++ не получаются.
  • Приложение C#, ссылающееся на проект C++ (например, собственный DLL), невозможно создать с dotnetпомощью . Создайте его с помощью Visual Studio илиMSBuild.exe, затем запустите winapp run <app>.csproj --no-buildили упаковите ее выходную папку с winapp package <folder>помощью.

Необходимые условия: Visual Studio или средства сборки для Visual Studio 2022 версии 17.8 или более поздней версии с инструментами сборки MSVC C++ для целевой архитектуры (разработка настольных компьютеров с рабочей нагрузкой C++) и пакетом SDK Windows для целевых объектов проекта. Приложения WinUI 3 также требуют средств разработки приложений WinUI на языке C++; с несколькими установками winapp использует новейший, который может создать проект. Пакет SDK для .NET не требуется. Когда средства сборки, набор инструментов платформы (MSB8020) или пакет SDK Windows (MSB8036) отсутствуют, говорит, что необходимо установить, winapp run включая winget команду.

См. пример приложения cpp-winui-app.

Однофайловый режим (.NET файловых приложений)

.NET 10 позволяет запускать один .cs файл без файла проекта, настраивая его с #: директивами вверху. Наведите указатель winapp run на этот файл и создает приложение, создает для него appxmanifest и запускает его с удостоверением пакета — поэтому Windows.ApplicationModel.Package.Current приложение получает реальный AUMID и запись меню "Пуск", а API- интерфейсы, которые просто требуют удостоверения (уведомления приложений, ApplicationDataАИ на устройстве).

Интеграции оболочки, такие как обработчики протоколов, сопоставления файлов, целевые объекты общего доступа и задачи запуска, требуют объявленной <Extensions> записи, которая не содержит созданного манифеста. Чтобы добавить его, создайте собственный манифест. См. раздел "Добавить собственный манифест " ниже.

winapp run counter.cs

Или запустите его с помощью обычного dotnet run кода— см. раздел "Выполнение с dotnet run помощью ниже".

Вы не создаете манифест. Опишите пакет с #:property директивами.

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

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

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

Свойства манифеста. Все являются необязательными; каждый возвращается к разумному умолчанию:

Недвижимость Наборы По умолчанию
WinAppPackageName Identity/@Name (удостоверение пакета) имя файла, дезинфицируемое [-.A-Za-z0-9]в , а также короткий хэш пути файла (counter.cs → counter-a1b2c3d4)
WinAppDisplayName Имя, отображаемое в меню "Пуск" и "Параметры" Имя файла без расширения
WinAppPublisher Identity/@Publisher CN=<your Windows user name>. Голое имя упаковывается как CN=<name>.
WinAppVersion Identity/@Version $(Version), нормализовано (см. ниже)
WinAppDescription Описание, показанное во время установки и в параметрах отображаемое имя
WinAppCapabilities Возможности объявления, разделенные или разделенные ;, нет

Version. Версия пакета должна иметь ровно четыре числа, каждая из которых — 0–65535. WinAppVersion (или, если он не задан, стандартное Version свойство) нормализуется для соответствия: -preview/-rc суффикс удаляется и отсутствующие компоненты заполняются нулями, поэтому #:property Version=1.2.3-preview.4 становится 1.2.3.0 и задает версию сборки и версию пакета вместе. Значение, которое не может быть задано , — компонент выше 65535 или более четырех компонентов — отклоняется с ошибкой , а не автоматически изменено.

Capabilities

Приложение запускает полное доверие с удостоверением, которое удовлетворяет API, для которых требуется только упаковаемое приложение. Но некоторые API включены в объявленную возможность независимо от того, Windows API ИИ являются общим случаем. (Интеграции оболочки, такие как обработчики протоколов и сопоставления файлов, являются третьим случаем: им нужны созданные <Extensions> записи, а не возможности, поэтому используйте собственный манифест для них.)

#:property WinAppCapabilities=systemAIModels

Это все Phi Silica и другие API модели на устройстве, необходимые из манифеста. Объявите несколько, разделив их:

#:property WinAppCapabilities=systemAIModels;internetClient;microphone

winapp записывает каждую из них в элемент и пространство имен XML, которое на самом деле требуется, объявляет это пространство имен и вызывает MaxVersionTested , когда возможность нуждается в новой. Это имеет больше, чем это звучит: возможности распределяются по нескольким различным элементам, и один и тот же список выше становится тремя разными фигурами —

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

Имена winapp знают, написаны для вас. Для чего-либо другого — ограниченный набор растет со временем— квалифицируйте его с префиксом пространства имен:

Префикс Выдает
rescap: <rescap:Capability> — ограниченные возможности
uap:, , uap6:uap7:uap11: <uap*:Capability>
systemai: <systemai:Capability>
device: <DeviceCapability>
app: <Capability> в пространстве имен по умолчанию 
#:property WinAppCapabilities=rescap:broadFileSystemAccess

Нераспознанное имя без ошибок отклоняется при именовании этих префиксов, а не догадывается— возможность, созданная в неправильном пространстве имен, создает манифест, Windows либо отказывается регистрировать, либо принимает, не предоставляя его.

Создание собственного манифеста

Если вам нужно, что свойства не охватываются — обработчик протокола, сопоставление файлов, псевдоним выполнения — создайте манифест и winapp run будет использовать его подробно вместо создания. Он выбирается из, в порядке:

  1. --manifest <path> в командной строке.
  2. #:property WinAppManifestPath=<path> .cs в файле.
  3. Манифест, сидящий рядом с файлом .cs (напримерcounter.appxmanifest, <filename>.appxmanifest рядомcounter.cs).

Автоматически выбирается только имя каждого файла. appxmanifest.xml Или Package.appxmanifest в той же папке намеренно игнорируются— несколько .cs файлов могут совместно использовать папку, и при принятии общего имени автоматически запускается одно приложение под удостоверением другого. Чтобы использовать один манифест для нескольких файлов, назовите его явным образом или --manifestWinAppManifestPath.

Package.appxmanifest В противном случае создается в выходные данные сборки, а также ресурсы образов по умолчанию и обновляются во всех запусках.

Options. Каждый параметр режима папок работает: --no-launch, --with-alias/--symbols--debug-output--clean--detach--unregister-on-exit--args----executable--json--output-appx-directory--manifest--without-aliasа также --no-build-c/--configuration, --no-restoreи .-p/--property

Tip

Консольное приложение выводит в терминал по умолчанию. Упаковаемое приложение, запущенное с помощью AUMID, не имеет консоли, поэтому приложение, доступное только для консоли, будет работать правильно и печатать ничего. Winapp избегает этого: приложение с OutputType=Exe псевдонимом выполнения запускается с помощью псевдонима выполнения, который наследует stdin/stdout/stderr этого терминала. Вы по-прежнему получаете удостоверение пакета, и вам не нужно запрашивать его:

winapp run counter.cs

Передайте --without-alias для принудительной активации AUMID, а затем приложение запускается без консоли и не печатает здесь ничего. Окно отображается в окнеWinExe, поэтому оно сохраняет активацию AUMID; передается --with-alias , если вы хотите его в этом терминале в любом случае. Чтобы исправить выбор в файле, а не в каждой командной строке, задайте одно и то же свойство .csproj , которое использует:

#:property WinAppRunUseExecutionAlias=false

Псевдоним winapp объявляется в честь имени семейства пакетов, с winapp- префиксом , поэтому com.contoso.counter опубликовано с помощью CN=You получает winapp-com.contoso.counter_gspb8g6x97k2t.exe. Эта конечная часть является хэш-Windows издателя, поэтому два приложения совместного использования имени в разных издателях по-прежнему получают разные псевдонимы. Префикс сохраняет имя без реальных команд: приложение получает python.cswinapp-… псевдоним, никогда не python.exe. Если вы создаете собственный манифест, псевдоним, который вы объявляете, используется as-is и winapp ничего не добавляет.

Это относится только к псевдониму. Сама регистрация связана с именем пакета, поэтому при запуске второго приложения, которое объявляет то же самое WinAppPackageName при другом издателе, заменяет первую регистрацию, а не сидя рядом с ней. Присвойте каждому приложению собственное имя, если вы хотите одновременно зарегистрировать оба приложения.

winapp run выводит псевдоним, зарегистрированный, поэтому вам не нужно вычислять хэш, чтобы найти его.

Псевдоним — это команда в PATH, которая длится до тех пор, пока пакет остается зарегистрированным. Если другой пакет уже владеет именем, winapp говорит так. При выводе псевдонима для вас запускается с помощью AUMID, а не запускаемого неправильного приложения; когда вы попросили один явно - с --with-alias или #:property WinAppRunUseExecutionAlias=true - он завершается сбоем вместо того, чтобы тихо делать что-то другое.

Два параметра режима проекта не применяются, так как приложение на основе файлов настраивает себя. Они отклоняются с именем директивы, используемой вместо этого:

Опция Вместо этого используйте
-f/--framework #:property TargetFramework=net10.0-windows10.0.22621.0
--project ничего — .cs файл является проектом

--arch и -r/--runtime работает как они выполняются в режиме проекта. Если вы не передаете ни один из них, сборки winapp для архитектуры компьютера — это то, что требуется автономному Windows App SDK приложению, так как без него сборки AnyCPU пакета SDK и завершается сбоемWindowsAppSDKSelfContained requires a supported Windows architecture. В файле учитывается, #:property RuntimeIdentifier=win-arm64 явный --arch/--runtime переопределяет его.

Упакованные и распакованные обе работы, обнаруженные из эффективного WindowsPackageType режима проекта: по умолчанию регистрирует свободный макет и запускает его с удостоверением, при #:property WindowsPackageType=None создании приложения устанавливается соответствующее приложение для Windows Runtime и запускается .exe напрямую. (Упаковаемое приложение запускается с помощью псевдонима выполнения или с помощью активации AUMID— см. примечание консоли выше. Этот выбор отличается от того, упаковается ли он.) Параметры удостоверений (--no-launch, , --with-alias--without-alias, --clean--unregister-on-exit, , --manifest) --output-appx-directoryприменяются только к упакованным приложениям.

Выполнение с помощью dotnet run

Вам не нужно winapp вводить вообще. Ссылка на пакет из файла и простой dotnet run предоставляет тот Microsoft.Windows.SDK.BuildTools.WinApp же пакетный запуск:

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

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

dotnet run counter.cs

MsBuild пакета предназначен для перенаправления запуска в winapp, который упаковывает, регистрирует и запускает приложение, которое только что dotnet run создано — оно не перестроено. Обработка манифеста остается неизменной: winapp разрешает его точно так же, как и winapp run<filename>.appxmanifest.cs#:property WinAppManifestPath=… рядом с ними (см. собственный манифест), расширение каталога по-прежнему Package.appxmanifest игнорируется, и в противном случае он создается из #:property директив и обновляется каждый запуск.

Для перенаправления необходимо сохранить два условия:

Директива Почему
#:package Microsoft.Windows.SDK.BuildTools.WinApp@* целевые объекты, выполняя отправку перенаправления в этом пакете
#:property TargetFramework=net10.0-windows… Обычный net10.0 файл остается в одиночку, поэтому выполняется распаковка

Добавление #:property WindowsPackageType=None также оставляет файл в одиночку: dotnet run затем выполняется .exe непосредственно без удостоверения. Используйте winapp run для распаковки пути, если сначала необходимо установить соответствующую среду выполнения приложение для Windows.

Установите #:property EnableWinAppRunSupport=false для полного отказа от перенаправления и WinAppRun* свойства, описанные в разделе "Конфигурация ", чтобы сформировать запуск, например:

#:property WinAppRunUnregisterOnExit=true

Если dotnet run приложение распаковывало, когда ожидалось удостоверение, попросите MSBuild зачем. Использование dotnet build, а не dotnet msbuild только dotnet build синтезирует виртуальный проект, с помощью который компилируется файловое приложение:

dotnet build counter.cs -t:WinAppRunSupportInfo

Для однофайлового режима требуется пакет SDK для .NET версии 10.0.300 или более поздней версии.

Регистрация выходит за пределы выполнения. winapp run counter.cs оставляет пакет зарегистрированным после выхода приложения, точно так же, как папка и режим проекта, поэтому LocalState выживает и повторно запускает тот же файл повторно, а не накапливает регистрацию. Winapp говорит так, что при первом регистрации приложения и winapp unregister принимает сам себя .cs :

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

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

winapp unregister counter.cs не требует пути манифеста: он вычисляет значения файла #:property так же, как run это делает, и удаляет только пакет, зарегистрированный из выходных данных сборки этого файла. Одно именованное приложение, зарегистрированное из другой папки, отказывается, если вы не передайте --force. Если запуск использовал параметр, который формирует удостоверение или макет, передайте тот же параметр unregister:

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

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

-p переопределяет собственные директивы файла и Directory.Build.props рядом .cs с ключом WinAppPackageName выключения $(Configuration) или $(RuntimeIdentifier) — поэтому каждый из них может изменить, какой пакет регистрируется.

После очистки временных выходных данных winapp unregister counter.cs пакета SDK больше не сможет подтвердить регистрацию из этого файла и пропустить его — использовать winapp unregister --prune для очистки регистраций, файлы которых удалены, или --force для удаления определенного файла в любом случае. Если используется --output-appx-directoryзапуск, передайте тот же каталог, чтобы unregister он смог распознать макет.

Это же относится к пользовательскому выходному пути: владение подтверждается в стандартном <root>\bin\<configuration> макете пакета SDK, поэтому выполнение, созданное с -p OutputPath=<somewhere-else> ним, не может быть сопоставлено с исходным файлом. unregister пропускает его, а не угадывается в более широком каталоге — присвойте макету --output-appx-directoryили используйте --forceего.

Примеры однофайловых файлов:

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

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

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

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

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

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

# Remove the package it registered
winapp unregister counter.cs

Замечание

Удостоверение по умолчанию включает короткий хэш пути файла — counter.cs становится примерно таким counter-a1b2c3d4 , что два counter.cs файла в разных папках являются различными приложениями и сохраняют свои собственные параметры и LocalState. Хэш является производным от пути, поэтому он выживает изменения и повторно выполняется, а при перемещении файла изменяется только при перемещении файла. Установите #:property WinAppPackageName=<name> для выбора стабильного удостоверения самостоятельно; оно нормализуется до того, что Identity/@Name позволяет — символы за пределами [-.A-Za-z0-9] удаляются, имена короче 3 символов заполняются, 1и результат ограничен 50 символами, поэтому My App регистрируется как MyApp. В любом случае меню "Пуск" и "Параметры" отображаются WinAppDisplayName (по умолчанию: имя файла), а не удостоверение. Удостоверение всегда распространяется на учетную запись пользователя, поэтому она никогда не сталкивается с другим пользователем на том же компьютере.

Свойства MSBuild (пакет NuGet):

При использовании пакета NuGet Microsoft.Windows.SDK.BuildTools.WinAppdotnet run автоматически вызывает winapp run.

Все, записанное после dotnet run отправки в приложение, точно так же, как и без пакета. Настройте средство запуска со следующими свойствами MSBuild:

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

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

Следующие свойства MSBuild можно задать в .csproj поведении элемента управления:

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

WinAppRunUseExecutionAlias намеренно не в этом списке, в любом направлении. false запрашивает активацию AUMID, которая уже используется без запуска и отсоединения; true просто не применяется, если задано одно из этих псевдонимов, так как псевдоним выполнения нуждается в отслеживаемом, запущенном процессе. Таким образом, проект, который все еще выполняется <WinAppRunUseExecutionAlias>true</WinAppRunUseExecutionAlias> чисто dotnet run -p:WinAppRunDetach=true, запускается с помощью AUMID, а не завершается сбоем.

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

Аргументы:

  • input— Путь к .NET файловому приложению (одному.cs), пакет которого следует отменить регистрацию. Его удостоверение разрешается таким же образом winapp run , как и в случае с созданным манифестом, если приложение имеет одно, в противном случае из значений #:property — поэтому путь манифеста не требуется. Не следует использовать --manifest или автоматически обнаруживать манифест в текущем каталоге. Не удается сочетать с --manifestпакетом другой способ и может разрешаться в другой.

Варианты.

  • --manifest <path> — Путь к Package.appxmanifest (по умолчанию: автоматическое обнаружение из текущего каталога)
  • --force — Для локальной отмены регистрации пропустите проверку каталога установки и отмените регистрацию, даже если пакет был зарегистрирован из другого дерева проекта. Отклонено --onс; проверки владения целевыми объектами не могут быть обходить.
  • --on <target> — Удалите соответствующую регистрацию разработки winapp, sandboxа не на этом компьютере. Требует манифеста и не поддерживает --force. См. очистку приложения песочницы.
  • --prune — удалите каждую регистрацию в режиме разработки, файлы которой исчезли. Не удается объединить входные данные, --manifest--property, , --configuration, --arch, --runtimeили --output-appx-directory.
  • -p, --property <Name=Value> — свойство MSBuild, используемое при разрешении .cs удостоверения приложения на основе файлов. Повторяемые. Передайте те же свойства, влияющие на удостоверение, используемое выполнение (например -p WinAppPackageName=..., так как свойство командной строки переопределяет собственные #:property директивы файла. Применяется только к входным .cs данным.
  • -c, --configuration <name> — Конфигурация сборки, используемая при разрешении .cs удостоверения приложения на основе файлов. По умолчанию: Debug. Передайте ту же конфигурацию, в которую использовался запуск: Directory.Build.props рядом с WinAppPackageName параметром .cs или WinAppManifestPath условно.$(Configuration) Применяется только к входным .cs данным.
  • --arch <x64|arm64|x86> — Целевая архитектура, используемая при разрешении .cs удостоверения приложения на основе файлов. По умолчанию: текущая архитектура процесса. Передайте ту же архитектуру, что и используемый запуск, так как удостоверение также можно отключить $(RuntimeIdentifier). Применяется только к входным .cs данным.
  • -r, --runtime <rid>— Целевой .NET идентификатор среды выполнения (напримерwin-x64, используется при разрешении .cs удостоверения приложения на основе файлов. Используется только его архитектура, и она переопределяется --arch. Применяется только к входным .cs данным.
  • --output-appx-directory <path> — Каталог макета AppX, из который был зарегистрирован пакет. Требуется только при использовании --output-appx-directoryзапуска, так как ничего не отображается в записях пакета, в которых был создан параметр запуска.
  • --json — формат выходных данных в формате JSON

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

  • Определяет имя пакета из .cs разрешенного удостоверения файла или путем чтения манифеста.
  • Поиск обоих {name} пакетов и {name}.debug пакетов (вариант отладки создается с помощью create-debug-identity)
  • Проверяет, зарегистрирован ли каждый пакет в режиме разработки (IsDevelopmentMode == true)
  • Проверяет, принадлежит ли пакет приложению, которое вы назвали (если --forceне ) — его расположение установки должно находиться под каталогом, который вы определили: .cs собственные выходные данные сборки файла, каталог манифеста, текущий каталог или явный --output-appx-directory. Пакет, расположение установки которого не может быть разрешено (его файлы были удалены) пропускается, так как удостоверение само по себе не является подтверждением владения: два приложения, которые оба задают #:property WinAppPackageName=counter одинаковые удостоверения из разных папок. Используется --prune для очистки регистраций, файлы которых исчезли.
  • Отмена регистрации сопоставленных пакетов

Очистка мертвых регистраций (--prune):

Регистрация выходит за пределы своих файлов. Удаление выходных данных сборки, дерева проекта или (для файлового приложения) позволяет Windows очистку%LOCALAPPDATA%\Temp, а пакет остается зарегистрированным: Windows сохраняет удостоверение и запись меню "Пуск", но активация автоматически не делает ничего. Эти накапливаются невидимо.

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

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

Рассматриваются только регистрации в режиме разработки, и каждая из них удаляется по полному имени пакета, поэтому один и тот же именованный пакет по-прежнему установлен из динамического расположения. Запрос существует, так как отсутствующее расположение установки обычно является удаленной папкой, но также описывает пакет, зарегистрированный из отключенной сетевой папки или съемный диск, — просмотрите список перед подтверждением.

Примеры:

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

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

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

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

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

# JSON output for scripting
winapp unregister --json

cert

Создание, проверка и установка сертификатов разработки.

Сгенерировать сертификат

Создайте сертификаты разработки для подписывания пакетов.

winapp cert generate [options]

Варианты.

  • --manifest <Package.appxmanifest>— извлеките сертификат publisher из манифестаIdentity/@Publisher. Требуется только издатель, поэтому частично завершенный манифест по-прежнему работает. Если манифест не имеет используемого издателя, команда завершается ошибкой вместо замены значения по умолчанию, поэтому сертификат никогда не может автоматически совпадать с манифестом.
  • --publisher <name>— Publisher для сертификата. При создании сертификата этот параметр имеет приоритет над; явно пустое значение завершается --manifestошибкой вместо использования издателя манифеста. Принимает полное различающееся имя (например, CN=Contoso, O=Contoso Ltd, C=USX.500) или полное имя, которое автоматически упаковывается в виде CN=<name>. Компоненты должны быть однозначными и разделенными запятыми; Многозначные RDN (CN=Foo+OU=Bar) и обратные очки не поддерживаются, так как издатель манифеста MSIX не может представлять их. Неправильно сформированное имя (например CN= , или CN=A,,O=B) отклоняется при выходе, отличном от нуля, и ошибка именования проблемы, а не создание сертификата, который никогда не может соответствовать издателю манифеста.
  • --output <path> — Путь к файлу выходного сертификата (поддерживает абсолютные и относительные пути)
  • --password <password> — пароль сертификата (по умолчанию: passwordобщеизвестный — см. выходные данные JSON и безопасность)
  • --valid-days <valid-days> — Количество дней, в течение которых сертификат действителен (по умолчанию: 365)
  • --install — установка сертификата в локальное хранилище компьютеров после создания
  • --if-exists <Error|Overwrite|Skip> — Задайте поведение, если файл сертификата уже существует (по умолчанию: ошибка)
  • --export-cer — Экспортируйте файл (только открытый .cer ключ) вместе с файлом .pfx. Полезно для распространения общедоступного сертификата отдельно для установки доверия.
  • --json — формат выходных данных в формате JSON для программного использования. Ошибки также возвращаются в формате JSON ({"error": "..."}).

Выходные данные JSON:

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

publisher — отображаемое имя и subjectName полное различающееся имя сертификата. defaultPasswordIsPublic всегда присутствует при создании сертификата. Если это trueтак, .pfx пароль защищен любым пользователем, поэтому сертификат должен подписать только сборки, которые остаются на своих компьютерах, — проверьте его, прежде чем скрипт передает сертификат любому другому. warnings имеет то же раскрытие, что и текст и опущен, если нет ничего для отчета. publicCertificatePath отображается только с --export-cer.

Если --if-exists skipфайл сертификата уже существует, команда оставляет ее нетронутой и возвращает только путь:

{
  "certificatePath": "C:\\app\\devcert.pfx",
  "skipped": true
}

Проверьте skipped перед чтением других полей. Чтобы проверить существующий сертификат, выполните команду winapp cert info.

Сведения о сертификате

Отображение сведений о сертификате из PFX или CER-файла. Полезно для проверки соответствия сертификата манифесту перед подписью.

winapp cert info <cert-path> [options]

Аргументы:

  • cert-path — Путь к файлу сертификата (PFX или CER)

Варианты.

  • --password <password> — пароль для PFX-файла, игнорируемый для общедоступного CER (по умолчанию: "пароль")
  • --json — формат выходных данных в формате JSON

Установка сертификата

Установите сертификат в хранилище сертификатов компьютера.

winapp cert install <cert-path> [options]

Аргументы:

  • cert-path — Путь к файлу сертификата для установки

Примеры:

# Generate certificate for specific publisher
winapp cert generate --publisher "CN=My Company" --output ./mycert.pfx

# Generate certificate and export public key .cer file
winapp cert generate --publisher "CN=My Company" --export-cer

# Generate certificate with JSON output (for scripting)
winapp cert generate --publisher "CN=My Company" --json

# View certificate details
winapp cert info ./mycert.pfx

# View certificate details as JSON
winapp cert info ./mycert.pfx --json

# Install certificate to machine
winapp cert install ./mycert.pfx

знак

Подписывайте пакеты MSIX и исполняемые файлы с помощью сертификатов.

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

Аргументы:

  • file-path — Путь к пакету MSIX или исполняемому файлу для подписывания
  • cert-path — Путь к сертификату подписи (PFX)

Варианты.

  • --password <password> — пароль сертификата (по умолчанию: "пароль")
  • --timestamp <url> — URL-адрес сервера метки времени RFC 3161

Примеры:

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

# Sign executable with a non-default certificate password
winapp sign ./bin/MyApp.exe ./mycert.pfx --password mypassword

az-sign

Подписывание файла (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

Проверка подписи

Средства сборки загружаются из NuGet, а затем выполняются, поэтому winapp проверяет каждую из них для допустимой Microsoft подписи Authenticode непосредственно перед запуском. Сертификат должен называться Microsoft Corporation в качестве организации подписывания. Это относится к каждой команде, которая оболочки выполняется в средстве SDK, включая toolи packagesign. Средство, которое завершается ошибкой проверки, не выполняется:

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

Сбой здесь означает, что файл на диске не является тем, что Microsoft опубликовано — чаще всего повреждено или частичное скачивание. Удалите пакет из кэша NuGet и снова запустите команду, чтобы winapp повторно скачайте его.

Затем winapp сохраняет средство открытым до тех пор, пока он выполняется, поэтому проверенный файл является файлом Windows загрузки. Если средство не может храниться на месте, оно не выполняется:

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

Закройте любой файл — антивирусную проверку или открытый редактор — обычную причину— и снова выполните команду. Если средство не используется, удалите пакет из кэша NuGet, чтобы winapp повторно скачать его.

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 рабочей области
  • Каталоги установки пакетов
  • Созданные расположения заголовков

target

Выполнение команд, копирование файлов, проверка состояния или запись всего гостевого рабочего стола.

Каждая команда принимает sandbox в качестве первого аргумента. snapshotКроме того, эти команды могут подготовить или запустить песочницу. Ознакомьтесь с Windows выполнении песочницы для предварительных требований, разрешений, жизненного цикла и восстановления.

target exec

Выполните команду от имени гостевого пользователя.

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

Аргументы после -- сохранения своих границ. Перенаправляются стандартные потоки и код выхода гостевого процесса; это не полный терминал. --json форматирует сбои winapp на stderr без изменения stdout дочерней команды. Используйте структурную error.code структуру, чтобы отличить целевой сбой от состояния выхода приложения.

Явное WINAPP_UI_WORKFLOW_ID также группирование вызовов гостевого пользовательского интерфейса, выполненных командой; см. раздел "Координация пользовательского интерфейса песочницы".

целевой push-запрос и целевой вытягивание

Скопируйте файл или каталог в направлении с именем команды.

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

Целевые пути относятся к управляемой рабочей области целевого объекта; Абсолютные, корневые и UNC целевые пути отклоняются. Назначение файла содержит его имя файла. См. статью "Выполнение команд" и копирование файлов для макета каталога, обработки ссылок и выполнения скопированного скрипта.

целевой моментальный снимок

Подготовка отчета, развертывания и гостевые окна без запуска песочницы.

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

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

Снимок экрана с целевым объектом

Захват гостевого рабочего стола в собственном размере пикселя в виде PNG узла без селектора приложений или границ окна узла. --json сообщает источник гостевой координаты.

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

Вместо этого используйте ui screenshot --on sandbox -a <app> окно приложения. См. снимки экрана и записи для требований клиента, ограничений фокуса и обработки выходных данных.

целевая запись

Запишите гостевой рабочий стол на H.264 MP4. Файлы видео и кадра узла поступают после завершения записи; JSON и манифест кадра описывают любое масштабирование или заполнение.

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

Использует параметры длительности, кадра, перезаписи и результата ui record, но фиксирует рабочий стол, а не одно приложение. Предпочитайте положительный --duration-sec вариант использования автоматического интерфейса командной строки; требуется durationSecвспомогательный модуль npm. См. запись песочницы для частичных доказательств и сбоев готовности к захвату.

Find-ui

Агент-первый. find-ui создается в первую очередь для агентов программирования ИИ — это позволяет агенту извлекать реальные, компилируя разметку WinUI из коллекций доставки, а не изобретать ее, и --json делает каждый результат (и каждый сбой) машинно-читаемым. Он работает так же хорошо, как и по руке.

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

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

Коллекция, набор средств и корпус Реактора внутри ИНТЕРФЕЙСА командной строки, поэтому find-ui работает без доступа к сети, включая первый запуск в песочнице агента или за корпоративным прокси-сервером, который блокирует raw.githubusercontent.com. Когда GitHub доступен, ИНТЕРФЕЙС командной строки обновляет его и кэширует результат для каждого пользователя <global .winapp>/cache/find-uiв; встроенный корпус является только полом, никогда не потолок. Кэшированные данные обновляются не более чем каждые 24 часа или по запросу --refresh.

Встроенный корпус повторно извлекается из GitHub каждый раз, когда создается стабильный выпуск, и обновление, которое завершается сбоем, которое останавливает сборку выпуска, а не тихо доставка старых данных — пекарь получает через тот же путь --refresh кода используется, поэтому сбой означает, что динамическое обновление не работает слишком и стоит исследовать перед доставкой. Выпуск по-прежнему можно сократить по отношению к ранее зафиксированным корпусу, но только как явное переопределение. Когда результаты отслуживаются из встроенной копии коллекции/Toolkit/Reactor corpora, find-ui говорится, что на stderr и --json выходных данных несет "corpus": "embedded" (другие значения: "network" для свежего получения, "cache" для локального кэша). Запрос только для ядра ( --source coreили --id набор, который является всеми основными шаблонами— отчеты "embedded" тоже, потому что курируемые основные шаблоны компилируются в CLI и никогда не извлекаются; он не печатает устаревших уведомлений, так как --refresh не может изменить их. Поле corpus сообщается всякий раз, когда результаты были обработаны; он отсутствует только в том случае, если не удалось загрузить корпус вообще.

Варианты.

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

Связанные:find-ui выполняет поиск примеров WinUI; используется find-api для поиска поверхности API (типов, членов, перечислений) ссылок на проект и winapp ui search поиска дерева пользовательского интерфейса запущенного приложения .

find-api

Агент-первый. find-api создается в первую очередь для агентов программирования искусственного интеллекта— он создает код на поверхности API, который фактически ссылается на проект, а не на воспоминания модели, а --json также ненулевых кодов выхода на отсутствующие символы позволяют кодегену ворот агента на ответе. Он работает так же хорошо, как и по руке.

Выполните поиск и проверьте область API Windows/WinRT (типы, члены, перечисления, пространства имен), доступную для проекта, разрешенную из его ссылочных .winmd/.dll метаданных. Поиск голой формы; Вложенные команды детализация по определенному типу, пространству имен или самому индексу.

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

Индекс создается из восстановленных пакетов NuGet/SDK проекта (через project.assets.json) при первом использовании и обновлении автоматически при восстановлении проекта. Он находится в глобальном .winapp кэше (cache/find-api/) и предоставляется совместно в проектах. Сначала восстановите проект (winapp restore или dotnet restore).

Каждое совпадение отображается в своем пространстве имен с пакетом, который поставляет его и однострочный сводка о том, что он делает, поэтому результат можно использовать без второго members вызова:

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

Добавьте --verbose также на печать файла кэша на диске, который поддерживает каждое пространство имен, что полезно при диагностике устаревшего или неожиданного индекса.

Выполнение winapp find-api без запроса на всех выводит краткую сводку об использовании и завершает работу 0 — это запрос на помощь, а не поиск, который ничего не нашел.

Области. Каждый ответ поступает из ровно одной области, как scope и в --json виде заметки в текстовых выходных данных:

  • project — проект в текущем каталоге (или --project / --project-dir). Охватывает пакет SDK Windows, Windows App SDK и собственные пакеты NuGet проекта. Метаданные Windows App SDK — это выпуск ссылок на проект: если на компьютере установлена более новая среда выполнения приложение для Windows, find-api предупреждает и покидает его, а не подтверждает типы, для которого проект не может компилироваться.
  • sdk— пакет SDK для Windows на уровне компьютера + Windows App SDK метаданные, используемые автоматически, если текущий каталог не содержит проекта и нет решения. Это позволяет find-api изучать API до существования любого проекта и не требует доступа к сети. Он намеренно не включает сторонние пакеты NuGet, поэтому тип из (скажем) набора средств сообщества не будет найден в этой области.

Запрос из каталога без проекта и никакого решения всегда отвечает sdk областью , никогда не выполняя индексирование проекта в общем кэше, поэтому результаты никогда не зависят от связанного глобального состояния. Передайте --project sdk область пакета SDK явно из проекта и winapp find-api refresh --project sdk перестроите ее после установки нового пакета SDK Windows.

Каталоги решений. В каталоге, где .sln/.slnx нет файла проекта рядом с ним, проекты решения создают ответ вместо sdk области. Они индексируются по запросу, поэтому их пакеты NuGet включены. Когда решение создает несколько индексированных проектов, запрос перечисляет их и запрашивает --project <name> , а не выбирает один.

Команды:

  • (голая)find-api "<query>" ["<query>"...] — Имена типов поиска и членов, возвращаясь к документированные сводки, сгруппированные по пространству имен
  • members <type> [<type>...] [--filter <text>] — вывод списка свойств, событий и методов типа (объявленных членов с сигнатурами, унаследованными элементами, обобщаемыми декларируемыми типами)
  • check-property <type> <property> [<property>...] — Проверка свойств существует в типе (завершается без нуля, если отсутствует). Свойство только для чтения сообщается с ⚠️ и "только для чтения, не может быть назначено", а не простое ✅, поэтому такое свойство, как ActualWidth не ошибочно для чего-то, что можно задать. Имена свойств соответствуют регистру, так как C# и XAML: check-property Button background завершается ненулевым и предлагает Background в качестве близкого совпадения, а не сообщает имя, которое вы не можете на самом деле написать.
  • enums <type> [<type>...] [--filter <text>] — вывод списка значений перечисления (завершается без нуля, если тип не является перечислением)
  • packages — вывод списка индексированных пакетов метаданных с числом типов и членов для каждого пакета
  • stats — Отображение статистической статистики индекса (пакеты, пространства имен, типы, члены, .winmd файлы)
  • refresh [--scan] — перестроение индекса для проекта (--scan индексирует каждый проект в каталоге). При этом --project <name>имя, соответствующее ни одному индексованного проекта, не выполняется индексирование текущего каталога.

Batching.search, members, enumsи check-property принять несколько субъектов в одном вызове. Для агента ИИ это единственный самый большой затратный рычаг: маргинальная стоимость подстановки доминирует круглой поездки (каждый звонок повторно отправляет весь разговор), а не по размеру полезных данных, поэтому один вызов ответов на десять вопросов гораздо дешевле, чем десять вызовов.

  • Одна тема возвращает точно фигуру полезных данных, которая всегда имеется как в тексте, так и --jsonв тексте.
  • Два или более предметов возвращают конверт — { "count": N, "results": [ ... ] } в --json, при этом каждый элемент является обычной полезной нагрузкой с одним субъектом; check-property добавляется missingCount. Вывод текста отрисовывает каждый субъект в последовательности в одном заголовке области.
  • check-property пакетные свойства одного типа: первый аргумент является типом, каждый аргумент после него является свойством. В пакетном режиме свойство, которое существует, печатает одну ✅ строку; полная детализация почти отсутствует печатается только для тех, кто не имеет значения.
  • Пакет завершает работу 0 только в том случае, если каждая тема устранена и найдена, поэтому пакет по-прежнему безопасно ворот кодегена.

Ранжирование поиска. Запрос, который точно соответствует имени типа, ранжируется впереди частичных совпадений, и когда короткое имя совместно используется несколькими пространствами имен только конфликтующими именами, перечислены как неоднозначные — запрос, например NavigationView , сообщает горстку пространств имен, определяющих этот точный тип, а не каждое пространство имен, содержащее аналогичный символ. Список неоднозначности подчиняется --max, и обычные результаты по-прежнему печатаются под ним.

Введите имена.members, check-propertyи enums примите короткое имя (NavigationView) или полное (Microsoft.UI.Xaml.Controls.NavigationView). Если короткое имя совместно используется современным Microsoft.* типом и его устаревшим Windows.* двойником UWP, Microsoft.* то есть проекцией, используемой приложением Windows App SDK, всегда отображается разрешенное полное имя. Любой другой конфликт выходит ненулевым и перечисляет кандидатов вместо угадывание.

Сигнатуры метода. Подпись печатается так, как вы будете писать вызов: метод, вызываемый типом, а не на экземпляре, отображается, staticа параметр по ссылке отображается с ключевым словом, который он фактически нуждается , outinили ref. Поэтому TryGetValue считывает Boolean TryGetValue(String key, out String value), который компилируется как написанный.

Варианты.

  • --max <n> — максимальное количество результатов поиска, сгруппированных по пространству имен (только по умолчанию 5; только для поиска). Кроме того, заголовок списка неоднозначности, поэтому короткий запрос, который сталкивается во многих пространствах имен, остается читаемым.
  • --filter <text> — сузить описание membersenumsи : совпадение подстроки без учета регистра в имени члена или значения. Лучше всего использовать для типов с сотнями членов. Большинство перечислений достаточно малы, чтобы сбросить весь (даже Symbol, самый большой в WinUI в 197 значениях), поэтому фильтрация их обычно стоит больше, чем она экономит после того, как вы фактор во втором предположении. Никогда не выполняйте одну и ту же команду с другим текстом фильтра— дамп один раз и считывать его.
  • --all members— В списке полной поверхности: полные подписи для унаследованных элементов, а также статические значения идентификаторов зависимостей и описания идентификаторов свойств для каждого члена, все из которых нефильтрованный список опишируется (см. список ниже). --verbose подразумевает его; используется --all при желании --json, которое не может быть объединено с --verbose.
  • --scan — рекурсивное обнаружение и индексирование каждого проекта в каталоге (refresh только)
  • --project <name>— Project запрашивать (соответствует .csproj/.vcxproj имени) или sdk запрашивать область пакета SDK на уровне компьютера Windows
  • --project-dir <path>— Project каталог для запроса (по умолчанию используется текущий каталог). Путь, который не существует, является ошибкой— он никогда не будет автоматически отвечать из sdk области.
  • --json — выдает полезные данные, доступные для чтения компьютером, на stdout (поддерживается каждой командой). Полезные данные запросов определяют индекс, который отвечает через scope (project или sdk) projectNameи projectDir (отсутствует для области ПАКЕТА SDK) — имена проектов не являются уникальными в разных каталогах, поэтому projectDir это надежное удостоверение. При --jsonкаждом сбое , включая ошибки аргумента или синтаксического анализа, такие как не целочисленное число --max , создается как неструктурированный {"error": "..."} объект на stdout с кодом выхода без нуля, поэтому выходные данные остаются доступны для чтения компьютером.

Примеры:

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

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

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

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

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

# Manage the index
winapp find-api refresh

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

При --filter применении выходные данные по-прежнему сообщают о нефильтрованном итоговом (totalValuesилиtotalEvents//totalPropertiestotalMethods в--json), поэтому узкое представление никогда не ошибается для небольшого API. Фильтр, который ничего не совпадает 0 , по-прежнему завершается и говорит так явно , что "ничего не соответствует вашему фильтру", а не "нет такого типа".

Размер списка. Нефильтрованный members список является одной дорогой фигурой — members Button охватывает 288 членов, из которых 280 наследуются от 6 базовых типов. Нефильтрованный вызов — это запрос ориентации ("что такое тип, примерно то, что это может сделать?"), поэтому он отвечает на то, что и опустит части ничего не написаны из:

  • Наследуемые подписи членов — наследуемые элементы группируются путем объявления типа и перечислены только по имени, поэтому форма наследуемой поверхности по-прежнему видна без 280 полных подписей.
  • Статические значения идентификатора зависимостей (BackgroundProperty) — 28% типичных свойств элемента управления WinUI. Они должны быть переданы GetValue/SetValue, а не назначены.
  • Описания каждого члена — прозе XML-doc, примерно 16% полезных данных.
  • Поля, подразумеваемые их окружением: --jsonkind (подразумеваемые содержащимevents/methodsproperties/массивом), returnType (ведущий маркерsignature), а также inherited когда значение false (подразумевается).declaringType

То, что было опущено, всегда сообщается (hiddenDependencyProperties, descriptionsOmittedи hint в --json; строка "Опущено:" в тексте), а итоги по-прежнему описывают весь тип. Как --filter и --all увидеть полную поверхность с полными сигнатурами и описаниями, поэтому members Button --filter BackgroundProperty по-прежнему находит идентификатор и members Button --filter Click по-прежнему возвращает Clickунаследованную подпись. Измеряется на samples/winui-app, это занимает members Button --json от 91 954 до 10567 символов (-88,5%) при выходе --filter и --all байтовой идентичной.

Сопоставление запроса. winapp find-api "language model" ряды LanguageModel выше, слова которых разбросаны по пространствам имен и членам, включая вне проекта при индексировании типа. Поиск лексический, а не семантический: он соответствует целым словам идентификатора, а не любому запуску букв, поэтому llm находит IImageLLMAdapterSession , но не ScrollMode. Если запрос не соответствует имени, он пытается использовать документированные сводки типов и членов, что позволяет "random-access stream" найти IRandomAccessStream. Описания ниже каждого соответствия имени и только сводки по пакетам фактически доступны для поиска— пакет без XML-документации не содержит текста описания.

Проекты без файла проекта MSBuild. Приложение Electron (или любое другое приложение, отличное от .NET на основе winapp.yaml) не .csproj имеет и поэтому нетproject.assets.json. find-api индексирует его из .winapp/winmds.lock.jsonwinapp restore записей, которые записывают то же самое: каждый разрешенный пакет, его версия и .winmd файлы, которые он вносит. Такой проект называется каталогом, и его индекс становится устаревшим при перезаписи файла блокировки. Каталог, содержащий как a, .csproj так и индексируется winapp.yaml из .csprojиндекса, который является более точным описанием того, что проект компилирует против.

Отрицательные ответы квалифицированы, если индекс является неполным. Если метаданные пакета не удалось прочитать, "такой тип" и "этот пакет никогда не индексировался" выглядят идентичными, и при выполнении первого действия, когда он действительно второй создает код для API, который вы сказали, не существует. Поэтому каждый отрицательный search ответ, в том числе возвращающий ноль результатов, содержит примечание о том, что индекс является частичным и точками в winapp find-api refresh. Положительные ответы не затрагиваются.

Имена универсальных типов. Метаданные хранят универсальные типы с суффиксом arity (IAsyncOperation`1), что не так, как кто-то записывает их. members, enumsи примите каждую форму: IAsyncOperation<StorageFile>IAsyncOperation, и IAsyncOperation`1check-property все разрешаются в один тип. Голое имя соответствует любому arity; Указанное arity (в любой нотации) должно соответствовать, поэтому Holder<A, B> не будет разрешаться в один параметр Holder<T>.

--json Полезные данные опустили диагностику. Пути к файлам кэша отображаются только в --verbose разделе (соответствующие текстовые выходные данные, где они уже были подробными) и пустые массивы предложений не сериализуются []как .

Коды выхода:search без попаданий, check-property отсутствующих свойств и enums в типе, отличном от перечисления, все выходы ненулевых — создание кода ворот и проверка CI на них. Пакетный вызов завершает работу без нуля, если какой-либо субъект завершается ошибкой. Свойство, доступное только для чтения, не является сбоем— оно существует, поэтому check-property завершает 0 работу и помечает его в выходных данных (writable: false в --json). Свойство init сообщает writable: false по той же причине: его можно задать в инициализаторе объекта, и его подпись говорит { get; init; }, но назначение его после этого не компилируется.

Связанные:find-api ответы "существует ли этот API и каковы его члены?"; используется find-ui для поиска рабочего примера WinUI для элемента управления.

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

(Доступно только в пакете 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 создает этот каталог, когда команда сначала нуждается в ней.

Если winapp не может записывать данные в глобальный каталог кэша

Некоторые среды, такие как песочницы агента, которые разрешают запись только в текущий проект, блокируют доступ к %USERPROFILE%\.winapp. Большинство команд по-прежнему работают там, и проверка обновления пропускается. Если winapp не завершил свой первый запуск в этом каталоге, каждый запуск также выводит уведомление телеметрии одной строки в stderr.

Эти команды должны записываться в каталог кэша и останавливаться с ошибкой, которая называет путь:

Command Что он пишет
find-api Индекс API, когда его необходимо создать или обновить. Существующий индекс up-to-date по-прежнему считывается.
store Интерфейс командной строки разработчика Microsoft Store при первом установке.

Чтобы исправить его, задайте WINAPP_CLI_CACHE_DIRECTORY для папки winapp запись (например, один внутри проекта), а затем повторите попытку.

winapp ui команды сохраняют свое состояние %USERPROFILE%\.winapp\state\uiвыполнения. Если они не могут получить доступ к нему, они по-прежнему выполняются, но не ожидая других winapp ui команд на одном рабочем столе, и печатают одно предупреждение (опущено с --json или --quiet). Избегайте выполнения других winapp ui команд на этом рабочем столе одновременно.

команды песочницы Windows сохраняют свое состояние%USERPROFILE%\.winapp\state. Если эта папка не является записываемой, они останавливаются и sandbox_state_unavailable называют переменную, которую нужно задать.

Проверка обновлений

Интерфейс командной строки 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')

Удостоверение рабочего процесса пользовательского интерфейса

winapp ui Команды, которые управляют физическим рабочим столом, всегда принимают совместные повороты, поэтому два рабочих процесса, выполняемых одновременно, не могут украсть фокус друг друга или закрыть меню друг друга. Этот арбитраж не нуждается в настройке и не может быть отключен.

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

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

Используйте то же значение для сотрудничества процессов (например, записи и щелчков, которые он должен записывать) и различных значений для независимых рабочих процессов. Каждая команда без идентификатора — это собственный рабочий процесс с одним выстрелом, даже если несколько запускаются из одной оболочки, поэтому узлы, запускающие новую оболочку для каждой команды, должны внедрить одно и то же явное значение в каждую из них. Значение непрозрачно, никогда не рассматривается как учетные данные и всегда сохраняется как хэш SHA-256. См. раздел модель автоматизации пользовательского интерфейса → Координирование параллельных рабочих процессов пользовательского интерфейса.

ui

Проверьте и взаимодействуйте с запущенными пользовательскими интерфейсами приложений Windows с помощью модель автоматизации пользовательского интерфейса (UIA). Запустите winapp ui --help основной рабочий процесс; см. полное руководство по автоматизации пользовательского интерфейса .

winapp ui [command] [options]

Команды:

  • status — Подключение к приложению и отображение сведений
  • inspect — Представление дерева элементов
  • search — Поиск элементов по селектору
  • get-property — чтение свойств элемента
  • get-text / get-value — чтение значения и текста из элемента (TextPattern, ValuePattern или Name)
  • screenshot — Запись окна или элемента в формате PNG (несколько окон формы один составной PNG; см. область записи)
  • record— Запись области окна или элемента в видео H.264 MP4 (Windows запись графики + Media Foundation)
  • invoke — Активировать элемент (щелчок, переключатель, развернуть); --action выбирает точную операцию (см. вызов)
  • 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 — Сообщите об элементе, ориентированном на данный момент
  • yield — выпуск поворота пользовательского интерфейса текущего рабочего процесса; требуется WINAPP_UI_WORKFLOW_ID

Варианты.

  • -a, --app <app> — Целевое приложение (имя, название или PID)
  • -w, --window <hwnd> — Целевое окно по HWND (стабильная)
  • --on <target> — Выполнение любой ui команды в sandboxименах, идентификаторах piD и дескрипторах окон относится к гостевому. Выходные данные передаются узлу. Сведения о настройке, координации рабочих процессов и требованиях клиента см. в разделе автоматизации пользовательского интерфейса песочницы .
  • --type, — --root--class-name узкий селектор для команд, перечисленных в области и типизированных запросах

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

Запишите область окна или элемента в H.264 MP4.

# Record a window for 10 seconds at 15 fps
winapp ui record -a Calculator --duration-sec 10 --fps 15 -o demo.mp4

# Record until Ctrl+C, downscaled so the longest edge is 1280px
winapp ui record -a "My App" --duration-sec 0 --max-edge 1280 -o capture.mp4

# Record just one element's region
winapp ui record -a "My App" btn-save-1234 -o button.mp4

# Keep an agent-readable timeline alongside the MP4
winapp ui record -a Calculator --frames --duration-sec 10 --fps 10 -o evidence.mp4

Параметры записи:

  • --duration-sec <n> — длина записи в секундах. 0 записывается до ctrl+C (по умолчанию 0).
  • --fps <n> — кадры в секунду для записи (по умолчанию 15).
  • --max-edge <px> - Уменьшение масштаба, поэтому самый длинный край находится в большинстве этих пикселей (0 = без уменьшения).
  • --capture-screen — Запись с экрана, поэтому включены наложения или всплывающие окна (может записывать окна occluding).
  • -o, --output <path> — выходной .mp4recording-<timestamp>-<guid>.mp4путь (по умолчанию — ).
  • --overwrite — замените существующие выходные данные записи после завершения нового выполнения; Существующие выходные данные отклоняются по умолчанию. Предыдущие пакеты кадров сохраняются. См. раздел "Запись восстановления выходных данных".
  • --frames — запись меток времени JPEG, frames.ndjsonа также manifest.json в <output-name>.frames. Поддерживает 1-30 fps и --max-edge 64-4096 (по умолчанию 1280) с ограничением кадров 1 ГиБ.

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

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

  • Последнее обновление: