Freigeben über

WSL-Plug-Ins

  • Artikel

Windows-Anwendungen können jetzt mit WSL-Plug-Ins Linux-Prozesse erstellen und mit Linux-Prozessen interagieren, die innerhalb des Windows-Subsystems für Linux (WSL) ausgeführt werden. In diesem Artikel finden Sie einen Überblick über ihre Funktionsweise und die ersten Schritte für ihre Nutzung.

Grundlegendes zur Plug-In-Funktionalität

WSL-Plug-Ins bieten diese Kernfunktionen:

  • Ermöglicht Anwendungen das Angeben einer ausführbaren Windows-Datei, die gestartet wird, wenn der virtuelle WSL-Computer gestartet wird
  • Die ausführbare Windows-Datei kann Linux-Prozesse innerhalb von WSL erstellen und mithilfe eines virtualisierten Sockets direkt mit ihnen kommunizieren

Mithilfe dieser Funktionen können Windows-Anwendungen auf WSL-Umgebungen aufbauen und zusätzliche Funktionen im Zusammenhang mit dem Windows-Subsystem für Linux bereitstellen.

Installieren eines Plug-Ins

Als WSL-Plug-In-Ersteller können Sie Ihr Plug-In auf einem Computer installieren, indem Sie einen Registrierungsschlüssel festlegen, um auf die DLL-Datei Ihres Plug-Ins zu verweisen.

Und als WSL-Benutzer installiert jede Anwendung, die Sie verwenden, automatisch WSL-Plug-Ins als Teil des normalen Installationsprozesses.

Erstellen Ihres eigenen Plug-Ins

Um ein Plug-In-Projekt zu starten, müssen Sie eine Win32-DLL erstellen. Die einfachste Möglichkeit zum Einrichten ist das Testen unseres WSL-Plug-In-Beispielprojekts. Dazu können Sie das WSL-Plug-In-Beispiel-Repository mit git clone in einen lokalen Ordner klonen und in Visual Studio öffnen.

Wenn Sie das Projekt öffnen, navigieren Sie zu der dllmain.cpp-Datei (https://github.com/microsoft/wsl-plugin-sample/blob/main/plugin.cpp) und Sie sehen die Liste der Funktionen, die für WSL-Plug-Ins verfügbar sind.

Sie können dann die Registerkarte „Build“ drücken und Ihr Projekt erstellen, wodurch eine DLL ausgegeben wird, die Sie sofort verwenden können, wahrscheinlich unter wsl-plugin-sample\x64\Debug\WSLPluginSample.dll.

Testen Ihres Plug-Ins

WSL-Plug-Ins werden nur ausgeführt, wenn sie digital signiert sind. Um dies zu testen, müssen Sie die Testsignatur auf Ihrem Computer aktivieren.

Aktivieren der Testsignatur und Erstellen einer Testzertifizierung

Öffnen Sie ein PowerShell-Fenster mit erhöhten Rechten, und aktivieren Sie die Testsignatur, indem Sie diesen Befehl ausführen:

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

Sobald die Testsignatur aktiviert ist (möglicherweise ist ein Neustart erforderlich), erstellen wir in einer PowerShell-Eingabeaufforderung mit erhöhten Rechten, die sich im Verzeichnis der oben erstellten WSLPluginSample.dll-Datei befindet, ein WSL-Testzertifikat:

# 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

Importieren Sie das Zertifikat zuletzt in die vertrauenswürdige Stammzertifizierungsstelle:

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

Weitere Informationen finden Sie auf der Dokumentseite Erstellen eines selbstsignierten Zertifikats.

Installieren des Plug-Ins

Führen Sie im gleichen PowerShell-Fenster mit erhöhten Rechten den folgenden Befehl aus, um das Plug-In zu installieren, und achten Sie darauf, den Pfad zur Plug-In-DLL in Ihren vorhandenen Pfad zu ändern:

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

Um das Plug-In zu verwenden, starten Sie den wsl-Dienst neu über:

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

Ihr Plug-In sollte jetzt geladen sein. Weitere Informationen finden Sie im Abschnitt Problembehandlung und zusätzliche Informationen, wenn das Plug-In nicht geladen werden konnte.

Und wenn Sie fertig sind, können Sie diesen Befehl ausführen, um das Plug-In zu entfernen (Beachten Sie bitte, dass Sie den WSL-Dienst neu starten müssen, damit er wirksam wird):

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

Problembehandlung und zusätzliche Informationen

Häufige Fehlercodes:

  • Wsl/Service/CreateInstance/CreateVm/Plugin/ERROR_MOD_NOT_FOUND -> Die Plug-In-DLL konnte nicht geladen werden. Überprüfen Sie, ob der Plug-In-Registrierungspfad korrekt ist
  • Wsl/Service/CreateInstance/CreateVm/Plugin/TRUST_E_NOSIGNATURE -> Die Plug-In-DLL ist nicht signiert, oder ihre Signatur wird vom Computer nicht als vertrauenswürdig eingestuft
  • Wsl/Service/CreateInstance/CreateVm/Plugin/* –> Die Plug-In-DLL hat einen Fehler in WSLPLUGINAPI_ENTRYPOINTV1 oder OnVmStarted() zurückgegeben
  • Wsl/Service/CreateInstance/Plugin/* –> Die Plug-In-DLL hat in OnDistributionStarted() einen Fehler zurückgegeben

Plug-Ins Linux-Benutzerbereich

Linux-Prozesse, die über ExecuteBinary() erstellt werden, werden im Stammnamespace des virtuellen WSL2-Computers ausgeführt. Dieser Namespace ist keiner Verteilung zugeordnet und verfügt über ein sehr minimales Mariner-basiertes Stammdateisystem.

Dieses Dateisystem ist ein schreibbarer Tmpfs, was bedeutet, dass alle daran vorgenommenen Änderungen gelöscht werden, wenn der virtuelle WSL2-Computer heruntergefahren wird.

Sie können den Inhalt des Stammnamespaces prüfen, indem Sie wsl --debug-shell ausführen, während WSL ausgeführt wird.

Weitere Überlegungen

  • Alle WSL-Plug-In-Hooks sind synchron, was bedeutet, dass WSL wartet, bis die Plug-In-Hooks abgeschlossen werden, bevor sie fortfahren.
  • Jeder von einem Plug-In zurückgegebene Fehler wird von WSL als schwerwiegend betrachtet (d. h., die Distribution des Benutzers wird nicht gestartet)
  • Der Plug-In-Code wird im gleichen Adressraum wie der WSL-Dienst ausgeführt. Jeder Absturz in einem Plug-In stürzt den gesamten WSL-Dienst ab, was zu Datenverlust führen kann