Execução do Windows Sandbox

Compile no seu computador e, em seguida, execute e automatize o app 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 do aplicativo ou pelo PID de convidado impresso por run. --detach retorna após a inicialização para que o próximo comando possa inspecionar o aplicativo; sem ele, run aguarda a saída do aplicativo. O Sandbox permanece em execução entre comandos e recompilações.

Antes de começar

  • Use Windows 11 24H2 ou mais recente em uma edição com suporte, com a virtualização de hardware habilitada.
  • O winapp convidado dá suporte a x64 e Arm64. Um aplicativo x86 requer suporte de convidado para executá-lo e corresponder a dependências x86; um runtime x64 não atende a um aplicativo x86.
  • Mantenha a sessão do host desbloqueada para entrada real e captura de tela.

Habilite o Sandbox do Windows em Ativar ou desativar recursos do Windows ou execute isto em um terminal como administrador:

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

Salve seu trabalho e reinicie Windows quando estiver pronto. Em seguida, abra a Área Restrita do Windows a partir do menu Iniciar e conclua qualquer instalação ou atualização de cliente. O winapp não habilita o recurso, não instala o cliente, não solicita elevação de privilégios nem reinicia o Windows. Se houver pré-requisitos ausentes, a execução será interrompida com instruções de instalação; uma reinicialização pendente do Windows detectada será informada separadamente.

Uma conexão fria ou reconexão pode se concentrar brevemente. Uma vez conectado, o winapp mantém sua própria janela do cliente fora da tela sem ativá-la. Uma janela do Sandbox que você mesmo abriu permanece no lugar.

Importante

Os builds ainda são executados no computador. A avaliação do projeto, a restauração e a compilação não são processos isolados. --on sandbox não torna um projeto não confiável seguro para compilação.

Um Sandbox é um ambiente compartilhado. Aplicativos e fluxos de trabalho dentro dele compartilham o usuário, a área de trabalho, o registro, os pacotes, os runtimes e o acesso à rede. Eles podem observar ou interferir uns com os outros. Use computadores separados para fluxos de trabalho mutuamente não confiáveis.

O Windows permite apenas uma Sandbox por vez. o winapp reutiliza uma instância em execução, incluindo uma que você mesmo abriu. A preparação adiciona as pastas de bootstrap compartilhadas do winapp, o agente convidado, o Modo de Desenvolvedor e uma regra de firewall de entrada. o winapp não interrompe uma instância adotada nem remove aplicativos não relacionados. Não há nenhum fallback de host silencioso: um comando que solicita a área restrita é executado lá ou falha.

Execução e recompilaçã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, se aplicam no host. O registro, a execução e a depuração ocorrem no ambiente convidado; o aplicativo não está registrado na sua máquina.

Opção Efeito no sandbox
--detach Retornar após o lançamento em vez de aguardar a saída
--no-launch Implantar e registrar sem iniciar
--clean Reinstale esta implantação e limpe os dados do aplicativo
--unregister-on-exit Remover esse registro de pacote após a saída do aplicativo
--with-alias Iniciar seu alias para execução de convidado com fluxos redirecionados
--debug-output Transmitir saída de depuração do convidado; apenas aplicativos empacotados

Os aplicativos não empacotados iniciam o executável da pasta implantada. Eles não têm pacote algum para registrar. --debug-output é rejeitado para execuções em Sandbox sem empacotamento.

Executar novamente transfere arquivos alterados e remove arquivos excluídos da saída de build. Os dados do aplicativo são preservados, a menos que você solicite --clean. Uma implantação incompleta não é iniciada; uma nova tentativa recompila sua cópia convidada. Se os arquivos de build forem alterados enquanto o winapp os estiver preparando, conclua o build e tente novamente.

Os comandos da UI em modo de espera exibem apenas o resultado, sem repetir a mensagem de preparação do Sandbox. A inicialização do sandbox e a recuperação da conexão ainda continuam exibindo o progresso. Use --verbose para intervalos de conexão e detalhes de diagnóstico; --quiet e --json suprime o progresso. As execuções em JSON incluem um identificador do processo convidado e o escopo de destino:

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

Esses são campos adicionais no resultado da execução, não um documento separado. Copie todo o valor UiTargetArgs ao inspecionar o aplicativo: winapp ui inspect --on sandbox -a 4212. Descubra novamente os PIDs e os handles de janela depois que a Sandbox for recriada; eles pertencem a essa geração da Sandbox, não ao host nem a um futuro convidado.

Aplicativos desvinculados e o ciclo de vida do agente

