Bagikan melalui

Plugin WSL

  • Artikel

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
  • Windows yang dapat dieksekusi dapat membuat proses Linux di dalam WSL, dan dapat berkomunikasi langsung dengan mereka menggunakan 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 (https://github.com/microsoft/wsl-plugin-sample/blob/main/plugin.cpp) 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 (Reboot mungkin diperlukan), dalam prompt perintah Powershell yang ditingkatkan yang ada di direktori file WSLPluginSample.dll Anda yang dibuat di atas, 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

Terakhir impor sertifikat ke Otoritas Sertifikasi Akar Tepercaya:

certutil -addstore "Root" ".\$certname.cer"

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

Instal plugin

Di jendela PowerShell yang ditingkatkan yang sama, jalankan perintah di bawah ini untuk menginstal plugin, dan pastikan untuk mengubah jalur ke DLL plugin ke jalur yang ada:

Reg.exe add HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Lxss\Plugins /v demo-plugin /t REG_SZ /d C:\Path\to\plugin.dll  /f

Untuk menggunakan plugin, mulai ulang layanan wsl melalui:

sc.exe stop wslservice
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):

Reg.exe delete HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Lxss\Plugins /v demo-plugin

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/* -> DLL plugin mengembalikan kesalahan di OnDistributionStarted()

Ruang pengguna Plugin Linux

Proses Linux yang dibuat melalui ExecuteBinary() akan berjalan di namespace layanan akar WSL2 Virtual Machine. Namespace layanan ini tidak terkait dengan distribusi apa pun dan memiliki sistem file akar 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 konten namespace layanan akar dengan menjalankan wsl --debug-shell saat WSL sedang berjalan.

Pertimbangan tambahan

  • Semua kait plugin WSL sinkron, yang berarti bahwa WSL akan menunggu kait plugin 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 menabrak seluruh layanan WSL, berpotensi menyebabkan kehilangan data