Запуск песочницы Windows

Выполните сборку на вашем компьютере, а затем запустите и автоматизируйте приложение в Windows Sandbox:

winapp run . --on sandbox --detach
winapp ui inspect --on sandbox -a MyApp
winapp ui invoke --on sandbox SubmitButton -a MyApp

Замените MyApp именем приложения или гостевым PID, напечатанным run. --detach возвращается после запуска, чтобы следующая команда может проверить приложение; без него run ожидает завершения работы приложения. Песочница остается запущенной между командами и пересборками.

Перед началом работы

• Используйте Windows 11 24H2 или более поздней версии в поддерживаемом выпуске с включенной виртуализацией оборудования.
• Гостевое приложение WinApp поддерживает x64 и ARM64. Приложению x86 требуется гостевая поддержка запуска и сопоставления зависимостей x86; Среда выполнения x64 не удовлетворяет приложению x86.
• Оставьте сеанс на хосте разблокированным для непосредственного ввода и захвата экрана.

Включите Песочница Windows в разделе Включение или отключение компонентов Windows или выполните эту команду в терминале с правами администратора:

dism.exe /Online /Enable-Feature /FeatureName:Containers-DisposableClientVM /All /NoRestart

Сохраните работу и перезапустите Windows при готовности. Затем откройте Windows песочницу из меню "Пуск" и завершите установку или обновление клиента. winapp не включает эту функцию, не устанавливает клиент, не запрашивает повышение прав и не перезапускает Windows. Если необходимые компоненты отсутствуют, выполнение прерывается с инструкциями по установке; о наличии ожидающего перезапуска Windows сообщается отдельно.

Холодное подключение или повторное подключение могут ненадолго перехватить фокус. После подключения winapp сохраняет собственное окно клиента вне экрана, не активируя его. Окно песочницы, открытое вами, осталось на месте.

Important

Сборки по-прежнему выполняются на вашем компьютере. Оценка проекта, восстановление и компиляция не являются изолированными процессами. --on sandbox не делает ненадежный проект безопасным для сборки.

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

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

Запуск и пересборка

winapp run .\MyApp.csproj --on sandbox --detach --json
winapp run .\publish --on sandbox --detach
winapp run . --on sandbox --clean --detach

Параметры сборки, такие как --configuration, --arch, --framework, --property, --no-build и --no-restore, действуют на хосте. Регистрация, запуск и отладка происходят в гостевом приложении; Приложение не зарегистрировано на компьютере.

Опция	Эффект в песочнице
--detach	Возврат после запуска, а не ожидание выхода
--no-launch	Развертывание и регистрация без запуска
--clean	Переустановите это развертывание и очистите данные приложения
--unregister-on-exit	Удалить регистрацию этого пакета после завершения работы приложения
--with-alias	Запуск псевдонима гостевого выполнения с перенаправленными потоками
--debug-output	Передача выходных данных отладки гостевой системы; только для упакованных приложений

Распакованные приложения запускают исполняемый файл из развернутой папки. У них нет пакета для регистрации. --debug-output не поддерживается для запусков Sandbox без упаковки.

Повторное выполнение передает измененные файлы и удаляет файлы, удаленные из выходных данных сборки. Данные приложения сохраняются, если вы не запрашиваете --clean. Неполное развертывание не запускается; при повторной попытке его гостевая копия пересоздаётся. Если файлы сборки изменяются, пока winapp их подготавливает, завершите сборку и повторите попытку.

Команды теплого пользовательского интерфейса сообщают только о результатах, не повторяя сообщение о подготовке песочницы. Запуск песочницы и восстановление подключения по-прежнему отображают ход выполнения. Используется --verbose для времени подключения и диагностических сведений; --quiet и --json отключает ход выполнения. Запуски JSON включают идентификатор гостевого процесса и целевую область:

{
  "ProcessId": 4212,
  "Sandbox": true,
  "ProcessScope": "sandbox",
  "UiTargetArgs": "--on sandbox -a 4212",
  "ExecutionTarget": {
    "Kind": "sandbox",
    "Id": "default",
    "Architecture": "arm64",
    "Epoch": "..."
  }
}

