Utveckla ASP.NET Core-appar med hjälp av en filbevakare

Av Rick Anderson och Victor Hurdugaci

dotnet watch är ett verktyg som kör ett .NET CLI-kommando när källfilerna ändras. En filändring kan till exempel utlösa kompilering, testkörning eller distribution.

I den här självstudien används ett befintligt webb-API med två slutpunkter: en som returnerar en summa och en som returnerar en produkt. Produktmetoden har en bugg som fixas i den här handledningen.

Ladda ned exempelappen. Den består av två projekt: WebApp (ett ASP.NET Core-webb-API) och WebAppTests (enhetstester för webb-API:et).

I ett kommandogränssnitt navigerar du till mappen WebApp . Kör följande kommando:

dotnet run

Anmärkning

Du kan använda dotnet run --project <PROJECT> för att ange ett projekt som ska köras. Om du till exempel kör dotnet run --project WebApp från roten i exempelappen körs även WebApp-projektet .

Konsolens utdata visar meddelanden som liknar följande (som anger att appen körs och väntar på begäranden):

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

I en webbläsare navigerar du till http://localhost:<port number>/api/math/sum?a=4&b=5. Du bör se resultatet av 9.

Gå till produkt-API:et (http://localhost:<port number>/api/math/product?a=4&b=5). Den returnerar 9, inte 20 som förväntat. Det problemet åtgärdas senare i handledningen.

Kör .NET CLI-kommandon med hjälp av dotnet watch

Alla .NET CLI-kommandon kan köras med dotnet watch. Till exempel:

Befallning	Kommando med klocka
dotnet-körning	dotnet watch run
dotnet run -f netcoreapp3.1	dotnet watch run -f netcoreapp3.1
dotnet run -f netcoreapp3.1 -- --arg1	dotnet watch run -f netcoreapp3.1 -- --arg1
dotnet-test	dotnet watch test

Kör dotnet watch run i mappen WebApp . Konsolens utdata anger att watch har startats.

Att köra dotnet watch run på en webbapp startar en webbläsare som navigerar till appens URL när den är redo. dotnet watch gör detta genom att läsa appens konsolutdata och vänta på det färdiga meddelandet som visas av WebHost.

dotnet watch uppdaterar webbläsaren när den identifierar ändringar i övervakade filer. För att göra detta matar klockkommandot in ett mellanprogram till appen som ändrar HTML-svar som skapats av appen. Mellanprogrammet lägger till ett JavaScript-skriptblock på sidan som gör det möjligt dotnet watch att instruera webbläsaren att uppdatera. För närvarande leder ändringar i alla övervakade filer, inklusive statiskt innehåll som .html och .css filer, till att appen kompileras om.

dotnet watch:

• Bevakar endast filer som påverkar byggen som standard.
• Ytterligare övervakade filer (via konfiguration) resulterar fortfarande i att en build sker.

Mer information om konfiguration finns i dotnet-watch-konfigurationen i det här dokumentet.

Anmärkning

Du kan använda dotnet watch --project <PROJECT> för att ange ett projekt att titta på. Om du till exempel kör dotnet watch --project WebApp run från roten av exempelappen kommer du också att köra och övervaka WebApp-projektet.

Gör ändringar med dotnet watch

Kontrollera att dotnet watch körs.

Åtgärda felet i Product metoden MathController.cs för så att den returnerar produkten och inte summan:

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

Spara filen. Konsolens utdata anger att dotnet watch en filändring upptäcktes och appen startades om.

Verifiera http://localhost:<port number>/api/math/product?a=4&b=5 returnerar rätt resultat.

Köra tester med hjälp av dotnet watch

1. Ändra metoden för Product tillbaka till att returnera summan med MathController.cs. Spara filen.

2. I ett kommandogränssnitt navigerar du till mappen WebAppTests .

3. Kör dotnet restore.

4. Kör dotnet watch test. Dess utdata anger att ett test misslyckades och att bevakaren väntar på filändringar:

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

5. Product Åtgärda metodkoden så att den returnerar produkten. Spara filen.

dotnet watch identifierar filändringen och kör testerna igen. Konsolens utdata anger vilka tester som har godkänts.

Anpassa fillistan för övervakning

Som standard dotnet-watch spårar alla filer som matchar följande globmönster:

• **/*.cs
• *.csproj
• **/*.resx
• Innehållsfiler: wwwroot/**, **/*.config, , **/*.json

Fler objekt kan läggas till i bevakningslistan genom att redigera .csproj filen. Objekt kan anges individuellt eller med hjälp av globmönster.

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

Avregistrera filer som ska övervakas

dotnet-watch kan konfigureras för att ignorera standardinställningarna. Om du vill ignorera specifika filer lägger du till Watch="false" attributet i ett objekts definition i .csproj filen:

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

Specialdesignade klockprojekt

dotnet-watch är inte begränsat till C#-projekt. Anpassade klockprojekt kan skapas för att hantera olika scenarier. Överväg följande projektlayout:

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

Om målet är att titta på båda projekten skapar du en anpassad projektfil som konfigurerats för att titta på båda projekten:

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

Om du vill starta filvisning i båda projekten ändrar du till testmappen . Kör följande kommando:

dotnet watch msbuild /t:Test

VSTest körs när någon fil ändras i något av testprojekten.

dotnet-watch-konfiguration

Vissa konfigurationsalternativ kan skickas till dotnet watch via miljövariabler. Tillgängliga variabler är:

Inställning	Beskrivning
DOTNET_USE_POLLING_FILE_WATCHER	Om värdet är "1" eller "true" dotnet watch använder en avsökningsfilbevakare i stället för CoreFx.FileSystemWatcher Används när du tittar på filer på nätverksdelningar eller Docker-monterade volymer.
DOTNET_WATCH_SUPPRESS_MSBUILD_INCREMENTALISM	Som standard dotnet watch optimerar bygget genom att undvika vissa specifika åtgärder, exempelvis att köra återställning eller återutvärdera uppsättningen övervakade filer vid varje filändring. Om värdet är "1" eller "true" inaktiveras dessa optimeringar.
DOTNET_WATCH_SUPPRESS_LAUNCH_BROWSER	dotnet watch run försöker starta webbläsare för webbappar med launchBrowser konfigurerat i launchSettings.json. Om värdet är "1" eller "true" ignoreras det här beteendet.
DOTNET_WATCH_SUPPRESS_BROWSER_REFRESH	dotnet watch run försöker uppdatera webbläsare när den identifierar filändringar. Om värdet är "1" eller "true" ignoreras det här beteendet. Det här beteendet undertrycks också om DOTNET_WATCH_SUPPRESS_LAUNCH_BROWSER är inställt.

Webbläsaruppdatering

dotnet watch matar in ett skript i appen som gör att den kan uppdatera webbläsaren när innehållet ändras. I vissa scenarier, till exempel när appen aktiverar svarskomprimering, dotnet watch kanske inte kan mata in skriptet. I sådana fall under utveckling matar du in skriptet manuellt i appen. Om du till exempel vill konfigurera webbappen så att skriptet matas in manuellt uppdaterar du layoutfilen så att den inkluderar _framework/aspnet-browser-refresh.js:

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

Icke-ASCII-tecken

Visual Studio 17.2 eller senare innehåller .NET SDK 6.0.300 eller senare. Med .NET SDK version 6.0.300 eller senare skriver dotnet-watch ut icke-ASCII-tecken till konsolen under en hot reload-session. På vissa konsolvärdar, till exempel Windows conhost, kan dessa tecken verka förvrängda. Tänk på något av följande för att undvika förvrängda tecken:

• DOTNET_WATCH_SUPPRESS_EMOJIS=1 Konfigurera miljövariabeln så att den inte genererar dessa värden.
• Växla till en annan terminal, till exempel , som https://github.com/microsoft/terminalstöder återgivning av icke-ASCII-tecken.