spuštění sandboxu Windows

Sestavte na svém počítači a pak aplikaci spusťte a automatizujte v Windows Sandboxu:

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

Nahraďte MyApp názvem vaší aplikace nebo kódem PID hosta vytištěným run. --detach se po spuštění vrátí, takže další příkaz může aplikaci zkontrolovat; bez něj run čeká, dokud se aplikace neukončí. Sandbox zůstává spuštěná mezi jednotlivými příkazy i po opětovných sestaveních.

Než začnete

  • V podporované edici používejte Windows 11 24H2 nebo novější s povolenou virtualizací hardwaru.
  • Hostovaná aplikace winapp podporuje x64 a ARM64. Aplikace x86 vyžaduje pro spuštění podporu v hostovaném systému a odpovídající závislosti x86; běhové prostředí x64 pro aplikaci x86 nestačí.
  • Ponechte hostitelskou relaci odemknutou, aby byl možný skutečný vstup a snímání obrazovky.

Povolení Windows sandboxu v zapnutí nebo vypnutí funkcí Windows nebo spuštění z terminálu správce:

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

Uložte si práci a restartujte Windows, až budete připraveni. Potom otevřete Windows Sandbox z nabídky Start a dokončete instalaci nebo aktualizaci klienta. winapp tuto funkci nepovoluje, neinstaluje klienta, nevyžaduje zvýšení oprávnění ani nerestartuje systém Windows. Pokud chybí předpoklady, proces se zastaví a zobrazí pokyny k nastavení; zjištěný čekající restart systému Windows je hlášen samostatně.

Nové připojení nebo opětovné připojení může krátce převzít fokus. Po připojení winapp ponechá vlastní okno klienta mimo obrazovku, aniž by ho aktivovala. Okno sandboxu, které jste otevřeli sami, je ponecháno na místě.

Important

Buildy stále běží na vašem počítači. Vyhodnocení projektu, obnovení a kompilace neprobíhají izolovaně. --on sandbox nezajišťuje, že nedůvěryhodný projekt je bezpečný k sestavení.

Jeden sandbox je jedno sdílené prostředí. Aplikace a pracovní postupy v něm sdílejí uživatele, desktop, registr, balíčky, moduly runtime a síťový přístup. Můžou se vzájemně pozorovat nebo se vzájemně ovlivňovat. Pro vzájemně nedůvěryhodné pracovní postupy používejte samostatné počítače.

Windows umožňuje současně jeden sandbox. Winapp znovu použije spuštěnou instanci, včetně instance, kterou jste otevřeli sami. Při přípravě se přidají sdílené zaváděcí složky aplikace winapp, agent pro hosta, Režim pro vývojáře a příchozí pravidlo firewallu. Winapp nezastaví přijatou instanci ani neodebere nesouvisející aplikace. Neexistuje tichý záložní hostitel: příkaz, který požaduje spuštění v Sandboxu, se tam spustí, nebo selže.

Spuštění a opětovné sestavení

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

Možnosti sestavení, například --configuration, --arch, --framework, --property, --no-build a --no-restore, platí pro hostitele. Registrace, spuštění a ladění probíhá v hostu; aplikace není na vašem počítači zaregistrovaná.

Option Efekt v sandboxu
--detach Vraťte se po spuštění a nečekejte na ukončení.
--no-launch Nasazení a registrace bez spuštění
--clean Přeinstalujte toto nasazení a vymažte data aplikace.
--unregister-on-exit Odebrat registraci balíčku po ukončení aplikace
--with-alias Spuštění aliasu spuštění hosta s přesměrovanými datovými proudy
--debug-output Streamovat ladicí výstup hosta; pouze balíčkové aplikace

Rozbalené aplikace spustí spustitelný soubor z nasazené složky. Nemají k registraci žádný balíček. --debug-output se pro spuštění Sandboxu bez balíčku nepodporuje.

Opětovné obnovení přenese změněné soubory a odebere soubory odstraněné z výstupu sestavení. Data aplikace se zachovají, pokud o to nepožádáte --clean. Nekompletní nasazení se nespustí; opakování pokusu znovu sestaví jeho kopii hostovaného systému. Pokud se soubory sestavení změní, zatímco je winapp připravuje, dokončete sestavení a zkuste to znovu.

