Eksekusi Windows Sandbox

Buat di komputer Anda, lalu jalankan dan otomatisasikan aplikasi di Windows Sandbox:

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

Ganti MyApp dengan nama aplikasi Anda atau PID tamu yang dicetak oleh run. --detach kembali setelah diluncurkan sehingga perintah berikutnya dapat memeriksa aplikasi; tanpanya, run menunggu aplikasi keluar. Sandbox tetap berjalan di antara perintah dan proses build ulang.

Sebelum Anda mulai

Gunakan Windows 11 24H2 atau yang lebih baru pada edisi yang didukung, dengan virtualisasi perangkat keras diaktifkan.
Winapp tamu mendukung x64 dan Arm64. Aplikasi x86 memerlukan dukungan tamu untuk menjalankannya dan mencocokkan dependensi x86; runtime x64 tidak memenuhi aplikasi x86.
Biarkan sesi host tetap tidak dikunci untuk input langsung dan tangkapan layar.

Aktifkan Windows Sandbox di Mengaktifkan atau menonaktifkan fitur Windows, atau jalankan ini dari terminal administrator:

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

Simpan pekerjaan Anda dan mulai ulang Windows saat siap. Kemudian buka Windows Sandbox dari menu Mulai dan selesaikan penginstalan atau pembaruan klien apa pun. winapp tidak mengaktifkan fitur, menginstal klien, meminta elevasi, atau memulai ulang Windows. Jika prasyarat tidak terpenuhi, proses akan berhenti dengan instruksi penyiapan; restart Windows yang tertunda dan terdeteksi akan dilaporkan secara terpisah.

Koneksi dingin atau koneksi ulang dapat secara singkat mengambil fokus. Setelah terhubung, winapp menjaga jendela kliennya sendiri di luar layar tanpa mengaktifkannya. Jendela Sandbox yang Anda buka sendiri dibiarkan di tempat.

Important

Build masih berjalan di komputer Anda. Evaluasi proyek, pemulihan, dan kompilasi bukan proses yang terpisah. --on sandbox tidak membuat proyek yang tidak tepercaya menjadi aman untuk dibangun.

Satu Sandbox adalah satu lingkungan bersama. Aplikasi dan alur kerja di dalamnya berbagi pengguna, desktop, registri, paket, runtime, dan akses jaringan. Mereka dapat mengamati atau mengganggu satu sama lain. Gunakan komputer terpisah untuk alur kerja yang sama-sama tidak tepercaya.

Windows hanya mengizinkan satu Sandbox dalam satu waktu. winapp menggunakan kembali instans yang sedang berjalan, termasuk instans yang Anda buka sendiri. Menyiapkannya akan menambahkan folder bootstrap bersama milik winapp, agen tamu, Mode Pengembang, dan aturan firewall masuk. winapp tidak menghentikan instans yang diadopsi atau menghapus aplikasi yang tidak terkait. Tidak ada pengalihan diam-diam ke host: perintah yang meminta Sandbox akan dijalankan di sana atau gagal.

Menjalankan dan membangun kembali

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

Buat opsi seperti --configuration, , --arch--framework, --property, --no-build, dan --no-restore terapkan pada host. Pendaftaran, peluncuran, dan penelusuran kesalahan berlangsung di sistem tamu; aplikasi tidak terdaftar di komputer Anda.

Option	Efek di Kotak Pasir
`--detach`	Kembali setelah peluncuran daripada menunggu hingga keluar
`--no-launch`	Menerapkan dan mendaftarkan tanpa menjalankan
`--clean`	Instal ulang penyebaran ini dan hapus data aplikasinya
`--unregister-on-exit`	Hapus pendaftaran paket ini setelah aplikasi keluar
`--with-alias`	Luncurkan alias eksekusi tamu dengan stream yang diteruskan
`--debug-output`	Alirkan keluaran debug tamu; hanya untuk aplikasi terpaket

Aplikasi yang tidak dikemas meluncurkan executable dari folder yang disebarkan. Mereka tidak memiliki paket untuk didaftarkan. --debug-output ditolak untuk proses berjalan Sandbox tanpa paket.

Menjalankan ulang akan mentransfer file yang berubah dan menghapus file yang telah dihapus dari output build. Data aplikasi dipertahankan kecuali Anda meminta --clean. Deployment yang tidak lengkap tidak dapat dijalankan; mencoba lagi akan membangun ulang salinan mesin tamunya. Jika file build berubah saat winapp menyiapkannya, selesaikan build dan coba lagi.

