Entwickeln von ASP.NET Core-Apps mit einem Dateiüberwachungs-Element

Von Rick Anderson und Victor Hurdugaci

dotnet watch ist ein Tool, das einen .NET CLI-Befehl ausführt, wenn sich Quelldateien ändern. Beispielsweise kann eine Dateiänderung die Kompilierung, die Testausführung oder die Bereitstellung auslösen.

In diesem Lernprogramm wird eine vorhandene Web-API mit zwei Endpunkten verwendet: eine, die eine Summe zurückgibt und eine, die ein Produkt zurückgibt. Die Produktmethode hat einen Fehler, der in diesem Lernprogramm behoben ist.

Laden Sie die Beispiel-App herunter. Es besteht aus zwei Projekten: WebApp (eine ASP.NET Core Web API) und WebAppTests (Komponententests für die Web-API).

Navigieren Sie in einer Befehlsshell zum WebApp-Ordner . Führen Sie den folgenden Befehl aus:

dotnet run

Hinweis

Sie können verwenden dotnet run --project <PROJECT> , um ein auszuführenes Projekt anzugeben. Wenn Sie beispielsweise dotnet run --project WebApp aus dem Stammverzeichnis der Sample-App ausführen, wird auch das WebApp-Projekt ausgeführt.

Die Konsolenausgabe zeigt Nachrichten ähnlich wie die folgenden an (dies gibt an, dass die App ausgeführt wird und auf Anforderungen wartet):

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

Navigieren Sie in einem Webbrowser zu http://localhost:<port number>/api/math/sum?a=4&b=5. Sie sollten sich das Ergebnis von 9 ansehen.

