dotnet watch is a tool that runs a .NET Core CLI command when source files change. For example, a file change can trigger compilation, test execution, or deployment.
This tutorial uses an existing web API with two endpoints: one that returns a sum and one that returns a product. The product method has a bug, which is fixed in this tutorial.
Download the sample app. It consists of two projects: WebApp (an ASP.NET Core web API) and WebAppTests (unit tests for the web API).
In a command shell, navigate to the WebApp folder. Run the following command:
The console output shows messages similar to the following (indicating that the app is running and awaiting requests):
$ 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.
In a web browser, navigate to
http://localhost:<port number>/api/math/sum?a=4&b=5. You should see the result of
Navigate to the product API (
http://localhost:<port number>/api/math/product?a=4&b=5). It returns
20 as you’d expect. That problem is fixed later in the tutorial.
dotnet watch to a project
dotnet watch file watcher tool is included with version 2.1.300 of the .NET Core SDK. The following steps are required when using an earlier version of the .NET Core SDK.
- Add a
Microsoft.DotNet.Watcher.Toolspackage reference to the .csproj file:
<ItemGroup> <DotNetCliToolReference Include="Microsoft.DotNet.Watcher.Tools" Version="2.0.0" /> </ItemGroup>
- Install the
Microsoft.DotNet.Watcher.Toolspackage by running the following command:
Run .NET Core CLI commands using
Any .NET Core CLI command can be run with
dotnet watch. For example:
|Command||Command with watch|
|dotnet run||dotnet watch run|
|dotnet run -f netcoreapp2.0||dotnet watch run -f netcoreapp2.0|
|dotnet run -f netcoreapp2.0 — –arg1||dotnet watch run -f netcoreapp2.0 — –arg1|
|dotnet test||dotnet watch test|
dotnet watch run in the WebApp folder. The console output indicates
watch has started.
Make changes with
dotnet watch is running.
Fix the bug in the
Product method of MathController.cs so it returns the product and not the sum:
public static int Product(int a, int b) return a * b;
Save the file. The console output indicates that
dotnet watch detected a file change and restarted the app.
http://localhost:<port number>/api/math/product?a=4&b=5 returns the correct result.
Run tests using
Productmethod of MathController.cs back to returning the sum. Save the file.
In a command shell, navigate to the WebAppTests folder.
Run dotnet restore.
dotnet watch test. Its output indicates that a test failed and that the watcher is awaiting file changes:
Total tests: 2. Passed: 1. Failed: 1. Skipped: 0. Test Run Failed.
Productmethod code so it returns the product. Save the file.
dotnet watch detects the file change and reruns the tests. The console output indicates the tests passed.
Customize files list to watch
dotnet-watch tracks all files matching the following glob patterns:
More items can be added to the watch list by editing the .csproj file. Items can be specified individually or by using glob patterns.
<ItemGroup> <!-- extends watching group to include *.js files --> <Watch Include="***.js" Exclude="node_modules***;***.js.map;obj***;bin***" /> </ItemGroup>
Opt-out of files to be watched
dotnet-watch can be configured to ignore its default settings. To ignore specific files, add the
Watch="false" attribute to an item’s definition in the .csproj file:
<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="..ClassLibrary1ClassLibrary1.csproj" Watch="false" /> </ItemGroup>
Custom watch projects
dotnet-watch isn’t restricted to C# projects. Custom watch projects can be created to handle different scenarios. Consider the following project layout:
If the goal is to watch both projects, create a custom project file configured to watch both projects:
<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>
To start file watching on both projects, change to the test folder. Execute the following command:
dotnet watch msbuild /t:Test
VSTest executes when any file changes in either test project.
dotnet-watch in GitHub
dotnet-watch is part of the GitHub DotNetTools repository.