Gérer les requêtes avec des contrôleurs dans ASP.NET Core MVCHandle requests with controllers in ASP.NET Core MVC

Par Steve Smith et Scott AddieBy Steve Smith and Scott Addie

Les contrôleurs, les actions et les résultats des actions sont une part fondamentale dans la façon dont les développeurs créent des applications avec ASP.NET Core MVC.Controllers, actions, and action results are a fundamental part of how developers build apps using ASP.NET Core MVC.

Qu’est-ce qu’un contrôleur ?What is a Controller?

Un contrôleur est utilisé pour définir et regrouper un ensemble d’actions.A controller is used to define and group a set of actions. Une action (ou méthode d’action) est une méthode sur un contrôleur qui gère les demandes.An action (or action method) is a method on a controller which handles requests. Les contrôleurs regroupent de façon logique des actions similaires.Controllers logically group similar actions together. Cette agrégation des actions permet l’application collective de jeux de règles communs, comme le routage, la mise en cache et les autorisations.This aggregation of actions allows common sets of rules, such as routing, caching, and authorization, to be applied collectively. Les demandes sont mappées à des actions via un routage.Requests are mapped to actions through routing.

Par convention, les classes de contrôleur :By convention, controller classes:

  • Se trouvent dans le dossier Controllers au niveau de la racine du projetReside in the project's root-level Controllers folder
  • Héritent de Microsoft.AspNetCore.Mvc.ControllerInherit from Microsoft.AspNetCore.Mvc.Controller

Un contrôleur est une classe instanciable dans laquelle au moins une des conditions suivantes est vraie :A controller is an instantiable class in which at least one of the following conditions is true:

  • Le nom de classe a comme suffixe « Controller »The class name is suffixed with "Controller"
  • La classe hérite d’une classe dont le nom est suivi du suffixe « Controller »The class inherits from a class whose name is suffixed with "Controller"
  • La classe est décorée avec l’attribut [Controller]The class is decorated with the [Controller] attribute

Une classe de contrôleur ne doit pas avoir d’attribut [NonController] associé.A controller class must not have an associated [NonController] attribute.

Les contrôleurs doivent suivre le principe de dépendances explicites.Controllers should follow the Explicit Dependencies Principle. Il existe deux approches pour implémenter ce principe.There are a couple of approaches to implementing this principle. Si plusieurs actions de contrôleur nécessitent le même service, envisagez d’utiliser l’injection de constructeur pour demander ces dépendances.If multiple controller actions require the same service, consider using constructor injection to request those dependencies. Si le service est nécessaire pour une seule méthode d’action, envisagez d’utiliser l’injection d’action pour demander la dépendance.If the service is needed by only a single action method, consider using Action Injection to request the dependency.

Dans le Modèle-Vue-Contrôleur, un contrôleur est responsable du traitement initial de la demande et de l’instanciation du modèle.Within the Model-View-Controller pattern, a controller is responsible for the initial processing of the request and instantiation of the model. En règle générale, les décisions métier doivent être prises dans le modèle.Generally, business decisions should be performed within the model.

Le contrôleur prend le résultat du traitement du modèle (le cas échéant) et retourne la vue appropriée et les données associées à cette vue, ou bien le résultat de l’appel d’API.The controller takes the result of the model's processing (if any) and returns either the proper view and its associated view data or the result of the API call. Pour en savoir plus, consultez Vue d’ensemble d’ASP.NET Core MVC et Bien démarrer avec ASP.NET Core MVC et Visual Studio.Learn more at Overview of ASP.NET Core MVC and Get started with ASP.NET Core MVC and Visual Studio.

Le contrôleur est une abstraction au niveau de l’interface utilisateur.The controller is a UI-level abstraction. Ses responsabilités sont de garantir que les données de la demande sont valides et de choisir la vue (ou le résultat d’API) à retourner.Its responsibilities are to ensure request data is valid and to choose which view (or result for an API) should be returned. Dans les applications bien construites, il n’inclut pas directement l’accès aux données ni la logique métier.In well-factored apps, it doesn't directly include data access or business logic. Au lieu de cela, le contrôleur délègue à des services la gestion de ces responsabilités.Instead, the controller delegates to services handling these responsibilities.

