Использование интерфейса командной строки winapp с WinUI

В этом руководстве показано, как использовать winapp CLI на всех этапах внутреннего цикла разработки приложения WinUI 3: создание проекта из официального шаблона, сборка и запуск с удостоверением пакета, отладка сбоев, поиск элементов управления и API, автоматизация пользовательского интерфейса и создание подписанного пакета MSIX. Каждый шаг выполняется из командной строки, поэтому он работает в любом редакторе, в CI и с агентами программирования ИИ.

Шаблоны проектов WinUI уже включают Package.appxmanifest, поэтому вам не нужно запускать winapp init для приложения WinUI. Если вы добавляете удостоверение пакета в существующее приложение .NET, которое не использует WinUI, см. статью Использование winapp CLI с .NET вместо этого.

Prerequisites

  • Windows 10 версии 1809 или более поздней версии или Windows 11.

  • .NET SDK версии 8.0.100 или более поздней. Для экспериментальных шаблонов Reactor требуется пакет SDK для .NET 10. Интерфейс командной строки winapp не устанавливает цепочки инструментов, поэтому winapp new и winapp run останавливаются с подсказкой, если отсутствует .NET SDK.

  • winapp CLI:

    winget install Microsoft.winappcli --source winget

  • Режим разработчика, который Windows требует для регистрации приложения из выходных данных сборки. Включите его в Параметры > Система > Для разработчиков. Сведения об изменениях на компьютере см. в разделе Безопасность.

Создание приложения WinUI

winapp new создает каркас приложения WinUI из официального Microsoft.WindowsAppSDK.WinUI.CSharp.Templates пакета. Он устанавливает или обновляет пакет шаблонов по запросу, а затем вызывает для вас dotnet new.

# Pick a template and a name interactively
winapp new

# Or create a NavigationView app without prompts
winapp new --name MyApp --template winui-navview --use-defaults

Запустите winapp new --list , чтобы просмотреть шаблоны в установленном пакете. Пакет включает следующие шаблоны:

Template Description
winui Минимальное пустое приложение XAML (по умолчанию). См. снимок экрана
winui-navview Приложение XAML с оболочкой NavigationView. См. снимок экрана
winui-tabview Приложение XAML с оболочкой TabView. См. снимок экрана
winui-mvvm Приложение XAML, использующее шаблон MVVM с CommunityToolkit.Mvvm. См. снимок экрана
winui-lib Библиотека классов WinUI
winui-unittest Упакованный проект MSTest для модульных тестов WinUI
reactor, reactor-mvu, reactor-navview, reactor-tabview Экспериментальный. Приложения WinUI, написанные только на C#, без XAML

Note

Шаблоны Reactor ссылаются на пакеты предварительного выпуска Microsoft.UI.Reactor. Их API-интерфейсы могут изменяться или удаляться в будущем выпуске.

Для каждого параметра см. newсправочник команд.

Сборка и запуск с учетными данными

Из папки проекта команда winapp run собирает проект, устанавливает среду выполнения Windows App SDK, соответствующую вашей архитектуре, если она отсутствует, регистрирует приложение с удостоверением пакета и запускает его.

cd MyApp
winapp run

winapp run принимает файл проекта, файл решения, папку, содержащую один из них, или папку выходных данных сборки:

# A specific project and configuration
winapp run .\MyApp.csproj -c Release --arch arm64

# A solution: winapp CLI finds the single app project and skips libraries and tests
winapp run .\MySolution.sln

# A solution with more than one app project
winapp run .\MySolution.sln --project MyApp

# Build output that you produced yourself
winapp run .\bin\x64\Debug\net10.0-windows10.0.26100.0\win-x64

Winapp CLI считывает свойство проекта WindowsPackageType , чтобы решить, как его запустить. Упакованный проект запускается с идентификатором пакета. Проект, для которого WindowsPackageType имеет значение None, запускается как неупакованное приложение без идентификатора. Чтобы запустить упакованный проект в неупакованном виде, передайте свойство в командной строке:

winapp run -p WindowsPackageType=None

Другие полезные варианты включают: --clean удалить предыдущую регистрацию и сохраненные данные приложения (LocalState и параметры) для нового первого запуска, --no-launch зарегистрировать без запуска приложения, а --detach --json вернуть идентификатор процесса и выйти, чтобы скрипты и агенты могли продолжать работу, пока приложение выполняется. Полный список см. в режиме проектов (проекты .NET SDK).

Вместо этого используйте dotnet run

Если вы предпочитаете dotnet run, используйте пакет NuGet Microsoft.Windows.SDK.BuildTools.WinApp. Пакет перехватывает dotnet run, что позволяет вызывать winapp run и запускать приложение с идентификатором. Проекты, которые вы создаете с winapp new, уже содержат ссылку на пакет, поэтому dotnet run работает без дополнительной настройки. Для других проектов сначала добавьте пакет:

dotnet add package Microsoft.Windows.SDK.BuildTools.WinApp --prerelease
dotnet run