Это дополнительные поля в результате выполнения, а не отдельный документ. Скопируйте все UiTargetArgs значение при проверке приложения: winapp ui inspect --on sandbox -a 4212 Заново определяйте PID и дескрипторы окон после повторного создания песочницы; они относятся к этому поколению песочницы, а не к хосту или будущей гостевой системе.

Автономные приложения и время жизни агента

Автономное неупакованное приложение завершает работу, если гостевой агент останавливается, в том числе во время восстановления агента. Если он исчезает между командами, запустите команду повторно с --detach и заново определите его целевой элемент интерфейса. Ожидание приложения вместо отсоединения позволяет наблюдать за его завершением; это не позволяет приложению пережить потерю агента. Упакованные приложения используют активацию Windows, а не время существования процесса агента. Закрытие или перезапуск песочницы завершает работу всех приложений в ней.

Общие среды выполнения

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

Требования к пакету включают издателя, версию и архитектуру. Выбор общей среды выполнения .NET учитывает настроенную для приложения политику переноса вперёд и его архитектуру; не следует предполагать, что любая более новая среда выполнения в рамках той же основной версии будет работать.

Если платформа, конфигурация среды выполнения или зависимость не поддерживаются, команда завершается явной ошибкой перед запуском и определяет требование. Следуйте действию этой ошибки. Если ваш проект это поддерживает, публикация автономного приложения устраняет необходимость в соответствующей общей среде выполнения; но не устраняет несвязанные зависимости пакетов.

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

winapp ui list-windows --on sandbox
winapp ui inspect --on sandbox -a MyApp
winapp ui invoke --on sandbox SubmitButton -a MyApp
winapp ui screenshot --on sandbox -a MyApp -o .\result.png

Каждый ui глагол принимает --on sandbox. Имена приложений, идентификаторы процессов (PID), дескрипторы окон и селекторы определяются в гостевой системе. Используйте -a/--app или -w/--window для команд, предназначенных для приложений; winapp не угадывает последнее запущенное приложение. Если не указывать --on sandbox, будет выбран рабочий стол хост-системы.

Для реальных входных данных и записи требуется подключенный, неминимизированный клиент песочницы. Просмотр в режиме только чтения всё равно может работать, даже если ввод недоступен. winapp может восстановить собственный свернутый клиент без активации; Свернутый вручную открытый клиент должен быть восстановлен вами. Если после повторного подключения ввод недоступен, команда завершается ошибкой, вместо того чтобы сообщать, что ввод был передан. Используйте команду повторного подключения в ошибке и повторите попытку.

Используйте winapp target snapshot sandbox --json для проверки готовности к рабочему столу без запуска или повторного подключения песочницы. Распознанные окна ошибок терминала не считаются удаленными рабочими столами. Если winapp не может проверить выбранный рабочий стол, так как он по-прежнему подключается или не может быть проверен, готовность остается недоступной; подождите и повторите попытку. Несколько удалённых рабочих столов по-прежнему могут вызывать неоднозначность. Снимок не закрывает окна и не устраняет связанные с ними ошибки за вас.

См. сведения об автоматизации пользовательского интерфейса для селекторов, методов ввода и утверждений.

Координирование UI-процессов в Sandbox

Используйте один WINAPP_UI_WORKFLOW_ID для взаимосвязанных команд и отдельное значение для каждого независимого рабочего процесса. Устанавливайте это при каждом вызове, особенно если агент запускает новый экземпляр оболочки при каждом вызове инструмента. winapp перенаправляет хешированный идентификатор, специфичный для поколения Sandbox; исходное значение хоста не отправляется в гостевую систему.

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

Терминал 1.

$env:WINAPP_UI_WORKFLOW_ID = 'myapp-checkout-01'
winapp ui record --on sandbox -a MyApp --duration-sec 20 --frames -o .\checkout.mp4

