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

Note

Vous pouvez utiliser dotnet run --project <PROJECT> pour spécifier un projet à exécuter. Par exemple, l’exécution dotnet run --project WebApp à partir de la racine de l’exemple d’application exécute également le projet WebApp .

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. Par exemple:

Command	Commande avec montre
dotnet run	dotnet watch run
dotnet run -f netcoreapp3.1	dotnet watch run -f netcoreapp3.1
dotnet exécute -f netcoreapp3.1 -- --arg1	dotnet watch run -f netcoreapp3.1 -- --arg1
dotnet test	dotnet watch test

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

L’exécution dotnet watch run sur une application web lance un navigateur qui accède à l’URL de l’application une fois prête. dotnet watch effectue cette opération en lisant la sortie de la console de l’application et en attendant le message prêt affiché par WebHost.

dotnet watch actualise le navigateur lorsqu’il détecte les modifications apportées aux fichiers surveillés. Pour ce faire, la commande watch injecte un middleware à l'application qui modifie les réponses HTML créées par l'application. L’intergiciel ajoute un bloc de script JavaScript à la page qui permet dotnet watch d’indiquer au navigateur d’actualiser. Actuellement, les modifications apportées à tous les fichiers surveillés, y compris les fichiers de contenu statique comme .html et .css, entraînent la reconstruction de l’application.

dotnet watch :

• Surveille uniquement les fichiers qui ont un impact sur les builds par défaut.
• Tous les fichiers surveillés supplémentaires (via la configuration) entraînent toujours une génération.

Pour plus d’informations sur la configuration, consultez la configuration dotnet-watch dans ce document.

Note

Vous pouvez utiliser dotnet watch --project <PROJECT> pour spécifier un projet à surveiller. Par exemple, exécuter dotnet watch --project WebApp run depuis la racine de l'application exemple lancera et surveillera également le projet WebApp.

Apporter des modifications avec dotnet watch

Vérifiez 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. Vous pouvez spécifier des éléments individuellement ou en utilisant des 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.

configuration de dotnet-watch

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

Setting	Description
DOTNET_USE_POLLING_FILE_WATCHER	Si la valeur est « 1 » ou « true », dotnet watch utilise un observateur de fichiers d’interrogation au lieu du FileSystemWatcher de CoreFx. Utilisé pour surveiller des fichiers sur des partages réseau ou des volumes montés dans Docker.
DOTNET_WATCH_SUPPRESS_MSBUILD_INCREMENTALISM	Par défaut, dotnet watch optimise la build en évitant certaines opérations telles que l’exécution de la restauration ou la réévaluation de l’ensemble des fichiers surveillés sur chaque modification de fichier. Si la valeur est « 1 » ou « true », ces optimisations sont désactivées.
DOTNET_WATCH_SUPPRESS_LAUNCH_BROWSER	dotnet watch run tente de lancer des navigateurs pour les applications web avec launchBrowser configuré dans launchSettings.json. Si la valeur est « 1 » ou « true », ce comportement est supprimé.
DOTNET_WATCH_SUPPRESS_BROWSER_REFRESH	dotnet watch run tente d’actualiser les navigateurs lorsqu’il détecte les modifications de fichier. Si la valeur est « 1 » ou « true », ce comportement est supprimé. Ce comportement est également supprimé s’il DOTNET_WATCH_SUPPRESS_LAUNCH_BROWSER est défini.

Actualisation du navigateur

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>

Caractères non ASCII

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.

Limites de l’observateur de fichiers dans Linux

Lors de l’exécution dotnet watch sur Linux ou dans des conteneurs Docker, vous pouvez rencontrer une erreur indiquant que la limite d’utilisateur configurée sur le nombre d’instances inotify a été atteinte :

The configured user limit (128) on the number of inotify instances has been reached, or the per-process limit on the number of open file descriptors has been reached.

Si la limite d’instance inotify est épuisée, augmentez fs.inotify.max_user_instances. Si le processus a atteint sa limite open-file-descriptor, augmentez cette limite à la place. Le paramètre distinct fs.inotify.max_user_watches s’applique lorsque la limite de montres inotify est épuisée.

Pour augmenter temporairement ces limites, exécutez les commandes suivantes :

sudo sysctl fs.inotify.max_user_instances=524288
sudo sysctl fs.inotify.max_user_watches=524288

Pour rendre cette modification permanente, ajoutez les lignes suivantes au /etc/sysctl.conf fichier :

fs.inotify.max_user_instances=524288
fs.inotify.max_user_watches=524288

Note

Pour les conteneurs Docker, ces limites sont héritées du système d’exploitation hôte. Vous devez configurer les sysctl paramètres sur l’ordinateur hôte, plutôt qu’à l’intérieur du conteneur.