컨트롤러: 필터

필터 선택하기

Authorization 필터는 현재 사용자가 지금 처리 중인 요청에 대한 권한을 부여 받았는지 여부를 판단할 때 사용됩니다.

Resource 필터는 권한이 부여된 이후에 요청을 처리하는 가장 첫 번째 필터이자, 필터 파이프라인을 빠져 나갈때 요청에 관여할 수 있는 가장 마지막 필터 중 하나입니다. 이 필터는 캐싱을 구현하거나, 성능상의 목적으로 필터 파이프라인을 신속하게 빠져나가야 할 때 특히 유용합니다.

Action 필터는 개별 액션 메서드에 대한 호출을 감싸고, 액션으로 전달되는 인자나 반환되는 액션 결과를 조정할 수 있습니다.

Exception 필터는 처리되지 않은 예외에 대한 MVC 응용 프로그램의 전역 정책을 적용할 때 사용됩니다.

Result 필터는 개별 액션 결과(Action Results)의 실행을 감싸며, 액션 메서드가 정상적으로 실행된 경우에만 실행됩니다. 뷰 실행이나 포맷터 실행을 감싸는 로직을 구현하기에 적합한 단계입니다.

구현

모든 필터는 서로 다른 두 가지 인터페이스 정의를 통해서 동기 구현과 비동기 구현 양쪽을 모두 지원할 수 있습니다. 동기 구현 혹은 비동기 구현 여부는 수행할 작업의 유형에 따라서 선택해야 하며, 프레임워크의 관점에 따라 서로 전환이 가능합니다.

동기 필터는 두 가지 메서드, 즉 OnStageExecuting 메서드와 OnStageExecuted 메서드를 정의합니다 (Authorization 필터 같은 예외적인 경우도 존재합니다). OnStageExecuting 메서드는 Stage 명에 해당하는 이벤트 파이프라인 단계 이전에 호출되고, OnStageExecuted 메서드는 Stage 명에 해당하는 이벤트 파이프라인 단계 이후에 호출됩니다.

using FiltersSample.Helper; 
using Microsoft.AspNetCore.Mvc.Filters;  

namespace FiltersSample.Filters 
{ 
    public class SampleActionFilter : IActionFilter    
    { 
        public void OnActionExecuting(ActionExecutingContext context)
        {
            // do something before the action executes
        }

        public void OnActionExecuted(ActionExecutedContext context) 
        {    
            // do something after the action executes
        }
    }
}

반면, 비동기 필터는 Stage 명에 해당하는 파이프라인 단계의 실행을 감싸는 단일 OnStageExecutionAsync 메서드 하나만 정의합니다. OnStageExecutionAsync 메서드는 호출되서 대기 중일 때, Stage 명에 해당하는 파이프라인 단계를 실행하는 StageExecutionDelegate 대리자를 제공받습니다.

using System.Threading.Tasks; 
using Microsoft.AspNetCore.Mvc.Filters;  

namespace FiltersSample.Filters 
{ 
    public class SampleAsyncActionFilter : IAsyncActionFilter 
    { 
        public async Task OnActionExecutionAsync(
            ActionExecutingContext context, 
            ActionExecutionDelegate next) 
        {
             // do something before the action executes
             await next();
             // do something after the action executes
        }
    }
}

필터 범위

필터는 세 가지 다른 수준의 범위로 설정이 가능합니다. 먼저, 특정 액션에 어트리뷰트를 적용해서 개별적으로 필터를 추가할 수 있습니다. 그리고 컨트롤러에 어트리뷰트를 적용해서 컨트롤러 내에 존재하는 모든 액션에 필터를 추가할 수도 있습니다. 마지막으로 모든 MVC 액션에 필터가 적용되도록 전역으로 필터를 등록할 수도 있습니다.

전역 필터는 Startup 파일의 ConfigureServices 메서드에서 MVC를 구성할 때 추가됩니다:

public void ConfigureServices(IServiceCollection services) 
{
    services.AddMvc(options =>
    {
        options.Filters.Add(typeof(SampleActionFilter)); // by type 
        options.Filters.Add(new SampleGlobalActionFilter()); // an instance
    });

    services.AddScoped<AddHeaderFilterWithDi>(); 
}

필터는 형식으로 추가할 수도 있고, 인스턴스로 추가할 수도 있습니다. 필터를 인스턴스로 추가하면 모든 요청에 해당 인스턴스가 사용됩니다. 반면, 형식으로 추가하면 형식 활성화(Type-Activated) 방식으로 처리되어 매번 요청 시마다 인스턴스가 생성되고 DI에 통해서 생성자의 모든 의존성이 채워지게 됩니다. 형식으로 필터를 추가하는 방식은 그 내용적으로 Filters.Add(new TypeFilterAttribute(typeof(MyFilter))) 코드와 동일합니다.

