Depurar aplicativos .NET no WSL com o Visual Studio

Você pode executar e depurar facilmente seus aplicativos .NET Core e .NET 5+ no Linux sem sair do Visual Studio usando o WSL. Se você for um desenvolvedor multiplataforma, use esse método como uma maneira simples de testar mais de seus ambientes de destino.

Para um usuário do Windows .NET direcionado ao Linux, o WSL tem um ponto ideal entre o realismo de produção e a produtividade. No Visual Studio, já é possível depurar em um ambiente Linux remoto usando o depurador remoto ou com contêineres usando as Ferramentas de Contêiner. Quando a realidade da produção é sua principal preocupação, use uma dessas opções. Quando um loop interno fácil e rápido é mais importante, o WSL é uma ótima opção.

Você não precisa escolher apenas um método. Você pode ter um perfil de inicialização para Docker e WSL no mesmo projeto e escolher o que for apropriado para uma execução específica. E depois que o aplicativo for implantado, você sempre pode usar o depurador remoto para anexá-lo se houver um problema.

Observação

A partir do Visual Studio 2019 versão 16.11 Versão Preliminar 3, o destino de depuração do WSL 2 foi renomeado para WSL.

Pré-requisitos

• Visual Studio 2019 v16.9 Versão Preliminar 1 ou versão posterior com a Depuração do .NET com componente opcional do WSL.

  Para verificar o componente WSL, selecione Ferramentas>Obter Ferramentas e Recursos. No Instalador do Visual Studio, verifique se o componente está instalado pela seleção do guia Componentes individuais e ao digitar WSL como o termo de pesquisa.

  Em algumas versões do Visual Studio, o componente opcional é incluído por padrão com algumas das cargas de trabalho do .NET.

• Instale o WSL.

• Instale a distribuição de sua escolha.

Iniciar depuração com WSL

1. Depois de instalar os componentes necessários, abra um aplicativo Web do ASP.NET Core ou um aplicativo de console do .NET Core no Visual Studio. Aparecerá um novo perfil de inicialização chamado WSL:

   

2. Selecione este perfil para adicioná-lo ao launchSettings.json.

   Alguns dos principais atributos no arquivo são mostrados no exemplo a seguir.

   Observação

   A partir do Visual Studio 2022 Versão Preliminar 3, o nome do comando no Perfil de Inicialização foi alterado de WSL2 para WSL.

   "WSL": {
       "commandName": "WSL",
       "launchBrowser": true,
       "launchUrl": "https://localhost:5001",
       "environmentVariables": {
           "ASPNETCORE_URLS": "https://localhost:5001;http://localhost:5000",
           "ASPNETCORE_ENVIRONMENT": "Development"
       },
       "distributionName": ""
   }
   

   Depois de selecionar o novo perfil, a extensão verifica se a distribuição do WSL está configurada para executar aplicativos .NET e ajuda você a instalar dependências ausentes. Depois de instalar essas dependências, você estará pronto para depurar no WSL.

3. Inicie a depuração normalmente e seu aplicativo será executado em sua distribuição WSL padrão.

   Uma maneira fácil de verificar se você está executando no Linux é verificar o valor de Environment.OSVersion.

Observação

Somente Ubuntu e Debian foram testados e são compatíveis. Outras distribuições compatíveis com o .NET devem funcionar, mas exigem a instalação manual do Runtime do .NET e do Curl.

Escolher uma distribuição específica

Por padrão, o perfil de inicialização do WSL 2 usa a distribuição padrão, conforme definido em wsl.exe. Se quiser que seu perfil de inicialização direcione uma distribuição específica, independente desse padrão, modifique seu perfil de inicialização. Por exemplo, se você estiver depurando um aplicativo Web e quiser testá-lo no Ubuntu 20.04, seu perfil de inicialização será semelhante a:

"WSL": {
    "commandName": "WSL",
    "launchBrowser": true,
    "launchUrl": "https://localhost:5001",
    "environmentVariables": {
        "ASPNETCORE_URLS": "https://localhost:5001;http://localhost:5000",
        "ASPNETCORE_ENVIRONMENT": "Development"
    },
    "distributionName": "Ubuntu-20.04"
}

Direcionar várias distribuições

E mais, se você estiver trabalhando em um aplicativo que precisa ser executado em várias distribuições e quiser uma forma rápida de testar cada uma delas, pode verificar vários perfis de inicialização. Por exemplo, se você precisar testar seu aplicativo de console no Debian, Ubuntu 18.04 e Ubuntu 20.04, use os seguintes perfis de inicialização:

"WSL : Debian": {
    "commandName": "WSL",
    "distributionName": "Debian"
},
"WSL : Ubuntu 18.04": {
    "commandName": "WSL",
    "distributionName": "Ubuntu-18.04"
},
"WSL : Ubuntu 20.04": {
    "commandName": "WSL",
    "distributionName": "Ubuntu-20.04"
}

Com esses perfis de inicialização, é possível alternar facilmente entre suas distribuições de destino, sem sair do conforto do Visual Studio.

Anexar a um processo WSL em execução

Além da depuração da inicialização do aplicativo usando F5, é possível depurar anexando a um processo WSL em execução com o recurso anexar ao processo.

1. Com o aplicativo em execução, escolha Depurar>Anexar ao Processo.

2. Para o Tipo de conexão, selecione Subsistema do Windows para Linux (WSL) e escolha a distribuição do Linux para o destino Conexão.

3. Selecione Anexar.

   

Configurações do WSL no perfil de inicialização

A tabela a seguir mostra as configurações com suporte no perfil de inicialização.

Nome	Padrão	Finalidade	Compatível com tokens?
executablePath	dotnet	O executável a ser executado	Sim
commandLineArgs	O valor da propriedade MSBuild TargetPath mapeada para o ambiente WSL	Argumentos de linha de comando passados para o executablePath	Sim
workingDirectory	Para aplicativos de console: {OutDir} Para aplicativos Web: {ProjectDir}	O diretório de trabalho no qual iniciar a depuração	Sim
environmentVariables		Pares de valores principais de variáveis de ambiente a serem definidos para o processo depurado.	Sim
setupScriptPath		Script a ser executado antes da depuração. Útil para executar scripts como ~/.bash_profile.	Sim
distributionName		Nome da distribuição WSL a ser usada.	Não
launchBrowser	false	Se deseja ou não iniciar um navegador	Não
launchUrl		URL a ser inicializada se launchBrowser for verdadeiro	Não

Tokens compatíveis:

{ProjectDir} – o caminho para o diretório do projeto

{OutDir} – o valor da propriedade MSBuild OutDir

Observação

Todos os caminhos são para WSL e não para Windows.

Passar um argumento de linha de comando

Use a configuração commandLineArgs para passar um argumento de linha de comando ao WSL no perfil de inicialização.

No exemplo a seguir, você passa dois argumentos a um projeto de DLL chamado ConsoleApp.

"WSL": {
  "commandName": "WSL",
  "commandLineArgs": "\"{OutDir}/ConsoleApp.dll\" arg1 arg2"
}