Entwickeln von ASP.NET Core-Apps mit einem Dateiwatcher

Von Rick Anderson und Victor Hurdugaci

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

In diesem Tutorial wird eine vorhandene Web-API mit zwei Endpunkten verwendet: der eine gibt eine Summe zurück, der andere ein Produkt. Die Produktmethode enthält einen Fehler, der in diesem Tutorial behoben wird.

Laden Sie die Beispiel-App herunter. Sie enthält zwei Projekte: WebApp (eine ASP.NET Core-Web-API) und WebAppTests (Komponententest für die Web-API).

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

dotnet run

Die Konsolenausgabe zeigt Meldungen ähnlich der folgenden (die angibt, 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. Es sollten die Ergebnisse von 9 angezeigt werden.

Navigieren Sie zur Produkt-API (http://localhost:<port number>/api/math/product?a=4&b=5). Es wird nicht wie erwartet 20 sondern 9 zurückgegeben. Dieses Problem wird später im Tutorial behoben.

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

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

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

Vornehmen von Änderungen mit dotnet watch

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

Korrigieren Sie den Fehler in der Product-Methode von MathController.cs so, dass das Produkt und nicht die Summe zurückgegeben wird:

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

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

Vergewissern Sie sich, dass http://localhost:<port number>/api/math/product?a=4&b=5 das richtige Ergebnis zurückgibt.

Ausführen von Tests mit dotnet watch

1. Ändern Sie die Product-Methode von MathController.cs so, dass wieder die Summe zurückgegeben wird. Speichern Sie die Datei.

2. Navigieren Sie in einer Befehlsshell zum Ordner WebAppTests.

3. Führen Sie dotnet restore aus.

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

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

5. Ändern Sie den Code der Product-Methode so, dass das Produkt zurückgegeben wird. Speichern Sie die Datei.

dotnet watch erkennt die Dateiänderung und führt die Tests erneut aus. Die Konsolenausgabe zeigt, dass die Tests bestanden wurden.

Anpassen der Liste mit den zu überwachenden Dateien

Standardmäßig überwacht dotnet-watch alle Dateien mit den folgenden Globmustern:

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

Durch Bearbeiten der .csproj-Datei können der Watchlist weitere Elemente hinzugefügt werden. Dabei können die Elemente 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>

Abwählen von zu überwachenden Dateien

Sie können dotnet-watch so konfigurieren, dass die Standardeinstellungen ignoriert werden. Wenn Sie bestimmte Dateien ignorieren möchten, fügen Sie der Definition eines Elements in der Datei .csproj das Watch="false"-Attribut 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 Überwachungsprojekte

dotnet-watch ist nicht auf C#-Projekte beschränkt. Sie können für unterschiedliche Szenarios benutzerdefinierte Überwachungsprojekte erstellen. Betrachten Sie das folgende Projektlayout:

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

Wenn beide Projekte überwacht werden sollen, erstellen Sie eine benutzerdefinierte Projektdatei, die so konfiguriert ist, dass beide Projekte überwacht werden:

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

Wechseln Sie zum Starten der Dateiüberwachung in beiden Projekten zum test-Ordner. Führen Sie den folgenden Befehl aus:

dotnet watch msbuild /t:Test

VSTest wird ausgeführt, wenn in einer beliebigen Datei in einem der Testprojekte Änderungen vorgenommen werden.

Konfiguration von dotnet-watch

Einige Konfigurationsoptionen können über Umgebungsvariablen an dotnet watch übergeben werden. Folgende Variablen sind verfügbar:

Browseraktualisierung

dotnet watch fügt ein Skript in die App ein, das es ihr erlaubt, den Browser zu aktualisieren, wenn sich der Inhalt ändert. In einigen Szenarien, z. B. wenn die App die Antwortkomprimierung aktiviert, kann dotnet watch das Skript möglicherweise nicht einfügen. In solchen Fällen, die sich in der Entwicklung befinden, müssen Sie das Skript manuell in die App einfügen. Um beispielsweise die Web-App so zu konfigurieren, dass das Skript manuell eingefügt wird, aktualisieren Sie die Layoutdatei so, dass sie _framework/aspnet-browser-refresh.js enthält:

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

Nicht-ASCII-Zeichen

Visual Studio ab Version 17.2 enthält das .NET SDK 6.0.300 und höher. Mit dem .NET SDK ab 6.0.300 gibt dotnet-watch während einer Hot-Reload-Sitzung Nicht-ASCII-Zeichen an die Konsole aus. Auf bestimmten Konsolenhosts, wie z. B. Windows conhost, können diese Zeichen unlesbar angezeigt werden. Um unlesbare Zeichen zu vermeiden, sollten Sie einen der folgenden Ansätze wählen:

• Konfigurieren Sie die Umgebungsvariable DOTNET_WATCH_SUPPRESS_EMOJIS=1 so, dass die Ausgabe dieser Werte unterdrückt wird.
• Wechseln Sie zu einem anderen Terminal, z. B https://github.com/microsoft/terminal, das das Rendern von Nicht-ASCII-Zeichen unterstützt.