Отладка с помощью удостоверения пакета

Многие API Windows (push-уведомления, фоновые задачи, цели общего доступа, задачи запуска, Windows API AI) требуют, чтобы ваше приложение имело package identity. Во время разработки вы не хотите каждый раз при тестировании создавать полный установщик MSIX — winapp предоставляет две команды, чтобы предоставить идентификацию приложения в реальном времени.

Используете Visual Studio с проектом по упаковке? Если вы уже используете Visual Studio для упаковаемого проекта, скорее всего, вам не нужен winapp для отладки. Visual Studio уже обрабатывает регистрацию пакетов, идентификацию, активацию AUMID, подключение отладчика и отладку кода активации — все это с использованием F5. Она также предлагает отладку → другие целевые объекты отладки → пакет установленного приложения отладки для расширенных сценариев. Приведенные ниже рабочие процессы наиболее полезны для пользователей VS Code, рабочих процессов на основе терминала и платформ, которые VS не упаковывает в собственном коде (Rust, Flutter, Tauri, Electron, plain C++).

Два подхода: `winapp run` и `create-debug-identity`

	`winapp run`	`create-debug-identity`
Что он регистрирует	Полный свободный пакет макета (вся папка)	Разреженный программный пакет (один файл exe)
Запуск приложения	Запускается программой winapp (псевдоним активации или выполнения AUMID)	Вы запускаете exe самостоятельно (командная строка, интегрированная среда разработки и т. д.)
Имитация установки MSIX	Да — ближайшее к рабочему поведению	Нет — только малонасыщенный идентификатор
Файлы остаются на месте	Скопировано в каталог макета AppX	Да — exe остается на исходном пути
Область идентификации	Все содержимое папки (exe, DLL, ресурсы)	Один исполняемый файл
Удобно для отладки	Присоединяйтесь к PID после запуска или используйте `--no-launch`, а затем запускайте через псевдоним	Запуск непосредственно из отладчика вашей интегрированной среды разработки — exe сохраняет свою идентичность в любых условиях.
Поддержка консольного приложения	`--with-alias` хранит stdin/stdout в терминале	Запуск exe непосредственно в терминале
лучше всего подходит для	Большинство платформ (.NET, C++, Rust, Flutter, Tauri)	Электрон или когда необходим полный контроль отладчика IDE (F5)

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

По умолчанию: `winapp run`

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

# Build your app, then:
winapp run .\build\output

`create-debug-identity` следует использовать в следующих случаях:

Ваш EXE-файл отделён от выходных данных сборки, например приложений Electron, в которых electron.exe находится node_modules/
Вам нужно выполнить отладку кода запуска и не удается подключить отладчик достаточно быстро после запуска AUMID
При использовании некоторых отладчиков, в которых невозможно запускать с AUMID и нужна идентификация в запущенном процессе, create-debug-identity регистрирует exe, чтобы у него была идентификация независимо от способа запуска.
Вы тестируете разреженное поведение пакета в частности (AllowExternalContent, TrustedLaunch)

# Register identity for an exe, then launch it however you want:
winapp create-debug-identity .\bin\Debug\myapp.exe
.\bin\Debug\myapp.exe   # or F5 in your IDE

Сценарии отладки

Сценарий A: Просто запуск с идентификацией

Самый простой рабочий процесс — сборка, запуск с удостоверением, завершено.

winapp run .\build\Debug

Winapp регистрирует папку как свободный пакет макета и запускает приложение. Интерфейсы API, требующие идентификации, работают немедленно. Это охватывает большинство сценариев разработки и тестирования.

Для консольных приложений , которым требуется stdin/stdout в текущем терминале, добавьте --with-alias:

winapp run .\build\Debug --with-alias

Сценарий Б. Присоединение отладчика к работающему приложению

Запустите с помощью winapp run, обратите внимание на PID, а затем подключите отладчик IDE.

winapp run .\build\Debug
# Output: Process ID: 12345

Затем в интегрированной среде разработки:

VS Code: запуск и отладка → выберите "Подключить" конфигурацию (см. инструкцию по настройке интегрированной среды разработки ниже)
WinDbg: windbg -p 12345

Ограничение: Вы пропустите любой код, который выполняется до того, как окончите подключение. Для отладки запуска используйте сценарий D (create-debug-identity).