Teplé příkazy uživatelského rozhraní hlásí pouze jejich výsledek, aniž by se opakovala zpráva o přípravě sandboxu. Spuštění sandboxu a obnovení připojení stále zobrazují průběh. Slouží --verbose k časování připojení a diagnostickým podrobnostem --quiet a --json potlačení průběhu. Spuštění JSON zahrnují ID procesu hosta a cílový obor:

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

Jedná se o další pole ve výsledku spuštění, nikoli samostatný dokument. Při kontrole aplikace zkopírujte celou UiTargetArgs hodnotu: winapp ui inspect --on sandbox -a 4212. Znovu zjišťovat PIDy a popisovače oken po opětovném vytvoření Sandboxu; patří k této generaci Sandboxu, nikoli hostiteli ani budoucímu hostu.

Odpojené aplikace a životnost agenta

Samostatná nebalená aplikace se ukončí, pokud se agent hosta zastaví, a to i během opravy agenta. Pokud mezi příkazy zmizí, spusťte ho znovu pomocí --detach a znovu najděte jeho cíl v uživatelském rozhraní. Čekání na aplikaci namísto odpojení vám umožní sledovat její ukončení; nezajistí však, že aplikace přežije ztrátu agenta. Balíčkové aplikace používají aktivaci systému Windows namísto životnosti procesu agenta. Zavření nebo restartování sandboxu ukončí všechny aplikace uvnitř.

Sdílená běhová prostředí

Winapp zkontroluje závislosti balíčků aplikace, Windows App SDK požadavky a *.runtimeconfig.json před spuštěním. Používá mezipaměti hostitelů nebo stahuje potřebné datové části a pak nainstaluje chybějící podporované moduly runtime v hostu, ne na váš počítač.

Požadavky na balíček zahrnují vydavatele, verzi a architekturu. Výběr sdíleného prostředí .NET Runtime respektuje nakonfigurované zásady přechodu na novější verzi a architekturu aplikace; nepředpokládejte, že bude fungovat jakékoli novější prostředí runtime v rámci stejné hlavní verze.

Pokud framework, konfiguraci modulu runtime nebo závislost nelze podporovat, příkaz před spuštěním explicitně selže a uvede daný požadavek. Postupujte podle akce této chyby. Pokud to váš projekt podporuje, publikování jako samostatné nasazení eliminuje potřebu odpovídajícího sdíleného modulu runtime; neodstraní však nesouvisející závislosti balíčků.

Automatizace uživatelského rozhraní

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

Každé ui sloveso přijímá --on sandbox. Názvy aplikací, identifikátory procesů (PID), popisovače oken a selektory jsou určovány uvnitř hostovaného systému. Použití -a/--app nebo -w/--window pro příkazy cílené na aplikaci; winapp neuhodne poslední spuštěnou aplikaci. Pokud --on sandbox vynecháte, místo toho se vybere desktop hostitelského systému.

Skutečný vstup a záznam vyžadují připojeného neminimizovaného klienta sandboxu. Inspekce pouze pro čtení může stále fungovat, i když vstup nelze použít. WinApp může obnovit vlastní minimalizovaný klient bez aktivace; Minimalizovaný ručně otevřený klient musí být obnoven vámi. Pokud vstup po opětovném připojení není k dispozici, příkaz selže, místo aby tvrdil, že vstup doručil. V chybě použijte příkaz pro opětovné připojení a zkuste to znovu.

Pomocí winapp target snapshot sandbox --json zkontrolujte připravenost desktopu bez spuštění nebo opětovného připojení Sandboxu. Rozpoznaná okna s terminálovou chybou se nepovažují za vzdálené plochy. Pokud winapp nemůže ověřit vybranou plochu, protože se stále připojuje nebo ji nelze zkontrolovat, připravenost zůstane nedostupná; počkejte a zkuste to znovu. Několik vzdálených ploch může být stále nejednoznačné. Snímek nezavírá okna ani nevyřešuje jejich chyby za vás.

Viz automatizaci UI, kde najdete selektory, metody zadávání vstupu a ověření.

Koordinace pracovních postupů uživatelského rozhraní v sandboxu

Použijte jednu WINAPP_UI_WORKFLOW_ID pro spolupracující příkazy a pro každý nezávislý pracovní postup použijte jinou hodnotu. Nastavte jej při každém spuštění, zejména když váš agent pro každé volání nástroje spouští nový shell. winapp přeposílá hashovanou identitu specifickou pro generaci Sandboxu; nezpracovaná hodnota hostitele se guestovi neodesílá.

