Esecuzione di Windows Sandbox

Compila sul tuo computer, quindi esegui e automatizza l'app in Windows Sandbox:

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

Sostituisci MyApp con il nome dell'app o il PID dell'ospite stampato da run. --detach restituisce dopo l'avvio in modo che il comando successivo possa esaminare l'app; senza di esso, run attende che l'app venga chiusa. La Sandbox rimane in esecuzione tra i comandi e le ricompilazioni.

Prima di iniziare

  • Usare Windows 11 24H2 o versione successiva in un'edizione supportata, con la virtualizzazione hardware abilitata.
  • L'app winapp guest supporta x64 e Arm64. Un'app x86 richiede il supporto dell'ambiente guest per essere eseguita e dipendenze x86 corrispondenti; un runtime x64 non è sufficiente per un'app x86.
  • Mantenere la sessione host sbloccata per l'input reale e l'acquisizione dello schermo.

Abilitare Windows Sandbox in Attivare o disattivare le funzionalità di Windows oppure eseguirlo da un terminale amministratore:

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

Salvare il lavoro e riavviare Windows quando si è pronti. Aprire quindi Windows Sandbox dal menu Start e completare l'installazione o l'aggiornamento del client. winapp non attiva la funzionalità; installa il client, richiedi l'elevazione dei privilegi o riavvia Windows. Se mancano i prerequisiti, il processo si interrompe mostrando le istruzioni di installazione; un riavvio di Windows in sospeso rilevato viene segnalato separatamente.

Una connessione iniziale o una riconnessione può acquisire temporaneamente lo stato attivo. Dopo la connessione, winapp mantiene la propria finestra client fuori schermo senza attivarla. Una finestra Sandbox aperta manualmente da te viene lasciata aperta.

Importante

Le compilazioni vengono comunque eseguite nel computer. La valutazione del progetto, il ripristino e la compilazione non sono isolati. --on sandbox non rende un progetto non attendibile sicuro per la compilazione.

Una sandbox è un ambiente condiviso. Le app e i flussi di lavoro all'interno condividono l'utente, il desktop, il registro, i pacchetti, i runtime e l'accesso alla rete. Possono osservare o interferire tra loro. Usare computer separati per flussi di lavoro reciprocamente non attendibili.

Windows consente una sandbox alla volta. Winapp riutilizza un'istanza in esecuzione, inclusa quella aperta manualmente. La procedura di preparazione aggiunge le cartelle bootstrap condivise di winapp, l'agente del sistema guest, la Modalità sviluppatore e una regola del firewall in ingresso. winapp non arresta un'istanza acquisita né rimuove app non pertinenti. Non è previsto alcun fallback silenzioso dell'host: un comando che richiede Sandbox viene eseguito lì oppure non riesce.

Esecuzione e rigenerazione

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

Opzioni di compilazione come --configuration, --framework--arch, --property, --no-build, e --no-restore si applicano all'host. La registrazione, l'avvio e il debug vengono eseguiti nel guest; l'app non è registrata nel computer.

Option Effetto nella sandbox
--detach Tornare dopo l'avvio anziché attendere l'uscita
--no-launch Distribuire e registrare senza avviare
--clean Reinstallare questa distribuzione e cancellare i dati dell'applicazione
--unregister-on-exit Rimuovere la registrazione del pacchetto dopo l'uscita dall'app
--with-alias Avviare l'alias di esecuzione ospite con flussi reindirizzati
--debug-output Trasmetti in streaming l'output di debug della macchina guest; solo app pacchettizzate

Le app senza pacchetti avviano il file eseguibile dalla cartella distribuita. Non hanno alcun pacchetto da registrare. --debug-output viene rifiutato per le esecuzioni sandbox non in pacchetto.

Riesecuzione trasferisce i file modificati e rimuove i file eliminati dall'output di compilazione. I dati dell'applicazione sono conservati a meno che non si richieda --clean. Una distribuzione non completata non si avvia; se si riprova, viene ricreata la relativa copia guest. Se i file di compilazione cambiano mentre winapp li sta preparando, completa la compilazione e riprova.

