ASP.NET Core 끝점. IEndpointRouteBuilder 확장 메서드를 사용하여 끝점 지원 미들웨어 추가

TL;DR

확장 방법(예: IEndpointConventionBuilder Map{FeatureToMap}(this IEndpointRouteBuilder endpoints )을 사용하여 특정 엔드포인트에 미들웨어를 추가할 수 있습니다.

미들웨어

미들웨어는 HTTP 파이프라인의 기본 빌딩 블록을 형성합니다. 교차 절단 문제를 구현하고 재사용 가능한 코드 조각을 ASP.NET 파이프라인에 짜 넣는 것은 정말 좋은 개념입니다. 미들웨어는 애플리케이션 수준의 기능을 제공합니다. 예를 들어 라우팅, 쿠키, 세션, CORS, 인증, HTTPS 리디렉션, 캐싱, 응답 압축, 예외 처리와 같은 기능을 구현하려면 미들웨어가 필요할 수 있습니다. 대부분의 경우 프레임워크에서 제공하는 옵션out-of-the-box이 있습니다.

ASP.NET Core 파이프라인을 확장하기 위해 Startup.cs에 주입된 IApplicationBuilder을 사용합니다.

또한 ASP.NET Core 3.0부터는 HttpContext.GetEndpoint을 사용하여 선택한 엔드포인트/메타데이터를 검색할 수 있습니다. 예를 들면 다음과 같습니다.

// Before routing runs, endpoint is always null here
app.Use(next => context =>
{
    Console.WriteLine($"Endpoint: {context.GetEndpoint()?.DisplayName ?? "(null)"}");
    return next(context);
});

app.UseRouting();

// After routing runs, endpoint will be non-null if routing found a match
app.Use(next => context =>
{
    Console.WriteLine($"Endpoint: {context.GetEndpoint()?.DisplayName ?? "(null)"}");
    return next(context);
});

미들웨어는 간단한 인라인 메서드 또는 복잡하고 재사용 가능한 클래스로 존재할 수 있습니다. RequestDelegate 표기/양식이 마음에 들지 않는 경우. IApplicationBuilder.UseMiddleware 확장 메서드를 사용하여 미들웨어를 클래스로 추가하고 매개 변수에서 끝점에 액세스할 수 있습니다( HttpContext ).

// Startup.cs
app.UseMiddleware<MyAwesomeMiddleware>();
// ...
// MyAwesomeMiddleware.cs
public async Task InvokeAsync(HttpContext httpContext)
{
    var endpoint = httpContext.GetEndpoint();
}

더 세밀하고 아마도 더 강력한 것이 필요한 경우 Endpoint 개념을 사용할 수 있습니다.

라우팅 및 엔드포인트

라우팅은 들어오는 HTTP 요청을 일치시키고 해당 요청을 앱의 실행 가능한 끝점으로 디스패치합니다. IApplicationBuilder.UseEndpoints를 사용하여 선택한 경로를 기반으로 파이프라인 논리를 정의할 수 있습니다. 많은 ASP.NET Core 기능/측면은 라우팅 개념을 염두에 두고 구현됩니다. 예를 들어 IEndpointRouteBuilder.MapControllers 또는 IEndpointRouteBuilder.MapGrpcService 또는 이 확장 기능을 기반으로 고유한 프레임워크를 구축할 수 있습니다.

app.UseEndpoints(endpoints =>
{
    // Configure another endpoint, with authorization.
    endpoints.MapGet("/", async context =>
    {
        await context.Response.WriteAsync($"Hello from {context.GetEndpoint()}!");
    }).RequireAuthorization().WithMetadata(new AuditPolicyAttribute(needsAudit: true));
});

보시다시피 Endpoint에는 파이프라인 실행 중에 입력 및 관리되는 다양한 데이터를 보유하는 EndpointMetadataCollection가 포함되어 있습니다.

/// <summary>
/// Represents a logical endpoint in an application.
/// </summary>
public class Endpoint
{
    public Endpoint(
        RequestDelegate? requestDelegate,
        EndpointMetadataCollection? metadata,
        string? displayName)
    {
        RequestDelegate = requestDelegate;
        Metadata = metadata ?? EndpointMetadataCollection.Empty;
        DisplayName = displayName;
    }
    /// <summary>
    /// Gets the informational display name of this endpoint.
    /// </summary>
    public string? DisplayName { get; }
    /// <summary>
    /// Gets the collection of metadata associated with this endpoint.
    /// </summary>
    public EndpointMetadataCollection Metadata { get; }
    /// <summary>
    /// Gets the delegate used to process requests for the endpoint.
    /// </summary>
    public RequestDelegate? RequestDelegate { get; }
}

큰 그림:

실제 예

최근에 나는 IConfigurationRoot.GetDebugView을 우연히 발견했습니다. 기본적으로 구성 값을 덤프하고 구성 설정이 해결되는 방식에 대한 이유를 알 수 있습니다. 개인적으로 저는 이것이 구성 요소 구성을 읽는 데 정말 유용하고 생산적인 방법이라고 생각합니다. Startup.cs의 일부로 UseEndpoints 메서드에 다음 코드를 추가하여 특수 엔드포인트를 활성화하여 구성을 확인할 수 있습니다.

app.UseEndpoints(endpoints =>
{
    endpoints.MapGet("/config", async context =>
    {
        var config = (Configuration as IConfigurationRoot).GetDebugView();
        await context.Response.WriteAsync(config);
    });
});

다음은 출력 예입니다.

NikiforovAll.ConfigurationDebugViewEndpoint

위의 예는 모두 작동하지만 기회를 잡고 이 기능을 NuGet 패키지 - https://github.com/NikiforovAll/ConfigurationDebugViewEndpoint 에 래핑했습니다.

이것은 코드 베이스를 구성하고 기술을 적용하여 Startup.cs를 더 읽기 쉽고 구성 가능하게 만드는 방법의 예입니다. 과정을 안내해 드립니다.

우리의 목표는 끝점/config을 연결할 수 있는 확장 메서드를 갖는 것입니다. 이 같은:

app.UseEndpoints(endpoints =>
{
    endpoints.MapConfigurationDebugView("/config", (options) => options.AllowDevelopmentOnly = true);
});

ConfigurationDebugViewMiddleware부터 시작하겠습니다. IConfiguration 디버그 보기 출력을 Response 에 쓰려고 합니다.

public class ConfigurationDebugViewMiddleware
{
    public ConfigurationDebugViewMiddleware(RequestDelegate next) { }

    public async Task InvokeAsync(HttpContext httpContext)
    {
        var configuration = httpContext.RequestServices.GetService<IConfiguration>();
        var config = (configuration as IConfigurationRoot).GetDebugView();
        await httpContext.Response.WriteAsync(config);
    }
}

비결은 EndpointRouteBuilderExtensions.cs를 생성하고 플러그ConfigurationDebugViewMiddleware를 허용하는 작은 확장 메서드를 작성하는 것입니다.

일반적으로 다음 접근 방식/서명을 따릅니다.

IEndpointConventionBuilder Map{FeatureToMap}(this IEndpointRouteBuilder endpoints, string pattern = <defaultPattern>, Action<{FeatureOptions}> configure);

실제 구현은 IApplicationBuilder 파이프라인에 사용하는 것과 동일한 추상화(Startup.cs)를 사용하여 하위 파이프라인을 생성할 수 있다는 사실을 기반으로 합니다. IEndpointRouteBuilder.CreateApplicationBuilder은 사용 및 구성할 수 있는 IApplicationBuilder를 생성합니다.

예를 들어 다음은 SOAP 요청을 처리하는 가상 파이프라인의 정의입니다.

var pipeline = endpoints.CreateApplicationBuilder()
    .UseMiddleware<LoggingMiddleware>()
    .UseMiddleware<CachingMiddleware>()
    .UseMiddleware<SOAPEndpointMiddleware>()
    .Build();

return endpoints.Map(pattern, pipeline)

구현 완료:

/// <summary>
/// Provides extension methods for <see cref="IEndpointRouteBuilder"/> to add routes.
/// </summary>
public static class EndpointRouteBuilderExtensions
{
    /// <summary>
    /// Adds a configuration endpoint to the <see cref="IEndpointRouteBuilder"/> with the specified template.
    /// </summary>
    /// <param name="endpoints">The <see cref="IEndpointRouteBuilder"/> to add endpoint to.</param>
    /// <param name="pattern">The URL pattern of the endpoint.</param>
    /// <param name="optionsDelegate"></param>
    /// <returns>A route for the endpoint.</returns>
    public static IEndpointConventionBuilder? MapConfigurationDebugView(
        this IEndpointRouteBuilder endpoints,
        string pattern = "config",
        Action<ConfigurationDebugViewOptions>? optionsDelegate = default)
    {
        if (endpoints == null)
        {
            throw new ArgumentNullException(nameof(endpoints));
        }

        var options = new ConfigurationDebugViewOptions();
        optionsDelegate?.Invoke(options);

        return MapConfigurationDebugViewCore(endpoints, pattern, options);
    }

    private static IEndpointConventionBuilder? MapConfigurationDebugViewCore(IEndpointRouteBuilder endpoints, string pattern, ConfigurationDebugViewOptions options)
    {
        var environment = endpoints.ServiceProvider.GetRequiredService<IHostEnvironment>();
        var builder = endpoints.CreateApplicationBuilder();

        if (options.AllowDevelopmentOnly && !environment.IsDevelopment())
        {
            return null;
        }
        var pipeline = builder
            .UseMiddleware<ConfigurationDebugViewMiddleware>()
            .Build();

        return endpoints.Map(pattern, pipeline);
    }
}

요약

코드베이스를 구성하는 간단하지만 유용한 기술을 공유했습니다. 이를 통해 엔드포인트 관련 코드를 훌륭하고 깔끔하게 유지할 수 있으며 개발자는 규칙에 따라 확장을 쉽게 찾을 수 있습니다. 구성할 다른 모범 사례가 있습니까Startup.cs? 의견에 자유롭게 나열하십시오. 여러분의 의견을 듣고 싶습니다!

configuration-debug-view NuGet 패키지를 사용해 볼 수 있습니다. https://github.com/NikiforovAll/ConfigurationDebugViewEndpoint .

원본 블로그 게시물: https://nikiforovall.github.io/dotnet/aspnetcore/2021/03/23/endpoint-route-builder-extension-pattern.html

참조

ASP.NET Core Middleware

Routing in ASP.NET Core