Gérer les erreurs dans les API ASP.NET Core

Note

Ceci n’est pas la dernière version de cet article. Pour la version actuelle, consultez la version .NET 10 de cet article.

Avertissement

Cette version de ASP.NET Core n’est plus prise en charge. Pour plus d’informations, consultez la politique de support de .NET et .NET Core. Pour la version actuelle, consultez la version .NET 10 de cet article.

Cet article explique comment gérer les erreurs dans ASP.NET Core API. La documentation relative aux API minimales est sélectionnée. Pour afficher la documentation relative aux API basées sur le contrôleur, sélectionnez l’onglet Controllers. Pour obtenir des instructions de gestion des erreurs Blazor, consultez les erreurs Handle dans les applications ASP.NET Core Blazor.

Cet article explique comment gérer les erreurs dans ASP.NET Core API. La documentation relative aux API basées sur le contrôleur est sélectionnée. Pour afficher la documentation relative aux API Minimales, sélectionnez l’onglet API Minimales. Pour obtenir des instructions de gestion des erreurs Blazor, consultez Gérer les erreurs dans les applications ASP.NET Core Blazor.

Page d’exception du développeur

La page d’exceptions du développeur affiche des informations détaillées sur les exceptions de requête non gérées. Il utilise [nom de l'outil ou méthode] pour capter les exceptions synchrones et asynchrones issues du pipeline HTTP et pour générer des réponses d'erreur. La page d'exception du développeur s'exécute tôt dans le pipeline d'intergiciels, afin de pouvoir intercepter les exceptions non gérées levées dans les intergiciels suivants.

ASP.NET Core applications activent la page d’exception de développeur par défaut lorsque les deux :

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

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

Avertissement

N’activez pas la page d’exception du développeur, sauf si l’application s’exécute dans l’environnement. Ne partagez pas d’informations d’exception détaillées publiquement lorsque l’application s’exécute en production. Pour plus d’informations sur la configuration des environnements, consultez ASP.NET Core environnements d’exécution.

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

• Trace de pile
• Paramètres de chaîne de requête, le cas échéant
• Cookies, le cas échéant
• headers
• Métadonnées de point de terminaison, le cas échéant

La page d’exception du développeur n’est pas garantie de fournir des informations. Utilisez la journalisation pour obtenir des informations d’erreur complètes.

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

Page d’exception du développeur animée pour afficher chaque onglet sélectionné.

En réponse à une demande avec un en-tête, 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 du développeur dans une API minimale :

• Exécutez l’exemple d’application dans l’environnement.
• Accédez au point de terminaison.

Cette section fait référence à l’exemple d’application suivant pour illustrer les méthodes de gestion des exceptions dans une API minimale. Elle lève une exception lorsque le point de terminaison est demandé :

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

app.MapGet("/exception", () => 
{
    throw new InvalidOperationException("Sample Exception");
});

app.MapGet("/", () => "Test by calling /exception");

app.Run();

Pour afficher la page d’exception du développeur dans une API basée sur un contrôleur :

• 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 non de développement, utilisez l’intergiciel du gestionnaire d’exceptions pour produire une charge utile d’erreur.

Pour configurer le , appelez . Par exemple, le code suivant modifie l’application pour répondre avec une charge utile conforme RFC 7807 au client. Pour plus d’informations, consultez la section Détails du problème plus loin dans cet article.

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

app.UseExceptionHandler(exceptionHandlerApp 
    => exceptionHandlerApp.Run(async context 
        => await Results.Problem()
                     .ExecuteAsync(context)));

app.MapGet("/exception", () => 
{
    throw new InvalidOperationException("Sample Exception");
});

app.MapGet("/", () => "Test by calling /exception");

app.Run();

1. Dans , appelez pour ajouter l’intergiciel 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 :

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

L’action précédente envoie une charge utile compatible 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 . Les verbes explicites empêchent certaines requêtes 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é sur . Cette configuration d’attribut exclut l’action du gestionnaire d’erreurs de la spécification OpenAPI de l’application :

[ApiExplorerSettings(IgnoreApi = true)]

Autoriser l'accès anonyme à la méthode si les utilisateurs non authentifiés doivent voir l'erreur.

Réponses d’erreur client et serveur

Considérez l’application API minimale suivante.

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

app.MapGet("/users/{id:int}", (int id) 
    => id <= 0 ? Results.BadRequest() : Results.Ok(new User(id)));

app.MapGet("/", () => "Test by calling /users/{id:int}");

app.Run();

public record User(int Id);

Le endpoint produit une représentation de lorsque est supérieure à , sinon, il renvoie un code d'état sans contenu de réponse. Pour plus d’informations sur la création d’une réponse, consultez Créer des réponses dans les applications API minimales.

Il peut être configuré pour produire un contenu de corps commun, lorsqu’il est vide, pour toutes les réponses du client HTTP () ou du serveur (). L’intergiciel est configuré en appelant la méthode d’extension UseStatusCodePages .

Par exemple, l’exemple suivant modifie l’application pour répondre avec une charge utile conforme RFC 7807 au client pour toutes les réponses client et serveur, y compris les erreurs de routage (par exemple). Pour plus d’informations, consultez la section Détails du problème .

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

app.UseStatusCodePages(async statusCodeContext 
    => await Results.Problem(statusCode: statusCodeContext.HttpContext.Response.StatusCode)
                 .ExecuteAsync(statusCodeContext.HttpContext));

app.MapGet("/users/{id:int}", (int id) 
    => id <= 0 ? Results.BadRequest() : Results.Ok(new User(id)) );

app.MapGet("/", () => "Test by calling /users/{id:int}");

app.Run();

public record User(int Id);

Pour les API basées sur le contrôleur, la réponse d’erreur peut être configurée de l’une des manières suivantes :

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

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

La création automatique d’un code d’état d’erreur est activée par défaut.

Détails du problème

Les détails du problème ne sont pas le seul format de réponse à décrire une erreur d’API HTTP. Toutefois, ils sont couramment utilisés pour signaler des erreurs pour les API HTTP.

Le service détails du problème implémente l’interface IProblemDetailsService, qui prend en charge la création de détails de problème dans ASP.NET Core. La méthode d'extension sur [objet] enregistre l'implémentation par défaut.

Dans les applications ASP.NET Core, l'intergiciel suivant génère des réponses HTTP avec des détails de problème lorsque est appelé, sauf lorsque l'en-tête HTTP de la requête n'inclut pas l'un des types de contenu pris en charge par le enregistré (valeur par défaut : ) :

• : génère une réponse de détails sur le problème lorsqu’un gestionnaire personnalisé n’est pas défini.
• : génère une réponse de détails sur le problème par défaut.
• : génère une réponse de détails de problème au développement lorsque l’en-tête HTTP de la requête n’inclut pas .

Les applications d'API minimales peuvent être configurées pour générer une réponse comprenant les détails du problème pour toutes les réponses d'erreur client et serveur HTTP qui n'ont pas encore de contenu de la réponse, à l'aide de la méthode d'extension.

Le code suivant configure l’application pour générer les détails du problème :

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddProblemDetails();

var app = builder.Build();

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

app.MapGet("/users/{id:int}", (int id) 
    => id <= 0 ? Results.BadRequest() : Results.Ok(new User(id)));

app.MapGet("/", () => "Test by calling /users/{id:int}");

app.Run();

public record User(int Id);

Pour plus d’informations sur l’utilisation , consultez Détails du problème

Secours IProblemDetailsService

Dans le code suivant, retourne une erreur si l’implémentation n’est pas en mesure de générer un :

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddProblemDetails();

var app = builder.Build();

app.UseExceptionHandler(exceptionHandlerApp =>
{
    exceptionHandlerApp.Run(async httpContext =>
    {
        var pds = httpContext.RequestServices.GetService<IProblemDetailsService>();
        if (pds == null
            || !await pds.TryWriteAsync(new() { HttpContext = httpContext }))
        {
            // Fallback behavior
            await httpContext.Response.WriteAsync("Fallback: An error occurred.");
        }
    });
});

app.MapGet("/exception", () =>
{
    throw new InvalidOperationException("Sample Exception");
});

app.MapGet("/", () => "Test by calling /exception");

app.Run();

Code précédent :

• Écrit un message d’erreur avec le code de repli si le système n’est pas en mesure d’écrire un . Par exemple, un point de terminaison dans lequel l'en-tête de la demande Accept spécifie un type de média que le serveur ne prend pas en charge.
• Utilise l’intergiciel du gestionnaire d’exceptions.

Note

Supporte les types de média suivants dans l’en-tête de la requête :

• application/json
• application/problem+json
• Types génériques tels que et

Les types de supports non JSON, tels que ou , ne sont pas pris en charge et déclenchent le comportement de secours.

L’exemple suivant est similaire à l’exemple précédent, sauf qu’il appelle le .

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddProblemDetails();

var app = builder.Build();

app.UseStatusCodePages(statusCodeHandlerApp =>
{
    statusCodeHandlerApp.Run(async httpContext =>
    {
        var pds = httpContext.RequestServices.GetService<IProblemDetailsService>();
        if (pds == null
            || !await pds.TryWriteAsync(new() { HttpContext = httpContext }))
        {
            // Fallback behavior
            await httpContext.Response.WriteAsync("Fallback: An error occurred.");
        }
    });
});

app.MapGet("/users/{id:int}", (int id) =>
{
    return id <= 0 ? Results.BadRequest() : Results.Ok(new User(id));
});

app.MapGet("/", () => "Test by calling /users/{id:int}");

app.Run();

public record User(int Id);

Service de détails de problème

ASP.NET Core prend en charge la création de Détails de problème pour les API HTTP à l’aide du IProblemDetailsService.

Le code suivant configure l’application pour générer une réponse de détails sur le problème pour toutes les réponses d’erreur client et serveur 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 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 de 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 aucun point de terminaison correspondant.
• Une exception non gérée se produit.

Personnaliser les détails du problème avec

Le code suivant utilise pour définir :

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();

Mettre en œuvre

MVC utilise pour produire toutes les instances de et . Cette fabrique est utilisée pour :

• Réponses aux erreurs du client
• Réponses d’erreur d’échec de validation
• et

Pour personnaliser la réponse des détails du problème, inscrivez une implémentation personnalisée dans :

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

Utilisez .

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

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

Fonctionnalités supplémentaires de gestion des erreurs

Migration de contrôleurs vers des API minimales

Si vous migrez des API basées sur le contrôleur vers des API minimales :

1. Remplacer des filtres d’action par des filtres de point de terminaison ou un intergiciel
2. Remplacer la validation du modèle par une validation manuelle ou une liaison personnalisée
3. Remplacer les filtres d’exceptions par le middleware de gestion des exceptions
4. Configurer les détails du problème pour garantir des réponses d’erreur cohérentes

Quand utiliser la gestion des erreurs basée sur le contrôleur

Envisagez les API basées sur le contrôleur si vous avez besoin des éléments suivants :

• Scénarios de validation de modèle complexes
• Gestion centralisée des exceptions sur plusieurs contrôleurs
• Contrôle précis sur la mise en forme de réponse aux erreurs
• Intégration à des fonctionnalités MVC telles que des filtres et des conventions

Pour plus d’informations sur la gestion des erreurs basée sur le contrôleur, notamment les erreurs de validation, la personnalisation des détails du problème et les filtres d’exceptions, consultez les sections de l’onglet Contrôleurs .

Réponse d’erreur d’échec de validation

Pour les contrôleurs d’API web, MVC répond avec un type de réponse lorsque la validation du modèle échoue. MVC utilise les résultats pour construire la réponse d'erreur en cas d'échec de validation. L’exemple suivant remplace le facteur par défaut par une implémentation qui prend également en charge le formatage des réponses en XML, dans :

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

Utiliser des exceptions pour modifier la réponse

Le contenu de la réponse peut être modifié en dehors 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é :

   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é :

   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 une valeur entière maximale moins 10. Cela permet à d’autres filtres de fonctionner à la fin du pipeline.

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

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

Principales différences pour les contrôleurs

• Validation automatique du modèle : les contrôleurs valident automatiquement l’état du modèle et retournent des réponses pour les échecs de validation
• Filtres d’exceptions : utiliser des filtres d’action et des filtres d’exception pour la gestion centralisée des erreurs
• Détails du problème intégré : Configurer pour les réponses d’erreur standardisées
• Réponses d’erreur personnalisées : remplacement de la mise en forme d’erreur de validation personnalisée

Ressources supplémentaires

• How to Use ModelState Validation in ASP.NET Core Web API
• Afficher ou télécharger l’exemple de code
• Hellang.Middleware.ProblemDetails