ejecución de Windows Sandbox

Compila en tu equipo y luego ejecuta y automatiza la aplicación en Windows Sandbox:

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

Sustituya MyApp por el nombre de su aplicación o por el PID del invitado mostrado por run. --detach devuelve después del inicio para que el siguiente comando pueda inspeccionar la aplicación; sin ella, run espera a que se cierre la aplicación. El espacio aislado permanece ejecutándose entre comandos y recompilaciones.

Antes de comenzar

  • Use Windows 11 24H2 o posterior en una edición compatible, con la virtualización de hardware habilitada.
  • Guest winapp admite x64 y Arm64. Una aplicación x86 requiere compatibilidad de invitado para ejecutarla y hacer coincidir dependencias x86; Un entorno de ejecución x64 no satisface una aplicación x86.
  • Mantenga desbloqueada la sesión del anfitrión para permitir la entrada directa y la captura de pantalla.

Habilitar Espacio aislado de Windows en Activar o desactivar las características de Windows, o ejecutar esto desde un terminal con privilegios de administrador:

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

Guarde el trabajo y reinicie Windows cuando esté listo. A continuación, abra Windows Sandbox desde el menú Inicio y complete cualquier instalación o actualización del cliente. winapp no habilita la característica, instala el cliente, solicita elevación o reinicia Windows. Si faltan requisitos previos, el proceso se detiene mostrando instrucciones de configuración; además, se notifica por separado si se detecta un reinicio de Windows pendiente.

Una conexión fría o una reconexión pueden centrarse brevemente. Una vez conectado, winapp mantiene su propia ventana de cliente fuera de pantalla sin activarla. Se mantiene la ventana del entorno aislado que usted mismo abrió.

Importante

Las compilaciones siguen ejecutándose en tu equipo. La evaluación del proyecto, la restauración y la compilación no están aisladas. --on sandbox no convierte un proyecto no confiable en seguro de compilar.

Un sandbox es un entorno compartido. Las aplicaciones y los flujos de trabajo que contiene comparten el usuario, el escritorio, el registro, los paquetes, los entornos de ejecución y el acceso a la red. Pueden observar o interferir entre sí. Use máquinas independientes para flujos de trabajo que no son de confianza mutua.

Windows solo permite un entorno Sandbox a la vez. winapp reutiliza una instancia en ejecución, incluida la que abrió usted mismo. Al prepararlo se añaden las carpetas compartidas de arranque de winapp, el agente invitado, el Modo de desarrollador y una regla de entrada del firewall. winapp no detiene una instancia adoptada ni quita aplicaciones no relacionadas. No hay alternativa de respaldo silenciosa al host: un comando que solicita ejecutarse en Sandbox se ejecuta en él o falla.

Ejecución y recompilación

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

Las opciones de compilación como --configuration, --arch, --framework, --property, --no-buildy --no-restore se aplican en el host. El registro, el inicio y la depuración se realizan en el sistema invitado; la aplicación no está registrada en tu equipo.

Option Efecto en el entorno aislado
--detach Volver tras el inicio en lugar de esperar a salir
--no-launch Desplegar y registrar sin ejecutar
--clean Reinstalar esta implementación y borrar sus datos de aplicación
--unregister-on-exit Quitar este registro de paquete después de que se cierre la aplicación
--with-alias Iniciar su alias de ejecución como invitado con flujos redirigidos
--debug-output Redirigir la salida de depuración del sistema invitado; solo para aplicaciones empaquetadas

Las aplicaciones sin empaquetar inician su archivo ejecutable desde la carpeta implementada. No tienen ningún paquete que registrar. --debug-output se rechaza para las ejecuciones de espacio aislado sin empaquetar.

Volver a ejecutar transfiere archivos modificados y quita los archivos eliminados de la salida de compilación. Los datos de la aplicación se conservan a menos que solicite --clean. Un despliegue incompleto no se inicia; al reintentarlo, se reconstruye su copia invitada. Si los archivos de compilación cambian mientras winapp los prepara, finalice la compilación y vuelva a intentarlo.