Perintah UI hangat hanya melaporkan hasilnya, tanpa mengulangi pesan persiapan Sandbox. Inisialisasi sandbox dan pemulihan koneksi masih menunjukkan progres. Gunakan --verbose untuk waktu koneksi dan detail diagnostik; --quiet dan --json menyembunyikan kemajuan. Eksekusi JSON menyertakan ID proses tamu dan cakupan target:

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

Ini adalah kolom tambahan dalam hasil eksekusi, bukan dokumen terpisah. Salin seluruh UiTargetArgs nilai saat memeriksa aplikasi: winapp ui inspect --on sandbox -a 4212. Temukan kembali PID dan handle jendela setelah Sandbox dibuat ulang; keduanya milik generasi Sandbox tersebut, bukan hos atau guest di masa mendatang.

Aplikasi yang dilepas dan masa pakai agen

Aplikasi tanpa kemasan yang dilepas berakhir jika agen tamu berhenti, termasuk selama perbaikan agen. Jika menghilang di antara perintah, jalankan ulang dengan --detach dan cari kembali target UI-nya. Menunggu aplikasi alih-alih melepaskannya memungkinkan Anda mengamati saat aplikasi keluar; hal itu tidak membuat aplikasi tetap berjalan ketika agen hilang. Aplikasi yang dikemas menggunakan aktivasi Windows, bukan masa aktif proses agen. Menutup atau memulai ulang Sandbox mengakhiri semua aplikasi di dalamnya.

runtime bersama

winapp memeriksa dependensi paket aplikasi, persyaratan SDK Aplikasi Windows, dan *.runtimeconfig.json sebelum diluncurkan. Ini menggunakan cache host atau mengunduh payload yang diperlukan, lalu menginstal runtime pendukung yang belum ada di guest, bukan di mesin Anda.

Persyaratan paket termasuk penerbit, versi, dan arsitektur. Pemilihan runtime .NET bersama mematuhi kebijakan dan arsitektur roll-forward yang dikonfigurasi aplikasi; jangan asumsikan runtime yang lebih baru dalam versi utama yang sama akan berfungsi.

Jika kerangka kerja, konfigurasi runtime, atau dependensi tidak didukung, perintah akan gagal secara eksplisit sebelum peluncuran dan mengidentifikasi persyaratan yang diperlukan. Ikuti tindakan kesalahan tersebut. Jika didukung oleh proyek Anda, penerbitan mandiri akan menghapus kebutuhan akan runtime bersama yang sesuai; ini tidak menghapus dependensi paket yang tidak terkait.

Mengotomatiskan UI

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

Setiap verba ui menerima --on sandbox. Nama aplikasi, PID, handle jendela, dan selektor ditentukan di dalam sistem tamu. Gunakan -a/--app atau -w/--window untuk perintah yang ditargetkan aplikasi; winapp tidak menebak aplikasi terakhir yang diluncurkan. Mengosongkan --on sandbox akan memilih desktop host Anda sebagai gantinya.

Input dan rekaman nyata memerlukan klien Sandbox yang terhubung dan tidak diminimalkan. Inspeksi baca-saja masih dapat berfungsi ketika input tidak dapat dilakukan. winapp dapat memulihkan klien yang diminimalkan sendiri tanpa aktivasi; klien yang dibuka secara manual yang diminimalkan harus dipulihkan oleh Anda. Jika input tidak tersedia setelah tersambung kembali, perintah akan gagal alih-alih mengklaim bahwa input telah berhasil disampaikan. Gunakan perintah sambungkan ulang pada pesan kesalahan, lalu coba lagi.

Gunakan winapp target snapshot sandbox --json untuk memeriksa kesiapan desktop tanpa memulai atau menghubungkan kembali Sandbox. Jendela kesalahan terminal yang dikenali tidak dihitung sebagai desktop jarak jauh. Jika winapp tidak dapat memverifikasi desktop yang dipilih karena masih tersambung atau tidak dapat diperiksa, kesiapan tetap tidak tersedia; tunggu dan coba lagi. Beberapa desktop remote masih dapat membingungkan. Snapshot tidak menutup jendela atau mengatasi error pada jendela tersebut untuk Anda.

Lihat Otomatisasi UI untuk pemilih, metode input, dan pernyataan.

Mengoordinasikan alur kerja UI di Sandbox

