Pour afficher l’article en anglais, activez la case d’option Anglais. Vous pouvez aussi afficher la version anglaise dans une fenêtre contextuelle en faisant glisser le pointeur de la souris sur le texte.
Traduction
Anglais

Filtrage dans ASP.NET MVC

Dans ASP.NET MVC, les contrôleurs définissent des méthodes d'action qui entretiennent généralement une relation un-à-un avec les interventions d'utilisateur possibles, telles qu'un clic sur un lien ou l'envoi d'un formulaire. Par exemple, lorsque l'utilisateur clique sur un lien, une demande est routée vers le contrôleur spécifié et la méthode d'action correspondante est appelée.

Vous souhaitez parfois exécuter la logique avant l'appel d'une méthode d'action ou après l'exécution de la méthode. Pour prendre en charge ce comportement, ASP.NET MVC fournit des filtres. Les filtres sont des classes personnalisées qui fournissent à la fois des mécanismes déclaratifs et de programmation pour ajouter un comportement pré et post-action aux méthodes d'action de contrôleur.

Un projet Visual Studio (avec code source) est disponible pour accompagner cette rubrique : Download.

ASP.NET MVC prend en charge les types de filtres d'action suivants :

  • Filtres d'autorisation. Ces filtres implémentent IAuthorizationFilter et prennent des décisions de sécurité quant à l'exécution d'une méthode d'action, telle que l'exécution de l'authentification ou la validation des propriétés de la demande. Les classes AuthorizeAttribute et RequireHttpsAttribute sont des exemples de filtre d'autorisation. Filtres d'autorisation exécutés avant tout autre filtre.

  • Filtres d'action. Ces filtres implémentent IActionFilter et encapsulent l'exécution d'une méthode d'action. L'interface IActionFilter déclare deux méthodes : OnActionExecuting et OnActionExecuted. OnActionExecuting s'exécute avant la méthode d'action. OnActionExecuted s'exécute après la méthode d'action et peut exécuter d'autres traitements consistant notamment à fournir des données supplémentaires à la méthode d'action, à inspecter la valeur de retour ou à annuler l'exécution de la méthode d'action.

  • Filtres de résultat. Ces filtres implémentent IResultFilter et encapsule l'exécution de l'objet ActionResult. IResultFilter déclare deux méthodes : OnResultExecuting et OnResultExecuted. OnResultExecuting s'exécute avant que l'objet ActionResult ne soit exécuté. OnResultExecuted s'exécute après les résultats et peut exécuter d'autres traitements du résultat, tels que la modification de la réponse HTTP. La classe OutputCacheAttribute est un exemple de filtre de résultat.

  • Filtres d'exception. Ces filtres implémentent IExceptionFilter et s'exécutent si une exception non gérée est levée lors de l'exécution du pipeline ASP.NET MVC. Les filtres d'exception peuvent être utilisés pour des tâches telles que la journalisation ou l'affichage d'une page d'erreurs. La classe HandleErrorAttribute est un exemple de filtre d'exception.

La classe Controller implémente chacune des interfaces de filtre. Vous pouvez implémenter chacun des filtres pour un contrôleur spécifique en substituant la méthode On<Filter> du contrôleur. Par exemple, vous pouvez substituer la méthode OnAuthorization. Le contrôleur simple inclus dans l'exemple téléchargeable substitue chacun des filtres et écrit les informations de diagnostic à chaque fois qu'un filtre est exécuté. Vous pouvez implémenter les méthodes On<Filter> suivantes dans un contrôleur :

ASP.NET MVC inclut les filtres suivants, qui sont implémentés comme attributs. Les filtres peuvent être appliqués à la méthode d'action, au contrôleur ou au niveau de l'application.

  • AuthorizeAttribute . Restreint l'accès à l'aide de l'authentification et éventuellement de l'autorisation.

  • HandleErrorAttribute . Spécifie comment gérer une exception levée par une méthode d'action.

    RemarqueRemarque :

    Ce filtre n'intercepte pas d'exceptions à moins que l'élément customErrors soit autorisé dans le fichier Web.config.

  • OutputCacheAttribute . Fournit la mise en cache de sortie.

  • RequireHttpsAttribute . Force les requêtes HTTP non protégées à être renvoyées sur HTTPS.

Vous pouvez créer un filtre de différentes manières :

  • Substituez une ou plusieurs des méthodes On<Filter> du contrôleur.

  • Créez une classe d'attribut que dérive de ActionFilterAttribute et applique l'attribut à un contrôleur ou à une méthode d'action.

  • Inscrivez un filtre auprès du fournisseur de filtres (classe FilterProviders).

  • Inscrivez un filtre global à l'aide de la classe GlobalFilterCollection.