Los comandos de interfaz de usuario activa solo notifican su resultado, sin repetir un mensaje de preparación de espacio aislado. El inicio del entorno aislado y la recuperación de la conexión siguen mostrando el progreso. Use --verbose para los intervalos de conexión y los detalles de diagnóstico; --quiet y --json suprima el progreso. Las ejecuciones JSON incluyen un identificador de proceso de invitado y un ámbito de destino:

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

Estos son campos adicionales en el resultado de la ejecución, no un documento independiente. Copie el valor completo UiTargetArgs al inspeccionar la aplicación: winapp ui inspect --on sandbox -a 4212. Vuelva a detectar los PID y los identificadores de ventana después de recrear el entorno aislado; pertenecen a esa generación del entorno aislado, no al anfitrión ni a un invitado futuro.

Aplicaciones desacopladas y el tiempo de vida del agente

Una aplicación desempaquetada independiente finaliza si el agente invitado se detiene, incluso durante la reparación del agente. Si desaparece entre comandos, vuelva a ejecutar con --detach y vuelva a detectar su destino de interfaz de usuario. Esperar a que se cierre la aplicación, en lugar de desvincularla, te permite observar su finalización; no hace que la aplicación sobreviva a la pérdida del agente. Las aplicaciones empaquetadas usan la activación de Windows en lugar del tiempo de vida del proceso del agente. Cerrar o reiniciar el entorno aislado cierra todas las aplicaciones que contiene.

Entornos de ejecución compartidos

winapp comprueba las dependencias del paquete de la aplicación, los requisitos de SDK de Aplicaciones para Windows y *.runtimeconfig.json antes de iniciarse. Usa las cachés del host o descarga los paquetes necesarios y, a continuación, instala los entornos de ejecución compatibles que falten en el invitado, no en tu máquina.

Los requisitos de paquete incluyen el publicador, la versión y la arquitectura. La selección del entorno de ejecución compartido de .NET respeta la directiva de avance y la arquitectura configuradas de la aplicación; no dé por hecho que cualquier entorno de ejecución más reciente de la misma versión principal funcionará.

Si no se puede admitir un marco, una configuración en tiempo de ejecución o una dependencia, el comando produce un error explícitamente antes de iniciar e identifica el requisito. Realice la acción asociada a ese error. Cuando sea compatible con el proyecto, publicar autocontenido elimina la necesidad del entorno de ejecución compartido correspondiente; no quita las dependencias de paquetes no relacionadas.

Automatización de la interfaz de usuario

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

Cada ui verbo acepta --on sandbox. Los nombres de aplicación, los PID, los identificadores de ventana y los selectores se resuelven dentro del invitado. Use -a/--app o -w/--window para comandos de destino de la aplicación; winapp no adivina la última aplicación iniciada. Si se omite --on sandbox , se selecciona el escritorio del host en su lugar.

La entrada de datos real y la grabación requieren un cliente de Sandbox que esté conectado y no minimizado. La inspección de solo lectura puede seguir funcionando cuando la entrada de datos no funciona. winapp puede restaurar su propio cliente minimizado sin activarlo; un cliente abierto manualmente debe restaurarlo usted. Si la entrada no está disponible después de volver a conectarse, el comando falla en lugar de afirmar que proporcionó la entrada. Use el comando de reconexión en el error y vuelva a intentarlo.

Usa winapp target snapshot sandbox --json para comprobar si el escritorio está listo sin iniciar Sandbox ni volver a conectarlo. Las ventanas de error del terminal reconocidas no se consideran escritorios remotos. Si winapp no puede verificar el escritorio seleccionado porque todavía se está conectando o no se puede inspeccionar, la preparación sigue sin estar disponible; espere y vuelva a intentarlo. Varios escritorios remotos todavía pueden ser ambiguos. La instantánea no cierra ventanas ni resuelve sus errores por usted.

Consulte Automatización de la interfaz de usuario para selectores, métodos de entrada y aserciones.

Coordinación de flujos de trabajo de interfaz de usuario en el espacio aislado