Терминал 2, пока запись выполняется:

$env:WINAPP_UI_WORKFLOW_ID = 'myapp-checkout-01'
winapp ui invoke --on sandbox SubmitButton -a MyApp
$env:WINAPP_UI_WORKFLOW_ID = 'myapp-checkout-01'
winapp ui inspect --on sandbox -a MyApp

Завершив запись и действия, выполните следующие действия:

$env:WINAPP_UI_WORKFLOW_ID = 'myapp-checkout-01'
winapp ui yield --on sandbox

Именованный рабочий процесс сохраняет свою очередь пользовательского интерфейса в течение четырех секунд после последней команды; yield немедленно освобождает его. Без идентификатора каждая команда освобождает очередь после завершения. Таким образом, запись no-ID блокирует на всё время её выполнения другие процессы, изменяющие рабочий стол. Проверка в режиме «только чтение» выполняется без ожидания. Этапы интерфейса пользователя хоста и гостевой системы разделены.

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

Снимки экрана и записи

Используйте ui захват для окна приложения или target захват для всего собственного гостевого рабочего стола, включая диалоги оболочки и установщика:

winapp ui record --on sandbox -a MyApp --duration-sec 10 --frames -o .\app.mp4
winapp target screenshot sandbox -o .\sandbox.png
winapp target record sandbox --duration-sec 20 --frames -o .\sandbox.mp4

Выходные данные попадают на хост, в том числе если опустить -o. Для снимков экрана по умолчанию используется screenshot.png; для записей — recording-<timestamp>-<guid>.mp4. Для записей <output-name>.frames также предоставляет каталог --frames, содержащий файлы JPEG, frames.ndjson и manifest.json. Пути узла отчета результатов. Записи цели выполняются в гостевой системе; их файлы на хосте становятся доступными после завершения записи и доставки.

target screenshot ожидает очереди интерфейса гостевой системы, не активируя ни одно окно. Исключаются строка заголовка и границы окна песочницы хоста. Его PNG-изображение не масштабируется: при начале координат гостевого экрана (0,0) координаты изображения можно использовать напрямую в командах, принимающих координаты, таких как ui drag или ui touch --at, вместе с --on sandbox. Добавьте сообщаемый источник для рабочего стола с отрицательным источником. Используйте --json, чтобы прочитать coordinates.sourceBounds и coordinates.contentRect; оба используют физические пиксели и исключительные правую и нижнюю границы.

Целевые записи содержат одинаковые поля в JSON и в манифесте фрейма. Кадры MP4 и JPEG используют одно и то же сопоставление, включая масштабирование --max-edge и отступы кодировщика. Чтобы сопоставить пиксель изображения (x,y), сначала отклоните точки вне contentRect, а затем вычислите каждую исходную координату как sourceStart + floor((pixel - contentStart + 0.5) * sourceSize / contentSize). Уменьшение изображения приводит к потере точности; используйте PNG исходного размера, если важны точные координаты. Изменение границ рабочего стола гостевой системы останавливает запись с display_changed, сохраняя только кадры, записанные до этого изменения, и помечая манифест кадров как неполный.

Существующий каталог MP4 или парный .frames каталог отклоняется по умолчанию. Используйте новый путь или передайте --overwrite их, чтобы заменить их после завершения нового выполнения. Предыдущие пакеты кадров сохраняются как <output-name>.frames.previous-<id>, в том числе когда при замене пропускается --frames. Сбой записи оставляет старую запись нетронутой.

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

Ctrl+C после начала записи может успешно завершить её и вернуть запись с помощью stopReason: cancelled. Другие прерывания могут сохранять полезные видео или кадры. Учитывайте stopReason, partialOutput и recoveryHint, если они присутствуют, и используйте указанные пути к доказательствам вместо того, чтобы предполагать штатное завершение. Если захват всего рабочего стола становится недоступным во время записи, захват останавливается с capture_unavailable вместо того, чтобы продолжать захватывать недоступный рабочий стол. Не выводит Песочницу на передний план, чтобы восстановить кадр. Захват может завершиться неудачей до появления каких-либо пригодных доказательств.