Um aplicativo desconectado não empacotado é encerrado se o agente convidado parar, inclusive durante o reparo do agente. Se ele desaparecer entre comandos, execute novamente com --detach e redescubra seu alvo na interface. Aguardar o aplicativo, em vez de se desvincular dele, permite acompanhar seu encerramento; isso não faz com que o aplicativo sobreviva à perda do agente. Os aplicativos empacotados usam a ativação do Windows em vez do ciclo de vida do processo do agente. Fechar ou reiniciar a Sandbox encerra todos os aplicativos em execução nela.

Runtimes compartilhados

winapp verifica as dependências do pacote do aplicativo, os requisitos do SDK do Aplicativo Windows e *.runtimeconfig.json antes da inicialização. Ele usa o cache do host ou baixa os payloads necessários e depois instala os runtimes compatíveis ausentes no convidado, não na sua máquina.

Os requisitos do pacote incluem editor, versão e arquitetura. A seleção do runtime compartilhado do .NET respeita a política de roll-forward configurada do aplicativo e a arquitetura; não presuma que qualquer runtime mais recente dentro da mesma versão principal funcionará.

Se não houver suporte para uma estrutura, configuração de runtime ou dependência, o comando falhará explicitamente antes de iniciar e identificará o requisito. Siga a ação associada a esse erro. Quando houver suporte no seu projeto, publicar como autocontido remove a necessidade do tempo de execução compartilhado correspondente; isso não remove dependências de pacotes não relacionadas.

Automatizando a interface do usuário

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

Todo verbo ui aceita --on sandbox. Nomes de aplicativos, PIDs, identificadores de janela e seletores são resolvidos dentro do convidado. Use -a/--app ou -w/--window para comandos direcionados ao aplicativo; o winapp não adivinha o último aplicativo iniciado. Omitir --on sandbox seleciona, em vez disso, a sua área de trabalho host.

A entrada real e a gravação exigem um cliente Sandbox conectado e não minimizado. A inspeção somente leitura ainda pode funcionar quando a entrada não pode. o winapp pode restaurar seu próprio cliente minimizado sem ativação; um cliente aberto manualmente minimizado deve ser restaurado por você. Se a entrada estiver indisponível após a reconexão, o comando falhará em vez de reivindicar a entrada entregue. Use o comando reconectar no erro e tente novamente.

Use winapp target snapshot sandbox --json para verificar se a área de trabalho está pronta sem iniciar ou reconectar o Sandbox. Janelas de erro de terminal reconhecidas não contam como áreas de trabalho remotas. Se winapp não puder verificar a área de trabalho selecionada porque ela ainda estiver se conectando ou não puder ser inspecionada, o status de prontidão permanecerá indisponível; aguarde e tente novamente. Vários desktops remotos ainda podem ser ambíguos. O Snapshot não fecha janelas nem corrige os erros delas para você.

Consulte a automação da interface do usuário para seletores, métodos de entrada e declarações.

Coordenando fluxos de trabalho da 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 agente inicia um novo shell para cada chamada de ferramenta. winapp encaminha uma identidade com hash específica da geração do Sandbox; o valor bruto do host não é enviado ao convidado.

Por exemplo, registre e interaja 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á em execução:

$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 que a gravação e as ações tiverem sido concluídas:

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

Um fluxo de trabalho nomeado mantém sua vez na interface do usuário por quatro segundos após o último comando; yield a libera imediatamente. Sem um identificador, cada comando libera sua vez ao ser concluído. Uma gravação sem identificação, portanto, bloqueia outros workflows que alteram a área de trabalho durante a execução. A inspeção somente leitura não aguarda. Os turnos de interação na interface do anfitrião e do convidado são separados.

Após uma pausa, inspecione novamente e reabra qualquer menu ou caixa de diálogo necessária: outro fluxo de trabalho pode ter usado a área de trabalho convidada. Os turnos cooperativos não isolam os aplicativos entre si.

Capturas de tela e gravações

Use a captura com ui para a janela de um aplicativo ou a captura com target para a área de trabalho nativa inteira do 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 são direcionadas ao host, mesmo quando você omite -o. Capturas de tela são salvas por padrão como screenshot.png; 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.ndjsone manifest.json. O relatório de resultados mostra os caminhos do host. As gravações de destino são executadas no sistema convidado; os arquivos correspondentes no sistema hospedeiro tornam-se disponíveis após a conclusão da gravação e da entrega.

target screenshot aguarda a vez da UI do convidado sem ativar nenhuma janela. Ele exclui a barra de título e as bordas da janela Sandbox do hospedeiro. O arquivo PNG não está redimensionado: com a origem da tela do convidado em (0,0), as coordenadas da imagem podem ser usadas diretamente por verbos de entrada de coordenadas como ui drag ou ui touch --at, com --on sandbox. Adicione a origem informada para um desktop com origem negativa. Use --json para ler coordinates.sourceBounds e coordinates.contentRect; ambos utilizam pixels físicos e as bordas direita/inferior exclusivas.

