Gérer les erreurs d’API web basées sur le contrôleur ASP.NET Core

Cet article explique comment gérer les erreurs et personnaliser la gestion des erreurs dans ASP.NET Core API web basé sur le contrôleur. Pour plus d’informations sur la gestion des erreurs d’API minimal, consultez Gérer les erreurs dans ASP.NET Core et Gérer les erreurs dans les API minimales.

Page d’exceptions du développeur

La Page d’exception du développeur affiche des informations détaillées sur les exceptions des requêtes non prises en charge. Il utilise DeveloperExceptionPageMiddleware pour capturer des exceptions synchrones et asynchrones à partir du pipeline HTTP et pour générer des réponses d’erreur. La page d’exception du développeur s’exécute au début du pipeline intergiciel, de manière qu’elle puisse intercepter les exceptions non prises en charge levées dans l’intergiciel qui suit.

Les applications ASP.NET Core activent la page d’exception du développeur par défaut en présence des deux éléments suivants :

• Exécution dans l’environnement de développement.
• L’application a été créée avec les modèles actuels, c’est-à-dire à l’aide de WebApplication.CreateBuilder.

Les applications créées à l’aide de modèles antérieurs, c’est-à-dire à l’aide de WebHost.CreateDefaultBuilder, peuvent activer la page d’exception de développeur en appelant app.UseDeveloperExceptionPage.

Avertissement

Activez la Page d’exception de développeur uniquement quand l’application est en cours d’exécution dans l’environnement de développement. Il n’est pas souhaitable de partager publiquement des informations détaillées sur les exceptions quand l’application s’exécute en production. Pour plus d’informations sur la configuration selon l’environnement, consultez Utiliser plusieurs environnements dans ASP.NET Core.

La page d’exception du développeur peut inclure les informations suivantes sur l’exception et la requête :

• Trace de pile
• Paramètres de la chaîne de requête, le cas échéant
• Cookies (le cas échéant)
• En-têtes
• Métadonnées du point de terminaison, le cas échéant

Il n’est pas garanti que la page d’exception du développeur fournisse des informations. Utilisez la journalisation pour obtenir des informations complètes sur l’erreur.

L’image suivante montre un exemple de page d’exception de développeur avec animation pour afficher les onglets et les informations affichées :

En réponse à une demande avec un en-tête Accept: text/plain, la page d’exception du développeur retourne du texte brut au lieu de HTML. Par exemple :

Status: 500 Internal Server Error
Time: 9.39 msSize: 480 bytes
FormattedRawHeadersRequest
Body
text/plain; charset=utf-8, 480 bytes
System.InvalidOperationException: Sample Exception
   at WebApplicationMinimal.Program.<>c.<Main>b__0_0() in C:\Source\WebApplicationMinimal\Program.cs:line 12
   at lambda_method1(Closure, Object, HttpContext)
   at Microsoft.AspNetCore.Diagnostics.DeveloperExceptionPageMiddlewareImpl.Invoke(HttpContext context)

HEADERS
=======
Accept: text/plain
Host: localhost:7267
traceparent: 00-0eab195ea19d07b90a46cd7d6bf2f

Pour afficher la page d’exception de développeur :

• Ajoutez l’action de contrôleur suivante à une API basée sur un contrôleur. L’action lève une exception lorsque le point de terminaison est demandé.

  [HttpGet("Throw")]
  public IActionResult Throw() =>
      throw new Exception("Sample exception.");
  

• Exécutez l’application dans l’environnement de développement.

• Accédez au point de terminaison défini par l’action du contrôleur.

Gestionnaire d’exceptions

Dans les environnements hors développement, utilisez l’intergiciel de gestion des exceptions pour produire une erreur :

1. Dans Program.cs, appelez UseExceptionHandler pour ajouter le middleware de gestion des exceptions :

   var app = builder.Build();
   
   app.UseHttpsRedirection();
   
   if (!app.Environment.IsDevelopment())
   {
       app.UseExceptionHandler("/error");
   }
   
   app.UseAuthorization();
   
   app.MapControllers();
   
   app.Run();
   

2. Configurez une action de contrôleur pour répondre à l’itinéraire /error :

   [Route("/error")]
   public IActionResult HandleError() =>
       Problem();
   

L’action précédente HandleError envoie une charge utile conforme À la norme RFC 7807 au client.

Avertissement

Ne marquez pas la méthode d’action du gestionnaire d’erreurs avec des attributs de méthode HTTP, tels que HttpGet. Les verbes explicites empêchent certaines demandes d’atteindre la méthode d’action.

