Développer des applications ASP.NET Core à l’aide d’un observateur de fichiers

Par Rick Anderson et Victor Hurdugaci

dotnet watch est un outil qui exécute une commande CLI .NET lorsque les fichiers sources changent. Par exemple, une modification de fichier peut déclencher la compilation, l’exécution de test ou le déploiement.

Ce tutoriel utilise une API web existante avec deux points de terminaison : un qui retourne une somme et un autre qui retourne un produit. La méthode de produit a un bogue, qui est résolu dans ce tutoriel.

Téléchargez l’exemple d’application. Il se compose de deux projets : WebApp (une API web ASP.NET Core) et WebAppTests (tests unitaires pour l’API web).

Dans un interpréteur de commandes, accédez au dossier WebApp . Exécutez la commande suivante:

dotnet run

La sortie de la console affiche des messages similaires à ce qui suit (indiquant que l’application est en cours d’exécution et attend les demandes) :

$ dotnet run
Hosting environment: Development
Content root path: C:/Docs/aspnetcore/tutorials/dotnet-watch/sample/WebApp
Now listening on: http://localhost:5000
Application started. Press Ctrl+C to shut down.

Dans un navigateur web, accédez à http://localhost:<port number>/api/math/sum?a=4&b=5. Vous devriez voir le résultat de 9.

Accédez à l’API de produit (http://localhost:<port number>/api/math/product?a=4&b=5). Elle retourne 9, pas 20 comme prévu. Ce problème est résolu plus loin dans le didacticiel.

Exécuter des commandes CLI .NET à l’aide de dotnet watch

Toute commande CLI .NET peut être exécutée avec dotnet watch. For example:

Exécutez dotnet watch run dans le dossier WebApp. La sortie de la console indique que watch a démarré.

Apporter des modifications avec dotnet watch

Assurez-vous que dotnet watch est en cours d’exécution.

Corrigez le bogue dans la Product méthode de MathController.cs sorte qu’il retourne le produit et non la somme :

public static int Product(int a, int b)
{
    return a * b;
}

Enregistrez le fichier. La sortie de la console indique qu’une dotnet watch modification de fichier a été détectée et redémarrée l’application.

Vérifiez que http://localhost:<port number>/api/math/product?a=4&b=5 retourne le résultat correct.

Exécuter des tests à l’aide de dotnet watch

1. Changez la méthode de Product de MathController.cs pour de nouveau renvoyer la somme. Enregistrez le fichier.

2. Dans un interpréteur de commandes, accédez au dossier WebAppTests .

3. Exécutez dotnet restore.

4. Exécutez dotnet watch test. Sa sortie indique qu’un test a échoué et que l’observateur attend les modifications de fichier :

   Total tests: 2. Passed: 1. Failed: 1. Skipped: 0.
   Test Run Failed.
   

5. Corrigez le code de méthode Product afin qu’il retourne le produit. Enregistrez le fichier.

dotnet watch détecte la modification du fichier et réexécute les tests. La sortie de la console indique les tests réussis.

Personnaliser la liste des fichiers à surveiller

Par défaut, dotnet-watch effectue le suivi de tous les fichiers correspondant aux modèles glob suivants :

• **/*.cs
• *.csproj
• **/*.resx
• Fichiers de contenu : wwwroot/**, **/*.config, **/*.json

Vous pouvez ajouter d’autres éléments à la liste de surveillance en modifiant le .csproj fichier. Les éléments peuvent être spécifiés individuellement ou à l’aide de modèles glob.

<ItemGroup>
    <!-- extends watching group to include *.js files -->
    <Watch Include="**\*.js" Exclude="node_modules\**\*;**\*.js.map;obj\**\*;bin\**\*" />
</ItemGroup>

Désactiver les fichiers à surveiller

dotnet-watch peut être configuré pour ignorer ses paramètres par défaut. Pour ignorer des fichiers spécifiques, ajoutez l’attribut Watch="false" à la définition d’un élément dans le .csproj fichier :

<ItemGroup>
    <!-- exclude Generated.cs from dotnet-watch -->
    <Compile Include="Generated.cs" Watch="false" />

    <!-- exclude Strings.resx from dotnet-watch -->
    <EmbeddedResource Include="Strings.resx" Watch="false" />

    <!-- exclude changes in this referenced project -->
    <ProjectReference Include="..\ClassLibrary1\ClassLibrary1.csproj" Watch="false" />
</ItemGroup>

<ItemGroup>
     <!-- Exclude all Content items from being watched. -->
    <Content Update="@(Content)" Watch="false" />
</ItemGroup>

Projets de montres personnalisées

dotnet-watch n’est pas limité aux projets C#. Les projets de surveillance personnalisés peuvent être créés pour gérer différents scénarios. Tenez compte de la disposition de projet suivante :

• test/
  • UnitTests/UnitTests.csproj
  • IntegrationTests/IntegrationTests.csproj

Si l’objectif est de surveiller les deux projets, créez un fichier projet personnalisé configuré pour surveiller les deux projets :

<Project>
    <ItemGroup>
        <TestProjects Include="**\*.csproj" />
        <Watch Include="**\*.cs" />
    </ItemGroup>

    <Target Name="Test">
        <MSBuild Targets="VSTest" Projects="@(TestProjects)" />
    </Target>

    <Import Project="$(MSBuildExtensionsPath)\Microsoft.Common.targets" />
</Project>

Pour démarrer le suivi des fichiers sur les deux projets, accédez au dossier de test . Exécutez la commande suivante :

dotnet watch msbuild /t:Test

VSTest s’exécute lorsqu’un fichier change dans l’un ou l’autre projet de test.

dotnet-watch configuration

Certaines options de configuration peuvent être transmises à dotnet watch par des variables d’environnement. Les variables disponibles sont les suivantes :

Browser refresh

dotnet watch injecte un script dans l’application qui lui permet d’actualiser le navigateur lorsque le contenu change. Dans certains scénarios, par exemple lorsque l’application active la compression de la réponse, dotnet watch peut ne pas être en mesure d’injecter le script. Dans ce cas de développement, injectez manuellement le script dans l’application. Par exemple, pour configurer l’application web pour injecter manuellement le script, mettez à jour le fichier de disposition pour inclure _framework/aspnet-browser-refresh.js:

@* _Layout.cshtml *@
<environment names="Development">
    <script src="/_framework/aspnetcore-browser-refresh.js"></script>
</environment>

Non-ASCII characters

Visual Studio 17.2 ou version ultérieure inclut le Kit de développement logiciel (SDK) .NET 6.0.300 ou version ultérieure. Avec le Kit de développement logiciel (SDK) .NET et la version 6.0.300 ultérieurement, dotnet-watch émet des caractères non ASCII dans la console pendant une session de rechargement à chaud. Sur certains hôtes de console, tels que le conhost Windows, ces caractères peuvent apparaître illisibles. Pour éviter les caractères illisibles, envisagez l’une des approches suivantes :

• Configurez la variable d’environnement DOTNET_WATCH_SUPPRESS_EMOJIS=1 pour supprimer l’émission de ces valeurs.
• Basculez vers un autre terminal, par exemple https://github.com/microsoft/terminal, qui prend en charge le rendu de caractères non ASCII.