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

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:

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

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

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.

Dateiüberwachungsgrenzwerte in Linux

Wenn Sie dotnet watch unter Linux oder in Docker-Containern ausführen, tritt möglicherweise ein Fehler auf, dass der konfigurierte Grenzwert pro Benutzer für die Anzahl der inotify-Instanzen erreicht wurde:

The configured user limit (128) on the number of inotify instances has been reached, or the per-process limit on the number of open file descriptors has been reached.

Wenn das Instanzlimit für inotify erreicht ist, erhöhen Sie fs.inotify.max_user_instances. Wenn der Prozess seinen Grenzwert für die Open-File-Deskriptor erreicht hat, erhöhen Sie stattdessen diesen Grenzwert. Die gesonderte fs.inotify.max_user_watches Einstellung gilt, wenn das Limit für inotify-Überwachungen ausgeschöpft ist.

Führen Sie die folgenden Befehle aus, um diese Grenzwerte vorübergehend zu erhöhen:

sudo sysctl fs.inotify.max_user_instances=524288
sudo sysctl fs.inotify.max_user_watches=524288

Um diese Änderung dauerhaft zu ändern, fügen Sie der /etc/sysctl.conf Datei die folgenden Zeilen hinzu:

fs.inotify.max_user_instances=524288
fs.inotify.max_user_watches=524288