Execução do Windows Sandbox

Constrói na tua máquina e depois executa e automatiza a aplicação no Windows Sandbox:

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

Substitua MyApp pelo nome da sua aplicação ou pelo PID de convidado impresso por run. --detach regressa após o lançamento para que o comando seguinte possa inspecionar a aplicação; sem ele, run espera que a aplicação saia. A Sandbox continua em execução entre comandos e recompilações.

Antes de começar

  • Use o Windows 11 24H2 ou mais recente numa edição suportada, com virtualização de hardware ativada.
  • Guest winapp suporta x64 e Arm64. Uma aplicação x86 requer suporte de convidados para a executar e corresponder dependências x86; um runtime x64 não satisfaz uma aplicação x86.
  • Mantém a sessão do anfitrião desbloqueada para input real e captura de ecrã.

Ative o Sandbox do Windows em Ativar ou desativar as funcionalidades do Windows, ou execute isto a partir de um terminal de administrador:

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

Guarda o teu trabalho e reinicia o Windows quando estiveres pronto. Depois abre o Sandbox do Windows no menu Iniciar e termina qualquer instalação ou atualização do cliente. O WinApp não ativa a funcionalidade, não instala o cliente, não solicita elevação nem reinicia o Windows. Se faltarem pré-requisitos, interrompe o processo com instruções de configuração; uma reinicialização pendente do Windows detetada é indicada separadamente.

Uma ligação fria ou reconexão pode ocupar brevemente o foco. Uma vez ligado, o winapp mantém a sua própria janela de cliente fora do ecrã sem a ativar. Uma janela de caixa de areia que tu próprio abriste está no lugar.

Importante

As compilações continuam a ser executadas na tua máquina. A avaliação, o restauro e a compilação do projeto não são isolados. --on sandbox não torna um projeto não confiável seguro para construir.

Um Sandbox é um ambiente partilhado. As aplicações e fluxos de trabalho dentro dele partilham o utilizador, ambiente de trabalho, registo, pacotes, runtimes e acesso à rede. Podem observar-se mutuamente ou interferir umas com as outras. Use máquinas separadas para fluxos de trabalho mutuamente não confiáveis.

O Windows permite um Sandbox de cada vez. o winapp reutiliza uma instância em execução, incluindo uma que tenha sido aberta por si. Ao prepará‑lo, adiciona as pastas partilhadas de inicialização do winapp, o agente convidado, o Modo de Programador e uma regra de entrada da firewall. O WinApp não impede uma instância adotada nem remove aplicações não relacionadas. Não existe recurso silencioso ao host: um comando que solicite o Sandbox é executado no Sandbox ou falha.

Funcionamento e reconstrução

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

Opções de compilação como --configuration, --arch, --framework, --property, --no-build e --no-restore aplicam-se ao anfitrião. O registo, o lançamento e a depuração ocorrem no sistema convidado; a aplicação não está registada na sua máquina.

Option Efeito no Sandbox
--detach Regresso após o lançamento em vez de esperar pela saída
--no-launch Instalar e registar sem iniciar
--clean Reinstale esta implementação e limpe os dados da aplicação
--unregister-on-exit Remova o registo deste pacote depois de a aplicação sair
--with-alias Lançar o seu alias de execução convidada com streams encaminhados
--debug-output Saída de depuração de convidados em stream; apenas aplicações empacotadas

As aplicações não empacotadas lançam o seu executável a partir da pasta implementada. Eles não têm nenhum pacote para registar. --debug-output é rejeitado para execuções de Sandbox sem empacotamento.

A reexecução transfere ficheiros alterados e remove ficheiros eliminados da saída da compilação. Os dados da aplicação são preservados, a menos que solicite --clean. Uma implantação incompleta não arranca; ao tentar novamente, a sua cópia do sistema convidado é reconstruída. Se os ficheiros de build mudarem enquanto o winapp os está a preparar, termina a build e tenta novamente.

