Partilhar via

WSL Plugins

Os aplicativos do Windows agora podem criar e interagir com processos Linux executados dentro do Subsistema Windows para Linux (WSL) com plug-ins WSL. Este artigo fornece uma visão geral de como eles funcionam e como começar a usá-los.

Noções básicas sobre a funcionalidade do plug-in

Os plugins WSL fornecem estas funcionalidades principais:

  • Permite que os aplicativos especifiquem um executável do Windows que é iniciado quando a máquina virtual WSL é iniciada
  • O executável do Windows pode criar processos Linux dentro do WSL e pode se comunicar diretamente com eles usando um soquete virtualizado

Usando estes, os aplicativos do Windows podem se basear em experiências WSL e fornecer funcionalidades adicionais relacionadas ao Subsistema Windows para Linux.

Instalando um plug-in

Como criador de plug-ins WSL, você pode instalar seu plug-in em uma máquina definindo uma chave do Registro para apontar para o arquivo DLL do plug-in.

E como um usuário WSL, qualquer aplicativo que você usar instalará automaticamente plug-ins WSL como parte de seu processo normal de instalação.

Criando seu próprio Plugin

Para iniciar um projeto de plugin, você precisará construir uma dll Win32. A maneira mais simples de se configurar com isso é experimentar nosso projeto de exemplo de plug-in WSL. Você pode fazer isso clonando o repositório de exemplo de plug-in WSL para uma pasta local com git clone e abri-lo no Visual Studio.

Quando você abrir o projeto, navegue até o dllmain.cpp arquivo e você verá a lista de funções disponíveis para plugins WSL.

Você pode então pressionar a guia "Build" e construir seu projeto, que produzirá uma DLL pronta para usar, provavelmente em wsl-plugin-sample\x64\Debug\WSLPluginSample.dll.

Testando seu plug-in

Os plug-ins WSL só serão executados se forem assinados digitalmente. Para testar isso, você precisará habilitar a assinatura de teste em sua máquina.

Habilitando a assinatura de teste e criando um certificado de teste

Abra uma janela elevada do PowerShell e habilite a assinatura de teste executando este comando:

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

Assim que a assinatura de teste estiver habilitada (uma reinicialização pode ser necessária), em um prompt de comando do PowerShell elevado que esteja no diretório do seu arquivo de WSLPluginSample.dll criado acima, criaremos um certificado de teste 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

Última importação do certificado para a Autoridade de Certificação Raiz Confiável:

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

Consulte a página como criar documentos de certificado autoassinados para obter mais informações.

Instale o plugin

Na mesma janela elevada do PowerShell, execute o comando abaixo para instalar o plugin e certifique-se de alterar o caminho para a DLL do plugin para o caminho existente:

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

Para usar o plugin, reinicie o serviço wsl via:

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

Seu plugin agora deve ser carregado. Consulte a seção Solução de problemas e informações adicionais para obter mais informações se o plug-in não for carregado.

E então, quando terminar, você pode executar este comando para remover o plug-in (Lembre-se de que você precisará reiniciar o serviço WSL para que ele entre em vigor):

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

Solução de problemas e informações adicionais

Códigos de erro comuns:

  • Wsl/Service/CreateInstance/CreateVm/Plugin/ERROR_MOD_NOT_FOUND -> A DLL do plugin não pôde ser carregada. Verifique se o caminho de registro do plugin está correto
  • Wsl/Service/CreateInstance/CreateVm/Plugin/TRUST_E_NOSIGNATURE -> A DLL do plugin não está assinada ou sua assinatura não é confiável pelo computador
  • Wsl/Service/CreateInstance/CreateVm/Plugin/* -> A DLL do plugin retornou um erro no WSLPLUGINAPI_ENTRYPOINTV1 ou OnVmStarted()
  • Wsl/Service/CreateInstance/Plugin/* -> A DLL do plugin retornou um erro em OnDistributionStarted()

Plugins Linux espaço de utilizador

Os processos Linux criados via ExecuteBinary() serão executados no namespace raiz da máquina virtual WSL2. Este namespace não está associado a nenhuma distribuição e tem um sistema de arquivos raiz baseado em Mariner muito mínimo.

Esse sistema de arquivos é um tmpfs gravável, o que significa que todas as alterações feitas nele serão descartadas quando a máquina virtual WSL2 for desligada.

Você pode inspecionar o conteúdo do namespace raiz executando wsl --debug-shell enquanto o WSL está em execução.

Considerações adicionais

  • Todos os ganchos de plug-in da WSL são síncronos, o que significa que a WSL aguardará que os ganchos de plug-in sejam concluídos antes de continuar.
  • Qualquer erro retornado por um plugin é considerado fatal pela WSL (o que significa que a distribuição do usuário não será iniciada)
  • O código do plugin é executado no mesmo espaço de endereço que o serviço WSL. Qualquer falha em um plugin irá travar todo o serviço WSL, potencialmente causando perda de dados
  • Last updated on