Définition d’actionsDefining Actions

Les méthodes publiques sur un contrôleur, sauf celles qui sont décorées avec l’attribut [NonAction], sont des actions.Public methods on a controller, except those decorated with the [NonAction] attribute, are actions. Les paramètres sur les actions sont liés aux données des demandes et sont validés avec la liaison de modèle.Parameters on actions are bound to request data and are validated using model binding. La validation du modèle est effectuée pour tout ce qui est lié au modèle.Model validation occurs for everything that's model-bound. La valeur de la propriété ModelState.IsValid indique si la liaison de modèle et la validation ont réussi.The ModelState.IsValid property value indicates whether model binding and validation succeeded.

Les méthodes d’action doivent contenir la logique nécessaire pour mapper une demande à un problème métier.Action methods should contain logic for mapping a request to a business concern. Les problèmes métier doivent généralement être représentés comme des services auxquels le contrôleur accède via l’injection de dépendances.Business concerns should typically be represented as services that the controller accesses through dependency injection. Les actions mappent ensuite le résultat de l’action métier à un état de l’application.Actions then map the result of the business action to an application state.

Les actions peuvent retourner des valeurs de n’importe quel type, mais elles retournent souvent une instance de IActionResult (ou de Task<IActionResult> pour les méthodes asynchrones) qui produit une réponse.Actions can return anything, but frequently return an instance of IActionResult (or Task<IActionResult> for async methods) that produces a response. La méthode d’action est responsable du choix du type de réponse.The action method is responsible for choosing what kind of response. Le résultat de l’action constitue la réponse.The action result does the responding.

Méthodes helper des contrôleursController Helper Methods

Les contrôleurs héritent généralement de la classe Controller, bien que ce ne soit pas obligatoire.Controllers usually inherit from Controller, although this isn't required. Le fait de dériver de Controller fournit l’accès à trois catégories de méthodes helper :Deriving from Controller provides access to three categories of helper methods:

1. Méthodes aboutissant à un corps de réponse vide1. Methods resulting in an empty response body

Aucune en-tête de réponse HTTP Content-Type n’est présente, étant donné que le corps de la réponse n’a pas de contenu à décrire.No Content-Type HTTP response header is included, since the response body lacks content to describe.

Il existe deux types de résultats dans cette catégorie : Redirection et Code d’état HTTP.There are two result types within this category: Redirect and HTTP Status Code.

  • Code d’état HTTPHTTP Status Code

    Ce type retourne un code d’état HTTP.This type returns an HTTP status code. BadRequest, NotFound et Ok sont des méthodes helper de ce type.A couple of helper methods of this type are BadRequest, NotFound, and Ok. Par exemple, return BadRequest(); produit un code d’état 400 quand elle est exécutée.For example, return BadRequest(); produces a 400 status code when executed. Quand des méthodes comme BadRequest, NotFound et Ok sont surchargées, elles ne sont plus qualifiées comme répondeurs de code d’état HTTP, étant donné que la négociation du contenu est en cours.When methods such as BadRequest, NotFound, and Ok are overloaded, they no longer qualify as HTTP Status Code responders, since content negotiation is taking place.

  • RedirectionRedirect

    Ce type retourne une redirection vers une action ou une destination (avec Redirect, LocalRedirect, RedirectToAction ou RedirectToRoute).This type returns a redirect to an action or destination (using Redirect, LocalRedirect, RedirectToAction, or RedirectToRoute). Par exemple, return RedirectToAction("Complete", new {id = 123}); redirige vers Complete, en passant un objet anonyme.For example, return RedirectToAction("Complete", new {id = 123}); redirects to Complete, passing an anonymous object.

    Le type de résultat Redirection diffère du type Code d’état HTTP principalement par l’ajout d’un en-tête de réponse HTTP Location.The Redirect result type differs from the HTTP Status Code type primarily in the addition of a Location HTTP response header.

2. Méthodes aboutissant à un corps de réponse de non vide avec un type de contenu prédéfini2. Methods resulting in a non-empty response body with a predefined content type

La plupart des méthodes helper de cette catégorie incluent une propriété ContentType, qui vous permet de définir l’en-tête de réponse Content-Type pour décrire le corps de la réponse.Most helper methods in this category include a ContentType property, allowing you to set the Content-Type response header to describe the response body.