Os comandos Warm UI reportam apenas o seu resultado, sem repetir uma mensagem de preparação Sandbox. O arranque da sandbox e a recuperação da ligação continuam a indicar progresso. Use --verbose para tempos de ligação e detalhes de diagnóstico; --quiet e --json suprima o progresso. As execuções em JSON incluem um ID do processo convidado e o âmbito de destino:

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

Estes são campos adicionais no resultado da execução, não um documento separado. Copie o valor completo UiTargetArgs ao inspecionar a aplicação: winapp ui inspect --on sandbox -a 4212. Redescobrir os PIDs e os identificadores de janelas depois de a sandbox ser recriada; pertencem a essa geração da sandbox, não ao anfitrião nem a um futuro convidado.

Aplicações desacopladas e o tempo de vida do agente

Uma aplicação autónoma não empacotada termina se o agente convidado parar, incluindo durante a respetiva reparação. Se desaparecer entre comandos, execute novamente com --detach e volte a detetar o elemento-alvo da IU. Esperar pela aplicação em vez de desligar permite-lhe observar a sua saída; isso não faz com que a aplicação sobreviva à perda de agente. As aplicações empacotadas usam a ativação do Windows em vez do tempo de vida do processo do agente. Fechar ou reiniciar o Sandbox termina todas as aplicações dentro dele.

Tempos de execução partilhados

O WinApp verifica as dependências dos pacotes da aplicação, os requisitos do SDK de Aplicações Windows e *.runtimeconfig.json antes do lançamento. Utiliza caches do anfitrião ou transfere os payloads necessários e, em seguida, instala os runtimes suportados em falta no convidado, não no seu computador.

Os requisitos do pacote incluem editora, versão e arquitetura. A seleção do runtime .NET partilhado respeita a política de roll-forward e a arquitetura configuradas para a aplicação; não presuma que qualquer runtime mais recente da mesma versão principal funcione.

Se uma estrutura, configuração em tempo de execução ou dependência não puder ser suportada, o comando falha explicitamente antes do lançamento e identifica o requisito. Segue a ação desse erro. Quando suportado pelo seu projeto, publicar conteúdo autónomo elimina a necessidade do tempo de execução partilhado correspondente; não remove dependências de pacotes não relacionados.

Automatização da interface de utilizador

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

Todos os verbos ui aceitam --on sandbox. Nomes de aplicações, PIDs, manípulos de janelas e seletores são resolvidos dentro do convidado. Use -a/--app ou -w/--window para comandos direcionados a apps; o winapp não adivinha qual foi a última app lançada. Omitir --on sandbox seleciona o ambiente de trabalho do anfitrião.

A entrada real e a gravação requerem um cliente Sandbox conectado e não minimizado. A inspeção em modo só de leitura pode continuar a funcionar mesmo quando a entrada não funciona. A WinApp pode restaurar o seu próprio cliente minimizado sem ativação; um cliente minimizado aberto manualmente deve ser restaurado por si. Se a entrada não estiver disponível após a reconexão, o comando falha em vez de afirmar que foi entregue a entrada. Usa o comando de reconexão no erro e tenta novamente.

Uso winapp target snapshot sandbox --json para verificar a prontidão do ambiente de trabalho sem iniciar ou religar o Sandbox. As janelas de erro do terminal reconhecidas não contam como áreas de trabalho remotas. Se o winapp não conseguir verificar o desktop selecionado porque ainda se está a ligar ou não pode ser inspecionado, o estado de preparação permanece indisponível; aguarde e tente novamente. Múltiplos desktops remotos ainda podem ser ambíguos. Snapshot não fecha janelas nem corrige os respetivos erros por si.

Consulte Automação de UI para seletores, métodos de entrada e asserções.

Coordenação dos fluxos de trabalho de UI no Sandbox