Můžete například zaznamenat a interagovat ve dvou terminálech pomocí stejné hodnoty. Zvolte novou hodnotu pro každý nový pracovní postup.

Terminál 1:

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

Terminál 2, zatímco je záznam spuštěný:

$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

Po dokončení nahrávání i akcí:

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

Pojmenovaný pracovní postup si zachová svůj tah v uživatelském rozhraní čtyři sekundy po posledním příkazu; yield jej okamžitě uvolní. Bez ID každý příkaz po dokončení uvolní svou řadu. Záznam bez ID proto po celou dobu svého trvání blokuje další postupy pro změnu plochy. Kontrola jen pro čtení nečeká. Otočení hostitelského a hostovaného uživatelského rozhraní jsou oddělená.

Po chvíli vše znovu zkontrolujte a znovu otevřete všechny nabídky nebo dialogová okna, která potřebujete: jiný proces mohl použít pracovní plochu hosta. Kooperativní střídání neizoluje aplikace navzájem.

Snímky obrazovek a nahrávky

Použijte ui zachycení pro okno aplikace nebo target zachytávání pro celou nativní plochu hosta, včetně dialogových oken prostředí a instalačního programu:

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

Výstupy skončí na hostiteli, i když -o vynecháte. Snímky obrazovky ve výchozím nastavení používají screenshot.png; nahrávky používají recording-<timestamp>-<guid>.mp4. Pro nahrávky --frames také poskytuje adresář <output-name>.frames obsahující soubory JPEG, frames.ndjson a manifest.json. Sestava výsledků uvádí cesty hostitele. Cílové nahrávky běží v hostu; jejich hostitelské soubory budou dostupné po dokončení nahrávání a dokončení doručení.

target screenshot čeká na zapnutí uživatelského rozhraní hosta bez aktivace jakéhokoli okna. Nezahrnuje záhlaví okna Sandbox hostitele ani jeho okraje. Jeho obrázek PNG není škálovaný: při počátku obrazovky hosta (0,0) lze souřadnice obrázku přímo použít se vstupními příkazy zadávanými souřadnicemi, jako jsou ui touch --at nebo ui drag, s --on sandbox. Přidejte nahlášený původ pro plochu s negativním původem. Použijte --json ke čtení coordinates.sourceBounds a coordinates.contentRect; oba používají fyzické pixely a exkluzivní pravý/dolní okraj.

Cílové nahrávky uvádějí stejná pole v JSON a v manifestu snímků. Snímky MP4 a JPEG používají stejné mapování, včetně škálování --max-edge a výplně kodéru. Pokud chcete namapovat pixel (x,y)obrázku , nejprve odmítněte body mimo contentRect, pak vypočítáte každou souřadnici zdroje jako sourceStart + floor((pixel - contentStart + 0.5) * sourceSize / contentSize). Při zmenšení dochází ke ztrátě přesnosti; pokud jsou důležité přesné souřadnice, použijte původní PNG. Změna hranic plochy hosta zastaví nahrávání pomocí display_changed, přičemž se zachovají pouze snímky pořízené před touto změnou a manifest snímků se označí jako neúplný.

Existující adresář MP4 nebo spárovaný .frames adresář se ve výchozím nastavení odmítne. Použijte novou cestu nebo zadejte --overwrite, čímž je nahradíte po dokončení nového záznamu. Předchozí svazky rámce jsou zachovány jako <output-name>.frames.previous-<id>, včetně případů, kdy nahrazení vynechá --frames. Neúspěšné zachycení ponechá původní záznam nedotčený.

Upřednostněte pozitivní --duration-sec pro skripty a agenty. Pomocné nástroje npm uiRecord a targetRecord vyžadují durationSec; jejich signál pro přerušení vynutí okamžité zrušení, nikoli šetrné ukončení. Viz ui record podporované hodnoty. Bez zadání doby trvání v příkazovém řádku nahrávání čeká na signál k zastavení.

