Exercice : Créer un projet d’API web

8 minutes

Ce module utilise le kit de développement logiciel (SDK) .NET 8.0. Assurez-vous que .NET 8.0 est installé en exécutant la commande suivante dans votre terminal de commandes préféré :

dotnet --list-sdks

Une sortie semblable à l’exemple suivant s’affiche :

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

Vérifiez que la liste comporte une version commençant par 8. S’il n’y en a pas ou que la commande est introuvable, installez la dernière version du kit de développement logiciel (SDK) .NET 8.0.

Création et exploration d’un projet d’API web

Pour configurer un projet .NET afin qu’il fonctionne avec l’API web, nous utilisons Visual Studio Code. Visual Studio Code comprend un terminal intégré qui facilite la création d’un projet. Si vous ne voulez pas utiliser un éditeur de code, vous pouvez exécuter les commandes de ce module dans un terminal.

Dans Visual Studio Code, sélectionnez Fichier>Ouvrir un dossier.
Créez un dossier nommé ContosoPizza à l’emplacement de votre choix, puis choisissez Sélectionner un dossier.
Ouvrez le terminal intégré à partir de Visual Studio Code en sélectionnant Affichage>Terminal dans le menu principal.
Dans la fenêtre de terminal, copiez et collez la commande suivante :
```
dotnet new webapi -controllers -f net8.0
```
Cette commande crée les fichiers d’un projet d’API web de base qui utilise des contrôleurs ainsi qu’un fichier projet C# nommé ContosoPizza.csproj, qui retourne une liste de prévisions météo. Si vous rencontrez une erreur, assurez-vous que le Kit de développement logiciel (SDK) .NET 8 est installé.

Important

Par défaut, les projets d’API web sont sécurisés par https. Si vous rencontrez des problèmes, configurez le certificat de développement HTTPS ASP.NET Core.

Vous pouvez recevoir une invite de Visual Studio Code pour ajouter des ressources afin de déboguer le projet. Sélectionnez Oui dans la boîte de dialogue.

La commande utilise un modèle de projet ASP.NET Core dont l’alias est webapi pour effectuer la génération de modèles automatique d’un projet d’API web C#. Un répertoire ContosoPizza est créé. Ce répertoire contient un projet ASP.NET Core s’exécutant sur .NET. Le nom du projet correspond au nom du répertoire ContosoPizza.

Vous devriez maintenant avoir accès à ces fichiers et répertoires :
```
-| Controllers
-| obj
-| Properties
-| appsettings.Development.json
-| appsettings.json
-| ContosoPizza.csproj
-| ConosoPizza.http
-| Program.cs
-| WeatherForecast.cs
```

Examinez les fichiers et répertoires suivants :

Nom	Description
Controllers/	Contient des classes avec des méthodes publiques exposées en tant que points de terminaison HTTP.
Program.cs	Configure les services et le pipeline de requêtes HTTP de l’application, et contient le point d’entrée managé de l’application.
ContosoPizza.csproj	Contient des métadonnées de configuration pour le projet.
ConosoPizza.http	Contient la configuration pour tester les API REST directement à partir de Visual Studio Code.

Génération et tests de l’API web

Exécutez la commande suivante de l’interface CLI .NET Core dans l’interpréteur de commandes :
```
dotnet run
```
La commande précédente :
- Localise le fichier de projet dans le répertoire courant.
- Récupère et installe toutes les dépendances de projet requises pour ce projet.
- Compile le code du projet.
- Héberge l’API web avec le serveur web Kestrel d’ASP.NET Core sur des points de terminaison HTTP et HTTPS.
Un port compris entre 5000 et 5300 est sélectionné pour HTTP, et entre 7000 et 7300 pour HTTPS, au moment de la création du projet. Vous pouvez facilement modifier les ports que vous utilisez pendant le développement en modifiant le fichier launchSettings.json du projet. Ce module utilise l’URL sécurisée localhost qui commence par https.

