Developing ASP.NET Core apps using dotnet watch
By Rick Anderson and Victor Hurdugaci
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.
In this tutorial, we use an existing Web API app with two endpoints: one that returns a sum and one that returns a product. The product method contains a bug that we’ll fix as part of this tutorial.
Download the sample app. It contains 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 and run the following command:
dotnet runThe 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 9.
Navigate to the product API (http://localhost:<port number>/api/math/product?a=4&b=5). It returns 9, not 20 as you’d expect. We’ll fix that later in the tutorial.
Add dotnet watch to a project
Add a
Microsoft.DotNet.Watcher.Toolspackage reference to the .csproj file:Install the
Microsoft.DotNet.Watcher.Toolspackage by running the following command:dotnet restore
Running .NET Core CLI commands using dotnet watch
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 |
Run dotnet watch run in the WebApp folder. The console output indicates watch has started.
Making changes with dotnet watch
Make sure dotnet watch is running.
Fix the bug in the Product method of MathController.cs so it returns the product and not the sum:
Save the file. The console output indicates that dotnet watch detected a file change and restarted the app.
Verify http://localhost:<port number>/api/math/product?a=4&b=5 returns the correct result.
Running tests using dotnet watch
- Change the
Productmethod of MathController.cs back to returning the sum and save the file. - In a command shell, navigate to the WebAppTests folder.
- Run
dotnet restore. Run
dotnet watch test. Its output indicates that a test failed and that watcher is awaiting file changes:Total tests: 2. Passed: 1. Failed: 1. Skipped: 0. Test Run Failed.Fix the
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.
dotnet-watch in GitHub
dotnet-watch is part of the GitHub DotNetTools repository.
The MSBuild section of the dotnet-watch ReadMe explains how dotnet-watch can be configured from the MSBuild project file being watched. The dotnet-watch ReadMe contains information on dotnet-watch not covered in this tutorial.
