Contrôleurs d’API web ASP.NET Core
Dans l’exercice précédent, vous avez créé une application web qui fournit des exemples de données de prévision météo, puis vous avez interagi avec celle-ci dans la boucle REPL HTTP.
Avant de vous plonger dans l’écriture de notre propre classe PizzaController, jetons un coup d’œil au code de l’exemple WeatherController pour comprendre comment il fonctionne. Dans cette leçon, vous allez découvrir comment WeatherController utilise la classe de base ControllerBase, ainsi que des attributs .NET pour créer une API web fonctionnelle en quelques dizaines de lignes de code. Une fois ces concepts compris, vous êtes prêt à écrire votre propre classe PizzaController.
Voici le code pour la classe WeatherController complète. Ne vous inquiétez pas si vous ne comprenez pas encore tout. Parcourons les étapes pas à pas.
using Microsoft.AspNetCore.Mvc;
namespace ContosoPizza.Controllers;
[ApiController]
[Route("[controller]")]
public class WeatherForecastController : ControllerBase
{
private static readonly string[] Summaries = new[]
{
"Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching"
};
private readonly ILogger<WeatherForecastController> _logger;
public WeatherForecastController(ILogger<WeatherForecastController> logger)
{
_logger = logger;
}
[HttpGet(Name = "GetWeatherForecast")]
public IEnumerable<WeatherForecast> Get()
{
return Enumerable.Range(1, 5).Select(index => new WeatherForecast
{
Date = DateTime.Now.AddDays(index),
TemperatureC = Random.Shared.Next(-20, 55),
Summary = Summaries[Random.Shared.Next(Summaries.Length)]
})
.ToArray();
}
}
La classe de base : ControllerBase
Un contrôleur est une classe publique avec une ou plusieurs méthodes publiques appelées actions. Par convention, un contrôleur est placé dans le répertoire Controllers de la racine du projet. Les actions sont exposées en tant que points de terminaison HTTP par le biais du routage. Par conséquent, une requête HTTP GET pour https://localhost:{PORT}/weatherforecast provoque l’exécution de la méthode Get() de la classe WeatherForecastController.
La première chose à noter est que cette classe hérite de la classe de base ControllerBase. Cette classe de base fournit plusieurs fonctionnalités standard pour la gestion des requêtes HTTP. Vous pouvez ainsi vous concentrer sur la logique métier spécifique pour votre application.
Remarque
Si vous avez de l’expérience avec le développement d’architectures Razor Pages ou MVC (model-view-controller) dans ASP.NET Core, vous avez déjà utilisé la classe Controller. Ne créez pas de contrôleur d’API web en effectuant une dérivation de la classe Controller. Controller dérive de ControllerBase et ajoute la prise en charge des vues. Elle permet donc de gérer des pages web, et non des requêtes d’API web.
Attributs de la classe Controller de l’API
Deux attributs importants sont appliqués à WeatherForecastController, comme illustré dans le code suivant :
[ApiController]
[Route("[controller]")]
public class WeatherForecastController : ControllerBase
[ApiController] active des comportements stricts qui facilitent la création d’API web. On compte parmi les comportements les améliorations* de l’inférence des paramètres sources, de l’exigence du routage des attributs et de la gestion des erreurs de validation du modèle.
[Route] définit le modèle de routage [controller]. Le nom du contrôleur (ne respectant pas la casse, sans le suffixe de contrôleur) remplace le jeton [controller]. Ce contrôleur gère les requêtes à https://localhost:{PORT}/weatherforecast.
Notes
La route peut contenir des chaînes statiques, comme dans api/[controller]. Dans cet exemple, ce contrôleur gère une requête à https://localhost:{PORT}/api/weatherforecast.
Fournir des résultats météorologiques avec la méthode Get()
WeatherForecastController comprend une action de contrôleur unique, désignée par l’attribut [HttpGet(Name = "GetWeatherForecast")]. Cet attribut route les requêtes HTTP GET vers la méthode public IEnumerable<WeatherForecast> Get(). Comme cela a été expliqué dans l’exercice précédent, les requêtes vers https://localhost:{PORT}/weatherforecast ont retourné les résultats météo.
Comme vous allez le découvrir plus loin dans ce module, d’autres actions courantes sont associées à une API web qui effectue des opérations CRUD (GET, PUT, POST, DELETE). Toutefois, un contrôleur d’API n’a besoin d’implémenter qu’une seule action de contrôleur.
Dans le cas présent, vous obtenez la liste complète des éléments WeatherForecast retournés. L’opération GET permet également de récupérer un seul élément en passant un identificateur. Dans ASP.NET, vous pouvez récupérer un seul élément à l’aide de l’attribut [HttpGet("{id}")]. Vous allez implémenter cet attribut dans l’exercice suivant.
Vous connaissez à présent les composants fondamentaux d’un contrôleur d’API web, vous êtes désormais prêt à créer votre propre classe PizzaController.