필터 인터페이스를 어트리뷰트(Attributes) 형태로 구현하면 편리한 경우가 많습니다. 필터 어트리뷰트는 컨트롤러와 액션 메서드에 적용할 수 있습니다. 프레임워크에는 서브클래싱이나 사용자 지정에 사용할 수 있는 내장 어트리뷰트-기본 필터들이 기본적으로 포함되어 있습니다. 이를테면, 다음 필터는 ResultFilterAttribute를 상속받은 다음, OnResultExecuting 메서드를 재정의해서 응답에 헤더를 추가합니다.

using Microsoft.AspNetCore.Mvc.Filters;  
                                                
namespace FiltersSample.Filters 
{ 
    public class AddHeaderAttribute : ResultFilterAttribute 
    {
        private readonly string _name;
        private readonly string _value;

        public AddHeaderAttribute(string name, string value)
        {
            _name = name;
            _value = value;
        }  
        
        public override void OnResultExecuting(ResultExecutingContext context) 
        {
            context.HttpContext.Response.Headers.Add(
                _name, new string[] { _value });
            base.OnResultExecuting(context);
        }
    } 
}

위의 예제에서 볼 수 있는 것처럼 어트리뷰트를 사용하면 필터에 인자를 전달할 수 있습니다. 다음과 같이 컨트롤러나 액션 메서드에 이 어트리뷰트를 적용한 다음, 응답에 추가하고자 하는 HTTP 헤더의 이름과 값을 지정하면 됩니다:

[AddHeader("Author", "Steve Smith @ardalis")] 
public class SampleController : Controller 
{
    public IActionResult Index()
    {
        return Content("Examine the headers using developer tools.");     
    } 
}

이 Index 액션의 결과는 다음과 같으며, 그림의 우측 하단에서 지정한 응답 헤더를 확인할 수 있습니다.

일부 필터 인터페이스는 사용자 지정 구현 시, 기본 클래스로 사용할 수 있는 대응하는 어트리뷰트를 갖고 있습니다.

필터 어트리뷰트:

• ActionFilterAttribute
• ExceptionFilterAttribute
• ResultFilterAttribute
• FormatFilterAttribute
• ServiceFilterAttribute
• TypeFilterAttribute

중단하고 빠져나가기

필터 메서드에 제공되는 context 매개변수의 Result 속성을 설정하면 언제든지 필터 파이프라인을 중단하고 빠져나갈 수 있습니다. 예를 들어서, 다음 ShortCircuitingResourceFilter는 모든 액션 필터를 비롯한, 파이프라인 상 이후에 실행되는 모든 다른 필터들의 실행을 막습니다.

using System; 
using Microsoft.AspNetCore.Mvc; 
using Microsoft.AspNetCore.Mvc.Filters;  

namespace FiltersSample.Filters 
{     
    public class ShortCircuitingResourceFilterAttribute : Attribute,
            IResourceFilter     
    {
        public void OnResourceExecuting(ResourceExecutingContext context)
        { 
            context.Result = new ContentResult() 
            { 
                Content = "Resource unavailable - header should not be set" 
            }; 
        }

        public void OnResourceExecuted(ResourceExecutedContext context)
        {
        }     
    } 
}

다음 코드에는 SomeResource 액션 메서드에 ShortCircuitingResourceFilter 필터와 AddHeader 필터가 적용되어 있습니다. 그러나 ShortCircuitingResourceFilter가 먼저 실행되기 때문에 파이프라인의 나머지 단계들이 모두 중단되므로, SomeResource 액션을 대상으로는 AddHeader 필터가 실행되지 않습니다. 두 필터를 모두 액션 메서드 수준에 적용하더라도 결과는 마찬가지며, 그 이유는 ShortCircuitingResourceFilter가 먼저 실행되기 때문입니다 (실행 순서 절을 참고하십시오).

