Compartilhar via

Plug-ins do WSL

Os aplicativos do Windows agora podem criar e interagir com processos do Linux em execução dentro do Subsistema do 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 plug-ins do WSL fornecem estas funcionalidades principais:

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

Usando esses, os aplicativos do Windows podem ser construídos sobre experiências WSL e fornecer funcionalidades adicionais relacionadas ao Subsistema do Windows para Linux.

Instalando um plug-in

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

E como usuário do WSL, qualquer aplicativo usado instalará automaticamente plug-ins WSL como parte do processo normal de instalação.

Criando seu próprio plug-in

Para iniciar um projeto de plug-in, você precisará criar 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 do plug-in WSL para uma pasta local e então abrir no Visual Studio.

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

Em seguida, você pode pressionar a guia "Compilar" e compilar seu projeto, que produzirá uma DLL pronta para uso, provavelmente em wsl-plugin-sample\x64\Debug\WSLPluginSample.dll.

Testando seu plug-in

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

Habilitando a assinatura de teste e criando um certificado de teste

Abra uma janela do PowerShell com privilégios elevados 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

Depois que a assinatura de teste estiver habilitada (uma reinicialização pode ser necessária), em um prompt de comando do PowerShell com privilégios elevados que está no diretório do arquivo 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"

Veja a página de documentação como criar um certificado autoassinado para obter mais informações.

Instalar o plug-in

Na mesma janela elevada do PowerShell, execute o comando abaixo para instalar o plug-in e certifique-se de alterar o caminho para a DLL do plug-in 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 plug-in, reinicie o serviço wsl por meio de:

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

Seu plug-in 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 tiver sido carregado.

E, quando terminar, você poderá 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 –> não foi possível carregar a DLL do plug-in. Verifique se o caminho de registro do plug-in está correto
  • Wsl/Service/CreateInstance/CreateVm/Plugin/TRUST_E_NOSIGNATURE -> A DLL do plug-in não está assinada ou sua assinatura não é confiável pelo computador
  • Wsl/Service/CreateInstance/CreateVm/Plugin/* -> A DLL do plug-in retornou um erro em WSLPLUGINAPI_ENTRYPOINTV1 ou OnVmStarted()
  • Wsl/Service/CreateInstance/Plugin/* -> A DLL do plug-in retornou um erro em OnDistributionStarted()

Plug-ins do espaço de usuário do Linux

Os processos do Linux criados por meio de ExecuteBinary() serão executados no namespace raiz da Máquina Virtual WSL2. Esse 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 hooks de plugin do WSL são síncronos, o que significa que o WSL aguardará a conclusão deles antes de continuar.
  • Qualquer erro retornado por um plug-in é considerado fatal pelo WSL (o que significa que a distribuição do usuário não será iniciada)
  • O código do plug-in é executado no mesmo espaço de endereço que o serviço WSL. Qualquer falha em um plug-in falhará em todo o serviço WSL, potencialmente causando perda de dados
  • Last updated on