Use um WINAPP_UI_WORKFLOW_ID para comandos de cooperação e um valor diferente para cada fluxo de trabalho independente. Defina-o em cada invocação, especialmente quando o seu agente inicia uma nova shell para cada chamada de ferramenta. WinApp encaminha uma identidade hashada, específica da geração Sandbox; o valor bruto do host não é enviado ao convidado.

Por exemplo, gravar e interagir em dois terminais usando o mesmo valor. Escolha um novo valor para cada novo fluxo de trabalho.

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, enquanto a gravação está a decorrer:

$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

Depois de terminarem tanto a gravação como as ações:

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

Um fluxo de trabalho nomeado mantém a sua ativação da interface durante quatro segundos após o último comando; yield liberta-o imediatamente. Sem um ID, cada comando liberta a sua vez ao ser concluído. Uma gravação sem ID bloqueia, portanto, outros processos que alteram o ambiente de trabalho enquanto durar. A inspeção apenas de leitura não espera. Os turnos da interface do anfitrião e dos convidados são separados.

Após uma pausa, inspecione novamente e abra novamente qualquer menu ou diálogo que precise: outro fluxo de trabalho pode ter usado o ambiente de trabalho convidado. Os turnos cooperativos não isolam as aplicações umas das outras.

Capturas de ecrã e gravações

Utilize ui para capturar a janela de uma aplicação, ou target para capturar todo o ambiente de trabalho nativo do sistema convidado, incluindo o shell e as caixas de diálogo do 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

As saídas vão parar ao host, mesmo quando se omite -o. As capturas de ecrã são guardadas por defeito em screenshot.png; as gravações usam recording-<timestamp>-<guid>.mp4. Para gravações, --frames também fornece o <output-name>.frames diretório que contém JPEGs, frames.ndjson, e manifest.json. Os resultados mostram os caminhos do anfitrião. As gravações de destino são executadas no sistema convidado; os ficheiros do anfitrião ficam disponíveis depois de a gravação terminar e de a entrega estar concluída.

target screenshot espera que o convidado vire na interface sem ativar qualquer janela. Exclui a barra de título e as bordas da janela Sandbox anfitriã. O seu PNG não está escalado: com a origem do ecrã convidado em (0,0), as coordenadas da imagem podem ser utilizadas diretamente por comandos de entrada por coordenadas, como ui drag ou ui touch --at, com --on sandbox. Adicione a origem reportada para um ambiente de trabalho com origem negativa. Uso --json para ler coordinates.sourceBounds e coordinates.contentRect; ambos usam píxeis físicos e as bordas direita/inferior exclusivas.

As gravações de destino incluem os mesmos campos em JSON e no manifesto de fotogramas. Os fotogramas MP4 e JPEG partilham o mesmo mapeamento, incluindo o dimensionamento --max-edge e o preenchimento do codificador. Para mapear o píxel da imagem (x,y), primeiro, rejeite os pontos fora de contentRect e, em seguida, calcule cada coordenada de origem como sourceStart + floor((pixel - contentStart + 0.5) * sourceSize / contentSize). A redução de escala perde precisão; use uma PNG nativa quando as coordenadas exatas importam. Uma alteração nos limites do ambiente de trabalho convidado interrompe a gravação com display_changed, preservando apenas os frames anteriores à alteração e marcando o manifesto do frame como parcial.

Um MP4 existente ou um diretório emparelhado .frames é rejeitado por predefinição. Use um novo caminho, ou passe --overwrite para os substituir depois da nova tomada terminar. Os feixes de quadros anteriores são mantidos como <output-name>.frames.previous-<id>, incluindo quando o substituto omite --frames. Uma captura falhada deixa a gravação antiga intacta.

Prefira um --duration-sec positivo para scripts e agentes. Os auxiliares npm uiRecord e targetRecord requerem durationSec; o respetivo sinal de anulação força o cancelamento, não uma paragem controlada. Consulte ui record para ver os valores suportados. Sem uma duração especificada na CLI, a gravação aguarda um sinal de paragem.

