Esercizio - Creare un progetto di API Web

8 minuti

Questo modulo usa .NET 8.0 SDK. Assicurarsi di avere installato .NET 8.0 eseguendo il comando seguente nel terminale dei comandi preferito:

dotnet --list-sdks

Verrà visualizzato un output simile all'esempio seguente:

6.0.317 [C:\Program Files\dotnet\sdk]
7.0.401 [C:\Program Files\dotnet\sdk]
8.0.100 [C:\Program Files\dotnet\sdk]

Assicurarsi che sia elencata una versione che inizia con 8. Se il comando non è presente nell'elenco o non viene trovato, installare la versione più recente di .NET 8.0 SDK.

Creare ed esplorare un progetto di API Web

Per configurare un progetto.NET in modo che funzioni con le API Web, viene usato Visual Studio Code. Visual Studio Code include un terminale integrato, che semplifica la creazione di un nuovo progetto. Se non si vuole usare un editor di codice, è possibile eseguire i comandi in questo modulo in un terminale.

In Visual Studio Code selezionare File>Apri cartella.
Creare una nuova cartella denominata ContosoPizza in un percorso a scelta e quindi scegliere Seleziona cartella.
Aprire il terminale integrato da Visual Studio Code selezionando Visualizza>Terminale nel menu principale.
Copiare e incollare il comando seguente nella finestra del terminale:
```
dotnet new webapi -controllers -f net8.0
```
Questo comando crea i file per un progetto API Web di base che usa controller, insieme a un file di progetto C# denominato ContosoPizza.csproj che restituisce un elenco di previsioni meteo. Se viene visualizzato un errore, assicurarsi di avere installato .NET 8 SDK.

Importante

I progetti di API Web vengono protetti con https per impostazione predefinita. Se si verificano problemi, configurare il certificato di sviluppo HTTPS di ASP.NET Core.

È possibile che in Visual Studio Code venga richiesto di aggiungere asset per eseguire il debug del progetto. Selezionare Sì nella finestra di dialogo.

Il comando usa un modello di progetto ASP.NET Core, con l'alias webapi, per eseguire lo scaffolding di un progetto di API Web basata su C#. Verrà creata una directory ContosoPizza. Questa directory contiene un progetto ASP.NET Core in esecuzione su .NET. Il nome del progetto corrisponde al nome di directory ContosoPizza.

A questo punto dovrebbe essere possibile accedere ai file e alle directory:
```
-| Controllers
-| obj
-| Properties
-| appsettings.Development.json
-| appsettings.json
-| ContosoPizza.csproj
-| ContosoPizza.http
-| Program.cs
-| WeatherForecast.cs
```

Esaminare i file e le directory seguenti:

Nome	Descrizione
Controllers/	Contiene le classi con i metodi pubblici esposti come endpoint HTTP.
Program.cs	Configura i servizi e la pipeline di richieste HTTP dell'app e contiene il punto di ingresso gestito dell'app.
ContosoPizza.csproj	Contiene i metadati di configurazione per il progetto.
ContosoPizza.http	Contiene la configurazione per testare le API REST direttamente da Visual Studio Code.

Compilare e testare l'API Web

Eseguire il comando seguente dell'interfaccia della riga di comando di .NET Core nella shell dei comandi:
```
dotnet run
```
Il comando precedente:
- Individua il file di progetto nella directory corrente.
- Recupera e installa tutte le dipendenze di progetto necessarie per questo progetto.
- Compila il codice del progetto.
- Ospita l'API con server Web Kestrel di ASP.NET Core su un endpoint HTTP e HTTPS.
Quando viene creato il progetto, viene selezionata una porta compresa tra 5000 e 5300 per HTTP e una porta compresa tra 7000 e 7300 per HTTPS. È possibile cambiare facilmente le porte usate durante lo sviluppo mediante la modifica del file launchSettings.json del progetto. Questo modulo usa l'URL sicuro localhost che inizia con https.

L'output dovrebbe essere simile al seguente, a indicare che l'app è in esecuzione:
```
Building...
info: Microsoft.Hosting.Lifetime[14]
      Now listening on: https://localhost:7294
info: Microsoft.Hosting.Lifetime[14]
      Now listening on: http://localhost:5118 
info: Microsoft.Hosting.Lifetime[0]
      Application started. Press Ctrl+C to shut down.
info: Microsoft.Hosting.Lifetime[0]
      Hosting environment: Development        
```
Se si esegue questa app nel proprio computer, è possibile indirizzare un browser al collegamento HTTPS visualizzato nell'output (nel caso precedente, https://localhost:7294) per visualizzare la pagina risultante. Occorre ricordare questa porta, perché viene usata nell'intero modulo quando si usa {PORT}.

Importante

Controllare l'output del terminale se si verifica un comportamento imprevisto. Se la compilazione non riesce o si verificano altri errori, le informazioni del file di log sono utili per risolvere i problemi. Quando si apportano modifiche al codice, sarà necessario arrestare l'API Web premendo i tasti CTRL+C ed eseguendo di nuovo il comando dotnet run.