I comandi dell'interfaccia utente ad accesso frequente segnalano solo il risultato, senza ripetere un messaggio di preparazione sandbox. L'avvio della sandbox e il ripristino della connessione continuano a segnalare lo stato di avanzamento. Usare --verbose per i tempi di connessione e i dettagli diagnostici; --quiet e --json sopprimono l'indicatore di avanzamento. Le esecuzioni JSON includono un ID del processo guest e un ambito di destinazione:

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

Si tratta di campi aggiuntivi nel risultato dell'esecuzione, non di un documento separato. Copia l'intero valore UiTargetArgs quando ispezioni l'app: winapp ui inspect --on sandbox -a 4212. Recuperare nuovamente i PID e gli handle di finestra dopo che la sandbox è stata ricreata; appartengono a quella generazione della sandbox, non all'host o a un futuro guest.

App separate e ciclo di vita dell'agente

Un'app isolata non pacchettizzata termina se il guest agent si arresta, anche durante la riparazione dell'agente. Se scompare tra un comando e l'altro, rieseguilo con --detach e rileva nuovamente il target dell'interfaccia utente. Attendere l'app invece di scollegarsene consente di osservarne la terminazione; non fa sì che l'app continui a funzionare in caso di perdita dell'agente. Le app pacchettizzate usano l'attivazione di Windows anziché la durata del processo dell'agente. La chiusura o il riavvio della sandbox termina tutte le app al suo interno.

Runtime condivisi

winapp controlla le dipendenze del pacchetto dell'app, i requisiti SDK per app di Windows e *.runtimeconfig.json prima dell'avvio. Usa cache host o scarica i payload necessari, quindi installa i runtime supportati mancanti nel guest, non nel computer.

I requisiti dei pacchetti includono editore, versione e architettura. La selezione del runtime .NET condiviso rispetta i criteri di roll-forward e l'architettura configurati per l'applicazione; non dare per scontato che qualsiasi runtime più recente della stessa versione principale funzioni.

Se non è possibile supportare un framework, una configurazione di runtime o una dipendenza, il comando ha esito negativo in modo esplicito prima dell'avvio e identifica il requisito. Segui l'azione associata a quell'errore. Se supportato dal progetto, la pubblicazione autonoma rimuove la necessità del runtime condiviso corrispondente; non rimuove le dipendenze del pacchetto non correlate.

Automazione dell'interfaccia utente

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

Ogni ui verbo accetta --on sandbox. I nomi delle app, i PID, gli handle di finestra e i selettori vengono risolti all'interno del guest. Usare -a/--app o -w/--window per i comandi di destinazione dell'app. Winapp non indovina l'ultima app avviata. Se si omette --on sandbox, viene invece selezionato il desktop dell'host.

L'input reale e la registrazione richiedono un client Sandbox connesso e nonminimizzato. L'ispezione in sola lettura può comunque funzionare anche quando l'immissione non è possibile. winapp può ripristinare il proprio client minimizzato senza attivarlo; un client aperto manualmente e minimizzato deve essere ripristinato manualmente. Se l'input non è disponibile dopo la riconnessione, il comando fallisce invece di sostenere di aver fornito l'input. Usare il comando di riconnessione nell'errore e riprovare.

Usare winapp target snapshot sandbox --json per controllare l'idoneità del desktop senza avviare o riconnettere la sandbox. Le finestre di errore del terminale riconosciute non vengono conteggiate come desktop remoti. Se winapp non è in grado di verificare il desktop selezionato perché è ancora connesso o non può essere controllato, l'idoneità rimane non disponibile; attendere e riprovare. Più desktop remoti possono ancora risultare ambigui. Lo snapshot non chiude le finestre o risolve automaticamente gli errori.

Vedere Automazione interfaccia utente per selettori, metodi di input e asserzioni.

Coordinamento dei flussi di lavoro dell'interfaccia utente nella sandbox

Usa un solo WINAPP_UI_WORKFLOW_ID per i comandi correlati e un valore diverso per ogni flusso di lavoro indipendente. Impostalo su ogni invocazione, soprattutto quando l'agente avvia una nuova shell per ogni invocazione dello strumento. winapp inoltra un'identità specifica di generazione sandbox con hash; il valore host non elaborato non viene inviato al guest.