Gunakan satu WINAPP_UI_WORKFLOW_ID untuk bekerja sama perintah, dan nilai yang berbeda untuk setiap alur kerja independen. Tetapkan ini pada setiap pemanggilan, terutama saat agen Anda memulai shell baru untuk setiap pemanggilan alat. winapp meneruskan identitas spesifik generasi Sandbox yang di-hash; nilai host mentah tidak dikirim ke tamu.

Misalnya, rekam dan berinteraksi di dua terminal menggunakan nilai yang sama. Pilih nilai baru untuk setiap alur kerja baru.

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, saat rekaman sedang berjalan:

$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

Setelah perekaman dan tindakan selesai:

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

Alur kerja bernama mempertahankan giliran UI-nya selama empat detik setelah perintah terakhirnya; yield merilisnya segera. Tanpa ID, setiap perintah melepaskan gilirannya setelah selesai. Oleh karena itu, perekaman tanpa ID menghambat alur kerja lain yang mengubah desktop selama durasi perekaman tersebut. Pemeriksaan hanya-baca tidak menunggu. Giliran antarmuka pengguna host dan tamu terpisah.

Setelah jeda, periksa lagi dan buka kembali menu atau dialog apa pun yang Anda butuhkan: alur kerja lain mungkin telah menggunakan desktop tamu. Giliran kooperatif tidak mengisolasi aplikasi satu sama lain.

Cuplikan layar dan rekaman

Gunakan ui perekaman untuk jendela aplikasi, atau target perekaman untuk seluruh desktop tamu native, termasuk shell dan dialog penginstal:

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

Output ditampilkan pada host, termasuk saat Anda menghilangkan -o. Tangkapan layar secara default disimpan sebagai screenshot.png; rekaman menggunakan recording-<timestamp>-<guid>.mp4. Untuk rekaman, --frames juga memberikan <output-name>.frames direktori yang berisi JPEG, frames.ndjson, dan manifest.json. Hasil melaporkan jalur host. Rekaman target berjalan di lingkungan guest; file host-nya tersedia setelah perekaman dan pengiriman selesai.

target screenshot menunggu giliran UI tamu tanpa mengaktifkan jendela apa pun. Ini tidak mencakup bilah judul dan bingkai jendela Sandbox host. Berkas PNG-nya tidak diubah skalanya: dengan titik asal layar tamu (0,0), koordinat gambar dapat langsung digunakan oleh perintah input koordinat seperti ui drag atau ui touch --at, dengan --on sandbox. Tambahkan origin yang dilaporkan untuk desktop yang memiliki origin negatif. Gunakan --json untuk membaca coordinates.sourceBounds dan coordinates.contentRect; keduanya menggunakan piksel fisik dan tepi kanan/bawah eksklusif.

Rekaman target melaporkan bidang yang sama di JSON dan manifes bingkai. Frame MP4 dan JPEG menggunakan pemetaan yang sama, termasuk penskalaan --max-edge dan padding pada encoder. Untuk memetakan piksel (x,y)gambar, pertama-tama tolak titik di luar contentRect, lalu komputasi setiap koordinat sumber sebagai sourceStart + floor((pixel - contentStart + 0.5) * sourceSize / contentSize). Penurunan skala kehilangan presisi; gunakan PNG asli ketika koordinat yang tepat penting. Perubahan pada batas tampilan desktop tamu menghentikan perekaman dengan display_changed, hanya mempertahankan frame dari sebelum perubahan dan menandai manifes frame sebagai parsial.

File MP4 yang sudah ada atau direktori yang dipasangkan .frames ditolak secara bawaan. Gunakan jalur baru, atau teruskan --overwrite untuk menggantinya setelah proses baru selesai. Bundel bingkai sebelumnya dipertahankan sebagai <output-name>.frames.previous-<id>, termasuk ketika penggantian menghilangkan --frames. Tangkapan yang gagal membuat rekaman lama tetap utuh.

Gunakan nilai positif --duration-sec untuk skrip dan agen. Helper npm uiRecord dan targetRecord memerlukan durationSec; sinyal abort-nya menghentikan secara paksa, bukan sebagai penghentian yang mulus. Lihat ui record untuk nilai yang didukung. Tanpa durasi CLI, perekaman menunggu sinyal berhenti.