Pour les API web qui utilisent Swagger/OpenAPI, marquez l’action du gestionnaire d’erreurs avec l’attribut [ApiExplorerSettings] et définissez sa propriété IgnoreApi sur true. Cette configuration d’attribut exclut l’action de gestionnaire d’erreurs de la spécification OpenAPI de l’application :

[ApiExplorerSettings(IgnoreApi = true)]

Autorisez l’accès anonyme à la méthode si les utilisateurs non authentifiés doivent consulter l’erreur.

L’intergiciel de gestion des exceptions peut également être utilisé dans l’environnement de développement pour produire un format de charge utile cohérent dans tous les environnements :

1. Dans Program.cs, inscrivez les instances d’intergiciels de gestion des exceptions spécifiques à l’environnement :

   if (app.Environment.IsDevelopment())
   {
       app.UseExceptionHandler("/error-development");
   }
   else
   {
       app.UseExceptionHandler("/error");
   }
   

   Dans le code précédent, l’intergiciel est inscrit avec :

   • Itinéraire de /error-development dans l’environnement de développement.
   • Itinéraire de /error dans les environnements non-développement.

2. Ajoutez des actions de contrôleur pour les routes Développement et Non Développement :

   [Route("/error-development")]
   public IActionResult HandleErrorDevelopment(
       [FromServices] IHostEnvironment hostEnvironment)
   {
       if (!hostEnvironment.IsDevelopment())
       {
           return NotFound();
       }
   
       var exceptionHandlerFeature =
           HttpContext.Features.Get<IExceptionHandlerFeature>()!;
   
       return Problem(
           detail: exceptionHandlerFeature.Error.StackTrace,
           title: exceptionHandlerFeature.Error.Message);
   }
   
   [Route("/error")]
   public IActionResult HandleError() =>
       Problem();
   

Utiliser des exceptions pour modifier la réponse

Le contenu de la réponse peut être modifié à l’extérieur du contrôleur à l’aide d’une exception personnalisée et d’un filtre d’action :

1. Créez un type d’exception connu nommé HttpResponseException :

   public class HttpResponseException : Exception
   {
       public HttpResponseException(int statusCode, object? value = null) =>
           (StatusCode, Value) = (statusCode, value);
   
       public int StatusCode { get; }
   
       public object? Value { get; }
   }
   

2. Créez un filtre d’action nommé HttpResponseExceptionFilter :

   public class HttpResponseExceptionFilter : IActionFilter, IOrderedFilter
   {
       public int Order => int.MaxValue - 10;
   
       public void OnActionExecuting(ActionExecutingContext context) { }
   
       public void OnActionExecuted(ActionExecutedContext context)
       {
           if (context.Exception is HttpResponseException httpResponseException)
           {
               context.Result = new ObjectResult(httpResponseException.Value)
               {
                   StatusCode = httpResponseException.StatusCode
               };
   
               context.ExceptionHandled = true;
           }
       }
   }
   

   Le filtre précédent spécifie un Order de la valeur entière maximale moins 10. Ce Order permet à d’autres filtres de s’exécuter à la fin du pipeline.

3. Dans Program.cs, ajoutez le filtre d’action à la collection filtres :

   builder.Services.AddControllers(options =>
   {
       options.Filters.Add<HttpResponseExceptionFilter>();
   });
   

Erreur de défaillance de validation des données

Pour les contrôleurs d’API web, MVC répond avec un ValidationProblemDetails type de réponse en cas d’échec de la validation du modèle. MVC utilise les résultats de InvalidModelStateResponseFactory pour construire la réponse d’erreur pour un échec de validation. L’exemple suivant remplace la fabrique par défaut par une implémentation qui prend également en charge la mise en forme des réponses au format XML, dans Program.cs :

builder.Services.AddControllers()
    .ConfigureApiBehaviorOptions(options =>
    {
        options.InvalidModelStateResponseFactory = context =>
            new BadRequestObjectResult(context.ModelState)
            {
                ContentTypes =
                {
                    // using static System.Net.Mime.MediaTypeNames;
                    Application.Json,
                    Application.Xml
                }
            };
    })
    .AddXmlSerializerFormatters();

Réponse d’erreur du client

Un résultat d’erreur est défini comme résultat avec un code d’état HTTP 400 ou supérieur. Pour les contrôleurs d’API web, MVC transforme un résultat d’erreur pour produire un ProblemDetails.

La création automatique d’un pour les ProblemDetails codes d’état d’erreur est activée par défaut, mais les réponses d’erreur peuvent être configurées de l’une des manières suivantes :