Ad esempio, registrare e interagire in due terminali usando lo stesso valore. Scegliere un nuovo valore per ogni nuovo flusso di lavoro.

Terminale 1:

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

Terminale 2, mentre la registrazione è in esecuzione:

$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

Al termine della registrazione e delle azioni:

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

Un flusso di lavoro denominato mantiene il turno dell'interfaccia utente per quattro secondi dopo l'ultimo comando; yield lo rilascia immediatamente. Senza un ID, ogni comando rilascia il proprio turno al termine dell'esecuzione. Una registrazione senza ID blocca quindi, per tutta la sua durata, altri flussi di lavoro che comportano modifiche al desktop. L'ispezione di sola lettura non attende. I turni dell'interfaccia utente host e guest sono separati.

Dopo una pausa, controllare di nuovo e riaprire qualsiasi menu o finestra di dialogo necessaria: un altro flusso di lavoro potrebbe aver usato il desktop guest. I turni cooperativi non isolano le app l'una dall'altra.

Screenshot e registrazioni

Usa ui la modalità di acquisizione per la finestra di un'app oppure target la modalità di acquisizione per l'intero desktop nativo del guest, incluse la shell e le finestre di dialogo del programma di installazione:

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

Gli output finiscono sull'host, anche quando si omette -o. Per impostazione predefinita, gli screenshot usano screenshot.png; le registrazioni usano recording-<timestamp>-<guid>.mp4. Per le registrazioni, --frames fornisce anche la directory <output-name>.frames contenente JPEG, frames.ndjson e manifest.json. Percorsi host del report dei risultati. Le registrazioni di destinazione vengono eseguite nel sistema guest; i file dell'host diventano disponibili una volta completate la registrazione e la consegna.

target screenshot attende il turno della UI del guest senza attivare alcuna finestra. Esclude la barra del titolo e i bordi della finestra sandbox host. La sua immagine PNG non è ridimensionata: con l’origine dello schermo guest (0,0), le coordinate dell’immagine sono direttamente utilizzabili da verbi che accettano coordinate in input, come ui drag o ui touch --at, con --on sandbox. Aggiungi l'origine segnalata per un desktop con un'origine negativa. Usare coordinates.sourceBounds per leggere coordinates.contentRect e --json; entrambi usano pixel fisici e bordi destro/inferiore esclusivi.

Le registrazioni di destinazione segnalano gli stessi campi in JSON e nel manifesto del frame. I fotogrammi MP4 e JPEG condividono la stessa mappatura, inclusi il ridimensionamento --max-edge e il padding del codificatore. Per mappare il pixel dell'immagine (x,y), scartare prima i punti al di fuori di contentRect, quindi calcolare ogni coordinata sorgente come sourceStart + floor((pixel - contentStart + 0.5) * sourceSize / contentSize). Il ridimensionamento perde la precisione; usare un file PNG nativo quando le coordinate esatte sono importanti. Una modifica ai limiti del desktop guest interrompe la registrazione con display_changed, mantenendo solo i fotogrammi prima della modifica e contrassegnando il manifesto del frame parziale.

Per impostazione predefinita, una directory MP4 o associata .frames esistente viene rifiutata. Usare un nuovo percorso o passare --overwrite per sostituirli al termine della nuova operazione. I bundle di frame precedenti vengono mantenuti come <output-name>.frames.previous-<id>, incluso quando la sostituzione omette --frames. Un'acquisizione non riuscita lascia intatta la registrazione precedente.

Prediligi un valore positivo --duration-sec per script e agenti. Le utilità npm targetRecord e uiRecord richiedono durationSec; il loro segnale di interruzione forza l'annullamento, non un arresto graduale. Vedere ui record per i valori supportati. Se non viene specificata una durata tramite CLI, la registrazione resta in attesa di un segnale di arresto.