Ctrl+C, após o início da captura, pode finalizar e devolver uma gravação com sucesso com stopReason: cancelled. Outras interrupções podem preservar o vídeo ou fotogramas úteis. Leia stopReason, partialOutput, e recoveryHint quando presente, e use os caminhos de evidência reportados em vez de assumir uma conclusão normal. Se a captura do ambiente de trabalho completo ficar indisponível durante uma gravação, é interrompida com capture_unavailable em vez de continuar a capturar um ambiente de trabalho indisponível. Não traz a sandbox para primeiro plano para recuperar um frame. A captura pode falhar antes de qualquer evidência utilizável estar disponível.

Em caso de falha na gravação de convidado, a evidência recuperada é colocada num diretório exclusivo <output>.partial-<id> no sistema anfitrião. Se a entrega falhar, os ficheiros recebidos permanecem no caminho de recuperação indicado, como <output>.recovery-<id>, e os ficheiros originais do convidado são mantidos. Mantenha o Sandbox a funcionar e siga a ação de recuperação do erro antes de tentar novamente ou fechá-lo. Um ficheiro parcial preservado não é necessariamente um vídeo reproduzível.

Capturas de ecrã e vídeos podem conter informações sensíveis. Trata o diretório de frames com o mesmo cuidado que o MP4. Consulte ui record para ver as opções de gravação e os campos de resultados.

Inspeção do Sandbox

winapp target snapshot sandbox
winapp target snapshot sandbox --json

Isto indica o estado de preparação, as implementações atuais e as janelas do sistema convidado sem ser necessário criar uma VM, restabelecer a ligação do cliente ou reparar o agente. Sem Sandbox a funcionar, reporta esse facto e sai com sucesso. Para iniciar uma, use winapp run . --on sandbox --detach.

O relatório distingue o que o convidado suporta do que o cliente atual pode fazer; um cliente minimizado pode impedir entrada ou captura mesmo quando o convidado suporta ambos. Utilize a lista de janelas convidadas para os PIDs da IU, não o processo de arranque monitorizado de uma implantação. O campo JSON workRoot (mostrado como Work root na saída de texto) é a base absoluta para caminhos relativos de transferência de ficheiros, normalmente C:\WinApp\work. Está separada de capabilities.managedRoot, normalmente C:\WinApp, e é omitida quando o convidado não indica a sua raiz administrada. Se várias janelas do cliente impedirem uma captura inequívoca, o erro lista candidatos; decide qual fechar antes de tentar novamente.

Execução de comandos e cópia de ficheiros

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

Use target exec para configuração e diagnóstico. Executa como utilizador convidado, encaminha fluxos padrão e devolve o código de saída do comando. Não é um terminal totalmente interativo; as aplicações de consola veem tubos redirecionados. --json formata erros do winapp, não a saída padrão do comando subordinado.

Para push e pull, os caminhos-alvo são relativos ao workRoot reportado por target snapshot. Os caminhos de destino absolutos, com raiz e UNC são rejeitados. Um único ficheiro aterra exatamente no destino que nomeas; um diretório preserva a sua estrutura por baixo desse destino. Use o caminho do convidado resolvido apresentado após um push (JSON targetPath) para escolher o --cwd do comando seguinte; para um único ficheiro, use o respetivo diretório pai. Se o convidado não reportar a sua raiz gerida, o push falha antes de copiar; siga as orientações de atualização do erro em vez de assumir um caminho padrão.

Só executa scripts de configuração em que confies. O exemplo usa process-scoped -ExecutionPolicy Bypass porque um Sandbox novo normalmente recusa scripts ao abrigo da sua Restricted política.

As transferências saltam ficheiros não alterados e verificam as substituições antes de as publicar. Ligações simbólicas e jonções não são seguidas: a implementação rejeita-as, enquanto cópias do diretório saltam entradas ligadas. Uma origem vinculada explicitamente nomeada ou um caminho de destino através de uma ligação são recusados. Copie os ficheiros ou diretórios reais em vez disso.

Remover uma aplicação e acabar com o Sandbox

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

