Sviluppare app ASP.NET Core usando un watcher per file

Di Rick Anderson e Victor Hurdugaci

dotnet watch è uno strumento che esegue un comando dell'interfaccia della riga di comando di .NET quando i file di origine cambiano. Ad esempio, una modifica di file può attivare la compilazione, l'esecuzione di test o la distribuzione.

Questa esercitazione usa un'API Web esistente con due endpoint, di cui uno restituisce una somma e l'altro un prodotto. Il metodo del prodotto ha un bug, che verrà corretto in questa esercitazione.

Scaricare l'app di esempio. Questa è costituita da due progetti: WebApp (un'API Web di ASP.NET Core) e WebAppTests (unit test per l'API Web).

In una shell dei comandi passare alla cartella WebApp. Eseguire il comando riportato di seguito:

dotnet run

L'output della console visualizza messaggi simili al seguente che indicano che l'app è in esecuzione e in attesa di richieste:

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

In un Web browser accedere a http://localhost:<port number>/api/math/sum?a=4&b=5. Dovrebbe essere visualizzato il risultato 9.

Passare all'API del prodotto (http://localhost:<port number>/api/math/product?a=4&b=5). Restituisce 9 e non 20 come previsto. Questo problema verrà corretto più avanti nell'esercitazione.

Eseguire i comandi dell'interfaccia della riga di comando di .NET usando dotnet watch

Qualsiasi comando dell'interfaccia della riga di comando di .NET può essere eseguito con dotnet watch. Ad esempio:

Eseguire dotnet watch run nella cartella WebApp. L'output della console indica che watch è stato avviato.

Apportare modifiche con dotnet watch

Assicurarsi che dotnet watch sia in esecuzione.

Correggere il bug nel Product metodo di MathController.cs in modo che restituisca il prodotto e non la somma:

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

Salvare il file. L'output della console indica che dotnet watch ha rilevato una modifica del file e ha riavviato l'app.

Verificare che http://localhost:<port number>/api/math/product?a=4&b=5 restituisca il risultato corretto.

Eseguire test con dotnet watch

1. Modificare il Product metodo di MathController.cs tornare a restituire la somma. Salvare il file.

2. In una shell dei comandi passare alla cartella WebAppTests.

3. Eseguire dotnet restore.

4. Eseguire dotnet watch test. L'output indica che un test non è stato superato e che il watcher è in attesa di modifiche ai file:

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

5. Correggere il codice del metodo Product in modo che restituisca il prodotto. Salvare il file.

dotnet watch rileva la modifica ai file ed esegue di nuovo i test. L'output della console indica che i test sono stati superati.

Personalizzare l'elenco dei file da controllare

Per impostazione predefinita, dotnet-watch tiene traccia di tutti i file che soddisfano i criteri GLOB seguenti:

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

È possibile aggiungere altri elementi all'elenco espressioni di controllo modificando il .csproj file. Gli elementi possono essere specificati singolarmente o tramite criteri GLOB.

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

Esclusione di file dal controllo

È possibile configurare dotnet-watch in modo che ignori le impostazioni predefinite. Per ignorare file specifici, aggiungere l'attributo Watch="false" alla definizione di un elemento nel .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>

Progetti di controllo personalizzati

dotnet-watch non è limitato a progetti C#. È possibile creare progetti di controllo personalizzati per gestire scenari diversi. Si consideri il layout di progetto seguente:

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

Se l'obiettivo consiste nel controllare entrambi i progetti, creare un file di progetto personalizzato configurato per controllarli entrambi:

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

Per avviare il controllo dei file per entrambi i progetti, passare alla cartella test. Eseguire il comando seguente:

dotnet watch msbuild /t:Test

VSTest viene eseguito quando un qualsiasi file viene modificato in uno dei progetti di test.

Configurazione dotnet-watch

Alcune opzioni di configurazione possono essere passate tramite variabili di dotnet watch ambiente. Le variabili disponibili sono:

Aggiornamento del browser

dotnet watch inserisce uno script nell'app che consente di aggiornare il browser quando cambia il contenuto. In alcuni scenari, ad esempio quando l'app abilita la compressione delle risposte, dotnet watch potrebbe non essere in grado di inserire lo script. Per questi casi in fase di sviluppo, inserire manualmente lo script nell'app. Ad esempio, per configurare l'app Web per inserire manualmente lo script, aggiornare il file di layout in modo da includere _framework/aspnet-browser-refresh.js:

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

Caratteri non ASCII

Visual Studio 17.2 e versioni successive include .NET SDK 6.0.300 e versioni successive. Con .NET SDK e 6.0.300 versioni successive, dotnet-watch genera caratteri non ASCII nella console durante una sessione di ricaricamento rapido. In alcuni host della console, ad esempio il conhost di Windows, questi caratteri potrebbero apparire incomprensibili. Per evitare caratteri incomprensibili, considerare uno degli approcci seguenti:

• Configurare la variabile di ambiente per eliminare l'emissione DOTNET_WATCH_SUPPRESS_EMOJIS=1 di questi valori.
• Passare a un terminale diverso, ad esempio https://github.com/microsoft/terminal, che supporta il rendering di caratteri non ASCII.