Déboguer des applications .NET dans WSL avec Visual Studio

Vous pouvez facilement exécuter et déboguer vos applications .NET Core et .NET 5+ dans Linux sans quitter Visual Studio à l’aide du sous-système Windows pour Linux (WSL). Si vous êtes développeur multiplateforme, vous pouvez utiliser cette méthode comme moyen simple de tester davantage d’environnements cibles.

Pour un utilisateur Windows .NET ciblant Linux, WSL vit dans un endroit idéal entre le réalisme de production et la productivité. Dans Visual Studio, vous pouvez déjà déboguer dans un environnement Linux distant à l'aide du débogueur distant , ou avec des conteneurs à l'aide des outils de conteneur . Lorsque le réalisme de production est votre principale préoccupation, vous devez utiliser l’une de ces options. Quand une boucle interne simple et rapide est plus importante, WSL est une excellente option.

Vous n’avez pas à choisir une seule méthode ! Vous pouvez avoir un profil de lancement pour Docker et WSL dans le même projet et choisir celui qui convient le mieux pour chaque exécution particulière. Une fois votre application déployée, vous pouvez toujours utiliser le débogueur distant pour vous y connecter en cas de problème. Pour déboguer un conteneur Docker Linux s’exécutant dans WSL, consultez Attacher à un processus s’exécutant sur un conteneur Docker.

Remarque

À partir de la version 16.11 Préversion 3 de Visual Studio 2019, la cible de débogage WSL 2 a été renommée en WSL.

Conditions préalables

• Visual Studio 2019 v16.9 Preview 1 ou version ultérieure avec le débogage .NET avec le composant facultatif WSL.

  Pour vérifier la présence du composant WSL, choisissez Outils>Obtenir des outils et des fonctionnalités. Dans Visual Studio Installer, vérifiez que le composant est installé en choisissant 'onglet Composants individuels et en tapant WSL comme terme de recherche.

  Dans certaines versions de Visual Studio, le composant facultatif est inclus par défaut avec certaines charges de travail .NET.

• Installez WSL.

• Installez la distribution de votre choix.

Démarrer le débogage avec WSL

1. Une fois que vous avez installé les composants requis, ouvrez une application web ASP.NET Core ou une application console .NET Core dans Visual Studio Vous verrez un nouveau profil de lancement nommé WSL :

   

2. Sélectionnez ce profil pour l’ajouter à votre launchSettings.json.

   Certains attributs clés du fichier sont présentés dans l’exemple suivant.

   Remarque

   À compter de Visual Studio 2022 Preview 3, le nom de la commande dans le profil de lancement est passé de WSL2 à WSL.

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

   Une fois que vous avez sélectionné le nouveau profil, l’extension vérifie que votre distribution WSL est configurée pour exécuter des applications .NET et vous aide à installer les dépendances manquantes. Une fois que vous avez installé ces dépendances, vous êtes prêt à déboguer dans WSL.

3. Démarrez le débogage comme normal, et votre application s’exécutera dans votre distribution WSL par défaut.

   Un moyen simple de vérifier que vous êtes en cours d’exécution dans Linux consiste à vérifier la valeur de Environment.OSVersion.

Note

Seuls Ubuntu et Debian ont été testés et sont pris en charge. D’autres distributions prises en charge par .NET devraient fonctionner, mais nécessitent l’installation manuelle du .NET Runtime et de Curl.

Choisir une distribution spécifique

Par défaut, le profil de lancement WSL 2 utilise la distribution par défaut définie dans wsl.exe. Si vous souhaitez que votre profil de lancement cible une distribution spécifique, quelle que soit la valeur par défaut, vous pouvez modifier votre profil de lancement. Par exemple, si vous déboguez une application web et que vous souhaitez la tester sur Ubuntu 20.04, votre profil de lancement se présente comme suit :

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

Cibler plusieurs distributions

Aller plus loin, si vous travaillez sur une application qui doit s’exécuter dans plusieurs distributions et que vous souhaitez un moyen rapide de tester chacun d’eux, vous pouvez avoir plusieurs profils de lancement. Par exemple, si vous devez tester votre application console sur Debian, Ubuntu 18.04 et Ubuntu 20.04, vous pouvez utiliser les profils de lancement suivants :

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

Avec ces profils de lancement, vous pouvez facilement basculer entre vos distributions cibles, tout cela sans laisser le confort de Visual Studio.

Se connecter à un processus WSL en cours d’exécution

Outre le débogage à partir du démarrage de l’application à l’aide de F5, vous pouvez déboguer en attachant à un processus WSL en cours d’exécution à l’aide de la fonctionnalité d’attachement au processus.

1. Une fois l’application en cours d’exécution, choisissez Déboguer>Rattacher au processus.

2. Pour le type de connexion , choisissez sous-système Windows pour Linux (WSL), puis choisissez la distribution Linux pour la cible de connexion .

3. Choisissez Joindre.

   

Paramètres WSL dans le profil de lancement

Le tableau suivant montre les paramètres pris en charge dans le profil de lancement.

Nom	Par défaut	Objectif	Prend en charge les jetons ?
executablePath	dotnet	Le fichier exécutable à lancer	Oui
commandLineArgs	Valeur de la propriété MSBuild TargetPath mappée à l’environnement WSL	Arguments de ligne de commande passés à exécutablePath	Oui
workingDirectory	Pour les applications console : {OutDir} Pour les applications web : {ProjectDir}	Le répertoire de travail dans lequel démarrer le débogage	Oui
variables d'environnement		Paires clé-valeur de variables d’environnement à définir pour le processus débogué.	Oui
setupScriptPath		Script à exécuter avant le débogage. Utile pour exécuter des scripts tels que ~/.bash_profile.	Oui
nom de distribution		Nom de la distribution WSL à utiliser.	Non
launchBrowser	faux	Indique s’il faut lancer ou non un navigateur	Non
launchUrl		URL à lancer si launchBrowser a la valeur true	Non

Jetons pris en charge :

{ProjectDir} - Chemin d’accès au répertoire du projet

{OutDir} : valeur de la propriété MSBuild OutDir

Note

Tous les chemins d’accès sont pour WSL et non Windows.

Transmission d’un argument de ligne de commande

Utilisez le paramètre commandLineArgs pour passer un argument de ligne de commande à WSL dans le profil de lancement.

Dans l’exemple suivant, vous passez deux arguments à un projet DLL nommé ConsoleApp.

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