Ctrl+C setelah pengambilan dimulai dapat menyelesaikan dan mengembalikan rekaman dengan sukses dengan stopReason: cancelled. Gangguan lain dapat mempertahankan video atau bingkai yang berguna. Baca stopReason, partialOutput, dan recoveryHint jika tersedia, dan gunakan jalur evidensi yang dilaporkan daripada mengasumsikan proses selesai secara normal. Jika perekaman seluruh desktop menjadi tidak tersedia selama perekaman, perekaman akan berhenti dengan capture_unavailable alih-alih terus merekam desktop yang tidak tersedia. Ini tidak membawa Sandbox ke latar depan untuk menyelamatkan bingkai. Pengambilan dapat gagal sebelum bukti yang dapat digunakan tersedia.

Untuk perekaman tamu yang gagal, data bukti yang dipulihkan ditempatkan di direktori <output>.partial-<id> yang unik pada komputer host. Jika pengiriman gagal, file yang diterima tetap berada di jalur pemulihan yang ditentukan, seperti <output>.recovery-<id>, dan file asli tamu tetap dipertahankan. Tetap jalankan Sandbox dan ikuti tindakan pemulihan kesalahan sebelum mencoba kembali atau menutupnya. File parsial yang dipertahankan belum tentu merupakan video yang dapat diputar.

Cuplikan layar dan video mungkin berisi informasi sensitif. Perlakukan direktori frame dengan kehati-hatian yang sama seperti MP4. Lihat ui record untuk opsi perekaman dan bidang hasil.

Memeriksa Kotak Pasir

winapp target snapshot sandbox
winapp target snapshot sandbox --json

Bagian ini menampilkan status kesiapan, deployment saat ini, dan jendela sistem tamu tanpa perlu membuat VM, menyambungkan kembali klien, atau memperbaiki agen. Jika tidak ada Sandbox yang berjalan, program akan melaporkan hal tersebut dan keluar dengan sukses. Untuk memulainya, gunakan winapp run . --on sandbox --detach.

Laporan ini membedakan apa yang didukung tamu dari apa yang dapat dilakukan klien saat ini; klien yang diminimalkan dapat mencegah input atau pengambilan bahkan ketika tamu mendukung keduanya. Gunakan daftar jendela tamu untuk PID UI, bukan proses peluncur yang dilacak milik deployment. Bidang JSON workRoot (ditampilkan seperti Work root dalam output teks) adalah dasar absolut untuk jalur transfer file relatif, biasanya C:\WinApp\work. Ini terpisah dari capabilities.managedRoot, biasanya berupa C:\WinApp, dan dihilangkan ketika guest tidak melaporkan root terkelolanya. Jika beberapa jendela klien membuat pengambilan tidak dapat ditentukan dengan pasti, pesan kesalahan akan mencantumkan daftar kandidat; tentukan jendela mana yang harus ditutup sebelum mencoba lagi.

Menjalankan perintah dan menyalin 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

Gunakan target exec untuk penyiapan dan diagnostik. Ini berjalan sebagai pengguna tamu, meneruskan aliran standar, dan mengembalikan kode keluar perintah. Ini bukan terminal yang sepenuhnya interaktif; aplikasi konsol mendeteksi pipa yang dialihkan. --json memformat kesalahan winapp, bukan stdout perintah turunan.

Untuk push dan pull, jalur target bersifat relatif terhadap workRoot yang dilaporkan oleh target snapshot. Jalur target absolut, berakar, dan UNC ditolak. Satu file mendarat tepat di tujuan yang Anda beri nama; direktori mempertahankan strukturnya di bawah tujuan tersebut. Gunakan path tamu yang ditampilkan setelah push (JSON targetPath) untuk memilih --cwd dari perintah berikutnya; untuk satu file, gunakan direktori induknya. Jika sistem tamu tidak melaporkan root terkelolanya, proses push akan gagal sebelum penyalinan dimulai; ikuti petunjuk pembaruan pada pesan kesalahan alih-alih mengasumsikan jalur default.

Hanya jalankan skrip penyetelan yang Anda percayai. Contoh ini menggunakan cakupan proses -ExecutionPolicy Bypass karena Sandbox yang baru biasanya menolak skrip di bawah kebijakan Restricted-nya.

Proses transfer mengabaikan file yang tidak berubah dan memverifikasi file pengganti sebelum dipublikasikan. Tautan simbolis dan persimpangan tidak diikuti: penyebaran menolaknya, sementara salinan direktori melewati entri tertaut. Sumber tertaut yang disebutkan secara langsung atau jalur tujuan via tautan ditolak. Salin file atau direktori nyata sebagai gantinya.

Menghapus aplikasi dan mengakhiri Sandbox

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