CTRL+C dopo l'avvio dell'acquisizione può finalizzare e restituire correttamente una registrazione con stopReason: cancelled. Altre interruzioni possono preservare video o fotogrammi utili. Leggere stopReason, partialOutpute recoveryHint quando presente e usare i percorsi di evidenza segnalati anziché presumere un completamento normale. Se l'acquisizione dell'intero desktop diventa non disponibile durante una registrazione, si interrompe con capture_unavailable anziché continuare ad acquisire un desktop non disponibile. Non porta la Sandbox in primo piano per salvare un frame. L'acquisizione può avere esito negativo prima che sia disponibile qualsiasi prova utilizzabile.

Per una registrazione guest non riuscita, i dati recuperati vengono collocati in una directory <output>.partial-<id> univoca sull'host. Se la consegna non riesce, i file ricevuti rimangono nel percorso di ripristino indicato, ad esempio <output>.recovery-<id>, e gli originali degli ospiti vengono conservati. Mantieni la Sandbox in esecuzione e segui l'azione di ripristino indicata dall'errore prima di riprovare o chiuderla. Un file parziale conservato non è necessariamente un video riproducibile.

Screenshot e video possono contenere informazioni riservate. Gestisci la directory dei fotogrammi con la stessa cura del file MP4. Vedere ui record per le opzioni di registrazione e i campi dei risultati.

Ispezione della sandbox

winapp target snapshot sandbox
winapp target snapshot sandbox --json

Questo indica lo stato di preparazione, le distribuzioni in corso e le finestre del guest senza creare una macchina virtuale, riconnettere il client o riparare l'agente. Se non è in esecuzione alcuna Sandbox, segnala questa condizione e termina correttamente. Per avviarne uno, usare winapp run . --on sandbox --detach.

