ASP.NET Core API에서 오류 처리

비고

이 기사는 최신 버전이 아닙니다. 현재 릴리스는 이 문서의 .NET 10 버전을 참조하세요.

경고

이 버전의 ASP.NET Core는 더 이상 지원되지 않습니다. 자세한 내용은 .NET 및 .NET Core 지원 정책을 참조하세요. 현재 릴리스에 대해서는 본 기사의 .NET 9 버전을 참조하십시오.

최소 API

이 문서에서는 ASP.NET Core API에서 오류를 처리하는 방법을 설명합니다. 최소 API에 대한 설명서가 선택되어 있습니다. 컨트롤러 기반 API에 대한 설명서를 보려면 컨트롤러 탭을 선택합니다. 오류 처리 지침은 BlazorASP.NET Core Blazor 앱의 오류 처리를 참조하세요.

컨트롤러

이 문서에서는 ASP.NET Core API에서 오류를 처리하는 방법을 설명합니다. 컨트롤러 기반 API에 대한 설명서가 선택됩니다. 최소 API에 대한 설명서를 보려면 최소 API 탭을 선택합니다. 오류 처리 지침은 BlazorASP.NET Core Blazor 앱의 오류 처리를 참조하세요.

개발자 예외 페이지

개발자 예외 페이지에는 처리되지 않은 요청 예외에 대한 자세한 정보가 표시됩니다. HTTP 파이프라인에서 동기 및 비동기 예외를 캡처하고 오류 응답을 생성하는 데 사용됩니다 DeveloperExceptionPageMiddleware . 개발자 예외 페이지는 미들웨어 파이프라인에서 초기에 실행되므로 다음 미들웨어에서 throw된 처리되지 않은 예외를 catch할 수 있습니다.

ASP.NET Core 앱은 다음과 같은 경우 기본적으로 개발자 예외 페이지를 사용하도록 설정합니다.

• 개발 환경에서 실행됩니다.
• 앱은 현재 템플릿, 즉 WebApplication.CreateBuilder.

이전 템플릿을 사용하여 만든 앱, 즉, 사용하여 WebHost.CreateDefaultBuilder개발자 예외 페이지를 호출 app.UseDeveloperExceptionPage하여 사용하도록 설정할 수 있습니다.

경고

개발 환경에서 앱이 실행되고 있지 않으면 개발자 예외 페이지를 사용하도록 설정하지 마세요. 앱이 프로덕션에서 실행되는 경우 자세한 예외 정보를 공개적으로 공유하지 마세요. 환경 구성에 대한 자세한 내용은 ASP.NET Core 런타임 환경을 참조하세요.

개발자 예외 페이지에는 예외 및 요청에 대한 다음 정보가 포함될 수 있습니다.

• 스택 추적
• 쿼리 문자열 매개 변수(있는 경우)
• 쿠키(있는 경우)
• Headers
• 엔드포인트 메타데이터(있는 경우)

개발자 예외 페이지는 정보를 제공하지 않습니다. 전체 오류 정보는 로깅 을 사용합니다.

다음 이미지는 탭 및 표시되는 정보를 표시하는 애니메이션이 있는 샘플 개발자 예외 페이지를 보여 줍니다.

헤더가 있는 요청에 Accept: text/plain 대한 응답으로 개발자 예외 페이지는 HTML 대신 일반 텍스트를 반환합니다. 다음은 그 예입니다.

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

최소 API

최소 API에서 개발자 예외 페이지를 보려면 다음을 수행합니다.

• 개발 환경에서 샘플 앱을 실행합니다.
• 엔드포인트로 /exception 이동합니다.

이 섹션에서는 최소 API에서 예외를 처리하는 방법을 보여 주는 다음 샘플 앱을 참조합니다. 엔드포인트 /exception 가 요청되면 예외가 throw됩니다.

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

컨트롤러

컨트롤러 기반 API에서 개발자 예외 페이지를 보려면 다음을 수행합니다.

• 컨트롤러 기반 API에 다음 컨트롤러 작업을 추가합니다. 엔드포인트가 요청되면 작업이 예외를 throw합니다.

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

• 개발 환경에서 앱을 실행합니다.

• 컨트롤러 작업으로 정의된 엔드포인트로 이동합니다.

예외 처리기

비개발 환경에서 는 예외 처리기 미들웨어 를 사용하여 오류 페이로드를 생성합니다.

최소 API

를 구성하려면 .를 Exception Handler Middleware호출합니다 UseExceptionHandler. 예를 들어 다음 코드는 RFC 7807 규격 페이로드를 사용하여 클라이언트에 응답하도록 앱을 변경합니다. 자세한 내용은 이 문서의 뒷부분에 있는 문제 세부 정보 섹션을 참조하세요.

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. 에서 Program.cs예외 처리 미들웨어를 추가하기 위한 호출 UseExceptionHandler :

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

2. 경로에 응답하도록 컨트롤러 작업을 구성합니다./error

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