Use un WINAPP_UI_WORKFLOW_ID para los comandos que cooperan y un valor distinto para cada flujo de trabajo independiente. Establézcalo en cada invocación, especialmente cuando el agente inicie un shell nuevo para cada llamada de herramienta. winapp reenvía una identidad hasheada específica de la generación del entorno aislado; el valor bruto del host no se envía al sistema invitado.

Por ejemplo, registre e interactúe en dos terminales con el mismo valor. Elija un nuevo valor para cada nuevo flujo de trabajo.

Terminal 1:

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

Terminal 2, mientras se ejecuta la grabación:

$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

Una vez finalizada la grabación y las acciones:

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

Un flujo de trabajo con nombre conserva su turno de interfaz de usuario durante cuatro segundos después de su último comando; yield lo libera inmediatamente. Sin un ID, cada comando libera su turno al finalizar. Por lo tanto, una grabación sin identificador bloquea otros flujos de trabajo que cambian el escritorio durante toda su duración. La comprobación en modo de solo lectura no espera. Los turnos de interfaz de usuario host e invitado son independientes.

Después de una pausa, inspeccione de nuevo y vuelva a abrir cualquier menú o cuadro de diálogo que necesite: es posible que otro flujo de trabajo haya usado el escritorio invitado. Los turnos cooperativos no aíslan las aplicaciones entre sí.

Capturas de pantalla y grabaciones

Use ui para capturar la ventana de una aplicación, o target para capturar todo el escritorio nativo del sistema invitado, incluidos el shell y los cuadros de diálogo del instalador:

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

Las salidas se envían al host, incluso cuando se omite -o. Las capturas de pantalla se guardan de forma predeterminada en screenshot.png; las grabaciones usan recording-<timestamp>-<guid>.mp4. Para las grabaciones, --frames también entrega el <output-name>.frames directorio que contiene JPEG, frames.ndjsony manifest.json. Rutas de acceso de host del informe de resultados. Las grabaciones de destino se ejecutan en el invitado; sus archivos host estarán disponibles después de que finalice la grabación y se complete la entrega.

target screenshot espera el turno de interfaz de usuario del invitado sin activar ninguna ventana. Excluye la barra de título y los bordes de la ventana Sandbox del host. Su PNG no se escala: con el origen (0,0)de la pantalla invitada, las coordenadas de imagen se pueden usar directamente mediante verbos de entrada de coordenadas como ui drag o ui touch --at, con --on sandbox. Agregue el origen notificado para un escritorio con un origen negativo. Use --json para leer coordinates.sourceBounds y coordinates.contentRect; ambos usan píxeles físicos y bordes derecho/inferior exclusivos.

Las grabaciones de destino notifican los mismos campos en JSON y el manifiesto de marco. Los fotogramas MP4 y JPEG comparten la misma asignación, incluido el escalado --max-edge y el relleno del codificador. Para mapear el píxel de la imagen (x,y), primero descarte los puntos fuera de contentRect, y, a continuación, calcule cada coordenada de origen como sourceStart + floor((pixel - contentStart + 0.5) * sourceSize / contentSize). El escalado descendente pierde precisión; use un PNG nativo cuando las coordenadas exactas sean importantes. Un cambio en los límites del escritorio invitado detiene la grabación con display_changed, conservando solo los fotogramas antes del cambio y marcando el manifiesto de marco parcial.

De forma predeterminada, se rechaza un directorio MP4 o emparejado .frames existente. Use una nueva ruta de acceso o indique --overwrite para reemplazarlas cuando termine la nueva toma. Los conjuntos de fotogramas anteriores se conservan como <output-name>.frames.previous-<id>, incluido cuando el reemplazo omite --frames. Una captura con error deja intacta la grabación antigua.

Prefiera un --duration-sec positivo para scripts y agentes. Las utilidades npm targetRecord y uiRecord requieren durationSec; su señal de abortado cancela de forma forzada, no como una parada ordenada. Consulte ui record para ver los valores admitidos. Si no se especifica una duración en la CLI, la grabación espera una señal de parada.