Com um manifesto no diretório atual, podes omitir --manifest. Isto remove apenas o pacote de desenvolvimento correspondente registado pela winapp no Sandbox atual. Um pacote instalado externamente é deixado intacto, mesmo que a sua identidade coincida. --force não é suportado por --on; não pode contornar verificações de propriedade. Isto é uma limpeza de pacotes baseada no manifesto, não um comando para anular o registo de aplicações não empacotadas nem uma entrada .cs.

O Sandbox continua a funcionar. Gerir a sua vida útil com a própria linha de comando do Windows Sandbox:

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

Parar descarta o convidado e o seu trabalho. Guarde primeiro as provas necessárias e obtenha o consentimento do utilizador antes de interromper uma instância que possa estar a usar. Os comandos winapp posteriores podem criar um Sandbox novo; redescobrir todos os alvos da app depois.

Troubleshooting

Siga o userAction do erro; uma recomendação nextCommand é uma sugestão, não uma permissão para executá-lo automaticamente. Na automação, inspecione a estrutura error.code. Falhas de infraestrutura podem terminar com 70, mas uma aplicação arbitrária também pode terminar com 70; o código numérico de saída, por si só, não permite distingui-los.

Comandos de recuperação sugeridos por operações de interface encaminhadas mantêm --on <target>, pelo que copiar uma sugestão mantém-na no mesmo alvo de execução.

Erro ou sintoma O que fazer
sandbox_unsupported Verifique a virtualização da edição/versão do Windows e do firmware
sandbox_setup_required Ativa o Sandbox do Windows usando as instruções acima e depois reinicia quando estiver pronto
sandbox_setup_requires_restart O Windows reporta um reinício pendente; guarde o trabalho e reinicie quando estiver pronto, depois tente novamente
sandbox_setup_incomplete Abra a Sandbox do Windows no menu Iniciar e conclua a configuração/atualização do cliente; em seguida, volte a tentar
sandbox_unmanaged_instance, sandbox_target_ambiguous Verifique as instâncias/janelas reportadas; não interrompa trabalho não relacionado para resolver ambiguidades
sandbox_input_not_ready, sandbox_no_interactive_session Restaure o cliente existente ou volte a ligar-se conforme indicado, depois tente novamente
sandbox_agent_incompatible Siga a indicação do erro de versão; atualize a CLI instalada utilizando o respetivo método de instalação, se solicitado, e, em seguida, feche e tente novamente apenas com consentimento
sandbox_agent_busy Espera que outro comando termine e depois tenta novamente
sandbox_terminated, sandbox_target_stale, sandbox_stale_handle Volta a executar a aplicação e volta a detetar os PIDs/janelas do sistema convidado
sandbox_state_unavailable Certifique-se de que %USERPROFILE%\.winapp\state é gravável ou corrija WINAPP_TARGET_STATE_ROOT se estiver definido.
sandbox_deployment_dirty, sandbox_transfer_interrupted Tentar novamente a implementação ou transferência
sandbox_runtime_provision_failed Resolva a dependência nomeada ou a configuração de ambiente de execução não suportada; consulte Ambientes de execução partilhados
sandbox_package_conflict, sandbox_provisioned_package_conflict Siga a ação específica do pacote; não remova pacotes não relacionados ou da caixa de entrada
sandbox_artifact_failed Verifique a saída reportada e o estado de prontidão do cliente; preserve qualquer evidência parcial
target_invalid, target_invalid_arguments Corrigir o alvo ou as opções mostradas no erro

winapp update atualiza as dependências do SDK do projeto, não a CLI instalada. Não é uma solução para a incompatibilidade da CLI host/convidado.

Destinos de partilha na Sandbox da build 28000

A build 28000 Sandbox testada não consegue enumerar alvos de Partilha. Testa outras funcionalidades da aplicação no Sandbox, mas valida os fluxos do Share de origem para destino fora dele.

Consulte também

  • Última atualização a