1. Utiliser le service des détails du problème
2. Implémenter ProblemDetailsFactory
3. Utiliser ApiBehaviorOptions.ClientErrorMapping

Réponse des détails du problème par défaut

Le fichier suivant Program.cs a été généré par les modèles d’application web pour les contrôleurs d’API :

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers();

var app = builder.Build();

app.UseHttpsRedirection();

app.UseAuthorization();

app.MapControllers();

app.Run();

Considérez le contrôleur suivant, qui retourne BadRequest lorsque l’entrée n’est pas valide :

[Route("api/[controller]/[action]")]
[ApiController]
public class Values2Controller : ControllerBase
{
    // /api/values2/divide/1/2
    [HttpGet("{Numerator}/{Denominator}")]
    public IActionResult Divide(double Numerator, double Denominator)
    {
        if (Denominator == 0)
        {
            return BadRequest();
        }

        return Ok(Numerator / Denominator);
    }

    // /api/values2 /squareroot/4
    [HttpGet("{radicand}")]
    public IActionResult Squareroot(double radicand)
    {
        if (radicand < 0)
        {
            return BadRequest();
        }

        return Ok(Math.Sqrt(radicand));
    }
}

Une réponse des détails du problème est générée avec le code précédent lorsque l’une des conditions suivantes s’applique :

• Le point de terminaison /api/values2/divide est appelé avec un dénominateur zéro.
• Le point de terminaison /api/values2/squareroot est appelé avec un radicand inférieur à zéro.

Le corps de la réponse des détails du problème par défaut a les valeurs , typeet titlestatus suivantes :

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "Bad Request",
  "status": 400,
  "traceId": "00-84c1fd4063c38d9f3900d06e56542d48-85d1d4-00"
}

Service détails du problème

ASP.NET Core prend en charge la création de détails du problème pour les API HTTP à l’aide de IProblemDetailsService. Pour plus d’informations, consultez le service Détails du problème.

Le code suivant configure l’application pour qu’elle génère une réponse sur les détails du problème pour toutes les réponses d’erreur de serveur et de client HTTP qui n’ont pas encore de contenu de corps :

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers();
builder.Services.AddProblemDetails();

var app = builder.Build();

app.UseExceptionHandler();
app.UseStatusCodePages();

if (app.Environment.IsDevelopment())
{
    app.UseDeveloperExceptionPage();
}

app.MapControllers();
app.Run();

Considérez le contrôleur d’API de la section précédente, qui retourne BadRequest lorsque l’entrée n’est pas valide :

[Route("api/[controller]/[action]")]
[ApiController]
public class Values2Controller : ControllerBase
{
    // /api/values2/divide/1/2
    [HttpGet("{Numerator}/{Denominator}")]
    public IActionResult Divide(double Numerator, double Denominator)
    {
        if (Denominator == 0)
        {
            return BadRequest();
        }

        return Ok(Numerator / Denominator);
    }

    // /api/values2 /squareroot/4
    [HttpGet("{radicand}")]
    public IActionResult Squareroot(double radicand)
    {
        if (radicand < 0)
        {
            return BadRequest();
        }

        return Ok(Math.Sqrt(radicand));
    }
}

Une réponse des détails du problème est générée avec le code précédent lorsque l’une des conditions suivantes s’applique :

• Une entrée non valide est fournie.
• L’URI n’a pas de point de terminaison correspondant.
• Une exception non prise en charge se produit.

La création automatique d’un ProblemDetails pour les codes d’état d’erreur est désactivée quand la propriété SuppressMapClientErrors est définie sur true :

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers()
    .ConfigureApiBehaviorOptions(options =>
    {
        options.SuppressMapClientErrors = true;
    });

var app = builder.Build();

app.UseHttpsRedirection();

app.UseAuthorization();

app.MapControllers();

app.Run();

À l’aide du code précédent, lorsqu’un contrôleur d’API retourne BadRequest, un état de réponse HTTP 400 est retourné sans corps de réponse. SuppressMapClientErrors empêche la création d’une ProblemDetails réponse, même lors de l’appel WriteAsync d’un point de terminaison de contrôleur d’API. WriteAsync est expliqué plus loin dans cet article.

La section suivante montre comment personnaliser le corps de la réponse des détails du problème, à l’aide de CustomizeProblemDetails, pour retourner une réponse plus utile. Pour plus d’options de personnalisation, consultez Personnalisation des détails du problème.

Personnaliser les détails du problème avec CustomizeProblemDetails