Ctrl+C po spuštění záznamu může dokončit a vrátit záznam úspěšně s stopReason: cancelled. Jiné přerušení může zachovat užitečné video nebo snímky. Přečtěte si partialOutput, recoveryHint a stopReason, jsou-li k dispozici, a používejte nahlášené cesty k důkazům namísto předpokladu běžného dokončení. Pokud během záznamu přestane být snímání celé plochy k dispozici, zastaví se s capture_unavailable místo toho, aby pokračovalo v zachytávání nedostupné plochy. Nepřináší sandbox do popředí k záchraně rámce. Zachycení může selhat, než budou k dispozici všechny použitelné důkazy.

V případě neúspěšného záznamu hosta se obnovená data uloží do samostatného adresáře <output>.partial-<id> v hostitelském systému. Pokud se doručení nezdaří, přijaté soubory zůstanou v uvedené cestě pro obnovení, například <output>.recovery-<id>, a původní soubory hosta budou zachovány. Nechte Sandbox v chodu a než akci zopakujete nebo jej zavřete, postupujte podle pokynů k obnovení po chybě. Uložený neúplný soubor nemusí být nutně přehratelné video.

Snímky obrazovky a video můžou obsahovat citlivé informace. Zpracujte adresář s rámečkem se stejnou opatrností jako u mp4. Podívejte se ui record na možnosti záznamu a pole výsledků.

Zkoumání sandboxu

winapp target snapshot sandbox
winapp target snapshot sandbox --json

Tato sestava hlásí připravenost, aktuální nasazení a okna hosta bez vytvoření virtuálního počítače, opětovného připojení klienta nebo opravy agenta. Když není spuštěný žádný sandbox, oznámí tuto skutečnost a úspěšně se ukončí. Pokud ho chcete spustit, použijte winapp run . --on sandbox --detach.

Zpráva rozlišuje mezi tím, co host podporuje, a tím, co aktuální klient dokáže; minimalizovaný klient může zabránit vstupu nebo snímání, i když host podporuje obojí. Pro PID uživatelského rozhraní použijte seznam oken hostovaného systému, nikoli sledovaný spouštěcí proces nasazení. Pole JSON workRoot (zobrazené jako Work root v textovém výstupu) je absolutní základ pro relativní cesty přenosu souborů, obvykle C:\WinApp\work. Je oddělená od capabilities.managedRoot, obvykle C:\WinAppa je vynechána, pokud host nehlásí svůj spravovaný kořen. Pokud několik klientských oken brání jednoznačnému zachycení, seznam chyb uvede možné kandidáty; před dalším pokusem rozhodněte, která z nich zavřít.

Spouštění příkazů a kopírování souborů

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

Slouží target exec k nastavení a diagnostice. Spustí se jako uživatel typu host, přesměruje standardní datové proudy a vrátí ukončovací kód příkazu. Nejedná se o úplný interaktivní terminál; konzolové aplikace vidí přesměrované kanály. --json formátuje chybová hlášení winapp, nikoli standardní výstup (stdout) podřízeného příkazu.

Pro push a pull jsou cílové cesty relativní k workRoot, které hlásí target snapshot. Absolutní, kořenové a cílové cesty UNC jsou odmítnuty. Jeden soubor bude umístěn přesně do zadaného cílového umístění; adresář si v tomto cílovém umístění zachová svou strukturu. Pomocí vyhodnocené cesty hosta vypsané po provedení operace push (JSON targetPath) zvolte --cwd dalšího příkazu; v případě jednoho souboru použijte jeho nadřazený adresář. Pokud hostovaný systém neohlásí svůj spravovaný kořen, push selže ještě před kopírováním; namísto předpokládání výchozí cesty se řiďte pokyny k aktualizaci uvedenými v chybové zprávě.

Spusťte instalační skripty, kterým důvěřujete. Příklad používá -ExecutionPolicy Bypass s rozsahem procesu, protože nový sandbox obvykle odmítá skripty na základě zásady Restricted.

Přenosy přeskočí nezměněné soubory a před publikováním ověřují nahrazení. Symbolické odkazy a spojovací body se nenásledují: nasazení je odmítne, zatímco kopírování adresářů přeskočí odkazované položky. Přímo pojmenovaný propojený zdroj nebo cílová cesta prostřednictvím odkazu se odmítne. Místo toho zkopírujte skutečné soubory nebo adresáře.

Odebrání aplikace a ukončení sandboxu

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