Il report distingue ciò che è supportato dal sistema guest da ciò che il client in uso può fare; un client minimizzato può impedire l'input o l'acquisizione anche quando il sistema guest supporta entrambe le funzionalità. Usare l'elenco delle finestre guest per i PID dell'interfaccia utente, non il processo di avvio rilevato di una distribuzione. Il campo JSON workRoot (illustrato come Work root nell'output di testo) è la base assoluta per i percorsi di trasferimento dei file relativi, in genere C:\WinApp\work. È separato da capabilities.managedRoot, in genere C:\WinApp, e viene omesso quando il guest non segnala la radice gestita. Se diverse finestre client impediscono un'acquisizione non ambigua, gli errori elencano i candidati; decidere quale chiudere prima di riprovare.

Esecuzione di comandi e copia di file

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

Usare target exec per la configurazione e la diagnostica. Viene eseguito come utente guest, inoltra flussi standard e restituisce il codice di uscita del comando. Non è un terminale interattivo completo; le applicazioni da console rilevano pipe reindirizzate. --json formatta gli errori di winapp, non lo stdout del comando secondario.

Per push e pull, i percorsi di destinazione sono relativi all'oggetto workRoot segnalato da target snapshot. I percorsi di destinazione assoluti, radicati e UNC non sono accettati. Un singolo file viene collocato esattamente nella destinazione specificata; una directory preserva la propria struttura all’interno di tale destinazione. Usare il percorso dell'ospite risolto visualizzato dopo un push (JSON targetPath) per scegliere il --cwd del comando successivo; per un singolo file, usare la directory padre. Se il guest non segnala la radice gestita, il push ha esito negativo prima della copia; seguire le indicazioni per l'aggiornamento dell'errore anziché presupporre un percorso predefinito.

Eseguire solo script di installazione attendibili. L'esempio usa -ExecutionPolicy Bypass con ambito di processo perché una Sandbox appena creata normalmente non consente gli script in base alla propria policy Restricted.

I trasferimenti ignorano i file non modificati e verificano le sostituzioni prima di pubblicarli. I collegamenti simbolici e i punti di giunzione non vengono risolti: la procedura di distribuzione li rifiuta, mentre durante la copia delle directory gli elementi collegati vengono ignorati. La specifica diretta di un'origine collegata o di un percorso di destinazione attraverso un collegamento è rifiutata. Copiare invece i file reali o le directory.

Rimozione di un'app e fine della sandbox

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

Con un file manifest nella directory corrente, puoi omettere --manifest. In questo modo viene rimosso solo il pacchetto di sviluppo corrispondente registrato da winapp nella sandbox corrente. Un pacchetto installato esternamente viene lasciato solo, anche se la sua identità corrisponde. --force non è supportato con --on; non può ignorare i controlli di proprietà. Si tratta della pulizia del pacchetto basata sul manifest, non di un comando di deregistrazione per le app non pacchettizzate o di un input .cs.

Il sandbox è ancora in esecuzione. Gestisci il ciclo di vita con la propria CLI di Windows Sandbox:

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

L'interruzione elimina l'ospite e il relativo lavoro. Salvare prima le prove necessarie e ottenere il consenso dell'utente prima di arrestare un'istanza che potrebbe usare. I comandi winapp successivi possono creare una nuova sandbox; riscoprire tutte le destinazioni dell'app in un secondo momento.

Risoluzione dei problemi

Segui le indicazioni dell'errore userAction; un avviso informativo nextCommand è un suggerimento, non un'autorizzazione a eseguire automaticamente l'operazione. In automazione, esamina l'oggetto strutturato error.code. I guasti dell'infrastruttura possono terminare con 70, ma anche una qualsiasi applicazione può restituire 70; il solo codice di uscita numerico non consente di distinguerli.

I comandi di ripristino suggeriti dalle operazioni indirizzate dell'interfaccia utente mantengono --on <target>, quindi la copia di un suggerimento lo mantiene nella stessa destinazione di esecuzione.

Errore o sintomo Cosa fare
sandbox_unsupported Controllare Windows edizione/versione e virtualizzazione del firmware
sandbox_setup_required Abilitare Windows Sandbox usando le istruzioni precedenti, quindi riavviare quando è pronto
sandbox_setup_requires_restart Windows segnala un riavvio in sospeso; salvare il lavoro e riavviare quando è pronto, quindi riprovare
sandbox_setup_incomplete Aprire Windows Sandbox da Start e completare l'installazione/aggiornamento del client, quindi riprovare
sandbox_unmanaged_instance, sandbox_target_ambiguous Esaminare le istanze/finestre segnalate; non arrestare il lavoro non correlato per risolvere l'ambiguità
sandbox_input_not_ready, sandbox_no_interactive_session Ripristinare il client esistente o riconnettersi come indicato, quindi riprovare
sandbox_agent_incompatible Seguire le indicazioni dell’errore di versione; aggiornare la CLI installata utilizzando il relativo metodo di installazione, se richiesto, quindi chiudere o riprovare solo con il consenso
sandbox_agent_busy Attendere il completamento di un altro comando, quindi riprovare
sandbox_terminated, sandbox_target_stale, sandbox_stale_handle Riavviare l'app e rilevare nuovamente i PID e le finestre dell'ospite
sandbox_state_unavailable Assicurarsi che %USERPROFILE%\.winapp\state sia scrivibile oppure correggere WINAPP_TARGET_STATE_ROOT se definito
sandbox_deployment_dirty, sandbox_transfer_interrupted Riprova la distribuzione o il trasferimento
sandbox_runtime_provision_failed Risolvi la dipendenza specificata o la configurazione runtime non supportata; consulta Shared runtimes
sandbox_package_conflict, sandbox_provisioned_package_conflict Seguire l'azione specifica del pacchetto; non rimuovere pacchetti non correlati o posta in arrivo
sandbox_artifact_failed Verificare l'output riportato e lo stato di preparazione del client; conservare qualsiasi evidenza parziale
target_invalid, target_invalid_arguments Correggere la destinazione o le opzioni visualizzate nell'errore

winapp update aggiorna le dipendenze dell'SDK del progetto, non la CLI installata. Non è una correzione per l'incompatibilità dell'interfaccia della riga di comando host/guest.

Condividere le destinazioni nella build 28000 Sandbox

La build 28000 Sandbox testata non può enumerare le destinazioni di condivisione. Testate altre funzionalità dell'app in Sandbox, ma convalidate i flussi di Share dall'origine alla destinazione fuori da Sandbox.

Vedere anche

  • Last updated on