Jika ada berkas manifes di direktori saat ini, Anda tidak perlu menyertakan --manifest. Ini hanya menghapus paket pengembangan yang cocok yang didaftarkan oleh winapp di Sandbox saat ini. Paket yang diinstal secara eksternal dibiarkan saja, bahkan jika identitasnya cocok. --force tidak didukung dengan --on; tidak dapat melewati pemeriksaan kepemilikan. Ini adalah pembersihan paket berbasis manifes, bukan perintah untuk membatalkan pendaftaran aplikasi yang tidak dikemas atau masukan .cs.

The Sandbox tetap berjalan. Kelola masa pakainya dengan CLI Windows Sandbox sendiri:

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

Menghentikan membuang tamu dan pekerjaannya. Simpan bukti yang diperlukan terlebih dahulu, dan dapatkan persetujuan pengguna sebelum menghentikan instans yang mungkin mereka gunakan. Nantinya perintah winapp dapat membuat Sandbox baru; menemukan kembali semua target aplikasi setelahnya.

Troubleshooting

Ikuti pesan kesalahan userAction; anjuran nextCommand adalah saran, bukan izin untuk menjalankannya otomatis. Dalam otomatisasi, periksa error.code yang terstruktur. Kegagalan infrastruktur dapat berakhir dengan kode keluar 70, tetapi aplikasi apa pun juga dapat mengembalikan 70; kode keluar numerik saja tidak dapat membedakan keduanya.

Perintah pemulihan yang disarankan oleh operasi UI terarah mempertahankan --on <target>, sehingga menyalin saran tersebut akan membuatnya tetap pada target eksekusi yang sama.

Kesalahan atau gejala	Apa yang harus dilakukan
`sandbox_unsupported`	Periksa edisi/versi Windows dan virtualisasi firmware
`sandbox_setup_required`	Aktifkan Windows Sandbox menggunakan instruksi di atas, lalu mulai ulang saat siap
`sandbox_setup_requires_restart`	Windows melaporkan mulai ulang yang tertunda; simpan pekerjaan dan mulai ulang saat siap, lalu coba lagi
`sandbox_setup_incomplete`	Buka Windows Sandbox dari Mulai dan selesaikan penyiapan/pembaruan klien, lalu coba lagi
`sandbox_unmanaged_instance`, `sandbox_target_ambiguous`	Periksa instans/jendela yang dilaporkan; jangan hentikan pekerjaan yang tidak terkait untuk mengatasi ambiguitas
`sandbox_input_not_ready`, `sandbox_no_interactive_session`	Pulihkan klien yang ada atau sambungkan kembali seperti yang diarahkan, lalu coba lagi
`sandbox_agent_incompatible`	Ikuti pesan kesalahan versi; perbarui CLI yang terinstal menggunakan metode instalasinya jika diminta, lalu tutup atau coba lagi hanya setelah mendapat persetujuan
`sandbox_agent_busy`	Tunggu perintah lain selesai, lalu coba lagi
`sandbox_terminated`, `sandbox_target_stale`, `sandbox_stale_handle`	Jalankan ulang aplikasi dan cari kembali PID/windows tamu
`sandbox_state_unavailable`	Pastikan `%USERPROFILE%\.winapp\state` dapat ditulisi, atau perbaiki `WINAPP_TARGET_STATE_ROOT` jika ditetapkan
`sandbox_deployment_dirty`, `sandbox_transfer_interrupted`	Coba ulang penerapan atau transfer
`sandbox_runtime_provision_failed`	Selesaikan dependensi yang disebutkan atau konfigurasi runtime yang tidak didukung; lihat runtime bersama
`sandbox_package_conflict`, `sandbox_provisioned_package_conflict`	Ikuti tindakan khusus paket; jangan hapus paket yang tidak terkait atau kotak masuk
`sandbox_artifact_failed`	Periksa output yang dilaporkan dan kesiapan klien; mempertahankan bukti parsial apa pun
`target_invalid`, `target_invalid_arguments`	Memperbaiki target atau opsi yang ditampilkan dalam kesalahan

winapp update memperbarui dependensi SDK proyek, bukan CLI yang diinstal. Ini bukan perbaikan untuk ketidakcocokan CLI antara host dan guest.

Sandbox build 28000 yang diuji tidak dapat menghitung target Berbagi. Uji fitur aplikasi lainnya di Sandbox, tetapi uji alur Share dari sumber ke target di luar Sandbox.

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2026-09-25