Aprire un Web browser e passare a:

https://localhost:{PORT}/weatherforecast

L'output JSON visualizzato dovrebbe essere simile all'esempio seguente:

[
    {
    "date": "2021-11-09T20:36:01.4678814+00:00",
    "temperatureC": 33,
    "temperatureF": 91,
    "summary": "Scorching"
    },
    {
    "date": "2021-11-09T20:36:01.4682337+00:00",
    "temperatureC": -8,
    "temperatureF": 18,
    "summary": "Cool"
    },
    // ...
]

Facoltativo: Esplorare con i file `.http`

Nel progetto è incluso ContosoPizza.http, un file usato per testare gli endpoint API tramite un formato standard. I file .http sono supportati in diversi ambienti di sviluppo integrati (IDE), tra cui Visual Studio e all'interno di Visual Studio Code con l'estensione client REST installata.

Aprire il file ContosoPizza.http.

In alcuni IDE questo file è preconfigurato con le variabili @ContosoPizza_HostAddress e un comando GET che chiama /weatherforecast/ che accetta application/json.

Se è presente nel file, selezionare il comando Invia richiesta sopra il comando GET che invia una richiesta al servizio in esecuzione.

La chiamata a questo comando apre una finestra di risposta con output simile a quello visualizzato nel browser:

HTTP/1.1 200 OK
Connection: close
Content-Type: application/json; charset=utf-8
Date: Wed, 17 Jan 2024 16:46:40 GMT
Server: Kestrel
Transfer-Encoding: chunked

[
    {
        "date": "2024-01-18",
        "temperatureC": -2,
        "temperatureF": 29,
        "summary": "Warm"
    },
    {
        "date": "2024-01-19",
        "temperatureC": 24,
        "temperatureF": 75,
        "summary": "Chilly"
    },
    // ..
]

Facoltativo: Esplorare le API con la riga di comando HTTP REPL

Aprire un nuovo terminale integrato da Visual Studio Code selezionando Terminale>Nuovo terminale dal menu principale ed eseguire il comando seguente:
```
dotnet tool install -g Microsoft.dotnet-httprepl
```
Il comando precedente installa lo strumento da riga di comando .NET HTTP Read-Eval-Print Loop (REPL) che viene usato per effettuare richieste HTTP all'API Web.
Connettersi all'API Web eseguendo questo comando:
```
httprepl https://localhost:{PORT}
```
In alternativa, eseguire questo comando in qualsiasi momento durante l'esecuzione di HttpRepl:
```
connect https://localhost:{PORT}
```
Suggerimento

Se lo strumento HttpRepl visualizza l'avviso Unable to find an OpenAPI description (Non è possibile trovare una descrizione OpenAPI), la causa più probabile è un certificato di sviluppo non attendibile. HttpRepl richiede una connessione attendibile. Prima di poter continuare, è necessario configurare il sistema in modo che consideri attendibile il certificato di sviluppo con dotnet dev-certs https --trust
Esplorare gli endpoint disponibili eseguendo il comando seguente:
```
ls
```
Il comando precedente rileva tutte le API disponibili nell'endpoint connesso e le elenca, come nell'output seguente:
```
https://localhost:{PORT}/> ls
.                 []
WeatherForecast   [GET] 
```
Passare all'endpoint WeatherForecast eseguendo questo comando:
```
cd WeatherForecast
```
Il comando precedente mostra un output di API disponibili per l'endpoint WeatherForecast:
```
https://localhost:{PORT}/> cd WeatherForecast
/WeatherForecast    [GET]
```

Effettuare una richiesta GET in HttpRepl usando questo comando:

get

Il comando precedente effettua una richiesta GET simile al passaggio all'endpoint nel browser:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Date: Fri, 02 Apr 2021 17:31:43 GMT
Server: Kestrel
Transfer-Encoding: chunked
[
    {
    "date": 4/3/2021 10:31:44 AM,
    "temperatureC": 13,
    "temperatureF": 55,
    "summary": "Sweltering"
    },
    {
    "date": 4/4/2021 10:31:44 AM,
    "temperatureC": -13,
    "temperatureF": 9,
    "summary": "Warm"
    },
    // ..
]

Terminare la sessione HttpRepl corrente usando il comando seguente:
```
exit
```
Tornare al terminale dotnet nell'elenco a discesa in Visual Studio Code. Arrestare l'API Web premendo i tasti CTRL+C.

Dopo avere creato l'API Web, è necessario modificarla per soddisfare le esigenze dell'API Web per la consegna a domicilio di pizza.

Continua

Esercizio - Creare un progetto di API Web

Creare ed esplorare un progetto di API Web

Compilare e testare l'API Web

Facoltativo: Esplorare con i file .http

Facoltativo: Esplorare le API con la riga di comando HTTP REPL

Commenti e suggerimenti

Facoltativo: Esplorare con i file `.http`