ASP.NET Core 애플리케이션에서 전역 예외 처리를 구현하려면 커스텀 예외 미들웨어(Custom Exception Middleware)를 활용하는 것이 가장 효과적입니다. 이 글에서는 미들웨어를 직접 작성하고 파이프라인에 등록하여 모든 HTTP 요청에서 발생하는 오류를 일관되게 처리하는 방법을 단계별로 살펴봅니다.
1. 예외 미들웨어 클래스 생성
먼저 프로젝트에 CustomExceptionMiddleware라는 이름의 새 폴더를 만들고, 그 안에 ExceptionMiddleware.cs 클래스를 생성합니다.
가장 먼저 해야 할 일은 의존성 주입(Dependency Injection)을 통해 ILoggerManager 서비스와 RequestDelegate를 등록하는 것입니다.
여기서 RequestDelegate 타입의 _next 매개변수는 HTTP 요청을 처리할 수 있는 함수 델리게이트입니다. 즉, 요청이 파이프라인의 다음 단계로 전달되도록 하는 역할을 담당합니다.
2. InvokeAsync() 메서드 구현
등록 과정이 끝나면 반드시 InvokeAsync() 메서드를 작성해야 합니다. 이 메서드가 없으면 RequestDelegate는 요청을 처리할 수 없습니다.
정상적인 흐름이라면 _next 델리게이트가 요청을 처리하고, 컨트롤러의 Get 액션이 성공적인 응답을 반환해야 합니다. 하지만 요청 처리 중 예외가 발생하면(이 예제에서는 의도적으로 예외를 강제 발생시킵니다) 미들웨어의 catch 블록이 실행되고, HandleExceptionAsync 메서드가 호출됩니다.
public class ExceptionMiddleware
{
private readonly RequestDelegate _next;
private readonly ILoggerManager _logger;
public ExceptionMiddleware(RequestDelegate next, ILoggerManager logger)
{
_logger = logger;
_next = next;
}
public async Task InvokeAsync(HttpContext httpContext)
{
try
{
await _next(httpContext);
}
catch (Exception ex)
{
_logger.LogError($"Something went wrong: {ex}");
await HandleExceptionAsync(httpContext, ex);
}
}
private Task HandleExceptionAsync(HttpContext context, Exception exception)
{
context.Response.ContentType = "application/json";
context.Response.StatusCode = (int)HttpStatusCode.InternalServerError;
return context.Response.WriteAsync(new ErrorDetails()
{
StatusCode = context.Response.StatusCode,
Message = "Internal Server Error from the custom middleware."
}.ToString());
}
}동작 방식 요약
- try 블록: 요청을 다음 미들웨어로 전달하여 정상적으로 처리합니다.
- catch 블록: 예외 발생 시 로거에 오류를 기록한 뒤, 클라이언트에게 JSON 형식의 500(Internal Server Error) 응답을 반환합니다.
3. 확장 메서드로 미들웨어 등록
다음으로 ExceptionMiddlewareExtensions 클래스에 아래와 같은 정적 확장 메서드를 추가합니다.
public static void ConfigureCustomExceptionMiddleware(this IApplicationBuilder app)
{
app.UseMiddleware<ExceptionMiddleware>();
}마지막으로 Startup 클래스의 Configure 메서드에서 이 확장 메서드를 호출하여 미들웨어를 파이프라인에 등록합니다.
app.ConfigureCustomExceptionMiddleware();
마무리
이렇게 구성하면 애플리케이션 어디에서든 발생하는 처리되지 않은 예외를 한 곳에서 잡아내고, 로그를 기록한 후 클라이언트에게 일관된 형식의 오류 응답(JSON)을 반환할 수 있습니다. 코드 중복을 줄이고 유지보수성을 높이는 전역 예외 처리 전략으로, 실무 ASP.NET Core 프로젝트에서 널리 사용되는 패턴입니다.