Pulsar Ctrl+C después de iniciar la captura puede finalizar la grabación y devolverla correctamente con stopReason: cancelled. Otras interrupciones pueden conservar fotogramas o vídeos útiles. Lea stopReason, partialOutput y recoveryHint cuando estén presentes, y use las rutas de evidencia notificadas en lugar de asumir una finalización normal. Si la captura del escritorio completo deja de estar disponible durante una grabación, se detiene con capture_unavailable en lugar de seguir capturando un escritorio que ya no está disponible. No trae la sandbox al primer plano para rescatar un fotograma. La captura puede producir un error antes de que haya disponible cualquier evidencia utilizable.

En el caso de una grabación de invitado con errores, la evidencia recuperada se coloca en un directorio único <output>.partial-<id> en el host. Si se produce un error en la entrega, los archivos recibidos permanecen en la ruta de recuperación notificada, como <output>.recovery-<id>, y los originales invitados se conservan. Mantenga el entorno aislado en ejecución y siga la acción de recuperación indicada para el error antes de volver a intentarlo o cerrarlo. Un archivo parcial conservado no es necesariamente un vídeo reproducible.

Las capturas de pantalla y el vídeo pueden contener información confidencial. Manipule el directorio de fotogramas con el mismo cuidado que el archivo MP4. Consulte ui record para ver las opciones de grabación y los campos de resultados.

Inspección del entorno aislado

winapp target snapshot sandbox
winapp target snapshot sandbox --json

Esto informa sobre el estado de preparación, las implementaciones actuales y las ventanas del sistema invitado sin crear una máquina virtual, volver a conectar el cliente ni reparar el agente. Si no hay ninguna Sandbox en ejecución, informa de ello y finaliza correctamente. Para iniciar una, use winapp run . --on sandbox --detach.

El informe distingue lo que admite el invitado de lo que puede hacer el cliente actual; Un cliente minimizado puede impedir la entrada o captura incluso cuando el invitado admite ambos. Utilice la lista de ventanas invitadas para los PID de la interfaz de usuario, no el proceso iniciador supervisado por una implementación. El campo JSON workRoot (que se muestra como Work root en la salida de texto) es la base absoluta para las rutas de acceso relativas de transferencia de archivos, normalmente C:\WinApp\work. Es independiente de capabilities.managedRoot, normalmente C:\WinApp, y se omite cuando el invitado no notifica su raíz administrada. Si varias ventanas de cliente impiden una captura inequívoca, el error enumera candidatos; decida qué cerrar antes de volver a intentarlo.

Ejecución de comandos y copia de archivos

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

Se usa target exec para la configuración y el diagnóstico. Se ejecuta como usuario invitado, reenvía secuencias estándar y devuelve el código de salida del comando. No es un terminal interactivo completo; Las aplicaciones de consola ven canalizaciones redirigidas. --json da formato a los errores de winapp, no al stdout del comando secundario.

Para push y pull, las rutas de acceso de destino son relativas a las workRoot notificadas por target snapshot. Se rechazan las rutas de acceso de destino absolutas, rootadas y UNC. Un solo archivo llega exactamente al destino que especifiques; un directorio conserva su estructura dentro de ese destino. Use la ruta resuelta del invitado que se muestra después de un push (JSON targetPath) para elegir el --cwd del siguiente comando; para un solo archivo, use su directorio padre. Si el sistema invitado no informa de su raíz gestionada, la operación de inserción falla antes de la copia; siga las indicaciones de actualización del error en lugar de asumir una ruta predeterminada.

Ejecute solo los scripts de instalación de confianza. En el ejemplo se usa -ExecutionPolicy Bypass con ámbito de proceso porque una sandbox recién creada normalmente rechaza los scripts debido a su política Restricted.

Las transferencias omiten los archivos sin cambios y comprueban los reemplazos antes de publicarlos. No se siguen los vínculos simbólicos y las uniones: la implementación los rechaza, mientras que las copias de directorio omiten las entradas vinculadas. Se rechaza un origen vinculado nombrado directamente o una ruta de acceso de destino mediante un vínculo. Copie los archivos o directorios reales en su lugar.

Quitar una app y finalizar Sandbox

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