As gravações de destino informam os mesmos campos no JSON e no manifesto de frames. Os quadros MP4 e JPEG usam o mesmo mapeamento, incluindo o escalonamento --max-edge e o preenchimento do codificador. Para mapear pixel (x,y)de imagem, primeiro rejeitar pontos externos contentRecte computar cada coordenada de origem como sourceStart + floor((pixel - contentStart + 0.5) * sourceSize / contentSize). O downscaling perde a precisão; use um PNG nativo quando as coordenadas exatas forem importantes. Uma alteração nos limites da área de trabalho do convidado interrompe a gravação com display_changed, preservando apenas os quadros anteriores à alteração e marcando o manifesto de quadros como parcial.

Um arquivo MP4 existente ou diretório .frames emparelhado existente é rejeitado por padrão. Use um novo caminho ou passe --overwrite para substituí-los após a conclusão da nova tomada. Os conjuntos de quadros anteriores são mantidos como <output-name>.frames.previous-<id>, mesmo quando a substituição omite --frames. Uma captura com falha deixa a gravação antiga intacta.

Prefira um valor positivo --duration-sec para scripts e agentes. Os auxiliares npm uiRecord e targetRecord exigem durationSec; seu sinal de abortamento cancela à força, não como uma interrupção graciosa. Consulte ui record para ver os valores compatíveis. Sem uma duração especificada na CLI, a gravação aguarda um sinal de parada.

Ctrl+C após o início da captura pode finalizar e retornar uma gravação com êxito com stopReason: cancelled. Outras interrupções podem preservar quadros ou vídeos úteis. Leia stopReason, partialOutpute recoveryHint quando estiver presente, e use os caminhos de evidência relatados em vez de assumir uma conclusão normal. Se a captura da área de trabalho completa ficar indisponível durante uma gravação, ela será interrompida com capture_unavailable em vez de continuar capturando uma área de trabalho indisponível. Ele não traz o Sandbox para o primeiro plano para recuperar um quadro. A captura pode falhar antes que qualquer evidência utilizável esteja disponível.

No caso de uma gravação de convidado que falhou, os dados recuperados são armazenados em um diretório <output>.partial-<id> exclusivo no host. Se a entrega falhar, os arquivos recebidos permanecem no caminho de recuperação informado, como <output>.recovery-<id>, e os originais do convidado são retidos. Mantenha o Sandbox em execução e siga a ação de recuperação indicada pelo erro antes de tentar novamente ou fechá-lo. Um arquivo parcial preservado não é necessariamente um vídeo reproduzível.

Capturas de tela e vídeo podem conter informações confidenciais. Manipule o diretório de quadros com o mesmo cuidado que o MP4. Consulte ui record para ver as opções de gravação e os campos de resultado.

Inspecionando a sandbox

winapp target snapshot sandbox
winapp target snapshot sandbox --json

Isso informa o status de prontidão, as implantações atuais e as janelas do sistema convidado sem a necessidade de criar uma VM, reconectar o cliente ou reparar o agente. Sem nenhuma Sandbox em execução, o programa relata esse fato e é encerrado. Para iniciar um, use winapp run . --on sandbox --detach.

O relatório distingue o que o sistema convidado suporta do que o cliente em uso pode fazer; um cliente minimizado pode impedir a entrada de dados ou a captura, mesmo quando o sistema convidado oferece suporte a ambos. Use a lista de janelas do convidado para PIDs de interface do usuário, e não para o processo do lançador monitorado 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 arquivo, normalmente C:\WinApp\work. Ele é separado de capabilities.managedRoot, normalmente C:\WinApp, e é omitido quando o convidado não relata sua raiz gerenciada. Se várias janelas de cliente impedirem uma captura inequívoca, o erro listará os candidatos; decidir qual fechar antes de tentar novamente.

Executando comandos e copiando arquivos

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. Ele é executado como o usuário convidado, encaminha fluxos padrão e retorna o código de saída do comando. Não é um terminal interativo completo; aplicativos de console veem os pipes redirecionados. --json formata erros do winapp, não o stdout do comando filho.

Para push e pull, os caminhos de destino são relativos ao workRoot relatado por target snapshot. Caminhos absolutos, ancorados na raiz e caminhos de destino UNC são recusados. Um único arquivo chega exatamente ao destino que você nomeia; um diretório preserva sua estrutura abaixo desse destino. Use o caminho resolvido no convidado, exibido após um push (JSON targetPath) para definir o --cwd do próximo comando; para um único arquivo, utilize o diretório pai. Se o convidado não informar sua raiz gerenciada, a operação de push falha antes da cópia; siga as orientações de atualização fornecidas na mensagem de erro em vez de presumir um caminho padrão.