Сценарий C. Регистрация идентификации, а затем запуск при помощи AUMID или псевдонима из вашей IDE

Используйте --no-launch для регистрации пакета, затем запустите приложение через его AUMID (указанный run) или псевдоним выполнения из вашей интегрированной среды разработки.

Шаг 1. Зарегистрируйте пакет без запуска:

winapp run .\build\Debug --no-launch

Шаг 2. Настройте интегрированную среду разработки для запуска с помощью AUMID или псевдонима выполнения (а не exe напрямую).

Запуск с помощью AUMID: используйте команду start shell:AppsFolder\<AUMID>. winapp run выводит AUMID при регистрации приложения.
Запуск с псевдонимом: псевдоним должен быть определен в манифесте (Package.appxmanifest предпочтительный, appxmanifest.xml также поддерживаемый).

Важно: Простое запуск файла exe в папке сборки не присвоит ему идентификацию. Приложение должно быть запущено с использованием активации AUMID или псевдонима его выполнения. Таким образом работают свободные пакеты макета — идентичность привязана к пути активации, а не к исполняемому файлу.

Сценарий D: Запуск из интегрированной среды разработки с идентификатором (отладка запуска)

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

winapp create-debug-identity .\build\Debug\myapp.exe

Теперь запустите exe так, как вам удобно — из терминала, нажав F5 в VS Code, из скрипта. Exe имеет идентификатор, так как Windows зарегистрировала разреженный пакет, указывающий непосредственно на него.

Как она отличается от winapp run: С create-debug-identity идентификация привязана к самому exe (через Add-AppxPackage -ExternalLocation). При этом winapp run идентификатор связан со свободным пакетом макета — приложение должно быть запущено с помощью AUMID или псевдонима. Это делает create-debug-identity лучший выбор, если вам нужна интегрированная среда разработки для запуска и отладки exe напрямую.

Это также лучший подход для приложений Electron , где путь exe отличается от исходного каталога.

Сценарий E. Захват выходных данных отладки и диагностики сбоев

Запись OutputDebugString сообщений и встроенных исключений первого шанса. Платформенный шум (WinUI, COM, DirectX (внутренние трассировки)) фильтруется из консоли, поэтому отображаются только отладочные сообщения вашего приложения. По-прежнему все записывается в файл журнала для полного анализа.

Если приложение завершится сбоем, минидамп записывается и анализируется автоматически.

winapp run .\build\Debug --debug-output

При сбое программы выходные данные включают тип исключения, сообщение и трассировку стека с исходным файлом и номерами строк (разрешены из PDB-файлов в выходной папке сборки). Управляемые (.NET) сбои анализируются в реальном времени без использования сторонних инструментов. Нативные сбои (C++/WinRT) отображают имена и смещения модулей; добавьте --symbols, чтобы скачать символы PDB для получения полных имен функций.

winapp run .\build\Debug --debug-output --symbols

Важно: Это прикрепляет winapp в качестве отладчика. Windows разрешает только один отладчик для каждого процесса, поэтому вы не можете одновременно присоединить Visual Studio, VS Code или WinDbg.

Настройка интегрированной среды разработки

VS Code

Расширение WinApp VS Code предоставляет пользовательский winapp тип отладки, который запускает приложение с удостоверением пакета и присоединяет отладчик — все из одного нажатия клавиши F5.

Отладка с помощью одного нажатия клавиши F5 с идентификацией

Добавьте конфигурацию запуска в winapp.vscode/launch.json:

{
    "version": "0.2.0",
    "configurations": [
        {
            "type": "winapp",
            "request": "launch",
            "name": "WinApp: Launch and Attach"
        }
    ]
}

При нажатии клавиши F5:

Расширение сканирует рабочую область в поиске каталогов выходных файлов сборки, содержащих файлы .exe.
Выберите папку сборки для запуска (или установите inputFolder, чтобы пропустить запрос).
Он запускает ваше приложение через winapp run, чтобы дать ему идентификатор пакета.
Дочерний сеанс отладки подключается к выполняемой процедуре с помощью указанного отладчика.

