Körning av Windows Sandbox

Bygg på datorn och kör och automatisera appen i Windows sandbox-miljö:

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

Ersätt MyApp med ditt appnamn eller gäst-PID som skrivs ut av run. --detach returnerar efter start så att nästa kommando kan inspektera appen. utan den run väntar på att appen ska avslutas. Sandbox-miljön fortsätter att köras mellan kommandon och återskapanden.

Innan du börjar

  • Använd Windows 11 24H2 eller senare i en version som stöds, med maskinvaruvirtualisering aktiverad.
  • Gäst winapp stöder x64 och Arm64. En x86-app kräver stöd i gästmiljön för att kunna köras samt motsvarande x86-beroenden; en x64-körningsmiljö uppfyller inte kraven för en x86-app.
  • Behåll värdsessionen olåst för verklig inmatning och skärmdump.

Aktivera Windows Sandbox i Aktivera eller inaktivera Windows funktioner eller kör detta från en administratörsterminal:

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

Spara ditt arbete och starta om Windows när du är klar. Öppna sedan Windows Sandbox från Start-menyn och slutför alla klientinstallationer eller uppdateringar. winapp aktiverar inte funktionen, installerar klienten, begär utökade privilegier eller startar om Windows. Om förutsättningar saknas avbryts det med installationsanvisningar; en väntande omstart av Windows rapporteras separat.

En kall anslutning eller återanslutning kan kort fokusera. När winapp är ansluten behåller den sitt eget klientfönster utanför skärmen utan att aktivera det. Ett sandbox-fönster som du öppnade själv finns kvar.

Important

Byggen körs fortfarande på din dator. Projektutvärdering, återställning och kompilering sker inte isolerat. --on sandbox gör inte ett obetrott projekt säkert att bygga.

En sandbox-miljö är en delad miljö. Appar och arbetsflöden inuti den delar samma användarkonto, skrivbord, register, paket, runtime-miljöer och nätverksåtkomst. De kan observera eller störa varandra. Använd separata datorer för ömsesidigt ej betrodda arbetsflöden.

Windows tillåter en sandbox-miljö i taget. winapp återanvänder en instans som körs, inklusive en som du öppnade själv. När den förbereds läggs winapps delade bootstrap-mappar, gästagenten, utvecklarläget och en inkommande brandväggsregel till. winapp stoppar inte en antagen instans eller tar bort orelaterade appar. Det finns ingen tyst värdåterställning: ett kommando som begär att Sandbox-miljön ska köras där eller misslyckas.

Körning och ombyggnad

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

Skapa alternativ som --configuration, , --arch--framework, --property, och --no-build--no-restore tillämpa på värden. Registrering, start och felsökning sker i gästen. appen är inte registrerad på datorn.

Alternativet Effekt i sandbox-miljö
--detach Returnera efter start i stället för att vänta på avslut
--no-launch Distribuera och registrera utan att starta
--clean Installera om den här distributionen och rensa programdata
--unregister-on-exit Ta bort den här paketregistreringen när appen har avslutats
--with-alias Starta sitt gästkörningsalias med vidarebefordrade strömmar
--debug-output Strömma gästens felsökningsutdata; endast paketerade appar

Opaketerade appar startar den körbara filen från distributionsmappen. De har inget paket att registrera. --debug-output avvisas för opaketerade Sandbox-körningar.

Att köra överföringen igen överför ändrade filer och tar bort filer som har tagits bort från byggutdata. Programdata bevaras om du inte begär --clean. En ofullständig distribution startas inte. återförsöket återskapar gästkopian. Om byggfilerna ändras medan winapp förbereder dem slutför du bygget och försöker igen.

Varma gränssnittskommandon rapporterar endast resultatet, utan att upprepa ett sandbox-förberedelsemeddelande. Sandbox-start och anslutningsåterställning rapporterar fortfarande förlopp. Använd --verbose för information om anslutningstider och diagnostiska detaljer; --json och --quiet döljer förloppsindikeringen. JSON-körningar innehåller ett gästprocess-ID och ett målområde:

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

Det här är ytterligare fält i körningsresultatet, inte ett separat dokument. Kopiera hela UiTargetArgs värdet när du inspekterar appen: winapp ui inspect --on sandbox -a 4212. Återupptäckta PID:er och fönsterhandtag när sandbox-miljön har återskapats. de tillhör den sandbox-generationen, inte värden eller en framtida gäst.

Frånkopplade appar och agentens livslängd

En fristående opaketerad app avslutas om gästagenten slutar fungera, även under reparation av agenten. Om det försvinner mellan två kommandon kör du det igen med --detach och identifierar dess UI-mål på nytt. Att vänta på appen i stället för att koppla loss låter dig se när den avslutas; det gör inte att appen överlever att agenten försvinner. Paketerade appar använder Windows aktivering i stället för agentens processlivslängd. När sandbox-miljön stängs eller startas om avslutas alla appar i den.