Le code suivant utilise ProblemDetailsOptions pour définir CustomizeProblemDetails :

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers();

builder.Services.AddProblemDetails(options =>
        options.CustomizeProblemDetails = (context) =>
        {

            var mathErrorFeature = context.HttpContext.Features
                                                       .Get<MathErrorFeature>();
            if (mathErrorFeature is not null)
            {
                (string Detail, string Type) details = mathErrorFeature.MathError switch
                {
                    MathErrorType.DivisionByZeroError =>
                    ("Divison by zero is not defined.",
                                          "https://wikipedia.org/wiki/Division_by_zero"),
                    _ => ("Negative or complex numbers are not valid input.",
                                          "https://wikipedia.org/wiki/Square_root")
                };

                context.ProblemDetails.Type = details.Type;
                context.ProblemDetails.Title = "Bad Input";
                context.ProblemDetails.Detail = details.Detail;
            }
        }
    );

var app = builder.Build();

app.UseHttpsRedirection();

app.UseStatusCodePages();

app.UseAuthorization();

app.MapControllers();

app.Run();

Contrôleur d’API mis à jour :

[Route("api/[controller]/[action]")]
[ApiController]
public class ValuesController : ControllerBase
{
    // /api/values/divide/1/2
    [HttpGet("{Numerator}/{Denominator}")]
    public IActionResult Divide(double Numerator, double Denominator)
    {
        if (Denominator == 0)
        {
            var errorType = new MathErrorFeature
            {
                MathError = MathErrorType.DivisionByZeroError
            };
            HttpContext.Features.Set(errorType);
            return BadRequest();
        }

        return Ok(Numerator / Denominator);
    }

    // /api/values/squareroot/4
    [HttpGet("{radicand}")]
    public IActionResult Squareroot(double radicand)
    {
        if (radicand < 0)
        {
            var errorType = new MathErrorFeature
            {
                MathError = MathErrorType.NegativeRadicandError
            };
            HttpContext.Features.Set(errorType);
            return BadRequest();
        }

        return Ok(Math.Sqrt(radicand));
    }

}

Le code suivant contient les MathErrorFeature et MathErrorType, qui sont utilisés avec l’exemple précédent :

// Custom Http Request Feature
class MathErrorFeature
{
    public MathErrorType MathError { get; set; }
}

// Custom math errors
enum MathErrorType
{
    DivisionByZeroError,
    NegativeRadicandError
}

Une réponse des détails du problème est générée avec le code précédent lorsque l’une des conditions suivantes s’applique :

• Le point de terminaison /divide est appelé avec un dénominateur zéro.
• Le point de terminaison /squareroot est appelé avec un radicand inférieur à zéro.
• L’URI n’a pas de point de terminaison correspondant.

Le corps de la réponse des détails du problème contient les éléments suivants lorsque l’un des points de terminaison squarerootest appelé avec un radicand inférieur à zéro :

{
  "type": "https://en.wikipedia.org/wiki/Square_root",
  "title": "Bad Input",
  "status": 400,
  "detail": "Negative or complex numbers are not allowed."
}

Afficher ou télécharger l’exemple de code

Implémentez ProblemDetailsFactory

MVC utilise Microsoft.AspNetCore.Mvc.Infrastructure.ProblemDetailsFactory pour produire toutes les instances de ProblemDetails et ValidationProblemDetails. Cette fabrique est utilisée pour :

• Réponses d’erreur du client
• Réponses d’erreur d’échec de validation
• ControllerBase.Problem et ControllerBase.ValidationProblem

Pour personnaliser la réponse aux détails du problème, inscrivez une implémentation personnalisée de ProblemDetailsFactory dans Program.cs :

builder.Services.AddControllers();
builder.Services.AddTransient<ProblemDetailsFactory, SampleProblemDetailsFactory>();

Utilisez ApiBehaviorOptions.ClientErrorMapping.

Utilisez la propriété ClientErrorMapping pour configurer le contenu de la réponse ProblemDetails. Par exemple, le code suivant dans Program.cs met à jour la propriété Link pour les réponses 404 :

builder.Services.AddControllers()
    .ConfigureApiBehaviorOptions(options =>
    {
        options.ClientErrorMapping[StatusCodes.Status404NotFound].Link =
            "https://httpstatuses.com/404";
    });

Ressources supplémentaires

• Guide pratique pour utiliser la validation ModelState dans ASP.NET Core API web
• Afficher ou télécharger l’exemple de code
• Hellang.Middleware.ProblemDetails