Mengembangkan aplikasi ASP.NET Core menggunakan pengamat file

Oleh Rick Anderson dan Victor Hurdugaci

dotnet watch adalah alat yang menjalankan perintah .NET Core CLI saat file sumber berubah. Misalnya, perubahan file dapat memicu kompilasi, eksekusi pengujian, atau penyebaran.

Tutorial ini menggunakan API web yang ada dengan dua titik akhir: yang mengembalikan jumlah dan yang mengembalikan produk. Metode produk memiliki bug, yang diperbaiki dalam tutorial ini.

Unduh aplikasi sampel. Ini terdiri dari dua proyek: WebApp (API web ASP.NET Core) dan WebAppTests (pengujian unit untuk API web).

Di shell perintah, navigasikan ke folder WebApp . Jalankan perintah berikut:

dotnet run

Catatan

Anda dapat menggunakan dotnet run --project <PROJECT> untuk menentukan proyek yang akan dijalankan. Misalnya, menjalankan dotnet run --project WebApp dari akar aplikasi sampel juga akan menjalankan proyek WebApp .

Output konsol menampilkan pesan yang mirip dengan yang berikut (menunjukkan bahwa aplikasi sedang berjalan dan menunggu permintaan):

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

Di browser web, arahkan ke http://localhost:<port number>/api/math/sum?a=4&b=5. Anda akan melihat hasil .9