Delade körmiljöer

winapp kontrollerar appens paketberoenden, Windows App SDK krav och *.runtimeconfig.json före start. Den använder värdcachar eller laddar ned de nyttolaster som behövs och installerar sedan saknade körmiljöer som stöds i gästen, inte på din dator.

Paketkraven omfattar utgivare, version och arkitektur. Val av delad .NET-körmiljö respekterar programmets konfigurerade roll-forward-princip och arkitektur; anta inte att någon nyare körmiljö inom samma huvudversion fungerar.

Om ett ramverk, en körningskonfiguration eller ett beroende inte stöds avbryts kommandot tydligt innan start och anger vilket krav som inte uppfylls. Följ åtgärden för det felet. Om projektet har stöd för det eliminerar publicering som självbärande behovet av motsvarande delad runtime; det eliminerar inte beroenden till orelaterade paket.

Automatisera användargränssnittet

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

Varje ui verb accepterar --on sandbox. appnamn, PID:er, fönsterhandtag och selektorer tolkas upp i gästen. Använd -a/--app eller -w/--window för appriktade kommandon. Winapp gissar inte att den senaste appen startades. Om du utelämnar --on sandbox väljs värddatorns skrivbord i stället.

Verklig indata och inspelning kräver en ansluten, icke-minimiserad Sandbox-klient. Skrivskyddad inspektion kan fortfarande fungera när indata inte kan användas. winapp kan återställa sin egen minimerade klient utan aktivering. en minimerad manuellt öppnad klient måste återställas av dig. Om indata inte är tillgängliga efter återanslutning misslyckas kommandot i stället för att påstå att indata levererades. Använd återanslutningskommandot i felet och försök igen.

Använd winapp target snapshot sandbox --json för att kontrollera skrivbordsberedskapen utan att starta eller återansluta sandbox-miljön. Identifierade terminalfelfönster räknas inte som fjärrskrivbord. Om winapp inte kan verifiera det valda skrivbordet eftersom det fortfarande ansluter eller inte kan inspekteras förblir beredskapen otillgänglig. vänta och försök igen. Flera fjärrskrivbord kan fortfarande vara tvetydiga. Snapshot stänger inte fönster eller åtgärdar deras fel åt dig.

Se automatisering av användargränssnitt för selektorer, inmatningsmetoder och asserteringar.

Samordna arbetsflöden för användargränssnitt i sandbox-miljön

Använd en WINAPP_UI_WORKFLOW_ID för samarbetskommandon och ett annat värde för varje oberoende arbetsflöde. Ställ in det vid varje anrop, särskilt när agenten startar ett nytt skal för varje verktygsanrop. winapp vidarebefordrar en hashad identitet som är specifik för sandbox-generationen; det råa värdvärdet skickas inte till gästen.

Du kan till exempel registrera och interagera i två terminaler med samma värde. Välj ett nytt värde för varje nytt arbetsflöde.

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, medan inspelningen körs:

$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

När både inspelningen och åtgärderna har slutförts:

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

Ett namngivet arbetsflöde behåller sin UI-sväng i fyra sekunder efter det sista kommandot. yield släpper den omedelbart. Utan ett ID släpper varje kommando sin tur vid slutförande. En no-ID inspelning blockerar därför andra arbetsflöden som ändras av skrivbordet under dess varaktighet. Skrivskyddad inspektion väntar inte. Värd- och gästgränssnittssvängar är separata.

Efter en paus kontrollerar du igen och öppnar valfri meny eller dialogruta som du behöver: ett annat arbetsflöde kan ha använt gästskrivbordet. Samarbetssvängningar isolerar inte appar från varandra.

Skärmbilder och inspelningar

Använd ui skärmupptagning för ett appfönster eller target skärmupptagning för hela det inbyggda gästskrivbordet, inklusive skalet och installationsprogrammets dialogrutor:

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

Utdata hamnar på hosten, även när du utelämnar -o. Skärmbilder som standard är screenshot.png; inspelningar använder recording-<timestamp>-<guid>.mp4. För inspelningar levererar --frames också katalogen med JPEG:er, frames.ndjson och manifest.json. Resultaten rapporterar värdsökvägar. Målinspelningar körs i gästsystemet; värdfilerna blir tillgängliga när inspelningen är slutförd och leveransen är klar.

target screenshot väntar på gästens tur i användargränssnittet utan att aktivera något fönster. Det exkluderar värdsandbox-fönstrets namnlist och kantlinjer. Dess PNG-bild är oskalad: med (0,0) som gästskärmens ursprung kan bildkoordinater användas direkt av verb för koordinatinmatning som ui drag eller ui touch --at, med --on sandbox. Lägg till det rapporterade ursprunget för ett skrivbord med ett negativt ursprung. Använd --json för att läsa coordinates.sourceBounds och coordinates.contentRect; båda använder fysiska bildpunkter och exklusiva höger-/nedre kanter.

