次の方法で共有

WSL プラグイン

Windows アプリケーションは、WSL プラグインを使用して、Windows Subsystem for Linux (WSL) 内で実行されている Linux プロセスを作成して操作できるようになりました。 この記事では、その動作の概要と、その使用を開始する方法について説明します。

プラグインの機能について

WSL プラグインは、次のコア機能を提供します。

  • WSL 仮想マシンの起動時に起動する Windows 実行可能ファイルをアプリケーションで指定できるようにします。
  • Windows 実行可能ファイルは、WSL 内に Linux プロセスを作成でき、仮想化されたソケットを使用して直接通信できます

これらの機能を使用して、Windows アプリケーションは WSL エクスペリエンスの上に構築し、Windows Subsystem for Linux に関連する追加機能を提供できます。

プラグインのインストール

WSL プラグイン作成者は、プラグインの DLL ファイルを指すようにレジストリ キーを設定することで、コンピューターにプラグインをインストールできます。

また、WSL ユーザーは、使用するすべてのアプリケーションが、通常のインストール プロセスの一部として WSL プラグインを自動的にインストールします。

独自のプラグインの作成

プラグイン プロジェクトを開始するには、Win32 dll をビルドする必要があります。 これを設定する最も簡単な方法は、WSL プラグインのサンプル プロジェクトを試してみる方法です。 これを行うには、git cloneを使用して WSL プラグインのサンプル リポジトリをローカル フォルダーに複製し、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() でエラーを返しました

Plugins Linux ユーザー空間

ExecuteBinary() を使用して作成された Linux プロセスは、WSL2 仮想マシンのルート名前空間で実行されます。 この名前空間はどのディストリビューションにも関連付けられていないので、マリナー ベースのルート ファイル システムはごくわずかです。

そのファイル システムは書き込み可能な tmpfs です。つまり、WSL2 仮想マシンがシャットダウンされると、それに加えられたすべての変更が削除されます。

WSL の実行中に wsl --debug-shell を実行することで、ルート名前空間の内容を調べることができます。

その他の考慮事項

  • すべての WSL プラグイン フックは同期的です。つまり、WSL はプラグイン フックが完了するまで待機してから続行します。
  • プラグインによって返されるすべてのエラーは、WSL によって致命的と見なされます (つまり、ユーザーの配布は開始されません)。
  • プラグイン コードは、WSL サービスと同じアドレス空間で実行されます。 プラグインでクラッシュすると WSL サービス全体がクラッシュし、データが失われる可能性があります
  • Last updated on