Navigieren Sie zur Produkt-API (http://localhost:<port number>/api/math/product?a=4&b=5). Es gibt 9 zurück, nicht 20, wie man erwarten würde. Dieses Problem wurde später im Lernprogramm behoben.

Ausführen von .NET CLI-Befehlen mit dotnet watch

Jeder .NET CLI-Befehl kann mit dotnet watch ausgeführt werden. Beispiel:

Befehl	Befehl mit Überwachung
dotnet run (Befehl zum Ausführen einer .NET-Anwendung)	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

Führen Sie dotnet watch run im Ordner WebApp aus. Die Konsolenausgabe gibt an, dass watch gestartet wurde.

Das Ausführen von dotnet watch run auf einer Web-App startet einen Browser, der zur URL der App navigiert, sobald die App bereit ist. dotnet watch tut dies, indem es die Konsolenausgabe der App liest und auf die von WebHost angezeigte Bereitschaftsmeldung wartet.

dotnet watch aktualisiert den Browser, wenn Änderungen an überwachten Dateien erkannt werden. Dazu fügt der Überwachungsbefehl eine Middleware in die App ein, die HTML-Antworten ändert, die von der App erstellt wurden. Die Middleware fügt der Seite einen JavaScript-Skriptblock hinzu, der es dotnet watch ermöglicht, den Browser zum Aktualisieren aufzufordern. Derzeit führen Änderungen an allen überwachten Dateien, einschließlich statischer Inhalte wie .html und .css Dateien, dazu, dass die App neu erstellt wird.

dotnet watch:

• Überwacht nur Dateien, die sich standardmäßig auf Builds auswirken.
• Alle zusätzlich überwachten Dateien (über die Konfiguration) führen immer noch zu einem Build-Vorgang.

Weitere Informationen zur Konfiguration finden Sie in diesem Dokument unter dotnet-watch-Konfiguration .

Hinweis

Sie können zum Angeben eines zu überwachenden Projekts verwenden dotnet watch --project <PROJECT> . Beispielsweise wird durch Ausführen von dotnet watch --project WebApp run aus dem Stammverzeichnis der Beispiel-App auch das WebApp-Projekt ausgeführt und überwacht.

Änderungen vornehmen mit dotnet watch

Stellen Sie sicher, dass dotnet watch ausgeführt wird.

Beheben Sie den Fehler in der Product Methode, MathController.cs damit es das Produkt und nicht die Summe zurückgibt:

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

Speichern Sie die Datei. Die Konsolenausgabe gibt an, dass dotnet watch eine Dateiänderung erkannt und die App neu gestartet wurde.

Überprüfen Sie, ob http://localhost:<port number>/api/math/product?a=4&b=5 das richtige Ergebnis zurückgibt.

Ausführen von Tests mithilfe von dotnet watch

1. Ändern Sie die Methode von Product bei MathController.cs, sodass sie wieder die Summe zurückgibt. Speichern Sie die Datei.

2. Navigieren Sie in einer Befehlsshell zum Ordner "WebAppTests ".

3. Führen Sie die dotnet-Wiederherstellung aus.

4. Führen Sie dotnet watch test aus. Die Ausgabe gibt an, dass ein Test fehlgeschlagen ist und dass der Watcher auf Dateiänderungen wartet:

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

5. Korrigieren Sie den Product Methodencode, damit es das Produkt zurückgibt. Speichern Sie die Datei.

dotnet watch erkennt die Dateiänderung und führen die Tests erneut aus. Die Konsolenausgabe gibt die bestandenen Tests an.

Anpassen der Dateiliste zur Überwachung

Standardmäßig wird dotnet-watch verwendet, um alle Dateien zu verfolgen, die den folgenden Globmustern entsprechen:

• **/*.cs
• *.csproj
• **/*.resx
• Inhaltsdateien: wwwroot/**, , **/*.config**/*.json

Weitere Elemente können der Überwachungsliste durch Bearbeiten der .csproj Datei hinzugefügt werden. Elemente können einzeln oder mithilfe von Globmustern angegeben werden.

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

Abmelden von Dateien, die überwacht werden sollen

dotnet-watch kann so konfiguriert werden, dass die Standardeinstellungen ignoriert werden. Um bestimmte Dateien zu ignorieren, fügen Sie das Watch="false" Attribut zur Definition eines Elements in der .csproj Datei hinzu:

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

Benutzerdefinierte Uhrenprojekte

dotnet-watch ist nicht auf C#-Projekte beschränkt. Benutzerdefinierte Uhrenprojekte können erstellt werden, um verschiedene Szenarien zu behandeln. Betrachten Sie das folgende Projektlayout:

• Test/
  • UnitTests/UnitTests.csproj
  • IntegrationTests/IntegrationTests.csproj

Wenn beide Projekte überwacht werden sollen, erstellen Sie eine benutzerdefinierte Projektdatei, die für die Überwachung beider Projekte konfiguriert ist:

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

Um die Dateibeobachtung für beide Projekte zu starten, wechseln Sie in den Testordner . Führen Sie den folgenden Befehl aus:

dotnet watch msbuild /t:Test

VSTest wird ausgeführt, wenn sich dateien in beiden Testprojekts ändern.

dotnet-watch-Konfiguration

Einige Konfigurationsoptionen können an dotnet watch durch Umgebungsvariablen übergeben werden. Die verfügbaren Variablen sind:

Konfiguration	BESCHREIBUNG
DOTNET_USE_POLLING_FILE_WATCHER	Wenn dieser Wert auf "1" oder "true" festgelegt ist, wird anstelle von CoreFx dotnet watch ein Polling-Dateiüberwacher FileSystemWatcher verwendet. Wird verwendet, wenn Dateien auf Netzwerkfreigaben oder docker-bereitgestellten Volumes überwacht werden.
DOTNET_WATCH_SUPPRESS_MSBUILD_INCREMENTALISM	Standardmäßig optimiert dotnet watch den Build, indem bestimmte Vorgänge wie das Ausführen des Wiederherstellungsvorgangs oder eine erneute Bewertung der überwachten Datei-Sets für jede Dateiänderung vermieden werden. Wenn dieser Wert auf "1" oder "true" festgelegt ist, werden diese Optimierungen deaktiviert.
DOTNET_WATCH_SUPPRESS_LAUNCH_BROWSER	dotnet watch run versucht, Browser für Web-Apps zu starten, die mit launchBrowser in launchSettings.json konfiguriert sind. Wenn dieser Wert auf "1" oder "true" festgelegt ist, wird dieses Verhalten unterdrückt.
DOTNET_WATCH_SUPPRESS_BROWSER_REFRESH	dotnet watch run versucht, Browser zu aktualisieren, wenn Dateiänderungen erkannt werden. Wenn dieser Wert auf "1" oder "true" festgelegt ist, wird dieses Verhalten unterdrückt. Dieses Verhalten wird auch unterdrückt, wenn DOTNET_WATCH_SUPPRESS_LAUNCH_BROWSER festgelegt wird.

Browseraktualisierung

dotnet watch fügt ein Skript in die App ein, mit dem der Browser aktualisiert werden kann, wenn sich der Inhalt ändert. In einigen Szenarien, z. B. wenn die App die Reaktionskomprimierung aktiviert, dotnet watch kann das Skript möglicherweise nicht eingefügt werden. Bei solchen Fällen in der Entwicklung wird das Skript manuell in die App eingefügt. Um beispielsweise die Web-App so zu konfigurieren, dass das Skript manuell eingefügt wird, aktualisieren Sie die Layoutdatei so, dass folgendes enthalten _framework/aspnet-browser-refresh.jsist:

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

Nicht-ASCII-Zeichen

Visual Studio 17.2 oder höher enthält das .NET SDK 6.0.300 oder höher. Mit der .NET SDK Version 6.0.300 und später gibt dotnet-watch während einer Hot-Reload-Sitzung nicht-ASCII-Zeichen an die Konsole aus. Auf bestimmten Konsolenhosts, wie zum Beispiel dem Windows-Conhost, können diese Zeichen möglicherweise fehlerhaft angezeigt werden. Um unleserliche Zeichen zu vermeiden, können Sie einen der folgenden Ansätze berücksichtigen.

• Konfigurieren Sie die DOTNET_WATCH_SUPPRESS_EMOJIS=1 Umgebungsvariable, um diese Werte zu unterdrücken.
• Wechseln Sie zu einem anderen Terminal, wie beispielsweise https://github.com/microsoft/terminal, das die Wiedergabe von Nicht-ASCII-Zeichen unterstützt.