Вы можете передать параметры dotnet run -p:WinAppRunDebugOutput=true в качестве свойств MSBuild winapp run, например WinAppRun*. Чтобы отключить интеграцию, установите EnableWinAppRunSupport в значение false в файле проекта. Дополнительные сведения см. в разделе о поддержке dotnet run.

Отладка сбоев

Добавьте --debug-output для записи сообщений OutputDebugString и исключений первого шанса во время работы приложения. Если приложение WinUI завершается сбоем с исключением stowed, winapp CLI анализирует аварийный дамп и выводит исходную ошибку и стек вызовов вместо универсального кода сбоя.

winapp run --debug-output

Добавьте --symbols, чтобы скачивать символы для полных имен нативных функций. Так как --debug-output подключает winapp CLI как отладчик, вы не можете подключить Visual Studio или другой отладчик к тому же процессу. Чтобы выполнить отладку с помощью IDE, см. Отладка с помощью winapp CLI. Дополнительные сведения об анализе stowed-exception см. в статье Триаж stowed-exception в WinUI.

Найдите элементы управления и API

winapp find-uiвыполняет поиск примеров XAML и C# из WinUI Gallery и Windows Community Toolkit по назначению и возвращает код для выбранного сценария. winapp find-apiвыполняет поиск по поверхности API Windows и WinRT, на которую ссылается ваш проект, например по типам, членам и перечислениям Windows App SDK и Windows SDK.

# Find a control by what you want to build
winapp find-ui "tabbed layout"

# Get the XAML and C# for one of the returned scenarios
winapp find-ui --id gallery-tabview-1

# Look up an API
winapp find-api NavigationView

Обе команды поддерживают --json, поэтому агенты программирования ИИ могут использовать их для выбора элементов управления и проверки имен API. Дополнительные сведения см. в ссылках find-ui и find-api.

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

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

winapp run --detach
winapp ui inspect -a MyApp
winapp ui search Button -a MyApp
winapp ui invoke PART_PaneToggleButton -a MyApp
winapp ui screenshot -a MyApp

Селектор PART_PaneToggleButton указывает на кнопку меню в шаблоне winui-navview. Для собственных элементов управления скопируйте селектор из выходных данных winapp ui inspect или winapp ui search.

Чтобы запустить приложение в песочнице Windows, а не на рабочем столе, добавьте --on sandbox в winapp run и winapp ui. Дополнительные сведения см. в разделе автоматизации пользовательского интерфейса и выполнения в песочнице.

Упаковать и подписать

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

winapp cert generate --manifest .\Package.appxmanifest
winapp pack .\MyApp.csproj -c Release --arch x64 --cert .\devcert.pfx

winapp pack собирает проект и создает подписанный .msix. Чтобы объединить сборки для нескольких архитектур в одну .msixbundle, ознакомьтесь с мультиархитектурными пакетами. Проект должен быть упакован, поэтому проект, который устанавливает WindowsPackageType в значение None, не может быть упакован. Для проектов WinUI сборка Windows App SDK управляет манифестом, точкой входа и созданием ресурсов, поэтому --manifest, --executable и --skip-pri не принимаются.

Сертификат разработки предназначен только для локального тестирования и использует пароль по умолчанию. Перед распространением приложения подписывайте его доверенным сертификатом, например, с помощью winapp az-sign и Azure Trusted Signing. Дополнительные сведения см. в разделе Упаковка проекта напрямую и Безопасность.

Существующие проекты WinUI

Winapp CLI работает с проектами WinUI, созданными в Visual Studio. Наведите указатель winapp run на файл проекта, файл решения или папку, содержащую один из них. Для winapp pack, передайте .csproj. Вы можете продолжать сборку и отладку в Visual Studio и использовать winapp CLI для сценариев, CI и рабочих процессов агента.

WinUI с C++

winapp run также создает и запускает проекты WinUI C++/WinRT (.vcxproj), созданные на основе шаблона Visual Studio WinUI Blank App (Packaged). Он собирает проект с помощью MSBuild Visual Studio, регистрирует приложение с идентификатором пакета и запускает его:

winapp run .\MyApp.vcxproj

# Or from the folder that contains the project
winapp run .

Для проектов C++ требуется Visual Studio или Build Tools for Visual Studio с рабочей нагрузкой Разработка классических приложений на C++ и средствами разработки приложений WinUI на C++. winapp pack не собирает .vcxproj проекты, поэтому создайте пакет MSIX в Visual Studio. Предварительные требования и параметры см. в проектах C++ (.vcxproj). Сведения о приложениях C++, которые не используют WinUI, см. в статье "Использование CLI winapp с C++".

Samples

  • winui-app: упакованое приложение WinUI с элементами управления, настроенными для winapp ui автоматизации
  • winui-unpackaged-app: приложение WinUI, которое выполняется без идентификатора пакета
  • winui-solution: решение с несколькими проектами, показывающее, как winapp run выбирает проект приложения
  • cpp-winui-app: упакованное приложение C++/WinRT WinUI (Visual Studio .vcxproj с XAML), которое работает с winapp run

Дальнейшие действия

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