Navigasikan ke API produk (http://localhost:<port number>/api/math/product?a=4&b=5). Ini mengembalikan 9, tidak 20 seperti yang Anda harapkan. Masalah tersebut diperbaiki nanti dalam tutorial.

Menjalankan perintah .NET Core CLI menggunakan dotnet watch

Setiap perintah .NET Core CLI dapat dijalankan dengan dotnet watch. Contohnya:

Perintah	Perintah dengan jam tangan
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	uji tonton dotnet

Jalankan dotnet watch run di folder WebApp . Output konsol watch menunjukkan telah dimulai.

Berjalan dotnet watch run di aplikasi web meluncurkan browser yang menavigasi ke URL aplikasi setelah siap. dotnet watch lakukan ini dengan membaca output konsol aplikasi dan menunggu pesan siap yang ditampilkan oleh WebHost.

dotnet watch me-refresh browser saat mendeteksi perubahan pada file yang ditonton. Untuk melakukan ini, perintah watch menyuntikkan middleware ke aplikasi yang memodifikasi respons HTML yang dibuat oleh aplikasi. Middleware menambahkan blok skrip JavaScript ke halaman yang memungkinkan dotnet watch untuk menginstruksikan browser untuk di-refresh. Saat ini, perubahan pada semua file yang ditonton, termasuk konten statis seperti .html dan .css file menyebabkan aplikasi dibangun kembali.

dotnet watch:

• Hanya mengawasi file yang memengaruhi build secara default.
• File yang ditonton tambahan (melalui konfigurasi) masih menghasilkan build yang sedang berlangsung.

Untuk informasi selengkapnya tentang konfigurasi, lihat konfigurasi dotnet-watch dalam dokumen ini.

Catatan

Anda dapat menggunakan dotnet watch --project <PROJECT> untuk menentukan proyek yang akan ditonton. Misalnya, menjalankan dotnet watch --project WebApp run dari akar aplikasi sampel juga akan berjalan dan menonton proyek WebApp .

Membuat perubahan dengan dotnet watch

Pastikan dotnet watch berjalan.

Perbaiki bug dalam Product metode MathController.cs sehingga mengembalikan produk dan bukan jumlahnya:

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

Simpan file. Output konsol menunjukkan bahwa dotnet watch mendeteksi perubahan file dan memulai ulang aplikasi.

Verifikasi http://localhost:<port number>/api/math/product?a=4&b=5 mengembalikan hasil yang benar.

Menjalankan pengujian menggunakan dotnet watch

1. Product Ubah metode kembali MathController.cs untuk mengembalikan jumlah. Simpan file.

2. Di shell perintah, navigasikan ke folder WebAppTests .

3. Jalankan pemulihan dotnet.

4. Jalankan dotnet watch test. Outputnya menunjukkan bahwa pengujian gagal dan pengamat menunggu perubahan file:

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

5. Product Perbaiki kode metode sehingga mengembalikan produk. Simpan file.

dotnet watch mendeteksi perubahan file dan menjalankan ulang pengujian. Output konsol menunjukkan pengujian lulus.

Menyesuaikan daftar file untuk ditonton

Secara default, dotnet-watch melacak semua file yang cocok dengan pola glob berikut:

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

Lebih banyak item dapat ditambahkan ke daftar tonton dengan mengedit .csproj file. Item dapat ditentukan satu per satu atau dengan menggunakan pola glob.

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

Menolak file yang akan ditonton

dotnet-watch dapat dikonfigurasi untuk mengabaikan pengaturan defaultnya. Untuk mengabaikan file tertentu, tambahkan Watch="false" atribut ke definisi item dalam .csproj file:

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

Proyek jam tangan kustom

dotnet-watch tidak dibatasi untuk proyek C#. Proyek pengawasan kustom dapat dibuat untuk menangani skenario yang berbeda. Pertimbangkan tata letak proyek berikut:

• Tes/
  • UnitTests/UnitTests.csproj
  • IntegrationTests/IntegrationTests.csproj

Jika tujuannya adalah untuk menonton kedua proyek, buat file proyek kustom yang dikonfigurasi untuk menonton kedua proyek:

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

Untuk memulai pengamatan file di kedua proyek, ubah ke folder pengujian . Jalankan perintah berikut:

dotnet watch msbuild /t:Test

VSTest dijalankan ketika ada perubahan file di salah satu proyek pengujian.

konfigurasi dotnet-watch

Beberapa opsi konfigurasi dapat diteruskan ke dotnet watch melalui variabel lingkungan. Variabel yang tersedia adalah:

Pengaturan	Deskripsi
DOTNET_USE_POLLING_FILE_WATCHER	Jika diatur ke "1" atau "true", dotnet watch menggunakan pengamat file polling alih-alih CoreFx FileSystemWatcher. Digunakan saat menonton file pada berbagi jaringan atau volume yang dipasang Docker.
DOTNET_WATCH_SUPPRESS_MSBUILD_INCREMENTALISM	Secara default, dotnet watch mengoptimalkan build dengan menghindari operasi tertentu seperti menjalankan pemulihan atau mengevaluasi kembali kumpulan file yang ditonton pada setiap perubahan file. Jika diatur ke "1" atau "true", pengoptimalan ini dinonaktifkan.
DOTNET_WATCH_SUPPRESS_LAUNCH_BROWSER	dotnet watch run mencoba meluncurkan browser untuk aplikasi web dengan launchBrowser dikonfigurasi di launchSettings.json. Jika diatur ke "1" atau "true", perilaku ini ditekan.
DOTNET_WATCH_SUPPRESS_BROWSER_REFRESH	dotnet watch run mencoba untuk menyegarkan browser ketika mendeteksi perubahan file. Jika diatur ke "1" atau "true", perilaku ini ditekan. Perilaku ini juga ditekan jika DOTNET_WATCH_SUPPRESS_LAUNCH_BROWSER diatur.

Refresh browser

dotnet watch menyuntikkan skrip ke dalam aplikasi yang memungkinkannya untuk me-refresh browser saat konten berubah. Dalam beberapa skenario, seperti ketika aplikasi mengaktifkan kompresi respons, dotnet watch mungkin tidak dapat menyuntikkan skrip. Untuk kasus tersebut dalam pengembangan, masukkan skrip secara manual ke dalam aplikasi. Misalnya, untuk mengonfigurasi aplikasi web untuk menyuntikkan skrip secara manual, perbarui file tata letak untuk menyertakan _framework/aspnet-browser-refresh.js:

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

Karakter non-ASCII

Visual Studio 17.2 dan yang lebih baru menyertakan .NET SDK 6.0.300 dan yang lebih baru. Dengan .NET SDK dan 6.0.300 lebih baru, dotnet-watch memancarkan karakter non-ASCII ke konsol selama sesi isi ulang panas. Pada host konsol tertentu, seperti conhost Windows, karakter ini mungkin tampak kacau. Untuk menghindari karakter kacau, pertimbangkan salah satu pendekatan berikut:

• Konfigurasikan DOTNET_WATCH_SUPPRESS_EMOJIS=1 variabel lingkungan untuk menekan pemancaran nilai-nilai ini.
• Beralih ke terminal yang berbeda, seperti https://github.com/microsoft/terminal, yang mendukung penyajian karakter non-ASCII.