Choisir entre des API basées sur un contrôleur et des API minimales
Remarque
Ceci n’est pas la dernière version de cet article. Pour la version actuelle, consultez la version .NET 9 de cet article.
Avertissement
Cette version d’ASP.NET Core n’est plus prise en charge. Pour plus d’informations, consultez la stratégie de support .NET et .NET Core. Pour la version actuelle, consultez la version .NET 9 de cet article.
Important
Ces informations portent sur la préversion du produit, qui est susceptible d’être en grande partie modifié avant sa commercialisation. Microsoft n’offre aucune garantie, expresse ou implicite, concernant les informations fournies ici.
Pour la version actuelle, consultez la version .NET 9 de cet article.
ASP.NET Core prend en charge deux approches pour créer des API : une approche basée sur un contrôleur et des API minimales. Dans un projet API, les contrôleurs sont des classes qui dérivent de ControllerBase. Les API minimales définissent des points de terminaison avec des gestionnaires logiques dans des expressions lambda ou des méthodes. Cet article met en évidence les différences entre les deux approches.
La conception d’API minimales masque la classe hôte par défaut et se concentre sur la configuration et l’extensibilité via des méthodes d’extension qui prennent des fonctions en tant qu’expressions lambda. Les contrôleurs sont des classes qui peuvent prendre des dépendances via l’injection de constructeur ou l’injection de propriétés, et qui suivent généralement des modèles orientés objet. Les API minimales prennent en charge l’injection de dépendances par le biais d’autres approches telles que l’accès au fournisseur de services.
Voici un exemple de code pour une API basée sur des contrôleurs :
namespace APIWithControllers;
public class Program
{
public static void Main(string[] args)
{
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddControllers();
var app = builder.Build();
app.UseHttpsRedirection();
app.MapControllers();
app.Run();
}
}
using Microsoft.AspNetCore.Mvc;
namespace APIWithControllers.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 = DateOnly.FromDateTime(DateTime.Now.AddDays(index)),
TemperatureC = Random.Shared.Next(-20, 55),
Summary = Summaries[Random.Shared.Next(Summaries.Length)]
})
.ToArray();
}
}
Le code suivant fournit les mêmes fonctionnalités dans un projet d’API minimal. Notez que l’approche d’API minimale implique d’inclure le code associé dans des expressions lambda.
namespace MinimalAPI;
public class Program
{
public static void Main(string[] args)
{
var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();
app.UseHttpsRedirection();
var summaries = new[]
{
"Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching"
};
app.MapGet("/weatherforecast", (HttpContext httpContext) =>
{
var forecast = Enumerable.Range(1, 5).Select(index =>
new WeatherForecast
{
Date = DateOnly.FromDateTime(DateTime.Now.AddDays(index)),
TemperatureC = Random.Shared.Next(-20, 55),
Summary = summaries[Random.Shared.Next(summaries.Length)]
})
.ToArray();
return forecast;
});
app.Run();
}
}
Les deux projets d’API font référence à la classe suivante :
namespace APIWithControllers;
public class WeatherForecast
{
public DateOnly Date { get; set; }
public int TemperatureC { get; set; }
public int TemperatureF => 32 + (int)(TemperatureC / 0.5556);
public string? Summary { get; set; }
}
Les API minimales ont la plupart des mêmes fonctionnalités que les API basées sur un contrôleur. Elles prennent en charge la configuration et la personnalisation nécessaires pour effectuer une mise à l’échelle vers plusieurs API, gérer des itinéraires complexes, appliquer des règles d’autorisation et contrôler le contenu des réponses d’API. Il existe quelques fonctionnalités disponibles avec les API basées sur un contrôleur qui ne sont pas encore prises en charge ou implémentées par les API minimales. Il s’agit notamment des paramètres suivants :
- Aucune prise en charge intégrée de la liaison de modèle (IModelBinderProvider, IModelBinder). Il est possible d’ajouter la prise en charge avec un shim de liaison personnalisé.
- Aucune prise en charge intégrée pour la validation (IModelValidator).
- Aucune prise en charge des composants d’application ou du modèle d’application. Il n’existe aucun moyen d’appliquer ou de créer vos propres conventions.
- Aucune prise en charge de rendu d’affichage intégrée. Nous vous recommandons d’utiliser Razor Pages pour le rendu des affichages.
- Aucune prise en charge de JsonPatch
- Aucune prise en charge d’OData
Voir aussi
ASP.NET Core prend en charge deux approches pour créer des API : une approche basée sur un contrôleur et des API minimales. Dans un projet API, les contrôleurs sont des classes qui dérivent de ControllerBase. Les API minimales définissent des points de terminaison avec des gestionnaires logiques dans des expressions lambda ou des méthodes. Cet article met en évidence les différences entre les deux approches.
La conception d’API minimales masque la classe hôte par défaut et se concentre sur la configuration et l’extensibilité via des méthodes d’extension qui prennent des fonctions en tant qu’expressions lambda. Les contrôleurs sont des classes qui peuvent prendre des dépendances via l’injection de constructeur ou l’injection de propriétés, et qui suivent généralement des modèles orientés objet. Les API minimales prennent en charge l’injection de dépendances par le biais d’autres approches telles que l’accès au fournisseur de services.
Voici un exemple de code pour une API basée sur des contrôleurs :
namespace APIWithControllers;
public class Program
{
public static void Main(string[] args)
{
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddControllers();
var app = builder.Build();
app.UseHttpsRedirection();
app.MapControllers();
app.Run();
}
}
using Microsoft.AspNetCore.Mvc;
namespace APIWithControllers.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 = DateOnly.FromDateTime(DateTime.Now.AddDays(index)),
TemperatureC = Random.Shared.Next(-20, 55),
Summary = Summaries[Random.Shared.Next(Summaries.Length)]
})
.ToArray();
}
}
Le code suivant fournit les mêmes fonctionnalités dans un projet d’API minimal. Notez que l’approche d’API minimale implique d’inclure le code associé dans des expressions lambda.
namespace MinimalAPI;
public class Program
{
public static void Main(string[] args)
{
var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();
app.UseHttpsRedirection();
var summaries = new[]
{
"Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching"
};
app.MapGet("/weatherforecast", (HttpContext httpContext) =>
{
var forecast = Enumerable.Range(1, 5).Select(index =>
new WeatherForecast
{
Date = DateOnly.FromDateTime(DateTime.Now.AddDays(index)),
TemperatureC = Random.Shared.Next(-20, 55),
Summary = summaries[Random.Shared.Next(summaries.Length)]
})
.ToArray();
return forecast;
});
app.Run();
}
}
Les deux projets d’API font référence à la classe suivante :
namespace APIWithControllers;
public class WeatherForecast
{
public DateOnly Date { get; set; }
public int TemperatureC { get; set; }
public int TemperatureF => 32 + (int)(TemperatureC / 0.5556);
public string? Summary { get; set; }
}
Les API minimales ont la plupart des mêmes fonctionnalités que les API basées sur un contrôleur. Elles prennent en charge la configuration et la personnalisation nécessaires pour effectuer une mise à l’échelle vers plusieurs API, gérer des itinéraires complexes, appliquer des règles d’autorisation et contrôler le contenu des réponses d’API. Il existe quelques fonctionnalités disponibles avec les API basées sur un contrôleur qui ne sont pas encore prises en charge ou implémentées par les API minimales. Il s’agit notamment des paramètres suivants :
- Aucune prise en charge intégrée de la liaison de modèle (IModelBinderProvider, IModelBinder). Il est possible d’ajouter la prise en charge avec un shim de liaison personnalisé.
- Aucune prise en charge de la liaison à partir de formulaires. Cela inclut la liaison IFormFile.
- Aucune prise en charge intégrée pour la validation (IModelValidator).
- Aucune prise en charge des composants d’application ou du modèle d’application. Il n’existe aucun moyen d’appliquer ou de créer vos propres conventions.
- Aucune prise en charge de rendu d’affichage intégrée. Nous vous recommandons d’utiliser Razor Pages pour le rendu des affichages.
- Aucune prise en charge de JsonPatch
- Aucune prise en charge d’OData
