Tworzenie aplikacji ASP.NET Core przy użyciu obserwatora plików

Artykuł
11/30/2023

dotnet watch to narzędzie uruchamiające polecenie interfejsu wiersza polecenia platformy .NET po zmianie plików źródłowych. Na przykład zmiana pliku może wyzwolić kompilację, wykonanie testu lub wdrożenie.

W tym samouczku jest używany istniejący internetowy interfejs API z dwoma punktami końcowymi: jeden, który zwraca sumę i jeden, który zwraca produkt. Metoda produktu zawiera usterkę, która została naprawiona w tym samouczku.

Pobierz przykładową aplikację. Składa się z dwóch projektów: WebApp (internetowy interfejs API platformy ASP.NET Core) i WebAppTests (testy jednostkowe internetowego interfejsu API).

W powłoce poleceń przejdź do folderu WebApp . Uruchom następujące polecenie:

dotnet run

Uwaga

Możesz użyć dotnet run --project <PROJECT> polecenia , aby określić projekt do uruchomienia. Na przykład uruchomienie dotnet run --project WebApp z poziomu katalogu głównego przykładowej aplikacji spowoduje również uruchomienie projektu aplikacji internetowej .

Dane wyjściowe konsoli zawierają komunikaty podobne do następujących (wskazujących, że aplikacja jest uruchomiona i oczekuje na żądania):

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

W przeglądarce internetowej przejdź do http://localhost:<port number>/api/math/sum?a=4&b=5adresu . Powinien zostać wyświetlony wynik .9

