閱讀英文

共用方式為


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 服務,可能會導致數據遺失