Un filtre peut implémenter la classe ActionFilterAttribute abstraite. Certains filtres, tels que AuthorizeAttribute, implémente directement la classe FilterAttribute. Les filtres d'autorisation sont toujours appelés avant que la méthode d'action ne soit exécutée et avant tous les autres types de filtres. D'autres filtres d'action, tels que OutputCacheAttribute, implémentent la classe ActionFilterAttribute abstraite, qui permet d'exécuter le filtre d'action avant ou après la méthode d'action.

Vous pouvez utiliser l'attribut de filtre de façon déclarative avec les méthodes d'action ou les contrôleurs. Si l'attribut marque un contrôleur, le filtre d'action s'applique à toutes les méthodes d'action de ce contrôleur.

L'exemple suivant illustre l'implémentation par défaut de la classe HomeController. Dans cet exemple, l'attribut HandleError est utilisé pour marquer le contrôleur. Par conséquent, le filtre s'applique à toutes les méthodes d'action du contrôleur.


[HandleError]
public class HomeController : Controller
{
    public ActionResult Index()
    {
        ViewData["Message"] = "Welcome to ASP.NET MVC!";

        return View();
    }

    public ActionResult About()
    {
        return View();
    }
}


Plusieurs fournisseurs de filtres peuvent être inscrits. Les fournisseurs de filtres sont inscrits à l'aide de la propriété Providers statique. La méthode GetFilters(ControllerContext, ActionDescriptor) regroupe les filtres de tous les fournisseurs dans une liste unique. Les fournisseurs peuvent être inscrits dans n'importe quel ordre ; l'ordre dans lequel ils sont enregistrés n'a aucun impact sur l'ordre d'exécution du filtre.

RemarqueRemarque :

Les fournisseurs de filtres sont une nouvelle fonctionnalité d'ASP.NET MVC 3.

Par défaut, ASP.NET MVC inscrit les fournisseurs de filtres suivants :

La méthode GetFilters retourne toutes les instances IFilterProvider dans le localisateur de service.

Les filtres sont exécutés dans l'ordre suivant :

  1. Filtres d'autorisation

  2. Filtres d'action

  3. Filtres de réponse

  4. Filtres d'exception