[AddHeader("Author", "Steve Smith @ardalis")] 
public class SampleController : Controller 
{ 
    [ShortCircuitingResourceFilter] 
    public IActionResult SomeResource()
    {
         return Content("Successful access to resource - header should be set.");     
    }

의존성 주입

일반적으로 어트리뷰트로 구현되고 컨트롤러 클래스나 액션 메서드에 직접 적용되는 필터는 생성자의 의존성을 의존성 주입(DI, Dependency Injection)에서 제공받을 수 없습니다. 어트리뷰트가 적용되는 시점에 생성자 매개변수를 전달받아야 하기 때문입니다. 이는 어트리뷰트 방식의 제약조건으로도 볼 수 있습니다.

그러나 필터가 DI를 통해서 제공받아야만 하는 의존성을 갖고 있는 경우를 대비해서, 이를 지원하는 몇 가지 접근 방식도 제공됩니다. 다음과 같은 어트리뷰트를 사용하면 의존성 주입이 필요한 필터를 클래스나 액션 메서드에 적용할 수 있습니다:

• ServiceFilterAttribute
• TypeFilterAttribute
• IFilterFactory (이 인터페이스는 사용자 지정 필터 어트리뷰트에서 직접 구현해야 합니다.)

먼저 TypeFilter는 필터의 인스턴스를 생성하고 DI의 서비스를 이용해서 의존성을 해결합니다. 반면 ServiceFilter는 DI를 이용해서 필터의 인스턴스 자체를 가져옵니다. 다음은 ServiceFilter의 사용법을 보여주는 예제입니다:

[ServiceFilter(typeof(AddHeaderFilterWithDi))] 
public IActionResult Index() 
{
    return View(); 
}

그러나 ConfigureServices에서 필터 형식을 등록하지 않고 ServiceFilter를 사용하면 다음과 같은 예외가 던져집니다:

System.InvalidOperationException: No service for type 
'FiltersSample.Filters.AddHeaderFilterWithDI' has been registered. 

이 예외를 피하려면 반드시 ConfigureServices에서 AddHeaderFilterWithDI 형식을 등록해야 합니다:

services.AddScoped<AddHeaderFilterWithDi>(); 

ServiceFilterAttribute는 IFilterFactory 인터페이스를 구현하고 있으며, 이 인터페이스는 IFilter 인스턴스를 생성하는 CreateInstance라는 단일 메서드를 노출합니다. ServiceFilterAttribute는 지정된 형식을 서비스 컨테이너(DI)로부터 로드하도록 IFilterFactory 인터페이스의 CreateInstance 메서드가 구현되어 있습니다.

TypeFilterAttribute도 ServiceFilterAttribute와 매우 비슷하지만 (그리고 역시 IFilterFactory를 구현하고 있지만), 전달된 형식에 대한 의존성을 직접 DI 컨테이너를 이용해서 해결하지 않습니다. 대신 Microsoft.Extensions.DependencyInjection.ObjectFactory를 이용해서 지정된 형식의 인스턴스를 생성합니다.

바로 이 차이점 때문에 TypeFilterAttribute를 이용해서 참조되는 형식들은 미리 컨테이너에 등록하지 않아도 무방합니다. (그러나 해당 형식 자체의 의존성은 여전히 컨테이너를 통해서 해결됩니다). 또한, TypeFilterAttribute는 선택적으로 해당 형식의 생성자의 인자를 전달 받을 수도 있습니다. 다음 예제는 TypeFilterAttribute를 이용해서 대상 형식에 인자들을 전달하는 방법을 보여줍니다:

[TypeFilter(typeof(AddHeaderAttribute),
    Arguments = new object[] { "Author", "Steve Smith (@ardalis)" })]
public IActionResult Hi(string name)
{
    return Content($"Hi {name}"); 
}

만약, 아무런 인자도 필요없지만 DI를 통해서 해결되어야 하는 생성자 의존성을 갖고 있는 간단한 필터가 필요한 경우에는, 클래스나 메서드에 TypeFilterAttribute를 상속받는 자체적으로 지정한 이름의 어트리뷰트를 적용할 수 있습니다 ([TypeFilter(typeof(FilterType))] 대신). 다음 필터는 이를 구현하는 방법을 보여줍니다:

public class SampleActionFilterAttribute : TypeFilterAttribute 
{
    public SampleActionFilterAttribute() : base(typeof(SampleActionFilterImpl))
    {
    }

    private class SampleActionFilterImpl : IActionFilter 
    {
        private readonly ILogger _logger;

        public SampleActionFilterImpl(ILoggerFactory loggerFactory)
        {
            _logger = loggerFactory.CreateLogger<SampleActionFilterAttribute>();
        }
        
        public void OnActionExecuting(ActionExecutingContext context)
        {
            _logger.LogInformation("Business action starting...");
            // perform some business logic work
        }
        