이전 HandleError 작업은 RFC 7807 규격 페이로드를 클라이언트에 보냅니다.

경고

오류 처리기 작업 메서드를 HTTP 메서드 특성(예: HttpGet.)으로 표시하지 마세요. 명시적 동사는 일부 요청이 작업 메서드에 도달하지 못하도록 합니다.

Swagger/OpenAPI를 사용하는 웹 API의 경우 오류 처리기 동작을 [ApiExplorerSettings] 특성으로 표시하고 해당 IgnoreApi 속성을 true.로 설정합니다. 이 특성 구성은 앱의 OpenAPI 사양에서 오류 처리기 작업을 제외합니다.

[ApiExplorerSettings(IgnoreApi = true)]

인증되지 않은 사용자에게 오류가 표시되어야 하는 경우 메서드에 대한 익명 액세스를 허용합니다.

클라이언트 및 서버 오류 응답

최소 API

다음 최소 API 앱을 고려합니다.

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

엔드포인트는 /users 응답 본문이 없는 상태 코드보다 200 OKjson 큰 경우 User 를 id 표현하여 생성 0400 BAD REQUEST 합니다. 응답을 만드는 방법에 대한 자세한 내용은 최소 API 앱에서 응답 만들기를 참조하세요.

Status Code Pages middleware 모든 HTTP 클라이언트() 또는 서버400-() 응답에 대해 공용 본문 콘텐츠(499500 -599비어 있는 경우)를 생성하도록 구성할 수 있습니다. 미들웨어는 UseStatusCodePages 확장 메서드를 호출하여 구성됩니다.

예를 들어 다음 예제에서는 라우팅 오류(예: )를 포함하여 모든 클라이언트 및 서버 응답에 대해 404 NOT FOUND 규격 페이로드로 응답하도록 앱을 클라이언트로 변경합니다. 자세한 내용은 문제 세부 정보 섹션을 참조하세요.

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

컨트롤러

컨트롤러 기반 API의 경우 다음 방법 중 하나로 오류 응답을 구성할 수 있습니다.

1. 문제 세부 정보 서비스 사용
2. ProblemDetailsFactory 구현
3. ApiBehaviorOptions.ClientErrorMapping 사용

오류 결과는 HTTP 상태 코드가 400 이상인 결과로 정의됩니다. 웹 API 컨트롤러의 경우 MVC는 오류 결과를 변환하여 을 생성합니다 ProblemDetails.

오류 상태 코드에 ProblemDetails 대한 자동 생성은 기본적으로 사용하도록 설정됩니다.

문제 세부 정보

문제 세부 정보는 HTTP API 오류를 설명하는 유일한 응답 형식은 아니지만 일반적으로 HTTP API에 대한 오류를 보고하는 데 사용됩니다.

문제 세부 정보 서비스는 ASP.NET Core에서 문제 세부 정보 만들기를 지원하는 인터페이스를 구현 IProblemDetailsService 합니다. 확장 메서드는 AddProblemDetails(IServiceCollection)IServiceCollection 기본 IProblemDetailsService 구현을 등록합니다.

ASP.NET Core 앱에서 다음 미들웨어는 AddProblemDetails HTTP Accept 헤더에 등록된 콘텐츠 형식(기본값: IProblemDetailsWriter

• ExceptionHandlerMiddleware: 사용자 지정 처리기가 정의되지 않은 경우 문제 세부 정보 응답을 생성합니다.
• StatusCodePagesMiddleware: 기본적으로 문제 세부 정보 응답을 생성합니다.
• DeveloperExceptionPageMiddleware: 요청 HTTP 헤더에 포함되지 Accept않은 경우 개발 시 text/html 문제 세부 정보 응답을 생성합니다.

최소 API

확장 메서드를 사용하여 모든 HTTP 클라이언트 및 서버 오류 응답에 대한 문제 세부 정보 응답을 생성하도록 최소 API 앱을 구성할 수 있습니다.

다음 코드는 문제 세부 정보를 생성하도록 앱을 구성합니다.

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

사용에 AddProblemDetails대한 자세한 내용은 문제 세부 정보를 참조하세요.

IProblemDetailsService 대체

다음 코드 httpContext.Response.WriteAsync("Fallback: An error occurred.") 에서는 구현에서 다음을 생성할 수 없는 경우 IProblemDetailsService 오류를 반환합니다.ProblemDetails

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

앞의 코드는 다음과 같습니다.

• 를 쓸 수 없는 경우 problemDetailsService 대체 코드와 함께 오류 메시지를 씁니다 ProblemDetails. 예를 들어 Accept 요청 헤더 가 지원하지 않는 미디어 형식을 지정하는 DefaulProblemDetailsWriter 엔드포인트입니다.
• 예외 처리기 미들웨어를 사용합니다.

다음 샘플은 을 호출한다는 점을 제외하고 이전 샘플과 Status Code Pages middleware유사합니다.

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

컨트롤러

문제 세부 정보 서비스

ASP.NET Core는 다음을 사용하여 HTTP API에 대한 문제 세부 정보 만들기를 IProblemDetailsService지원합니다.

다음 코드는 아직 본문 콘텐츠가 없는 모든 HTTP 클라이언트 및 서버 오류 응답에 대한 문제 세부 정보 응답을 생성하도록 앱을 구성합니다.

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

입력이 유효하지 않은 경우 반환 BadRequest 되는 이전 섹션의 API 컨트롤러를 고려합니다.

[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));
    }
}

