WSL 外掛程式

  • 發行項

Windows 應用程式現在可以使用 WSL 外掛程式，建立並與在 Windows 子系統 Linux 版 （WSL） 內執行的 Linux 行程互動。 本文概述其運作方式，以及如何開始使用它們。

瞭解外掛程式功能

WSL 外掛程式提供下列核心功能：

  • 允許應用程式指定啟動 WSL 虛擬機時啟動的 Windows 可執行檔
  • Windows 可執行檔可以在 WSL 內建立 Linux 進程，而且可以使用虛擬化套接字直接與它們通訊

使用這些應用程式，Windows 應用程式可以建置在 WSL 體驗之上，並提供與 Windows 子系統 Linux 版 相關的其他功能。

安裝外掛程式

身為 WSL 外掛程式建立者，您可以將登錄機碼設定為指向外掛程式的 DLL 檔案，在電腦上安裝外掛程式。

身為 WSL 使用者，您使用的任何應用程式都會在其一般安裝程式中自動安裝 WSL 外掛程式。

建立您自己的外掛程式

若要啟動外掛程式專案，您必須建置 Win32 dll。 最簡單的方式就是嘗試我們的 WSL 外掛程式範例專案。 您可以將 WSL 外掛程式範例存放庫複製到本機資料夾，git clone並在 Visual Studio 中開啟。

當您開啟專案時，請瀏覽至 dllmain.cpp 檔案 （https://github.com/microsoft/wsl-plugin-sample/blob/main/plugin.cpp），您會看到 WSL 外掛程式可用的函式清單。

然後，您可以按 [建置] 索引標籤並建置您的專案，這會輸出可供您使用的 DLL，很可能在 下方 wsl-plugin-sample\x64\Debug\WSLPluginSample.dll。

測試您的外掛程式

WSL 外掛程式只有在數位簽署時才會執行。 若要測試這項功能，您必須在機器上啟用測試簽署。

啟用測試簽署和建立測試認證

開啟提升權限的 PowerShell 視窗，並 執行下列命令來啟用測試簽署 ：

## 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

一旦啟用測試簽署（可能需要重新啟動），在已提升許可權的 Powershell 命令提示字元中，位於上方所建立WSLPluginSample.dll檔案的目錄中，我們將建立 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

最後將憑證匯入至受信任的跟證書授權單位：

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

如需詳細資訊，請參閱如何建立自我簽署憑證文件頁面。

安裝外掛程式

在相同提升許可權的 PowerShell 視窗中，執行下列命令來安裝外掛程式，並確定將外掛程式 DLL 的路徑變更為現有的路徑：

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

若要使用外掛程式，請透過下列方式重新啟動 wsl 服務：

sc.exe stop wslservice
wsl.exe echo “test”

您的外掛程式現在應該會載入。 如需外掛程式無法載入的詳細資訊，請參閱疑難解答和其他資訊一節。

然後當您完成時，您可以執行此命令來移除外掛程式（請記住，您必須重新啟動 WSL 服務才能生效）：

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

疑難解答和其他資訊

常見的錯誤碼：

  • Wsl/Service/CreateInstance/CreateVm/Plugin/ERROR_MOD_NOT_FOUND -> 無法載入外掛程式 DLL。 檢查外掛程式註冊路徑是否正確
  • Wsl/Service/CreateInstance/CreateVm/Plugin/TRUST_E_NOSIGNATURE -> 外掛程式 DLL 未簽署，或計算機不信任其簽章
  • Wsl/Service/CreateInstance/CreateVm/Plugin/* -> 外掛程式 DLL 在 WSLPLUGINAPI_ENTRYPOINTV1 或 OnVmStarted 中傳回錯誤
  • Wsl/Service/CreateInstance/Plugin/* -> 外掛程式 DLL 在 OnDistributionStarted 中傳回錯誤（）

外掛程式 Linux 用戶空間

透過 ExecuteBinary（） 建立的 Linux 進程將會在 WSL2 虛擬機的根命名空間中執行。 此命名空間與任何散發無關，而且具有極簡的 Mariner 根文件系統。

該文件系統是可寫入的 tmpfs，這表示當 WSL2 虛擬機關閉時，將會卸除對它所做的所有變更。

您可以在 WSL 執行時執行 wsl --debug-shell ，以檢查根命名空間的內容。

其他考量

  • 所有 WSL 外掛程式勾點都是同步的，這表示 WSL 會在繼續之前等待外掛程式攔截完成。
  • WSL 會將外掛程式傳回的任何錯誤視為嚴重錯誤（這表示使用者的散發套件不會啟動）
  • 外掛程式程式代碼會在與 WSL 服務相同的位址空間中執行。 外掛程式中的任何損毀都會損毀整個 WSL 服務，可能會導致數據遺失