通过

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 该文件，你将看到可用于 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

启用测试签名（可能需要重启）后，在上面创建的 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

最后一次将证书导入到受信任的根证书颁发机构：

Import-Certificate -FilePath ".\$certname.cer" -CertStoreLocation Cert:\LocalMachine\Root"

有关详细信息，请参阅 如何创建自签名证书 文档页。

安装插件

在同一提升的 PowerShell 窗口中，运行以下命令以安装插件，并确保将插件 DLL 的路径更改为现有路径：

Set-ItemProperty -Path "HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\Lxss\Plugins" -Name "demo-plugin" -Value "C:\Path\to\plugin.dll" -Force

若要使用插件，请通过以下方法重启 wsl 服务：

Stop-Service -Name "wslservice" -Force
wsl.exe echo "test"

现在应加载插件。 有关插件加载失败的详细信息，请参阅 故障排除和其他信息 部分。

完成后，可以运行以下命令来删除插件（请记住，需要重启 WSL 服务才能生效）：

Remove-ItemProperty -Path "HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\Lxss\Plugins" -Name "demo-plugin" -Force

故障排除和其他信息

常见错误代码：

  • 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 服务崩溃，这可能会导致数据丢失
  • Last updated on