Målinspelningar rapporterar samma fält i JSON och rammanifestet. MP4- och JPEG-bildrutor använder samma mappning, inklusive --max-edge skalning och utfyllnad i kodaren. Om du vill mappa bildpixel (x,y)avvisar du först punkter utanför contentRectoch beräknar sedan varje källkoordinat som sourceStart + floor((pixel - contentStart + 0.5) * sourceSize / contentSize). Nedskalning förlorar precision; använd en intern PNG när exakta koordinater spelar roll. En ändring av gästskrivbordets gränser stoppar inspelningen med display_changed, bevarar endast bildrutor från före ändringen och markerar bildrutemanifestet partiellt.

En befintlig MP4- eller parkopplad .frames katalog avvisas som standard. Använd en ny sökväg eller skicka --overwrite för att ersätta dem när den nya tagning har slutförts. Tidigare rampaket behålls som <output-name>.frames.previous-<id>, inklusive när ersättningen utelämnar --frames. En misslyckad avbildning lämnar den gamla inspelningen intakt.

Föredrar ett positivt --duration-sec för skript och agenter. npm uiRecord och targetRecord-hjälpprogrammen kräver durationSec; deras avbrottssignal avbryter med tvång, inte som ett mjukt stopp. Se ui record för värden som stöds. Utan en angiven varaktighet via CLI väntar inspelningen på en stoppsignal.

Ctrl+C efter att inspelningen har startat kan slutföra inspelningen och returnera den med stopReason: cancelled. Andra avbrott kan spara användbar video eller användbara bildrutor. Läs stopReason, partialOutput, och recoveryHint när de finns och använd de rapporterade bevissökvägarna i stället för att anta ett normalt slutförande. Om helskrivbordsavbildningen blir otillgänglig under en tagning slutar den med capture_unavailable i stället för att fortsätta att avbilda ett otillgängligt skrivbord. Den tar inte sandbox-miljön till förgrunden för att rädda en ram. Avbildningen kan misslyckas innan några användbara bevis är tillgängliga.

För en gästinspelning som misslyckats placeras återställd bevisning i en unik <output>.partial-<id>-katalog på värden. Om leveransen misslyckas finns de mottagna filerna kvar på den rapporterade återställningssökvägen, till exempel <output>.recovery-<id>, och gästernas originalfiler behålls. Håll sandbox-miljön igång och följ återställningsåtgärden för felet innan du försöker igen eller stänger den. En bevarad partiell fil är inte nödvändigtvis en uppspelningsbar video.

Skärmbilder och video kan innehålla känslig information. Hantera katalogen med bildrutor med samma omsorg som MP4-filen. Se ui record för inspelningsalternativ och resultatfält.

Granska sandlådemiljön

winapp target snapshot sandbox
winapp target snapshot sandbox --json

Detta rapporterar beredskap, aktuella distributioner och gästfönster utan att skapa en virtuell dator, återansluta klienten eller reparera agenten. Om ingen Sandbox körs, rapporterar den detta och avslutas utan fel. Om du vill starta en använder du winapp run . --on sandbox --detach.

Rapporten skiljer vad gästen stöder från vad den aktuella klienten kan göra. en minimerad klient kan förhindra indata eller avbildning även när gästen stöder båda. Använd listan över gästfönster för PID:er för användargränssnittet, inte driftsättningens spårade startprocess. JSON-fältet workRoot (visas som Work root i textutdata) är den absoluta basen för relativa filöverföringssökvägar, vanligtvis C:\WinApp\work. Den är separat från capabilities.managedRoot, normalt C:\WinApp, och utesluts när gästen inte rapporterar sin hanterade rot. Om flera klientfönster förhindrar en entydig fångst listas kandidaterna i felmeddelandet; avgör vilka som ska stängas innan du försöker igen.

Köra kommandon och kopiera filer

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

Använd target exec för installation och diagnostik. Den körs som gästanvändare, vidarebefordrar standardströmmar och returnerar kommandots slutkod. Det är inte en fullständig interaktiv terminal. konsolprogram ser omdirigerade rör. --json formatterar fel från winapp, inte underkommandots stdout.

För push och pull, är målsökvägar relativa till workRoot som rapporteras av target snapshot. Absoluta sökvägar, sökvägar från rotkatalogen och UNC-sökvägar godtas inte. En enskild fil hamnar på exakt det mål som du namnger. en katalog bevarar sin struktur under målet. Använd den lösta gästsökvägen som skrivs ut efter en push (JSON targetPath) för att välja --cwd för nästa kommando; om det gäller en enskild fil använder du dess överordnade katalog. Om gästen inte rapporterar sin hanterade rot, misslyckas push innan kopieringen påbörjas; följ felmeddelandets anvisningar för uppdatering i stället för att förutsätta en standardsökväg.

