WSL 插件
现在,Windows 应用程序可以使用 WSL 插件创建在适用于 Linux 的 Windows 子系统 (WSL) 内运行的 Linux 进程并与之交互。 本文概述了其工作原理以及如何开始使用它们。
WSL 插件提供以下核心功能:
- 支持应用程序指定在启动 WSL 虚拟机时启动的 Windows 可执行文件
- Windows 可执行文件可以在 WSL 内部创建 Linux 进程,并且可以使用虚拟化套接字直接与它们通信
使用这些资源,Windows 应用程序可以基于 WSL 体验构建,并提供与适用于 Linux 的 Windows 子系统相关的附加功能。
作为 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 插件的函数列表。
然后,可以按“生成”选项卡并生成项目,这可能会在 wsl-plugin-sample\x64\Debug\WSLPluginSample.dll
下面输出随时可用的 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
启用测试签名(可能需要重启)后,在上面创建的 WSLPluginSample.dll 文件的目录中提升的 Powershell 命令提示符下,我们将创建 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() 中返回错误
通过 ExecuteBinary() 创建的 Linux 进程将在 WSL2 虚拟机的根命名空间中运行。 此命名空间不与任何分发相关联,并且具有非常最小的基于 Mariner 的根文件系统。
文件系统是可写的 tmpfs,这意味着在关闭 WSL2 虚拟机时,将删除对它所做的所有更改。
可以通过在 WSL 运行时运行 wsl --debug-shell
来检查根命名空间的内容。
- 所有 WSL 插件挂钩是同步的,这意味着 WSL 将等待插件挂钩完成后才会继续。
- 插件返回的任何错误将被 WSL 视为致命错误(这意味着用户的分发不会启动)
- 插件代码与 WSL 服务在同一地址空间中运行。 插件中的任何崩溃会导致整个 WSL 服务崩溃,这可能会导致数据丢失