Par exemple, les filtres d'autorisation sont exécutés en premier et les filtres d'exception sont exécutés en dernier. Dans chaque type de filtre, la valeur Order spécifie l'ordre d'exécution. Dans chaque type et ordre de filtre, la valeur d'énumération Scope spécifie l'ordre des filtres. Cette énumération définit les valeurs de portée de filtre suivantes (dans l'ordre dans lequel ils sont exécutés) :

  1. First

  2. Global

  3. Controller

  4. Action

  5. Last

Par exemple, un filtre d'action pour lequel dont la propriété Order est de zéro et dont la portée du filtre est de First s'exécute avant un filtre d'action dont la propriété Order est zéro et dont la portée du filtre est de Action.

L'ordre d'exécution des filtres du même type, ordre et portée n'est pas défini.

Les filtres OnActionExecuting(ActionExecutingContext), OnResultExecuting(ResultExecutingContext), et OnAuthorization(AuthorizationContext) sont exécutés dans l'ordre de transmission. Les filtres OnActionExecuted(ActionExecutedContext), OnResultExecuting(ResultExecutingContext), et OnException(ExceptionContext) sont exécutés dans l'ordre inverse.

RemarqueRemarque :

Dans ASP.NET MVC version 3, l'ordre d'exécution des filtres d'exception a changé pour les filtres d'exception qui ont la même valeur Order. Dans ASP.NET MVC 2 et versions antérieures, les filtres d'exception sur le contrôleur avec la même valeur Order que ceux sur la méthode d'action étaient exécutés avant les filtres d'exception sur la méthode d'action. Cela était généralement le cas si les filtres d'exception étaient appliqués sans spécifier de valeur Order. Dans ASP.NET MVC 3, cet ordre a été inversé afin que le gestionnaire d'exceptions le plus spécifique s'exécute en premier. Pour plus d'informations, consultez la section relative à l'ordre des filtres plus loin dans ce document.

Vous pouvez annuler l'exécution des filtres dans les méthodes OnActionExecuting et OnResultExecuting en affectant une valeur non null à la propriété Result. Aucun des filtres OnActionExecuted et OnActionExecuting en attente n'est appelé et le demandeur n'appelle pas la méthode OnActionExecuted pour le filtre annulé ou pour les filtres en attente. Le filtre OnActionExecuted pour les filtres déjà exécutés s'exécute. Tous les filtres OnResultExecuted et OnResultExecuting s'exécutent.

Par exemple, imaginez une application ASP.NET MVC avec un contrôleur Home et un contrôleur simple. Un filtre global de l'horloge des demandes est appliqué à l'application. Le filtre de l'horloge des demandes implémente les quatre filtres d'action et de résultat (OnActionExecuting, OnActionExecuted, OnResultExecuting et OnResultExecuted). Chaque méthode de filtre de l'application écrit les informations de traçage avec le nom du filtre, le nom du contrôleur, le nom de l'action et le type du filtre. Dans ce cas, le type de filtre est un filtre de l'horloge des demandes. Une demande à l'action Index du contrôleur Home affiche la sortie suivante dans l'écouteur de la trace (fenêtre de débogage).

Méthode filter

Contrôleur

Action

Type de filtre

OnActionExecuting

Début

Index

Filtre de l'horloge des demandes

OnActionExecuted

Début

Index

Filtre de l'horloge des demandes

OnResultExecuting

Début

Index

Filtre de l'horloge des demandes

OnResultExecuted

Début

Index

Filtre de l'horloge des demandes

Prenez la même application où un filtre d'action de trace est appliqué au contrôleur simple. Le contrôleur simple implémente également les quatre filtres d'action et de résultat. Le contrôleur simple a trois filtres, chacun implémentant les quatre méthodes d'action et de résultat. Une demande à l'action Details du contrôleur Simple affiche la sortie suivante dans l'écouteur de la trace :

Méthode filter

Contrôleur

Action

Type de filtre

OnActionExecuting

Simple

Détails

Contrôleur simple

OnActionExecuting

Simple

Détails

Action de trace

OnActionExecuting

Simple

Détails

Horloge de demande

OnActionExecuted

Simple

Détails

Horloge de demande

OnActionExecuted

Simple

Détails

Action de trace

OnActionExecuted

Simple

Détails

Contrôleur simple

OnResultExecuting

Simple

Détails

Contrôleur simple

OnResultExecuting

Simple

Détails

Action de trace

OnResultExecuting

Simple

Détails

Horloge de demande

OnResultExecuted

Simple

Détails

Horloge de demande

OnResultExecuted

Simple

Détails

Action de trace

OnResultExecuted

Simple

Détails

Contrôleur simple

À présent, prenez la même application où le filtre d'action de trace affecte la valeur « Home/Index » à la propriété de résultat, comme indiqué dans l'exemple suivant :

if (filterContext.RouteData.Values.ContainsValue("Cancel")) {
    filterContext.Result = new RedirectResult("~/Home/Index");
    Trace.WriteLine(" Redirecting from Simple filter to /Home/Index");
}

La demande à l'action Details du contrôleur Simple avec le résultat annulé affiche la sortie suivante dans l'écouteur de la trace :

Méthode filter

Contrôleur

Action

Type de filtre

OnActionExecuting

Simple

Détails

Contrôleur simple

OnActionExecuting

Simple

Détails

Action de trace

OnActionExecuted

Simple

Détails

Contrôleur simple

OnResultExecuting

Simple

Détails

Contrôleur simple

OnResultExecuting

Simple

Détails

Action de trace

OnResultExecuting

Simple

Détails

Horloge de demande

OnResultExecuted

Simple

Détails

Horloge de demande

OnResultExecuted

Simple

Détails

Action de trace

OnResultExecuted

Simple

Détails

Contrôleur simple

OnActionExecuting

Début

Index

Filtre de l'horloge des demandes

OnActionExecuted

Début

Index

Filtre de l'horloge des demandes

OnResultExecuting

Début

Index

Filtre de l'horloge des demandes

OnResultExecuted

Début

Index

Filtre de l'horloge des demandes

L'exemple téléchargeable pour cette rubrique implémente le filtrage décrit dans ces tables.

Ne stockez pas l'état de filtre dans une instance de filtre. L'état par demande est généralement stocké dans la propriété Items. Cette collection est initialisée pour se vider à chaque demande et est supprimée lorsque la demande est terminée. L'état par utilisateur transitoire est généralement stocké dans la session de l'utilisateur. Les informations d'état de l'utilisateur sont souvent stockées dans une base de données. L'exemple téléchargeable pour cette rubrique inclut un filtre d'horloge qui utilise l'état par demande. Pour plus d'informations sur la création de filtres avec état, visionnez la vidéo Advanced MVC 3.

Title

Description

ASP.NET MVC 3 Service Location, Part 4: Filters

(Entrée de blog) Décrit des filtres ASP.NET MVC dans un contexte d'emplacement de service.

AuthorizeAttribute

Explique comment utiliser l'attribut Authorize pour contrôler l'accès à une méthode d'action.

OutputCacheAttribute

Explique comment utiliser l'attribut OutputCache pour assurer la mise en cache de sortie d'une méthode d'action.

HandleErrorAttribute

Explique comment utiliser l'attribut HandleError pour gérer les exceptions levées par une méthode d'action.

Création de filtres d'action personnalisés

Explique comment implémenter des filtres d'action personnalisés.

Comment : créer un filtre d'action personnalisé

Explique comment ajouter un filtre d'action personnalisé à une application ASP.NET MVC.

Ajouts de la communauté

AJOUTER
Afficher: