Uitvoering van Windows Sandbox

Bouw op uw computer en voer vervolgens de app uit en automatiseer deze in Windows Sandbox:

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

Vervang door MyApp de naam van uw app of de gast-PID die wordt afgedrukt door run. --detach keert na het starten van de app terug, zodat de volgende opdracht de app kan inspecteren; zonder deze optie wacht run tot de app wordt afgesloten. De Sandbox blijft draaien tussen commando's en nieuwe builds.

Voordat u begint

  • Gebruik Windows 11 24H2 of hoger op een ondersteunde editie, waarbij hardwarevirtualisatie is ingeschakeld.
  • Gast-winapp ondersteunt x64 en Arm64. Voor een x86-app is gastondersteuning vereist voor het uitvoeren ervan en overeenkomende x86-afhankelijkheden; een x64-runtime voldoet niet aan een x86-app.
  • Houd de hostsessie ontgrendeld voor echte invoer en schermopname.

Schakel Windows Sandbox in Turn Windows-functies in of uit, of voer deze uit vanuit een beheerdersterminal:

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

Sla uw werk op en start Windows opnieuw wanneer u klaar bent. Open vervolgens Windows Sandbox vanuit het menu Start en voltooi de installatie of update van de client. winapp schakelt de functie niet in, installeert de client, vraagt uitbreiding aan of start Windows opnieuw. Als er vereisten ontbreken, stopt het proces en worden installatie-instructies weergegeven; een gedetecteerde wachtende herstart van Windows wordt afzonderlijk gemeld.

Een koude verbinding of opnieuw verbinding maken kan kort de focus nemen. Zodra er verbinding is gemaakt, houdt winapp zijn eigen clientvenster buiten het scherm zonder deze te activeren. Er blijft een sandboxvenster staan dat u zelf hebt geopend.

Important

Builds worden nog steeds uitgevoerd op uw computer. Project evaluatie, herstel en compilatie worden niet geïsoleerd. --on sandbox maakt een niet-vertrouwd project niet veilig om te bouwen.

Eén sandbox is één gedeelde omgeving. Apps en werkstromen hierin delen de gebruiker, desktop, register, pakketten, runtimes en netwerktoegang. Ze kunnen elkaar waarnemen of verstoren. Gebruik afzonderlijke machines voor onderling niet-vertrouwde werkstromen.

Windows staat slechts één sandbox tegelijk toe. winapp hergebruikt een actief exemplaar, inclusief een exemplaar dat u zelf hebt geopend. Door het voor te bereiden worden de gedeelde bootstrapmappen van winapp, de gastagent, de Ontwikkelaarsmodus en een inkomende firewallregel toegevoegd. winapp stopt een aangenomen exemplaar niet of verwijdert niet-gerelateerde apps. Er is geen stilzwijgende host-terugval: een opdracht die om uitvoering in de Sandbox vraagt, wordt daar uitgevoerd of mislukt.

Uitvoeren en opnieuw opbouwen

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

Buildopties zoals --configuration, --arch, --framework, --property, --no-restore en --no-build zijn van toepassing op de host. Registratie, starten en foutopsporing vinden plaats in de gast; de app is niet geregistreerd op uw computer.

Option Effect in Sandbox
--detach Terugkeren na het opstarten in plaats van te wachten tot het programma wordt afgesloten
--no-launch Implementeren en registreren zonder te starten
--clean Installeer deze implementatie opnieuw en wis de bijbehorende toepassingsgegevens
--unregister-on-exit Deze pakketregistratie verwijderen nadat de app is afgesloten
--with-alias Start de alias voor uitvoering als gast met doorgestuurde gegevensstromen
--debug-output Debug-uitvoer van gasten streamen; alleen verpakte apps

Uitgepakte apps starten hun uitvoerbare bestand uit de geïmplementeerde map. Ze hebben geen pakket dat ze kunnen registreren. --debug-output wordt geweigerd voor uitgepakte sandbox-uitvoeringen.

Bij het opnieuw uitvoeren van overdrachten worden gewijzigde bestanden overgedragen en worden bestanden verwijderd die zijn verwijderd uit de build-uitvoer. Toepassingsgegevens blijven behouden, tenzij u dit aanvraagt --clean. Een onvolledige implementatie wordt niet gestart; Als u het opnieuw probeert, wordt de gastkopie opnieuw opgebouwd. Als build-bestanden veranderen terwijl winapp ze voorbereidt, voltooit u de build en probeert u het opnieuw.

Warme UI-opdrachten rapporteren alleen hun resultaat, zonder een sandboxvoorbereidingsbericht te herhalen. Het opstarten van de sandbox en het herstel van de verbinding geven nog steeds voortgang aan. Gebruik --verbose voor timinggegevens van verbindingen en diagnostische details; --quiet en --json onderdrukken de voortgang. JSON-uitvoeringen omvatten een gastproces-id en doelbereik:

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

Dit zijn extra velden in het uitvoeringsresultaat, niet een afzonderlijk document. Kopieer de hele UiTargetArgs waarde bij het inspecteren van de app: winapp ui inspect --on sandbox -a 4212. Ontdek PID’s en windowhandles opnieuw nadat de Sandbox opnieuw wordt aangemaakt; ze behoren tot die generatie van de Sandbox, niet tot de host of een toekomstige gast.

Ontkoppelde apps en de levensduur van de agent

Een losstaande niet-verpakte app wordt beëindigd als de guest agent stopt, ook tijdens herstel van de agent. Als deze tussen opdrachten verdwijnt, voer deze dan opnieuw uit met --detach en ontdek het UI-doel opnieuw. Als u op de app wacht in plaats van deze los te koppelen, kunt u zien wanneer deze wordt afgesloten; dat zorgt er niet voor dat de app blijft draaien als de agent wegvalt. Verpakte apps maken gebruik van Windows-activering in plaats van de looptijd van het proces van de agent. Als u de sandbox sluit of opnieuw start, worden alle apps erin beëindigd.

Gedeelde runtimes

winapp controleert de pakketafhankelijkheden van de app, Windows App SDK vereisten en *.runtimeconfig.json voordat ze worden gestart. Het maakt gebruik van hostcaches of downloadt de benodigde pakketten en installeert vervolgens ontbrekende ondersteunde runtimes in de gast, niet op uw computer.

Pakketvereisten omvatten uitgever, versie en architectuur. Gedeelde .NET runtimeselectie houdt rekening met het geconfigureerde roll-forward-beleid en de architectuur van de toepassing. Er wordt niet uitgegaan dat er een nieuwere runtime in dezelfde primaire versie werkt.

Als een framework, runtimeconfiguratie of afhankelijkheid niet kan worden ondersteund, mislukt de opdracht expliciet voordat deze wordt gestart en wordt de vereiste geïdentificeerd. Volg de actie van die fout. Wanneer dit wordt ondersteund door uw project, verwijdert het publiceren van zelfstandige inhoud de noodzaak voor de bijbehorende gedeelde runtime; hiermee worden niet-gerelateerde pakketafhankelijkheden niet verwijderd.

De gebruikersinterface automatiseren

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

Elke ui werkwoord accepteert --on sandbox. App-namen, PID's, vensterhandles en selectors worden in de gastomgeving opgelost. Gebruik -a/--app of -w/--window voor opdrachten die zijn gericht op apps; winapp raadt niet de laatste app die is gestart. Als u --on sandbox weglaat, wordt in plaats daarvan uw hostbureaublad geselecteerd.

Voor echte invoer en opname is een verbonden, niet-geïnminimiseerde Sandbox-client vereist. Inspectie met alleen-lezen-toegang kan nog steeds werken als invoer niet mogelijk is. winapp kan zijn eigen geminimaliseerde client herstellen zonder activering; een geminimaliseerde handmatig geopende client moet door u worden hersteld. Als de invoer niet beschikbaar is nadat u opnieuw verbinding hebt gemaakt, mislukt de opdracht in plaats van de geleverde invoer te claimen. Gebruik de opdracht 'Opnieuw verbinden' in de foutmelding en probeer het daarna opnieuw.

Gebruik winapp target snapshot sandbox --json dit om de gereedheid van het bureaublad te controleren zonder de sandbox te starten of opnieuw te verbinden. Gedetecteerde terminalfoutvensters tellen niet mee als externe bureaubladen. Als winapp het geselecteerde bureaublad niet kan verifiëren omdat het nog steeds verbinding maakt of niet kan worden geïnspecteerd, blijft gereedheid niet beschikbaar; wacht en probeer het opnieuw. Meerdere externe desktops kunnen nog steeds verwarrend zijn. Momentopname sluit geen vensters of lost de bijbehorende fouten voor u op.

Zie UI-automatisering voor selectors, invoermethoden en asserties.

Ui-werkstromen coördineren in de sandbox

Gebruik één WINAPP_UI_WORKFLOW_ID voor samenwerkende opdrachten, en een andere waarde voor elke onafhankelijke werkstroom. Stel deze in bij elke aanroep, met name wanneer uw agent een nieuwe shell start voor elke aanroep van het hulpprogramma. winapp stuurt een gehashte, sandbox-generatie specifieke identiteit door; de onbewerkte hostwaarde wordt niet naar de gast verzonden.

Registreer en communiceer bijvoorbeeld in twee terminals met dezelfde waarde. Kies een nieuwe waarde voor elke nieuwe werkstroom.

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, terwijl de opname wordt uitgevoerd:

$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

Zodra zowel de opname als de acties zijn voltooid:

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

Een benoemde werkstroom behoudt zijn UI-beurt gedurende vier seconden na de laatste opdracht; yield geeft die onmiddellijk vrij. Zonder ID geeft elke opdracht na voltooiing zijn beurt vrij. Een no-ID-opname blokkeert daarom andere processen die het bureaublad wijzigen zolang die opname duurt. Inspectie in alleen-lezenmodus hoeft niet te wachten. De beurten van de host- en gastgebruikersinterface zijn gescheiden.

Na een pauze controleert u opnieuw en opent u een menu of dialoogvenster dat u nodig hebt: mogelijk heeft een andere werkstroom het gastwerkblad gebruikt. Coöperatieve beurten isoleren geen apps van elkaar.

Schermafbeeldingen en opnamen

Gebruik ui om het venster van een app vast te leggen, of target om het volledige systeemeigen bureaublad van de gast vast te leggen, inclusief de shell en de dialoogvensters van het installatieprogramma:

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

Uitvoer landt op de host, inclusief wanneer u weglaat -o. Schermafbeeldingen gebruiken standaard screenshot.png; opnamen gebruiken recording-<timestamp>-<guid>.mp4. Voor opnamen --frames levert u ook de <output-name>.frames map met JPEG's en frames.ndjsonmanifest.json. Rapport met host-paden Doelopnames worden uitgevoerd in de gastomgeving; de bijbehorende hostbestanden komen beschikbaar nadat de opname is voltooid en de overdracht is afgerond.

target screenshot wacht op de UI-beurt van de gast zonder een venster te activeren. Het sluit de titelbalk en randen van het host sandbox-venster uit. De PNG is ongeschaald: met de oorsprong van het gastscherm op (0,0) kunnen afbeeldingscoördinaten direct worden gebruikt met coördinaatinvoeropdrachten zoals ui drag of ui touch --at, met --on sandbox. Voeg de gerapporteerde oorsprong voor een bureaublad toe met een negatieve oorsprong. Gebruik --json om coordinates.sourceBounds en coordinates.contentRect te lezen; beide gebruiken fysieke pixels en exclusieve rechter-/onderranden.

Doelopnamen rapporteren dezelfde velden in JSON en het framemanifest. MP4- en JPEG-frames gebruiken dezelfde mapping, inclusief --max-edge schaling en padding van de encoder. Als u de afbeeldings pixel (x,y)wilt toewijzen, wijst u eerst punten buiten contentRectaf en berekent u vervolgens elke broncoördinaat als sourceStart + floor((pixel - contentStart + 0.5) * sourceSize / contentSize). Omlaag schalen verliest precisie; gebruik een systeemeigen PNG wanneer exacte coördinaten van belang zijn. Een wijziging in de grenzen van het gastwerkblad stopt de opname met display_changed, waarbij alleen frames van vóór de wijziging behouden blijven en het framemanifest gedeeltelijk worden gemarkeerd.

Een bestaande MP4- of gekoppelde .frames map wordt standaard geweigerd. Gebruik een nieuw pad of geef --overwrite mee om ze te vervangen nadat de nieuwe opname is voltooid. Eerdere framebundels worden bewaard als <output-name>.frames.previous-<id>, inclusief wanneer de vervanging weglaat --frames. Een mislukte opname laat de oude opname intact.

Geef de voorkeur aan een positief --duration-sec voor scripts en agents. De npm uiRecord en targetRecord helpers vereisen durationSec; hun afgebroken signaal annuleert geforceerd, niet als een sierlijke stop. Zie ui record voor ondersteunde waarden. Zonder een via de CLI opgegeven duur blijft de opname doorgaan tot er een stopsignaal wordt gegeven.

Ctrl+C nadat de opname is gestart, kan een opname met succes worden voltooid en geretourneerd.stopReason: cancelled Andere onderbrekingen kunnen nuttige video of frames behouden. Lees stopReason, partialOutput en recoveryHint indien aanwezig, en gebruik de gerapporteerde paden naar het bewijsmateriaal in plaats van uit te gaan van een normale voltooiing. Als de volledige bureaubladopname tijdens een take niet meer beschikbaar is, stopt deze met capture_unavailable in plaats van door te gaan met het vastleggen van een niet-beschikbaar bureaublad. De sandbox wordt niet op de voorgrond geplaatst om een frame te redden. Vastleggen kan mislukken voordat bruikbaar bewijs beschikbaar is.

Voor een mislukte gastopname wordt hersteld bewijs in een unieke <output>.partial-<id> map op de host geplaatst. Als de levering mislukt, blijven ontvangen bestanden op het gerapporteerde herstelpad staan, zoals <output>.recovery-<id>, en blijven de originele gastbestanden behouden. Houd de sandbox actief en volg de herstelactie van de fout voordat u deze opnieuw probeert of sluit. Een behouden gedeeltelijk bestand is niet noodzakelijkerwijs een afspeelbare video.

Schermopnamen en video kunnen gevoelige informatie bevatten. Behandel de map met frames met dezelfde zorgvuldigheid als de MP4. Zie ui record voor opnameopties en resultaatvelden.

De sandbox inspecteren

winapp target snapshot sandbox
winapp target snapshot sandbox --json

Deze rapporteert gereedheid, huidige implementaties en gastvensters zonder een VIRTUELE machine te maken, opnieuw verbinding te maken met de client of de agent te herstellen. Als er geen Sandbox actief is, wordt dat gemeld en wordt het programma succesvol afgesloten. Als u er een wilt starten, gebruikt u winapp run . --on sandbox --detach.

Het rapport onderscheidt wat de gast ondersteunt van wat de huidige client kan doen; een geminimaliseerde client kan invoer of vastleggen voorkomen, zelfs wanneer de gast beide ondersteunt. Gebruik de gastvensterlijst voor UI-PID's, niet het bijgehouden opstartproces van een implementatie. Het JSON-veld workRoot (zoals in Work root de tekstuitvoer) is de absolute basis voor relatieve bestandsoverdrachtpaden, normaal gesproken C:\WinApp\work. Deze staat los van capabilities.managedRoot, normaal C:\WinApp, en wordt weggelaten wanneer de gast de beheerde root niet doorgeeft. Als meerdere clientvensters een eenduidige opname onmogelijk maken, vermeldt de foutmelding de mogelijke kandidaten; bepaal welke u wilt sluiten voordat u het opnieuw probeert.

Opdrachten uitvoeren en bestanden kopiëren

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

Gebruiken target exec voor installatie en diagnostische gegevens. Deze wordt uitgevoerd als gastgebruiker, stuurt standaardstreams door en retourneert de afsluitcode van de opdracht. Het is geen volledige interactieve terminal; consoletoepassingen zien omgeleide pijpen. --json formatteert winapp-foutmeldingen, niet de stdout van het onderliggende commando.

Voor pull en workRoot zijn push. Absolute doelpaden, doelpaden met een hoofdmap en UNC-doelpaden worden niet geaccepteerd. Eén bestand landt precies op de bestemming die u noemt; een map behoudt de structuur onder die bestemming. Gebruik het opgeloste gastpad dat na een push (JSON targetPath) wordt weergegeven om de --cwd van de volgende opdracht te kiezen; gebruik voor één bestand de bovenliggende map ervan. Als de gast de beheerde hoofdmap niet rapporteert, mislukt het pushen al vóór het kopiëren; volg de update-instructies in de foutmelding in plaats van uit te gaan van een standaardpad.

Voer alleen installatiescripts uit die u vertrouwt. In het voorbeeld wordt -ExecutionPolicy Bypass met procesbereik gebruikt, omdat een nieuwe Sandbox scripts normaal gesproken weigert op grond van het beleid Restricted.

Overdrachten slaan ongewijzigde bestanden over en controleren de vervangingen voordat ze worden gepubliceerd. Symbolische koppelingen en knooppunten worden niet gevolgd: de implementatie weigert deze, terwijl directorykopieën gekoppelde vermeldingen overslaan. Een rechtstreeks benoemde gekoppelde bron of een doelpad via een koppeling wordt geweigerd. Kopieer in plaats daarvan de echte bestanden of mappen.

Een app verwijderen en de sandbox beëindigen

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

Met een manifest in de huidige map kunt u weglaten --manifest. Hiermee verwijdert u alleen het overeenkomende ontwikkelingspakket dat is geregistreerd door winapp in de huidige sandbox. Een extern geïnstalleerd pakket wordt alleen gelaten, zelfs als de identiteit overeenkomt. --force wordt niet ondersteund met --on; het kan eigendomscontroles niet omzeilen. Dit is pakketopschoning op basis van een manifest, geen opdracht om de registratie van apps zonder pakket ongedaan te maken of een invoer van .cs.

De sandbox blijft actief. Beheer de levensduur ervan met de eigen CLI van Windows Sandbox:

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

Als u stopt, worden de gast en het bijbehorende werk verwijderd. Sla eerst het benodigde bewijsmateriaal op en verkrijg toestemming van de gebruiker voordat u een instantie stopt die de gebruiker mogelijk gebruikt. Latere winapp-opdrachten kunnen een nieuwe Sandbox aanmaken; ontdek daarna alle app-doelen opnieuw.

Troubleshooting

Volg de aanwijzing van de fout userAction; een aanbeveling nextCommand is een suggestie, geen toestemming om die automatisch uit te voeren. Inspecteer bij automatisering de gestructureerde error.code. Infrastructuurfouten kunnen afsluiten met 70, maar een willekeurige toepassing kan ook 70 retourneren; alleen op basis van de numerieke afsluitstatus kan geen onderscheid tussen beide worden gemaakt.

Herstelopdrachten die worden voorgesteld door gerouteerde UI-bewerkingen behouden --on <target>, zodat het kopiëren van een suggestie hetzelfde uitvoeringsdoel behoudt.

Fout of symptoom Wat moet u doen?
sandbox_unsupported Controleren Windows editie/versie en firmwarevirtualisatie
sandbox_setup_required Schakel Windows sandbox in met behulp van de bovenstaande instructies en start deze opnieuw wanneer u klaar bent
sandbox_setup_requires_restart Windows meldt dat opnieuw opstarten is vereist; sla uw werk op en start de computer opnieuw op wanneer u klaar bent. Probeer het daarna opnieuw.
sandbox_setup_incomplete Open Windows Sandbox via Start en voltooi de installatie/update van de client, en probeer het daarna opnieuw
sandbox_unmanaged_instance, sandbox_target_ambiguous Inspecteer de gerapporteerde exemplaren/vensters; niet stoppen met niet-gerelateerd werk om dubbelzinnigheid op te lossen
sandbox_input_not_ready, sandbox_no_interactive_session Herstel de bestaande client of maak opnieuw verbinding zoals aangegeven en probeer het vervolgens opnieuw
sandbox_agent_incompatible Volg de instructies in de versiefoutmelding; werk de geïnstalleerde CLI zo nodig bij met de bijbehorende installatiemethode en sluit de toepassing alleen af of probeer het alleen opnieuw met toestemming
sandbox_agent_busy Wacht tot een andere opdracht is voltooid en probeer het opnieuw
sandbox_terminated, sandbox_target_stale, sandbox_stale_handle De app opnieuw uitvoeren en gast-PID's/windows opnieuw ontdekken
sandbox_state_unavailable Controleer of %USERPROFILE%\.winapp\state schrijfbaar is, of corrigeer WINAPP_TARGET_STATE_ROOT indien ingesteld
sandbox_deployment_dirty, sandbox_transfer_interrupted De implementatie of overdracht opnieuw uitvoeren
sandbox_runtime_provision_failed Los de benoemde afhankelijkheid of de niet-ondersteunde runtimeconfiguratie op; zie Gedeelde runtimes
sandbox_package_conflict, sandbox_provisioned_package_conflict Volg de pakketspecifieke actie; verwijder geen niet-gerelateerde of inboxpakketten
sandbox_artifact_failed Controleer de gerapporteerde uitvoer en clientgereedheid; eventuele gedeeltelijke bewijzen behouden
target_invalid, target_invalid_arguments Corrigeer het doel of de opties die in de foutmelding worden weergegeven

winapp update werkt project-SDK-afhankelijkheden bij, niet de geïnstalleerde CLI. Het is geen oplossing voor incompatibiliteit van de host/gast-CLI.

Doelen delen in de build 28000 Sandbox

De geteste build 28000 Sandbox kan share-doelen niet inventariseren. Test andere app-functies in Sandbox, maar valideer de bron-naar-doelstromen van Share daarbuiten.

Zie ook

  • Last updated on