        public void OnActionExecuted(ActionExecutedContext context)
        {
            // perform some business logic work
            _logger.LogInformation("Business action completed.");
        }
    }
}

이 필터는 [TypeFilter]나 [ServiceFilter]를 사용하는 대신, [SampleActionFilter] 구문을 이용해서 클래스나 메서드에 적용할 수 있습니다.

마지막으로 IFilterFactory는 IFilter를 구현합니다. 따라서, IFilterFactory의 인스턴스는 필터 파이프라인 어디에서나 IFilter의 인스턴스로 사용이 가능합니다. 프레임워크는 필터 호출을 준비할 때, 먼저 필터를 IFilterFactory로 형변환할 수 있는지 시도해봅니다. 만약 이 형변환이 성공하면, 실행될 IFilter의 인스턴스를 생성하기 위해서 CreateInstance 메서드가 호출됩니다. 이런 방식은 매우 유연한 설계를 제공해주는데, 응용 프로그램이 시작될 때 필터 파이프라인을 명시적으로 정밀하게 설정할 필요가 없어지기 때문입니다.

필터를 구현할 수 있는 접근방식의 하나로, 자체적인 어트리뷰트 구현에서 IFilterFactory를 구현할 수도 있습니다:

public class AddHeaderWithFactoryAttribute : Attribute, IFilterFactory 
{
    // Implement IFilterFactory 
    public IFilterMetadata CreateInstance(IServiceProvider serviceProvider) 
    { 
        return new InternalAddHeaderFilter(); 
    }
    private class InternalAddHeaderFilter : IResultFilter
    {
        public void OnResultExecuting(ResultExecutingContext context)
        {
            context.HttpContext.Response.Headers.Add(
                "Internal", new string[] { "Header Added" });
        } 
            
        public void OnResultExecuted(ResultExecutedContext context)
        {
        }
    }
}

실행 순서

필터는 액션 메서드나 컨트롤러에 적용되거나 (어트리뷰트를 이용해서), 전역 필터 컬렉션에 추가될 수 있습니다. 일반적으로 이런 범위도 실행 순서를 결정하는 한 요인으로 작용합니다. 액션에 가장 가까운 필터의 실행이 가장 먼저 완료되기 때문에, 일반적으로 실행 순서를 명시적으로 지정하지 않고도 동작을 재지정할 수 있습니다. 이를 "러시안 인형" 중첩이라고도 부르는데, 마트료시카 인형처럼 범위가 증가될 때마다 이전 범위를 감싸기 때문입니다.

범위 외에 IOrderedFilter를 구현해서 필터의 실행 순서를 재정의 할 수도 있습니다. 이 인터페이스는 간단한 int Order 속성만 노출하는데, 필터는 이 속성의 숫자값을 기준으로 오름차순으로 실행됩니다. TypeFilterAttribute나 ServiceFilterAttribute를 비롯한 모든 내장 필터는 IOrderedFilter 인터페이스를 구현하고 있으며, 클래스나 메서드에 어트리뷰트를 적용할 때 필터의 순서를 지정할 수 있습니다. 기본적으로 모든 내장 필터들의 Order 속성은 0으로 설정되어 있으므로, 범위가 타이 브레이커(Tie-Breaker)로 사용되어 결정 요인으로 작용합니다 (Order 속성을 0 이외의 값으로 설정하지 않으면).

또한, Controller 기본 클래스를 상속받는 모든 컨트롤러는 OnActionExecuting 메서드와 OnActionExecuted 메서드를 포함합니다. 이 메서드들은 특정 액션을 대상으로 실행되는 필터들을 감싸며, 가장 먼저 실행되고 가장 마지막으로 실행됩니다. 모든 필터의 Order 속성이 설정되지 않았다고 가정할 경우, 범위에 기반한 실행 순서는 다음과 같습니다:

1. Controller 클래스의 OnActionExecuting 메서드
2. 전역 필터의 OnActionExecuting 메서드
3. 클래스 필터의 OnActionExecuting 메서드
4. 메서드 필터의 OnActionExecuting 메서드
5. 메서드 필터의 OnActionExecuted 메서드
6. 클래스 필터의 OnActionExecuted 메서드
7. 전역 필터의 OnActionExecuted 메서드
8. Controller 클래스의 OnActionExecuted 메서드

범위에 기반한 기본 실행 순서를 변경하려면, 클래스 수준 필터나 메서드 수준 필터의 Order 속성을 명시적으로 설정하면 됩니다. 예를 들어, 다음과 같이 메서드 수준 어트리뷰트에 Order=-1를 추가할 수 있습니다:

[MyFilter(Name = "Method Level Attribute", Order=-1)] 

이 경우, 0보다 작은 값을 지정했기 때문에 이 필터가 전역 필터나 클래스 수준 필터보다 (Order 속성을 설정하지 않았다고 가정할 경우) 먼저 실행됩니다.

새로운 실행 순서는 다음과 같습니다:

1. Controller 클래스의 OnActionExecuting 메서드
2. 메서드 필터의 OnActionExecuting 메서드
3. 전역 필터의 OnActionExecuting 메서드
4. 클래스 필터의 OnActionExecuting 메서드
5. 클래스 필터의 OnActionExecuted 메서드
6. 전역 필터의 OnActionExecuted 메서드
7. 메서드 필터의 OnActionExecuted 메서드
8. Controller 클래스의 OnActionExecuted 메서드