Il existe deux types de résultats dans cette catégorie : Vue et Réponse mise en forme.There are two result types within this category: View and Formatted Response.

  • AffichageView

    Ce type retourne une vue qui utilise un modèle pour rendre le HTML.This type returns a view which uses a model to render HTML. Par exemple, return View(customer); passe un modèle à la vue pour la liaison de données.For example, return View(customer); passes a model to the view for data-binding.

  • Réponse mise en formeFormatted Response

    Ce type retourne un format JSON ou un format d’échange de données similaire pour représenter un objet d’une manière spécifique.This type returns JSON or a similar data exchange format to represent an object in a specific manner. Par exemple, return Json(customer); sérialise l’objet fourni au format JSON.For example, return Json(customer); serializes the provided object into JSON format.

    File et PhysicalFile sont des méthodes courantes de ce type.Other common methods of this type include File and PhysicalFile. Par exemple, return PhysicalFile(customerFilePath, "text/xml"); retourne PhysicalFileResult.For example, return PhysicalFile(customerFilePath, "text/xml"); returns PhysicalFileResult.

3. Méthodes aboutissant à un corps de réponse non vide mise en forme selon un type de contenu négocié avec le client3. Methods resulting in a non-empty response body formatted in a content type negotiated with the client

Cette catégorie est plus connue sous le nom de Négociation de contenu.This category is better known as Content Negotiation. La Négociation de contenu s’applique chaque fois qu’une action retourne un type ObjectResult ou quelque chose d’autre qu’une implémentation de IActionResult.Content negotiation applies whenever an action returns an ObjectResult type or something other than an IActionResult implementation. Une action qui retourne une implémentation autre que IActionResult (par exemple object) retourne également une Réponse mise en forme.An action that returns a non-IActionResult implementation (for example, object) also returns a Formatted Response.

BadRequest, CreatedAtRoute et Ok sont des méthodes helper de ce type.Some helper methods of this type include BadRequest, CreatedAtRoute, and Ok. return BadRequest(modelState);, return CreatedAtRoute("routename", values, newobject); et return Ok(value); sont des exemples respectifs de ces méthodes.Examples of these methods include return BadRequest(modelState);, return CreatedAtRoute("routename", values, newobject);, and return Ok(value);, respectively. Notez que BadRequest et Ok effectuent une négociation de contenu seulement quand ils reçoivent une valeur ; si aucune valeur ne leur est passée, ils délivrent à la place des types de résultats Code d’état HTTP.Note that BadRequest and Ok perform content negotiation only when passed a value; without being passed a value, they instead serve as HTTP Status Code result types. La méthode CreatedAtRoute effectue quant à elle toujours une négociation de contenu, car ses surcharges nécessitent toutes qu’une valeur soit passée.The CreatedAtRoute method, on the other hand, always performs content negotiation since its overloads all require that a value be passed.

Problèmes transversauxCross-Cutting Concerns

En règle générale, les applications partagent des parties de leur flux de travail.Applications typically share parts of their workflow. C’est par exemple le cas d’une application qui exige une authentification pour l’accès au panier d’achat ou qui met en cache les données de certaines pages.Examples include an app that requires authentication to access the shopping cart, or an app that caches data on some pages. Pour exécuter la logique avant ou après une méthode d’action, utilisez un filtre.To perform logic before or after an action method, use a filter. L’utilisation de Filtres sur les problèmes transversaux peut réduire la duplication.Using Filters on cross-cutting concerns can reduce duplication.

La plupart des attributs des filtres, comme [Authorize], peuvent être appliqués au niveau du contrôleur ou de l’action, selon le niveau de granularité souhaité.Most filter attributes, such as [Authorize], can be applied at the controller or action level depending upon the desired level of granularity.

La gestion des erreurs et la mise en cache des réponses sont souvent des problèmes transversaux :Error handling and response caching are often cross-cutting concerns:

De nombreux problèmes transversaux peuvent être gérés en utilisant des filtres ou un intergiciel (middleware) personnalisé.Many cross-cutting concerns can be handled using filters or custom middleware.