Con un manifiesto en el directorio actual, puede omitir --manifest. Esto elimina solo el paquete de desarrollo correspondiente registrado por winapp en el entorno aislado actual. Un paquete instalado externamente se deja solo, incluso si su identidad coincide. --force no es compatible con --on; no puede eludir las comprobaciones de propiedad. Se trata de una limpieza de paquetes basada en el manifiesto, no de un comando para anular el registro de aplicaciones no empaquetadas ni de una entrada .cs.

El entorno aislado sigue ejecutándose. Administre su ciclo de vida con la propia CLI de Windows Sandbox:

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

Al detenerlo, se descartan el invitado y su trabajo. Guarde primero la evidencia necesaria y obtenga el consentimiento del usuario antes de detener una instancia que pueda usar. Los comandos winapp posteriores pueden crear un espacio aislado nuevo; redescubrir todos los destinos de la aplicación después.

Solución de problemas

Siga el mensaje de error userAction; un aviso informativo nextCommand es una sugerencia, no es un permiso para hacerlo automáticamente. En la automatización, inspeccione la estructura error.code. Los fallos de infraestructura pueden salir con 70, pero cualquier aplicación también puede devolver 70; el código de salida numérico por sí solo no permite distinguirlos.

Los comandos de recuperación sugeridos por las operaciones de interfaz de usuario enrutadas conservan --on <target>, por lo que copiar una sugerencia lo mantiene en el mismo destino de ejecución.

Error o síntoma Qué hacer
sandbox_unsupported Compruebe la edición o la versión de Windows y la virtualización del firmware
sandbox_setup_required Habilitar Espacio aislado de Windows siguiendo las instrucciones anteriores y después reiniciar cuando esté listo.
sandbox_setup_requires_restart Windows notifica un reinicio pendiente; guarde el trabajo y reinicie cuando esté listo y vuelva a intentarlo.
sandbox_setup_incomplete Abrir Windows Sandbox desde el menú Inicio y completar la instalación o actualización del cliente; después, volver a intentarlo.
sandbox_unmanaged_instance, sandbox_target_ambiguous Inspeccione las instancias o ventanas notificadas; no detenga tareas no relacionadas para resolver la ambigüedad
sandbox_input_not_ready, sandbox_no_interactive_session Restaure el cliente existente o vuelva a conectarse como se indica y vuelva a intentarlo.
sandbox_agent_incompatible Atienda el error de versión; actualice la CLI instalada usando el método con el que se instaló, si se le solicita; después, cierre o vuelva a intentarlo solo con autorización.
sandbox_agent_busy Espere a que finalice otro comando y vuelva a intentarlo.
sandbox_terminated, , sandbox_target_stale, sandbox_stale_handle Volver a ejecutar la aplicación y redescubrir los PIDs o ventanas invitados
sandbox_state_unavailable Asegúrese de que %USERPROFILE%\.winapp\state tenga permisos de escritura o corrija WINAPP_TARGET_STATE_ROOT si está establecido
sandbox_deployment_dirty, sandbox_transfer_interrupted Reintentar la implementación o transferencia
sandbox_runtime_provision_failed Solucione la dependencia con nombre o la configuración de tiempo de ejecución no compatible; consulte Entornos de ejecución compartidos
sandbox_package_conflict, sandbox_provisioned_package_conflict Siga la acción específica del paquete; no quitar paquetes de bandeja de entrada o no relacionados
sandbox_artifact_failed Compruebe la salida registrada y la preparación del cliente; conserve cualquier evidencia parcial
target_invalid, target_invalid_arguments Corregir el destino o las opciones que se muestran en el error

winapp update actualiza las dependencias del SDK del proyecto, no la CLI instalada. No es una solución para la incompatibilidad entre la CLI del anfitrión y la del invitado.

Destinos para compartir en el entorno aislado de la compilación 28000

El entorno aislado (Sandbox) de la compilación 28000 probada no puede enumerar los destinos para compartir. Pruebe otras funciones de la aplicación en Sandbox, pero valide los flujos de Compartir de origen a destino fuera de este entorno.

Consulte también

  • Last updated on