Pokud je v aktuálním adresáři soubor manifestu, můžete vynechat --manifest. Tím se odebere pouze odpovídající vývojový balíček zaregistrovaný aplikací winapp v aktuálním sandboxu. Externě nainstalovaný balíček zůstane sám, i když se jeho identita shoduje. --force není podporován s --on; nemůže obejít kontroly vlastnictví. Jde o vyčištění balíčků podle manifestu, nikoli o příkaz pro zrušení registrace nebalených aplikací ani o vstup .cs.

Sandbox zůstane spuštěný. Správa jeho životnosti pomocí vlastního rozhraní příkazového řádku sandboxu Windows:

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

Zastavení zahodí hosta a jeho práci. Nejprve uložte potřebné důkazy a před zastavením instance, kterou může používat, získejte souhlas uživatele. Následující příkazy winapp mohou vytvořit nový Sandbox; poté znovu vyhledejte všechny cíle aplikace.

Troubleshooting

Postupujte podle chybového hlášení userAction; upozornění nextCommand je doporučení, nikoli oprávnění k automatickému spuštění. V rámci automatizace zkontrolujte strukturovanou error.code. Při selhání infrastruktury může proces skončit s 70, ale 70 může vrátit i libovolná aplikace; pouze podle číselného návratového kódu je nelze rozlišit.

Příkazy pro obnovení navržené operacemi uživatelského rozhraní se směrováním obsahují také --on <target>, takže při zkopírování doporučení zůstane zachován stejný cíl spuštění.

Chyba nebo příznak Co dělat
sandbox_unsupported Kontrola Windows edice nebo verze a virtualizace firmwaru
sandbox_setup_required Povolte Windows Sandbox pomocí výše uvedených pokynů a potom restartujte, až budete připravení.
sandbox_setup_requires_restart Windows hlásí čekající restartování; uložte práci a restartujte ji, až bude připravená, a zkuste to znovu.
sandbox_setup_incomplete Otevřete Windows sandboxu z nabídky Start a dokončete instalaci nebo aktualizaci klienta a pak to zkuste znovu.
sandbox_unmanaged_instance, sandbox_target_ambiguous Zkontrolujte nahlášené instance/okna; nepřerušujte nesouvisející práci kvůli odstranění nejasnosti
sandbox_input_not_ready, sandbox_no_interactive_session Obnovte existujícího klienta nebo se znovu připojte podle pokynů a pak zkuste to znovu.
sandbox_agent_incompatible Postupujte podle chybového hlášení o verzi; pokud k tomu budete vyzváni, aktualizujte nainstalovaný nástroj CLI pomocí stejného způsobu instalace a poté zavřete nebo akci opakujte pouze se souhlasem.
sandbox_agent_busy Počkejte na dokončení dalšího příkazu a zkuste to znovu.
sandbox_terminated, sandbox_target_stale, sandbox_stale_handle Znovu spusťte aplikaci a znovu vyhledejte PID a okna hosta.
sandbox_state_unavailable Ujistěte se, že do %USERPROFILE%\.winapp\state lze zapisovat, nebo opravte WINAPP_TARGET_STATE_ROOT, pokud je nastaven.
sandbox_deployment_dirty, sandbox_transfer_interrupted Zkuste nasazení nebo přenos zopakovat.
sandbox_runtime_provision_failed Vyřešte pojmenovanou závislost nebo nepodporovanou konfiguraci běhového prostředí; viz Sdílená běhová prostředí
sandbox_package_conflict, sandbox_provisioned_package_conflict Postupujte podle akce specifické pro balíček; Neodstraňujte nesouvisející balíčky ani balíčky doručené pošty
sandbox_artifact_failed Zkontrolujte nahlášený výstup a připravenost klienta; zachovejte veškeré dílčí důkazy
target_invalid, target_invalid_arguments Oprava cíle nebo možností zobrazených v chybě

winapp update aktualizuje závislosti sady SDK projektu, nikoli nainstalované rozhraní příkazového řádku. Není to oprava nekompatibility CLI mezi hostitelem a hostem.

Sdílení cílů v sandboxu buildu 28000

Testovaný build 28000 Sandbox nemůže vytvořit výčet cílů služby Share. Otestujte ostatní funkce aplikace v Sandboxu, ale toky Share ze zdroje do cíle ověřte mimo něj.

Viz také

  • Last updated on