다음 조건 중 하나라도 적용되는 경우 이전 코드와 함께 문제 세부 정보 응답이 생성됩니다.

• 잘못된 입력이 제공됩니다.
• URI에 일치하는 엔드포인트가 없습니다.
• 처리되지 않은 예외가 발생합니다.

를 사용하여 문제 세부 정보 사용자 지정 CustomizeProblemDetails

다음 코드는 다음을 설정하는 ProblemDetailsOptions데 사용합니다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();

도구 ProblemDetailsFactory

MVC는 모든 인스턴스 및 Microsoft.AspNetCore.Mvc.Infrastructure.ProblemDetailsFactory.의 ProblemDetails 모든 인스턴스를 생성하는 데 사용합니다ValidationProblemDetails. 이 팩터리는 다음 용도로 사용됩니다.

• 클라이언트 오류 응답
• 유효성 검사 실패 오류 응답
• ControllerBase.Problem 및 ControllerBase.ValidationProblem

문제 세부 정보 응답을 사용자 지정하려면 다음의 ProblemDetailsFactory 사용자 지정 구현을 등록합니다.Program.cs

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

ApiBehaviorOptions.ClientErrorMapping 사용

ClientErrorMapping 속성을 사용하여 응답의 ProblemDetails 내용을 구성합니다. 예를 들어 다음 코드는 Program.cs 404 응답에 Link 대한 속성을 업데이트합니다.

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

추가 오류 처리 기능

최소 API

컨트롤러에서 최소 API로 마이그레이션

컨트롤러 기반 API에서 최소 API로 마이그레이션하는 경우:

1. 작업 필터를 엔드포인트 필터 또는 미들웨어로 바꾸기
2. 모델 유효성 검사를 수동 유효성 검사 또는 사용자 지정 바인딩으로 바꾸기
3. 예외 필터를 예외 처리 미들웨어로 바꾸기
4. 일관된 오류 응답을 사용하여 AddProblemDetails()

컨트롤러 기반 오류 처리를 사용하는 경우

필요한 경우 컨트롤러 기반 API를 고려합니다.

• 복잡한 모델 유효성 검사 시나리오
• 여러 컨트롤러에서 중앙 집중식 예외 처리
• 오류 응답 형식 지정에 대한 세분화된 제어
• 필터 및 규칙과 같은 MVC 기능과 통합

유효성 검사 오류, 문제 세부 정보 사용자 지정 및 예외 필터를 포함하여 컨트롤러 기반 오류 처리에 대한 자세한 내용은 컨트롤러 탭 섹션 을 참조하세요.

컨트롤러

유효성 검사 실패 오류 응답

웹 API 컨트롤러의 경우 MVC는 모델 유효성 검사에 실패할 ValidationProblemDetails 때 응답 형식으로 응답합니다. MVC는 결과를 InvalidModelStateResponseFactory 사용하여 유효성 검사 실패에 대한 오류 응답을 생성합니다. 다음 예제에서는 기본 팩터리를 XML 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();

예외를 사용하여 응답 수정

응답의 내용은 사용자 지정 예외 및 작업 필터를 사용하여 컨트롤러 외부에서 수정할 수 있습니다.

1. 다음과 같은 잘 알려진 예외 형식을 만듭니다 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. 다음과 같은 작업 필터를 만듭니다 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;
           }
       }
   }
   

   위의 필터는 최대 정수 값에서 10을 뺀 값을 지정 Order 합니다. 이렇게 Order 하면 파이프라인의 끝에서 다른 필터를 실행할 수 있습니다.

3. 에서 Program.cs필터 컬렉션에 작업 필터를 추가합니다.

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

컨트롤러의 주요 차이점

• 자동 모델 유효성 검사: 컨트롤러는 자동으로 모델 상태의 유효성을 검사하고 유효성 검사 실패에 대한 응답을 반환 400 Bad Request 합니다.
• 예외 필터: 중앙 집중식 오류 처리에 작업 필터 및 예외 필터 사용
• 기본 제공 문제 세부 정보: 표준화된 오류 응답 구성 ApiBehaviorOptions
• 사용자 지정 오류 응답: 사용자 지정 유효성 검사 오류 서식에 대한 재정 InvalidModelStateResponseFactory 의

추가 리소스

• ASP.NET Core Web API에서 ModelState 유효성 검사를 사용하는 방법
• 샘플 코드 보기 또는 다운로드
• Hellang.Middleware.ProblemDetails