Kör endast installationsskript som du litar på. I exemplet används -ExecutionPolicy Bypass på processnivå eftersom en ny sandbox normalt vägrar att köra skript enligt policyn Restricted.

Överföringar hoppar över oförändrade filer och verifierar ersättningar innan de publiceras. Symboliska länkar och korsningar följs inte: distributionen avvisar dem, medan katalogkopior hoppar över länkade poster. En direkt angiven länkad resurs eller en målsökväg via en länk avvisas. Kopiera de verkliga filerna eller katalogerna i stället.

Ta bort en app och avsluta sandlådan

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

Med ett manifest i den aktuella katalogen kan du utelämna --manifest. Detta tar bara bort det matchande utvecklingspaketet som registrerats av winapp i den aktuella sandbox-miljön. Ett externt installerat paket lämnas orört, även om identiteten matchar. --force stöds inte med --on. Det kan inte kringgå ägarskapskontroller. Det här är paketrensning baserad på manifest, inte ett kommando för avregistrering av appar utan paket eller indata från .cs.

Sandbox fortsätter att köras. Hantera dess livslängd med Windows sandbox-miljöns eget CLI:

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

Om du stoppar ignoreras gästen och dess arbete. Spara nödvändiga bevis först och få användarens medgivande innan du stoppar en instans som de kan använda. Efterföljande winapp-kommandon kan skapa en ny sandbox. Identifiera alla appmål på nytt efteråt.

Felsökning

Följ felets userAction. En rekommendation nextCommand är ett förslag, inte behörighet att köra det automatiskt. I automatisering granskar du den strukturerade error.code. Infrastrukturfel kan avsluta 70, men ett godtyckligt program kan också returnera 70. Enbart den numeriska avslutningsstatusen skiljer dem inte åt.

Återställningskommandon som föreslås av dirigerade åtgärder i användargränssnittet behåller --on <target>, så om du kopierar ett förslag behålls det på samma körningsmål.

Fel eller symptom Vad du bör göra
sandbox_unsupported Kontrollera Windows version/version och virtualisering av inbyggd programvara
sandbox_setup_required Aktivera Windows Sandbox med hjälp av anvisningarna ovan och starta sedan om när du är klar
sandbox_setup_requires_restart Windows rapporterar en väntande omstart; spara arbete och starta om när det är klart och försök sedan igen
sandbox_setup_incomplete Öppna Windows sandbox-miljö från Start och slutför klientkonfiguration/uppdatering och försök sedan igen
sandbox_unmanaged_instance, sandbox_target_ambiguous Inspektera rapporterade instanser/fönster; stoppa inte orelaterat arbete för att reda ut oklarheter
sandbox_input_not_ready, sandbox_no_interactive_session Återställ den befintliga klienten eller återanslut enligt anvisningarna och försök sedan igen
sandbox_agent_incompatible Följ anvisningarna i versionsfelmeddelandet; uppgradera det installerade CLI-verktyget med samma metod som användes för installationen om du uppmanas att göra det, och stäng och försök igen endast efter godkännande
sandbox_agent_busy Vänta tills ett annat kommando har slutförts och försök sedan igen
sandbox_terminated, sandbox_target_stale, sandbox_stale_handle Kör appen igen och återupptäcka gäst-PID:er/fönster
sandbox_state_unavailable Se till att %USERPROFILE%\.winapp\state är skrivbar eller korrigera WINAPP_TARGET_STATE_ROOT om den har ställts in
sandbox_deployment_dirty, sandbox_transfer_interrupted Försök att distribuera eller överföra igen
sandbox_runtime_provision_failed Åtgärda den namngivna beroendekonfigurationen eller den körningskonfiguration som inte stöds; se Delade körmiljöer
sandbox_package_conflict, sandbox_provisioned_package_conflict Följ den paketspecifika åtgärden. ta inte bort orelaterade paket eller inkorgspaket
sandbox_artifact_failed Kontrollera rapporterade utdata och klientberedskap. bevara eventuella partiella bevis
target_invalid, target_invalid_arguments Korrigera målet eller alternativen som visas i felet

winapp update uppdaterar projektets SDK-beroenden, inte det installerade CLI:et. Det är inte en korrigering för inkompatibilitet för värd-/gäst-CLI.

Delningsmål i Sandbox-version 28000

Den testade versionen 28000 av Sandboxen kan inte visa mål för delning. Testa andra appfunktioner i sandbox-miljön, men validera Share source-to-target-flöden utanför den.

Se även

  • Last updated on