Compartilhar via

Depurar aplicativos .NET no WSL com o Visual Studio

  • Artigo

Você pode executar e depurar facilmente seus aplicativos .NET Core e .NET 5+ no Linux sem sair do Visual Studio usando o WSL (Subsistema do Windows para Linux). 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. Para depurar um contêiner do Docker do Linux em execução no WSL, consulte Anexar a um processo em execução em um contêiner do Docker.

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:

    Perfil de inicialização do WSL na lista de perfis de inicialização

  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": ""
}

    "WSL": {
    "commandName": "WSL2",
    "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"
}

"WSL": {
    "commandName": "WSL2",
    "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"
}

"WSL : Debian": {
    "commandName": "WSL2",
    "distributionName": "Debian"
},
"WSL : Ubuntu 18.04": {
    "commandName": "WSL2",
    "distributionName": "Ubuntu-18.04"
},
"WSL : Ubuntu 20.04": {
    "commandName": "WSL2",
    "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.

Perfis múltiplos de inicialização do WSL na lista de perfis de inicialização

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.

    Captura de tela do processo WSL na caixa de diálogo anexar ao processo.

    Captura de tela do processo WSL na caixa de diálogo anexar ao processo.

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"
}