Если запись гостевой системы завершилась сбоем, восстановленные данные помещаются в уникальный каталог <output>.partial-<id> на хосте. Если доставка завершается ошибкой, полученные файлы остаются по указанному пути восстановления, например <output>.recovery-<id>, а исходные файлы гостевой ОС сохраняются. Не закрывайте Sandbox и выполните действие по восстановлению, указанное в сообщении об ошибке, прежде чем повторить попытку или закрыть его. Сохраненный частичный файл не обязательно является воспроизводимым видео.

Снимки экрана и видео могут содержать конфиденциальную информацию. Обрабатывайте каталог кадров с той же тщательностью, как и MP4-файл. См. ui record для получения сведений о параметрах записи и полях результатов.

Проверка песочницы

winapp target snapshot sandbox
winapp target snapshot sandbox --json

Это сообщает о готовности, текущих развертываниях и гостевых окнах без создания виртуальной машины, повторного подключения клиента или восстановления агента. Если Sandbox не запущена, об этом сообщается, и работа успешно завершается. Чтобы запустить его, используйте winapp run . --on sandbox --detach.

В отчете проводится различие между тем, что поддерживает гостевая система, и тем, что может текущий клиент; свернутый клиент может предотвращать ввод или захват, даже если гостевая система поддерживает и то и другое. Используйте список гостевых окон для идентификаторов пользовательского интерфейса, а не для отслеживаемого процесса запуска развертывания. Поле JSON workRoot (как показано Work root в текстовом выводе) является абсолютной базой для относительных путей передачи файлов, как правило C:\WinApp\work. Он отделяется от capabilities.managedRoot, обычно C:\WinApp, и не указывается, если гостевая система не сообщает свой управляемый корневой каталог. Если несколько окон клиента не позволяют однозначно выполнить захват, в сообщении об ошибке перечисляются возможные варианты; решите, что следует закрыть, прежде чем повторить попытку.

Выполнение команд и копирование файлов

winapp target exec sandbox -- dotnet --info
$copy = winapp target push sandbox .\setup.ps1 Setup\setup.ps1 --json | ConvertFrom-Json
winapp target exec sandbox --cwd (Split-Path -Parent $copy.targetPath) -- powershell -ExecutionPolicy Bypass -File .\setup.ps1
winapp target pull sandbox Results .\results

Используйте target exec для настройки и диагностики. Он выполняется от имени гостевого пользователя, пересылает стандартные потоки и возвращает код выхода команды. Это не полноценный интерактивный терминал; консольные приложения получают доступ к перенаправленным потокам. --json форматирует ошибки winapp, а не stdout дочерней команды.

Для push и pull, целевые пути указываются относительно workRoot, о котором сообщает target snapshot. Абсолютные пути, пути с корнем и целевые UNC-пути не допускаются. Отдельный файл попадает точно в указанное вами место назначения; каталог сохраняет свою структуру внутри него. Используйте разрешенный гостевой путь, напечатанный после отправки (JSON targetPath), чтобы выбрать следующую команду --cwd; для одного файла используйте родительский каталог. Если гость не сообщает об управляемом корневом каталоге, push-отправка завершается сбоем перед копированием; следуйте инструкциям по обновлению ошибки, а не предполагайте путь по умолчанию.

Запускайте только те сценарии установки, которым вы доверяете. В примере используется пространство имён -ExecutionPolicy Bypass уровня процесса, поскольку новая песочница обычно не разрешает выполнение сценариев в соответствии со своей политикой Restricted.

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

Удаление приложения и завершение песочницы

winapp unregister --on sandbox --manifest .\Package.appxmanifest

С помощью манифеста в текущем каталоге можно опустить --manifest. Это удаляет только соответствующий пакет разработки, зарегистрированный приложением winapp в текущей изолированной среде. Пакет, установленный извне, не затрагивается, даже если его идентификатор совпадает. --force не поддерживается при использовании с --on; он не может обойти проверки права собственности. Это очистка пакетов по манифесту, а не команда отмены регистрации для неупакованных приложений или входных данных .cs.

