Partilhar via

Depurar aplicativos .NET no WSL com o Visual Studio

  • Artigo

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

Para um usuário do Windows .NET voltado para Linux, o WSL vive em um ponto ideal entre realismo de produção e produtividade. No Visual Studio, você já pode depurar em um ambiente Linux remoto usando o depurador remoto, ou com contêineres usando o Container Tools. Quando o realismo de produção é sua principal preocupação, você deve usar uma dessas opções. Quando um loop interno fácil e rápido é mais importante, a 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 seu aplicativo for implantado, você sempre poderá usar o depurador remoto para anexá-lo se houver um problema. Para depurar um contentor do Linux Docker em execução no WSL, consulte Ligar a um processo em execução num contentor do Docker.

Observação

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

Pré-requisitos

  • Visual Studio 2019 v16.9 Preview 1 ou versões posteriores com o componente opcional de Depuração com .NET utilizando o WSL.

    Para verificar o componente WSL, escolha Ferramentas>Obter Ferramentas e Recursos. No Visual Studio Installer, certifique-se de que o componente está instalado escolhendo guia Componentes individuais e digitando 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 WSL.

  • Instale a distribuição de à sua escolha.

Iniciar a depuração com o WSL

  1. Depois de instalar os componentes necessários, abra um aplicativo Web ASP.NET Core ou um aplicativo de console .NET Core no Visual Studio Você verá um novo Perfil de Inicialização chamado WSL:

    perfil de lançamento da WSL na lista de perfis de lançamento

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

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

    Observação

    A partir do Visual Studio 2022 Preview 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 sua distribuição WSL está configurada para executar aplicativos .NET e ajuda você a instalar quaisquer dependências ausentes. Depois de instalar essas dependências, você estará pronto para depurar no WSL.

  3. Comece a depurar normalmente e a sua aplicação será executada na 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

Apenas Ubuntu e Debian foram testados e são suportados. Outras distribuições suportadas pelo .NET devem funcionar, mas requerem a instalação manual do .NET Runtime e Curl.

Escolha uma distribuição específica

Por padrão, o perfil de inicialização do WSL 2 usa a distribuição padrão definida em wsl.exe. Se você quiser que seu perfil de inicialização segmente uma distribuição específica, independentemente desse padrão, você pode modificar seu perfil de inicialização. Por exemplo, se estiveres a depurar uma aplicação web e quiseres testá-la no Ubuntu 20.04, o teu perfil de arranque ficaria assim:

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

Segmentar várias distribuições

Indo um passo além, se você estiver trabalhando em um aplicativo que precisa ser executado em várias distribuições e quiser uma maneira rápida de testar em cada uma delas, poderá ter 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, você pode usar 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, você pode alternar facilmente entre suas distribuições de destino, tudo sem sair do conforto do Visual Studio.

Vários perfis de inicialização WSL na lista de perfis de inicialização

Anexar a um processo WSL que está em execução

Além de depurar a partir do arranque da aplicação usando F5, pode depurar ligando-se a um processo WSL em execução através do recurso de ligação ao processo.

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

  2. Para o tipo de conexão , escolha o Subsistema Windows para Linux (WSL) e, em seguida, escolha a distribuição Linux para o alvo de conexão .

  3. Escolha 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 de WSL no perfil de inicialização

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

Nome Padrão Finalidade Suporta Tokens?
executablePath dotnet O executável a ser executado Sim
argumentos da linha de comando O valor da propriedade MSBuild TargetPath mapeado para o ambiente WSL Argumentos de linha de comando passados para executablePath Sim
diretório de trabalho Para aplicações de consola: {OutDir}
Para aplicações Web: {ProjectDir}		 O diretório de trabalho onde iniciar o debugging Sim
variáveis de ambiente Pares de valor chave de variáveis de ambiente a serem definidas para o processo depurado. Sim
setupScriptPath Script a ser executado antes da depuração. Útil para executar scripts como ~/.bash_profile. Sim
nome_da_distribuição Nome da distribuição WSL a ser usada. Não
iniciarNavegador falso Iniciar ou não um navegador Não
launchUrl URL para iniciar se o navegador estiver definido como verdadeiro Não

Tokens suportados:

{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 para o WSL no perfil de inicialização.

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

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