Execute somente scripts de instalação em que você confia. O exemplo usa -ExecutionPolicy Bypass com escopo de processo porque uma Sandbox nova normalmente se recusa a executar scripts devido à sua política Restricted.

As transferências ignoram arquivos inalterados e verificam as substituições antes de publicá-los. Links simbólicos e junções não são seguidos: a implantação os rejeita, enquanto as cópias de diretórios ignoram as entradas vinculadas. Uma origem vinculada especificada diretamente ou um caminho de destino por meio de um link é recusado. Em vez disso, copie os arquivos ou diretórios reais.

Removendo um aplicativo e encerrando a sandbox

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

Com um manifesto no diretório atual, você pode omitir --manifest. Isso remove apenas o pacote de desenvolvimento correspondente registrado pelo winapp na Sandbox atual. Um pacote instalado externamente é mantido como está, mesmo que sua identidade coincida. --force não é compatível com --on; não pode ignorar as verificações de propriedade. Trata-se de uma limpeza de pacotes baseada em manifesto, e não de um comando de cancelamento de registro para aplicativos não empacotados ou de uma entrada .cs.

O Sandbox continua em execução. Gerencie seu ciclo de vida com a interface de linha de comando (CLI) própria do Windows Sandbox:

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

Parar descarta o convidado e seu trabalho. Salve as evidências necessárias primeiro e obtenha o consentimento do usuário antes de interromper uma instância que ele possa estar usando. Comandos posteriores do winapp podem criar uma nova Sandbox; redescubra todos os alvos do aplicativo depois disso.

Troubleshooting

Siga o userAction do erro; um aviso nextCommand é uma sugestão, não uma permissão para executá-lo automaticamente. Na automação, inspecione o error.code estruturado. Falhas de infraestrutura podem resultar em 70, mas qualquer aplicativo também pode retornar 70; o valor numérico do status de saída, por si só, não permite distingui-los.

Os comandos de recuperação sugeridos pelas operações roteadas da interface do usuário retêm --on <target>, de modo que, ao copiar uma sugestão, ela é mantida no mesmo destino de execução.

Erro ou sintoma O que fazer
sandbox_unsupported Verifique a edição/versão do Windows e a virtualização de firmware
sandbox_setup_required Habilite o Windows Sandbox usando as instruções acima e, em seguida, reinicie quando estiver pronto
sandbox_setup_requires_restart Windows relata uma reinicialização pendente; salve o trabalho e reinicie quando estiver pronto e tente novamente
sandbox_setup_incomplete Abra o Windows Sandbox no menu Iniciar e conclua a configuração ou atualização do cliente, depois tente novamente
sandbox_unmanaged_instance, sandbox_target_ambiguous Inspecione as instâncias/janelas relatadas; não interrompa trabalhos não relacionados para resolver ambiguidades
sandbox_input_not_ready, sandbox_no_interactive_session Restaurar o cliente existente ou reconectar conforme indicado e tentar novamente
sandbox_agent_incompatible Siga a orientação da mensagem de erro de versão; atualize a CLI instalada usando o método pelo qual ela foi instalada, se solicitado, e feche e tente novamente apenas com consentimento
sandbox_agent_busy Aguarde até que outro comando seja concluído e tente novamente
sandbox_terminated, sandbox_target_stale, sandbox_stale_handle Execute o aplicativo novamente e redescubra os PIDs/janelas do convidado
sandbox_state_unavailable Verifique se %USERPROFILE%\.winapp\state está gravável ou corrija WINAPP_TARGET_STATE_ROOT, se estiver definido.
sandbox_deployment_dirty, sandbox_transfer_interrupted Tentar novamente a implantação ou a transferência
sandbox_runtime_provision_failed Resolva a dependência especificada ou a configuração de ambiente de execução sem suporte; consulte Ambientes de execução compartilhados
sandbox_package_conflict, sandbox_provisioned_package_conflict Siga a ação específica do pacote; não remova pacotes não relacionados ou de caixa de entrada
sandbox_artifact_failed Verifique a saída relatada e a prontidão do cliente; preserve quaisquer evidências parciais
target_invalid, target_invalid_arguments Corrigir o destino 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 correção para incompatibilidade da CLI de host/convidado.

Compartilhar destinos no Sandbox da build 28000

O Sandbox do build 28000 testado não pode listar destinos para compartilhamento. Teste outros recursos do app no sandbox, mas valide os fluxos do Share da origem ao destino fora dele.

Consulte também

  • Last updated on