AspNetCore.Docs/aspnetcore/tutorials/dotnet-watch.md

title	author	description	manager	ms.author	ms.date	ms.prod	ms.technology	ms.topic	uid
Develop ASP.NET Core apps using a file watcher	rick-anderson	This tutorial demonstrates how to install and use the .NET Core CLI's file watcher (dotnet watch) tool in an ASP.NET Core app.	wpickett	riande	05/31/2018	asp.net-core	aspnet	article	tutorials/dotnet-watch

Develop ASP.NET Core apps using a file watcher

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.

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:

dotnet run

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 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. That problem is fixed later in the tutorial.

::: moniker range="<= aspnetcore-2.0"

Add dotnet watch to a project

The 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.

1. Add a Microsoft.DotNet.Watcher.Tools package reference to the .csproj file:

   <ItemGroup>
       <DotNetCliToolReference Include="Microsoft.DotNet.Watcher.Tools" Version="2.0.0" />
   </ItemGroup>
   

2. Install the Microsoft.DotNet.Watcher.Tools package by running the following command:

   dotnet restore
   

::: moniker-end

Run .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.

Make 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:

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.

Verify http://localhost:<port number>/api/math/product?a=4&b=5 returns the correct result.

Run tests using dotnet watch

1. Change the Product method of MathController.cs back to returning the sum. Save the file.

2. In a command shell, navigate to the WebAppTests folder.

3. Run dotnet restore.

4. Run 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.
   

5. Fix the Product method 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 has information on dotnet-watch not covered in this tutorial.