Bagikan melalui

Plugin WSL

Aplikasi Windows sekarang dapat membuat dan berinteraksi dengan proses Linux yang berjalan di dalam Subsistem Windows untuk Linux (WSL) dengan plugin WSL. Artikel ini memberikan gambaran umum tentang cara kerjanya, dan cara mulai menggunakannya.

Memahami fungsionalitas Plugin

Plugin WSL menyediakan fungsionalitas inti ini:

  • Memungkinkan aplikasi menentukan executable Windows yang dimulai ketika komputer virtual WSL dimulai
  • File eksekusi Windows dapat membuat proses Linux di dalam WSL, dan dapat berkomunikasi langsung dengan mereka dengan soket virtual.

Dengan menggunakan ini, aplikasi Windows dapat membangun di atas pengalaman WSL dan menyediakan fungsionalitas tambahan yang terkait dengan Subsistem Windows untuk Linux.

Menginstal Plugin

Sebagai pembuat plugin WSL, Anda dapat menginstal plugin Anda pada komputer dengan mengatur kunci registri untuk menunjuk ke file DLL plugin Anda.

Dan sebagai pengguna WSL, aplikasi apa pun yang Anda gunakan akan secara otomatis menginstal plugin WSL sebagai bagian dari proses penginstalan normal mereka.

Membuat Plugin Anda sendiri

Untuk memulai proyek plugin, Anda harus membangun dll Win32. Cara paling sederhana untuk menyiapkan ini adalah dengan mencoba proyek sampel plugin WSL kami. Anda dapat melakukan ini dengan mengkloning repositori sampel plugin WSL ke folder lokal dengan git clone dan membukanya di Visual Studio.

Ketika Anda membuka proyek, navigasikan ke dllmain.cpp file dan Anda akan melihat daftar fungsi yang tersedia untuk plugin WSL.

Anda kemudian dapat menekan tab "Build" dan membangun proyek Anda, yang akan menghasilkan DLL yang siap Anda gunakan, kemungkinan di bawah wsl-plugin-sample\x64\Debug\WSLPluginSample.dll.

Menguji Plugin Anda

Plugin WSL hanya akan berjalan jika ditandatangani secara digital. Untuk menguji ini, Anda harus mengaktifkan penandatanganan pengujian di komputer Anda.

Mengaktifkan penandatanganan pengujian dan membuat sertifikasi pengujian

Buka Jendela PowerShell yang ditingkatkan dan aktifkan penandatanganan pengujian dengan menjalankan perintah ini:

## If this command results in "The value is protected by Secure Boot policy and cannot be modified or deleted"
## Then reboot the PC, go into BIOS settings, and disable Secure Boot. BitLocker may also affect your ability to modify this setting.
Bcdedit.exe -set TESTSIGNING ON

Setelah penandatanganan pengujian diaktifkan (pengaktifan ulang mungkin diperlukan), dalam prompt perintah PowerShell tertinggi yang ada di direktori file WSLPluginSample.dll Anda yang sudah dibuat sebelumnya, kami akan membuat sertifikat pengujian WSL:

# Create the cert
$certname = "WSLPluginTestCert"
$cert = New-SelfSignedCertificate -Subject "CN=$certname" -CertStoreLocation "Cert:\CurrentUser\My" -KeyExportPolicy Exportable -KeySpec Signature -KeyLength 2048 -KeyAlgorithm RSA -HashAlgorithm SHA256 -Type CodeSigningCert

# Export it to a local path
Export-Certificate -Cert $cert -FilePath ".\$certname.cer"

# Sign the DLL file
Set-AuthenticodeSignature -FilePath "C:\dev\Path\To\Your\WSLPlugin.dll" -Certificate $cert

Langkah terakhir, impor sertifikat ke Otoritas Sertifikasi Akar Tepercaya:

Import-Certificate -FilePath ".\$certname.cer" -CertStoreLocation Cert:\LocalMachine\Root"

Lihat halaman cara membuat dokumen sertifikat yang ditandatangani sendiri untuk informasi selengkapnya.

Instal plugin

Di jendela PowerShell yang ditingkatkan yang sama, jalankan perintah berikut untuk menginstal plugin, dan pastikan untuk mengubah jalur DLL plugin ke jalur yang sudah ada.

Set-ItemProperty -Path "HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\Lxss\Plugins" -Name "demo-plugin" -Value "C:\Path\to\plugin.dll" -Force

Untuk menggunakan plugin, mulai ulang layanan wsl melalui:

Stop-Service -Name "wslservice" -Force
wsl.exe echo "test"

Plugin Anda sekarang harus dimuat. Lihat bagian Pemecahan Masalah dan informasi tambahan untuk informasi selengkapnya jika plugin gagal dimuat.

Dan kemudian setelah selesai, Anda dapat menjalankan perintah ini untuk menghapus plugin (Harap diingat Bahwa Anda perlu memulai ulang layanan WSL agar berlaku):

Remove-ItemProperty -Path "HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\Lxss\Plugins" -Name "demo-plugin" -Force

Pemecahan masalah dan informasi tambahan

Kode kesalahan umum:

  • Wsl/Service/CreateInstance/CreateVm/Plugin/ERROR_MOD_NOT_FOUND -> DLL plugin tidak dapat dimuat. Periksa apakah jalur pendaftaran plugin sudah benar
  • Wsl/Service/CreateInstance/CreateVm/Plugin/TRUST_E_NOSIGNATURE -> DLL plugin tidak ditandatangani, atau tanda tangannya tidak dipercaya oleh komputer
  • Wsl/Service/CreateInstance/CreateVm/Plugin/* -> DLL plugin mengembalikan kesalahan dalam WSLPLUGINAPI_ENTRYPOINTV1 atau OnVmStarted()
  • Wsl/Service/CreateInstance/Plugin/* -> Plugin DLL mengembalikan kesalahan dalam OnDistributionStarted()

Ruang pengguna Plugin Linux

Proses Linux yang dibuat melalui ExecuteBinary() akan berjalan di namespace layanan akar WSL2 Virtual Machine. Namespace ini tidak terkait dengan distribusi apa pun dan memiliki sistem file root berbasis Mariner yang sangat minimal.

Sistem file tersebut adalah tmpf yang dapat ditulis, yang berarti bahwa semua perubahan yang dilakukan padanya akan dihilangkan ketika Komputer Virtual WSL2 dimatikan.

Anda dapat memeriksa isi namespace akar dengan menjalankan perintah wsl --debug-shell ketika WSL sedang aktif.

Pertimbangan tambahan

  • Semua hook plugin di WSL bersifat sinkron, yang berarti bahwa WSL akan menunggu sampai hook plugin tersebut selesai sebelum melanjutkan.
  • Kesalahan apa pun yang dikembalikan oleh plugin dianggap fatal oleh WSL (yang berarti bahwa distribusi pengguna tidak akan dimulai)
  • Kode plugin berjalan di ruang alamat yang sama dengan layanan WSL. Setiap crash dalam plugin akan mengakibatkan gangguan pada seluruh layanan WSL, berpotensi menyebabkan kehilangan data
  • Last updated on