Przejdź do interfejsu API produktu (http://localhost:<port number>/api/math/product?a=4&b=5). Zwraca wartość 9, a nie 20 zgodnie z oczekiwaniami. Ten problem został rozwiązany w dalszej części samouczka.

Dodawanie `dotnet watch` do projektu

Narzędzie dotnet watch obserwatora plików jest dołączone do wersji 2.1.300 zestawu .NET Core SDK. W przypadku używania starszej wersji zestawu .NET Core SDK wymagane są następujące kroki.

Microsoft.DotNet.Watcher.Tools Dodaj odwołanie do pakietu do .csproj pliku:

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

Zainstaluj pakiet Microsoft.DotNet.Watcher.Tools, uruchamiając następujące polecenie:
```
dotnet restore
```

Uruchamianie poleceń interfejsu wiersza polecenia platformy .NET przy użyciu polecenia `dotnet watch`

Każde polecenie interfejsu wiersza polecenia platformy .NET można uruchomić za pomocą polecenia dotnet watch. Na przykład:

Polecenie	Polecenie z zegarkiem
dotnet run	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

Uruchom polecenie dotnet watch run w folderze WebApp . Dane wyjściowe konsoli wskazują, że zostało uruchomione watch .

Uruchomienie dotnet watch run aplikacji internetowej powoduje uruchomienie przeglądarki, która przechodzi do adresu URL aplikacji po uzyskaniu gotowości. dotnet watch Robi to, odczytując dane wyjściowe konsoli aplikacji i czekając na gotowy komunikat wyświetlany przez WebHost.

dotnet watch odświeża przeglądarkę po wykryciu zmian w obserwowanych plikach. W tym celu polecenie watch wprowadza oprogramowanie pośredniczące do aplikacji, która modyfikuje odpowiedzi HTML utworzone przez aplikację. Oprogramowanie pośredniczące dodaje do strony blok skryptu JavaScript, który umożliwia dotnet watch poinstruowanie przeglądarki o odświeżeniu. Obecnie zmiany wszystkich obserwowanych plików, w tym zawartości statycznej, takiej jak .html i .css pliki, powodują ponowne skompilowanie aplikacji.

dotnet watch:

Tylko pliki, które mają wpływ na kompilacje domyślnie.
Wszystkie dodatkowo obserwowane pliki (za pośrednictwem konfiguracji) nadal są wynikiem kompilacji.

Aby uzyskać więcej informacji na temat konfiguracji, zobacz dotnet-watch configuration w tym dokumencie.

Uwaga

Możesz użyć dotnet watch --project <PROJECT> polecenia , aby określić projekt do obejrzenia. Na przykład uruchomienie dotnet watch --project WebApp run z poziomu katalogu głównego przykładowej aplikacji spowoduje również uruchomienie i obserwowanie projektu aplikacji internetowej .

Wprowadzanie zmian za pomocą polecenia `dotnet watch`

Upewnij się, że dotnet watch działa.

Napraw usterkę w Product metodzie , MathController.cs aby zwracała produkt, a nie sumę:

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

Zapisz plik. Dane wyjściowe konsoli wskazują, że dotnet watch wykryto zmianę pliku i uruchomiono ponownie aplikację.

Funkcja Verify http://localhost:<port number>/api/math/product?a=4&b=5 zwraca prawidłowy wynik.

Uruchamianie testów przy użyciu `dotnet watch`

Zmień metodę Product powrotu, MathController.cs aby zwrócić sumę. Zapisz plik.
W powłoce poleceń przejdź do folderu WebAppTests .
Uruchom polecenie dotnet restore.
Uruchom program dotnet watch test. Jego dane wyjściowe wskazują, że test zakończył się niepowodzeniem i że obserwator oczekuje na zmiany w pliku:
```
Total tests: 2. Passed: 1. Failed: 1. Skipped: 0.
Test Run Failed.
```
Napraw kod metody, Product aby zwracał produkt. Zapisz plik.

dotnet watch wykrywa zmianę pliku i uruchamia ponownie testy. Dane wyjściowe konsoli wskazują, że testy zostały pomyślnie wykonane.

Dostosowywanie listy plików do obejrzenia

Domyślnie dotnet-watch śledzi wszystkie pliki pasujące do następujących wzorców globu:

**/*.cs
*.csproj
**/*.resx
Pliki zawartości: wwwroot/**, , **/*.config**/*.json

Więcej elementów można dodać do listy obserwowanych, edytując .csproj plik. Elementy można określić indywidualnie lub za pomocą wzorców globu.

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

Rezygnacja z plików do obejrzenia

dotnet-watch Można skonfigurować tak, aby ignorować jego ustawienia domyślne. Aby zignorować określone pliki, dodaj Watch="false" atrybut do definicji elementu w .csproj pliku:

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

Projekty zegarków niestandardowych

dotnet-watch nie jest ograniczona do projektów w języku C#. Niestandardowe projekty zegarków można tworzyć w celu obsługi różnych scenariuszy. Rozważmy następujący układ projektu:

Test/
- UnitTests/UnitTests.csproj
- IntegrationTests/IntegrationTests.csproj

Jeśli celem jest obserwowanie obu projektów, utwórz niestandardowy plik projektu skonfigurowany do oglądania obu projektów:

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

Aby rozpocząć oglądanie plików w obu projektach, przejdź do folderu testowego. Wykonaj następujące polecenie:

dotnet watch msbuild /t:Test

Program VSTest jest wykonywany, gdy dowolny plik ulegnie zmianie w dowolnym projekcie testowym.

konfiguracja dotnet-watch

Niektóre opcje konfiguracji można przekazać do dotnet watch zmiennych środowiskowych. Dostępne zmienne to:

Ustawienie	opis
`DOTNET_USE_POLLING_FILE_WATCHER`	W przypadku ustawienia wartości "1" lub "true" `dotnet watch` użyje obserwatora `FileSystemWatcher`plików sondowania zamiast elementu CoreFx. Używany podczas oglądania plików w udziałach sieciowych lub woluminach zainstalowanych na platformie Docker.
`DOTNET_WATCH_SUPPRESS_MSBUILD_INCREMENTALISM`	Domyślnie optymalizuje kompilację, unikając niektórych operacji, `dotnet watch` takich jak uruchamianie przywracania lub ponowne ocenianie zestawu obserwowanych plików na każdej zmianie pliku. W przypadku ustawienia wartości "1" lub "true" te optymalizacje są wyłączone.
`DOTNET_WATCH_SUPPRESS_LAUNCH_BROWSER`	`dotnet watch run` próbuje uruchomić przeglądarki dla aplikacji internetowych ze skonfigurowanym `launchBrowser` w programie `launchSettings.json`. Jeśli ustawiono wartość "1" lub "true", to zachowanie jest pomijane.
`DOTNET_WATCH_SUPPRESS_BROWSER_REFRESH`	`dotnet watch run` program próbuje odświeżyć przeglądarki, gdy wykryje zmiany plików. Jeśli ustawiono wartość "1" lub "true", to zachowanie jest pomijane. To zachowanie jest również pomijane w przypadku `DOTNET_WATCH_SUPPRESS_LAUNCH_BROWSER` ustawienia.

Odświeżanie przeglądarki

dotnet watch wprowadza skrypt do aplikacji, który umożliwia jej odświeżenie przeglądarki po zmianie zawartości. W niektórych scenariuszach, takich jak włączenie kompresji odpowiedzi przez aplikację, dotnet watch może nie być w stanie wstrzyknąć skryptu. W takich przypadkach podczas programowania ręcznie wstrzyknąć skrypt do aplikacji. Aby na przykład skonfigurować aplikację internetową w celu ręcznego wstrzyknięcia skryptu, zaktualizuj plik układu, aby zawierał polecenie _framework/aspnet-browser-refresh.js:

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

Znaki inne niż ASCII

Program Visual Studio 17.2 lub nowszy zawiera zestaw .NET SDK 6.0.300 lub nowszy. W przypadku zestawu .NET SDK i wersji 6.0.300 nowszej dotnet-watch program emituje znaki inne niż ASCII do konsoli podczas sesji ponownego ładowania. Na niektórych hostach konsoli, takich jak conhost systemu Windows, te znaki mogą być wyświetlane zwijać. Aby uniknąć zwijania znaków, należy wziąć pod uwagę jedno z następujących podejść:

Skonfiguruj zmienną środowiskową, DOTNET_WATCH_SUPPRESS_EMOJIS=1 aby pominąć emitowanie tych wartości.
Przełącz się do innego terminalu, takiego jak , który obsługuje renderowanie znaków innych niż https://github.com/microsoft/terminalASCII.

Udostępnij za pośrednictwem

Tworzenie aplikacji ASP.NET Core przy użyciu obserwatora plików

Dodawanie `dotnet watch` do projektu

Uruchamianie poleceń interfejsu wiersza polecenia platformy .NET przy użyciu polecenia `dotnet watch`

Wprowadzanie zmian za pomocą polecenia `dotnet watch`

Uruchamianie testów przy użyciu `dotnet watch`

Dostosowywanie listy plików do obejrzenia

Rezygnacja z plików do obejrzenia

Projekty zegarków niestandardowych

konfiguracja dotnet-watch

Odświeżanie przeglądarki

Znaki inne niż ASCII

Dodatkowe zasoby

Udostępnij za pośrednictwem

Tworzenie aplikacji ASP.NET Core przy użyciu obserwatora plików

Dodawanie dotnet watch do projektu

Uruchamianie poleceń interfejsu wiersza polecenia platformy .NET przy użyciu polecenia dotnet watch

Wprowadzanie zmian za pomocą polecenia dotnet watch

Uruchamianie testów przy użyciu dotnet watch

Dostosowywanie listy plików do obejrzenia

Rezygnacja z plików do obejrzenia

Projekty zegarków niestandardowych

konfiguracja dotnet-watch

Odświeżanie przeglądarki

Znaki inne niż ASCII

Dodatkowe zasoby

Dodawanie `dotnet watch` do projektu

Uruchamianie poleceń interfejsu wiersza polecenia platformy .NET przy użyciu polecenia `dotnet watch`

Wprowadzanie zmian za pomocą polecenia `dotnet watch`

Uruchamianie testów przy użyciu `dotnet watch`