Песочница остается запущенной. Управляйте жизненным циклом Windows Sandbox с помощью её собственной командной строки:

wsb list
wsb connect --id <id>
wsb stop --id <id>

При остановке гостевая система и результаты её работы будут потеряны. Сначала сохраните необходимые доказательства и получите согласие пользователя, прежде чем останавливать экземпляр, которым он может пользоваться. Последующие команды winapp могут создать новую песочницу; после этого заново обнаружьте все целевые элементы приложения.

Troubleshooting

Следуйте указаниям ошибки userAction; предупреждение nextCommand носит рекомендательный характер, а не является разрешением на автоматический запуск. В автоматизации проверьте структурированный error.code. Сбои инфраструктуры могут приводить к завершению с кодом 70, но любое приложение также может возвращать код 70; сам по себе числовой код завершения не позволяет различить эти случаи.

Команды восстановления, предлагаемые операциями маршрутизированного интерфейса, сохраняют --on <target>, поэтому при копировании такой подсказки она остаётся для той же цели выполнения.

Ошибка или симптом	Что делать
sandbox_unsupported	Проверка Windows выпусков и версий и виртуализации встроенного ПО
sandbox_setup_required	Включите песочницу Windows с помощью приведенных выше инструкций, а затем перезапустите после готовности
sandbox_setup_requires_restart	Windows сообщает о ожидающей перезагрузке; сохраните работу и перезапустите после готовности, а затем повторите попытку
sandbox_setup_incomplete	Откройте песочницу Windows на начальном экране и завершите настройку и обновление клиента, а затем повторите попытку
sandbox_unmanaged_instance, sandbox_target_ambiguous	Проверьте указанные экземпляры/окна; не прерывайте работу, не связанную с устранением неоднозначности
sandbox_input_not_ready, sandbox_no_interactive_session	Восстановите существующего клиента или переподключитесь в соответствии с инструкциями, затем повторите попытку
sandbox_agent_incompatible	Следуйте указаниям в сообщении об ошибке о версии; при необходимости обновите установленный CLI тем же способом, которым он был установлен, затем закрывайте или повторяйте попытку только с согласия пользователя
sandbox_agent_busy	Дождитесь завершения другой команды, а затем повторите попытку
sandbox_terminated, sandbox_target_stale, sandbox_stale_handle	Повторное запуск приложения и повторное обнаружение гостевых ИДЕНТИФИКАТОРов и окон
sandbox_state_unavailable	Убедитесь, что %USERPROFILE%\.winapp\state доступен для записи, или исправьте WINAPP_TARGET_STATE_ROOT, если он задан
sandbox_deployment_dirty, sandbox_transfer_interrupted	Повторите развертывание или передачу
sandbox_runtime_provision_failed	Устраните именованную зависимость или неподдерживаемую конфигурацию среды выполнения; см. Общие среды выполнения
sandbox_package_conflict, sandbox_provisioned_package_conflict	Следуйте действиям, зависящим от пакета; Не удаляйте не связанные пакеты или пакеты папки "Входящие"
sandbox_artifact_failed	Проверьте заявленный результат и готовность клиента; сохраните любые частичные подтверждения
target_invalid, target_invalid_arguments	Исправление целевого объекта или параметров, показанных в ошибке

winapp update обновляет зависимости SDK проекта, а не установленный CLI. Это не исправление несовместимости хост-интерфейса командной строки или гостевого интерфейса командной строки.

Предоставление общего доступа к целевым объектам в песочнице сборки 28000

Тестируемая сборка 28000 Sandbox не может перечислить целевые объекты общего доступа. Проверьте другие функции приложения в Sandbox, но сценарии Share от источника к получателю проверяйте вне нее.

См. также

• Синтаксис команд
• Автоматизация пользовательского интерфейса
• Отладка с идентификацией пакета
• Руководство по безопасности