通过

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() 中返回错误

插件 Linux 用户空间

通过 ExecuteBinary() 创建的 Linux 进程将在 WSL2 虚拟机的根命名空间中运行。 此命名空间不与任何分发相关联，并且具有非常最小的基于 Mariner 的根文件系统。

文件系统是可写的 tmpfs，这意味着在关闭 WSL2 虚拟机时，将删除对它所做的所有更改。

可以通过在 WSL 运行时运行 wsl --debug-shell 来检查根命名空间的内容。

其他注意事项

  • 所有 WSL 插件挂钩是同步的，这意味着 WSL 将等待插件挂钩完成后才会继续。
  • 插件返回的任何错误将被 WSL 视为致命错误（这意味着用户的分发不会启动）
  • 插件代码与 WSL 服务在同一地址空间中运行。 插件中的任何崩溃会导致整个 WSL 服务崩溃，这可能会导致数据丢失