Vous devez obtenir une sortie similaire à ce qui suit, ce qui indique que votre application est en cours d’exécution :
```
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        
```
Si vous exécutez cette application sur votre propre ordinateur, vous pouvez diriger un navigateur vers le lien HTTPS affiché dans la sortie (dans le cas précédent, https://localhost:7294) afin de voir la page qui s’affiche. Mémorisez ce port, car vous en aurez besoin tout au long du module où {PORT} est utilisé.

Important

Vérifiez la sortie du terminal si vous rencontrez un comportement inattendu. Si la génération échoue ou si d’autres erreurs se produisent, les informations du fichier journal aident à résoudre les problèmes. Lorsque vous apportez des modifications au code, vous devrez arrêter l’API web en appuyant CTRL+C sur le clavier et en relançant la commande dotnet run.

Ouvrez un navigateur web et accédez à :

https://localhost:{PORT}/weatherforecast

Vous devez voir une sortie JSON similaire à cet exemple :

[
    {
    "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"
    },
    // ...
]

Explorer avec les fichiers .http

Inclus dans le projet, le fichier ContosoPizza.http permet de tester les points de terminaison d’API via un format standard. Les fichiers .http sont pris en charge dans plusieurs environnements IDE, notamment Visual Studio et dans Visual Studio Code avec l’extension client REST installée.

Ouvrez le fichier ContosoPizza.http.

Ce fichier a été préconfiguré avec les variables @ContosoPizza_HostAddress et une commande GET appelant /weatherforecast/ qui accepte application/json.

Sélectionnez la commande Send Request (Envoyer la demande) au-dessus de l’instruction GET pour envoyer une demande au service en cours d’exécution.

L’appel de cette commande ouvre une fenêtre de réponse avec une sortie similaire à ce que nous avons vu dans le navigateur :

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"
    },
    // ..
]

Facultatif : Explorer les API avec la ligne de commande HTTP REPL

Ouvrez un nouveau terminal intégré à partir de Visual Studio Code en sélectionnant Terminal>Nouveau terminal dans le menu principal, puis exécutez la commande suivante :
```
dotnet tool install -g Microsoft.dotnet-httprepl
```
La commande précédente installe l’outil en ligne de commande HTTP REPL .NET, qui vous permet d’envoyer des requêtes HTTP à l’API web.
Connectez-vous à l’API web en exécutant la commande suivante :
```
httprepl https://localhost:{PORT}
```
Vous pouvez aussi exécuter la commande suivante à tout moment pendant l’exécution de HttpRepl :
```
connect https://localhost:{PORT}
```
Conseil

Si l’outil HttpRepl avertit Impossible de trouver une description OpenAPI, la cause la plus probable est un certificat de développement non approuvé. HttpRepl nécessite une connexion approuvée. Avant de continuer, vous devezconfigurer votre système pour approuver le certificat de développement avec dotnet dev-certs https --trust
Explorez les points de terminaison disponibles en exécutant la commande suivante :
```
ls
```
La commande précédente détecte et liste toutes les API disponibles sur le point de terminaison connecté, comme dans la sortie suivante :
```
https://localhost:{PORT}/> ls
.                 []
WeatherForecast   [GET] 
```
Accédez au point de terminaison WeatherForecast en exécutant la commande suivante :
```
cd WeatherForecast
```
La commande précédente affiche une sortie des API disponibles pour le point de terminaison WeatherForecast :
```
https://localhost:{PORT}/> cd WeatherForecast
/WeatherForecast    [GET]
```

Effectuez une requête GET dans HttpRepl en utilisant la commande suivante :

get

La commande précédente effectue une requête GET similaire au point de terminaison dans le navigateur :

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"
    },
    // ..
]

Quittez la session HttpRepl en cours en utilisant la commande suivante :
```
exit
```
Revenez au terminal dotnet dans la liste déroulante de Visual Studio Code. Arrêtez l’API web en sélectionnant CTRL + C sur votre clavier.

Une fois l’API web créée, nous pouvons la modifier pour répondre aux besoins de l’API web de pizza.

Continuer

Création et exploration d’un projet d’API web

Génération et tests de l’API web

Explorer avec les fichiers .http

Facultatif : Explorer les API avec la ligne de commande HTTP REPL

Commentaires