После подключения отладчика вы получите полный интерфейс отладки VS Code — установите точки останова, щелкнув по полю, шагайте по строке кода (F10), входите в функции (F11), проверяйте переменные в области Переменные и оцените выражения в Консоли отладки. Приложение выполняется с удостоверением пакета во всем, поэтому API-интерфейсы, зависящие от удостоверений, ведут себя точно так же, как и в рабочей среде.

Важно: Тип winapp отладки не создает проект автоматически. После внесения изменений в код перестройте проект перед нажатием клавиши F5.

Автоматизация сборок с помощью `preLaunchTask`

Чтобы избежать забывания перестроения, добавьте preLaunchTask, который собирает ваш проект перед каждым сеансом отладки.

Определите задачу сборки в .vscode/tasks.json (например, .NET):

{
    "version": "2.0.0",
    "tasks": [
        {
            "label": "build",
            "command": "dotnet",
            "type": "process",
            "args": ["build", "${workspaceFolder}"],
            "problemMatcher": "$msCompile"
        }
    ]
}

Ссылайтесь на него в вашей launch.json:

{
    "type": "winapp",
    "request": "launch",
    "name": "WinApp: Launch and Attach",
    "preLaunchTask": "build"
}

Свойства конфигурации

Недвижимость	Тип	По умолчанию	Description
`inputFolder`	string		Путь к выходной папке сборки, содержащей двоичные файлы приложения (например, `${workspaceFolder}/bin/Debug/net8.0-windows10.0.22621`). Если этот параметр не задан, вам будет предложено выбрать папку.
`manifest`	string		Путь к файлу манифеста AppX (например, `AppxManifest.xml`, `Package.appxmanifest` или `appxmanifest.xml`). Если параметр не задан, интерфейс командной строки автоматически определяет входную папку или текущий каталог.
`debuggerType`	string	`coreclr`	Базовый отладчик для использования (`coreclr`, `cppvsdbg`или `node`).
`workingDirectory`	string	Папка рабочей области	Рабочий каталог для приложения.
`args`	string		Аргументы командной строки для передачи в приложение.
`outputAppxDirectory`	string		Выходной каталог для пакета свободной компоновки. По умолчанию используется папка `AppX`, находящаяся внутри входной папки.
`port`	Номер	`9229`	(`node` только) Порт, используемый для прослушивателя Node.js `--inspect` и для установки соединения. Переопределите, если порт по умолчанию уже занят.

Поддерживаемые отладчики

`debuggerType`	Language	Обязательное расширение
`coreclr` (по умолчанию)	C# / .NET	Комплект средств разработки на C#
`cppvsdbg`	C/ C++	C/C++
`node`	Node.js / Electron	Built-in

Пример для проекта C++:

{
    "type": "winapp",
    "request": "launch",
    "name": "WinApp: Launch C++ App",
    "debuggerType": "cppvsdbg"
}

Запуск отладки с помощью создания удостоверения отладки

Если вам нужно отлаживать код запуска из самой первой инструкции, подход подключения F5 может пропустить ранний код. Вместо этого используйте команду WinApp: Создайте отладочное удостоверение из палитры команд (Ctrl+Shift+P) для регистрации разреженного пакета для исполняемого файла, а затем запустите его с помощью стандартного отладчика:

{
    "name": "Launch (with identity)",
    "type": "coreclr",
    "request": "launch",
    "program": "${workspaceFolder}/bin/Debug/net8.0-windows10.0.22621/myapp.exe"
}

Так как create-debug-identity регистрирует идентичность в самом exe-файле, приложение имеет идентичность независимо от того, как оно запускается, в том числе из стандартной конфигурации запуска VS Code.

Присоединение к запущенным процессам

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

{
    "name": "Attach to Process",
    "type": "coreclr",
    "request": "attach",
    "processId": "${command:pickProcess}"
}

Для C++/Rust используйте "type": "cppvsdbg" (MSVC) или "type": "lldb" (LLDB):

{
    "name": "Attach (C++)",
    "type": "cppvsdbg",
    "request": "attach",
    "processId": "${command:pickProcess}"
}

Очистка

После завершения тестирования выполните WinApp: отмена регистрации пакета из палитры команд, чтобы удалить загруженные пакеты разработки без выхода из VS Code.

Обратная связь

Были ли сведения на этой странице полезными?

Last updated on 2026-05-12