다음은 Middleware 의 내용을 번역했습니다.
번역이 많이 부족합니다. 참고로만 사용하셔요 ^^;
ASP.NET Core 미들웨어 기초
미들웨어란 무엇인가?
미들웨어란 Request와 Response 를 처리하기위해서 Pipeline 으로 조립된 소프트웨어다.
파이프라인에서 각 구성요소는 Request 를 다음 구성요소로 전달할지 여부를 결정하고, 파이프라인에서 다음 구성요소가 호출되기 이전, 이후에 특정 Action 을 수행하는 것이 가능하다.
Request delegate(요청 대리자, 위임자) 들은 Request Pipelie 을 구성하는데 사용된다.
Request delegate 들은 각 HTTP Request 를 처리한다.
Request delegate 는 IApplicationBuilder 인스턴스에서 Run, Map 과 Use 확장 메서드로 구성되며 Startup클래스의 Configure 메서드로 전달된다.
개별적인 Request delegate 는 anonymous(익명) 메서드 (in-line middleware 라 불리는) 로서 in-line 에서 지정하거나 재사용가능한 클래스내에서 정의하는 것이 가능하다.
이런 재사용가능한 클래스와 인라인 익명 메서드는 미들웨어 이거나 미들웨어 구성요소다.
Request pipeline 의 각 미들웨어 구성요소는 pipeline 내에서 다음 구성요소를 호출하거나 적절한 경우 연결(Chain)을 끊는다.
Migrating HTTP Modules to Middleware 에서는 ASP.NET Core 와 이전 버전에서의 Request Pipeline 의 차이점에 대해 설명하고 더 많은 Middleware 예제를 제공한다.
IApplicationBuilder를 사용하여 미들웨어 파이프 라인 만들기
ASP.NET Core Request Pipeline 은 Request Delegate 들의 순서로 구성되며 Diagram에서 보듯이 차례대로 호출된다. (검정색 화살표 방향으로 실행이 진행된다.):
각 Delegate 는 다음 Delegate 가 실행되기 전후에 작업을 수행하는 것이 가능하다.
Delegate 는 또한 다음 Delegate 로 Request 를 전달할지 결정하는 것이 가능하며 이것을 Request Pipeline 을 단락(Short-circuiting)시킨다 라고 부른다.
Short-Circuiting 은 불필요한 작업을 피할 수 있기 때문에 종종 바람직하다.
예를 들어, 정적파일 Middleware 는 정적파일을 작성하기위한 Request 를 반환하거나 Pipeline 의 나머지 작업을 Short-Circuiting 하는 것이 가능하다.
Exception-handling Delegate 는 Pipeline 의 초기에 호출될 필요가 있으며, 그 결과로 Pipeline 이후단계에서 Exception 을 Catch 하는 것이 가능하다.
가장 단순하고도 실행가능한 ASP.NET Core App은 모든 Request를 처리하는 단일 Request delegate 를 구성한다.
이 경우 실제 Request Pipeline 을 포함하지 않는다.
대신 모든 HTTP Request 에 대해 Response 로 단일 anonymous function 이 호출된다.
using Microsoft.AspNetCore.Builder;using Microsoft.AspNetCore.Hosting;using Microsoft.AspNetCore.Http;
public class Startup
{
public void Configure(IApplicationBuilder app)
{
app.Run(async context =>
{
await context.Response.WriteAsync("Hello, World!");
});
}
}
첫번째 app.Run Delegate 는 Pipeline 을 종료한다.
app.Use 을 사용하여 여러 Request Delegate 들을 연결하는 것이 가능하다.
pipeline 에서 next Parameter 는 다음 Delegate 를 나타낸다.(next Parameter 를 호출하지 않음으로써 Pipeline 을 Short-Circuit 가능하다는 점을 기억하라.)
이 예제처럼 다음 Delegate 전후에 Action 을 전형적으로 수행하는 것이 가능하다.
public class Startup
{
public void Configure(IApplicationBuilder app)
{
app.Use(async (context, next) =>
{
// Do work that doesn't write to the Response.
await next.Invoke();
// Do logging or other work that doesn't write to the Response.
});
app.Run(async context =>
{
await context.Response.WriteAsync("Hello from 2nd delegate.");
});
}
}
경고
Response 를 Client 에 전송한 후 next.Invoke 를 호출하지 말 것.
Response 가 시작된 이후에 HttpResponse 를 변경하면 exception 을 발생한다.
예를 들어 headers, status code등의 구성을 변경하는 작업은 exception을 발생한다.
next를 호출한 이후에 Response body 를 작성하라 :
protocol violation 의 원인이 될 수 있다. 예를 들어 content-length 보다 더 작성하는
body format 을 손상할 수도 있다. 예를 들어 CSS 파일에 HTML footer 를 작성하는
HttpResponse.HasStarted 는 Header 가 보내졌는지 그리고/혹은 body 가 작성되었는지 알 수 있는 유용한 Hint 다.
순서정하기
Configure method 에 추가된 Middleware 구성요소의 순서는 Request 에서 호출되는 순서를 정의하며,
Response 의 역순이다.
이 순서는 보안, 성능, 기능에 중요하다.
(아래 보이는) Configure mathod 는 다음 Middleware 구성요소를 추가하고 있다.
1. Exception/error handling
2. Static file server
3. 인증
4. MVC
public void Configure(IApplicationBuilder app)
{
app.UseExceptionHandler("/Home/Error"); // Call first to catch exceptions
// thrown in the following middleware.
app.UseStaticFiles(); // Return static files and end pipeline.
app.UseIdentity(); // Authenticate before you access
// secure resources.
app.UseMvcWithDefaultRoute(); // Add MVC to the request pipeline.
}
위 코드에서 UseExceptionHandler 는 Pipeline 에 첫번째로 추가된 Middleware Component 로 이후 호출에서 발생하는 모든 exception 을 catch한다.
호출된 Static file Middleware Pipeline 의 초기에 호출되어 나머지 component를 거치지 않고도 Request 와 short-circuit 를 처리하는 것이 가능하다.
Static file Middleware 는 권한 Check 기능을 제공하지 않는다.
wwwroot 아래에 있는 파일들을 포함하여 Static file Middleware 에 의해 제공하는 모든 파일은 공개적으로 사용가능하다.
static file 의 보안 방법에 대해서는 Working with static files 를 참고하라.
만약 Request 가 static file middleware 에 의해 처리되지 않으면 인증을 수행하는 Identity middleware(app.UseIdentity) 로 전달된다.
Identity 는 인증되지 않는 request 를 short-circuit 하지 않는다.
Identity 가 request를 인증한다고 하더라고 권한부여(그리고 거부) 은 MVC 가 특정 Controller 와 Action 를 선택한 이후에만 나타난다.
다음 예제는 static file 이 Response 압축 Middleware 이전에 static file middleware 에 의해 처리되도록하는 middleware 의 순서를 정하는 모습을 보여준다.
이 middleware의 순서에서 보면 static file 은 압축되지 않는다.
UseMvcWithDefaultRoute 의 MVC response 는 압축이 가능하다.
public void Configure(IApplicationBuilder app)
{
app.UseStaticFiles(); // Static files not compressed
// by middleware.
app.UseResponseCompression();
app.UseMvcWithDefaultRoute();
}
Run, Map, 그리고 Use
Run, Map, 그리고 Use를 사용하여 HTTP pipeline 을 구성한다.
Run method 는 pipeline을 short-circuit 한다.(즉, next request delegate 를 호출하지 않는다.)
Run 은 규칙이며, 일부 middleware component 는 pipeline 의 마지막에 실행하는 Run[Middleware] method 를 노출할 수도 있다.
Map* extention 은 pipeline 을 분기(branch)하기 위한 규칙으로 사용한다.
Map 은 주어진 request 경로와 일치하는 것을 기반으로 request pipeline 을 분기한다.
만약 request 경로가 주어진 경로로 시작한다면 분기는 실행된다.
public class Startup
{
private static void HandleMapTest1(IApplicationBuilder app)
{
app.Run(async context =>
{
await context.Response.WriteAsync("Map Test 1");
});
}
private static void HandleMapTest2(IApplicationBuilder app)
{
app.Run(async context =>
{
await context.Response.WriteAsync("Map Test 2");
});
}
public void Configure(IApplicationBuilder app)
{
app.Map("/map1", HandleMapTest1);
app.Map("/map2", HandleMapTest2);
app.Run(async context =>
{
await context.Response.WriteAsync("Hello from non-Map delegate. <p>");
});
}
}
다음 표는 이전코드를 사용한 http://localhost:1234 의 Request 와 Response 를 보여준다.
|
Request |
Response |
|
localhost:1234 |
Hello from non-Map delegate. |
|
localhost:1234/map1 |
Map Test 1 |
|
localhost:1234/map2 |
Map Test 2 |
|
localhost:1234/map3 |
Hello from non-Map delegate. |
Map 이 사용되면 일치하는 경로 segment 는 HttpRequest.Path 에서 제거되고 각 request 의 HttpRequest.PathBase 에 추가된다.
MapWhen 은 주어진 predicate 의 결과를 기반으로 result pipeline 을 분기한다.
Func<HttpContext, bool> type 의 모든 predicate 는 request를 Pipeline 의 새로운 분기에 map 하는데 사용하는 것이 가능하다.
다음 예제에서 predicate 는 Query String 에 branch 가 variable 로 포함되어 있는지 검색하기 위해서 사용된다.
public class Startup{ private static void HandleBranch(IApplicationBuilder app) { app.Run(async context => { var branchVer = context.Request.Query["branch"]; await context.Response.WriteAsync($"Branch used = {branchVer}"); }); } public void Configure(IApplicationBuilder app) { app.MapWhen(context => context.Request.Query.ContainsKey("branch"), HandleBranch); app.Run(async context => { await context.Response.WriteAsync("Hello from non-Map delegate. <p>"); }); }}
다음 표는 이전코드를 사용한 http://localhost:1234 의 Request 와 Response 를 보여준다.
|
Request |
Response |
|
localhost:1234 |
Hello from non-Map delegate. |
|
localhost:1234/?branch=master |
Branch used = master |
다음 예처럼 Map 은 nesting 을 지원한다.:
app.Map("/level1", level1App => { level1App.Map("/level2a", level2AApp => { // "/level1/level2a" //... }); level1App.Map("/level2b", level2BApp => { // "/level1/level2b" //... }); });
다음 예제 처럼 Map 은 한번에 다양한 segments 또한 일치(match)시키는데 사용하는 것도 가능하다.:
app.Map("/level1/level2", HandleMultiSeg);
내장(Built-in) Middleware
ASP.NET Core 에는 다음 미들웨어 구성 요소들이 들어 있다.
Middleware 작성하기
Middleware 는 일반적으로 class 내에서 encapsulate 되어있고 extention method 로 노출된다.
다음은 Query string 으로 부터 현재 request 의 문화권을 설정하는 Middleware 로 살펴보기 바란다.
public class Startup
{
public void Configure(IApplicationBuilder app)
{
app.Use((context, next) =>
{
var cultureQuery = context.Request.Query["culture"];
if (!string.IsNullOrWhiteSpace(cultureQuery))
{
var culture = new CultureInfo(cultureQuery);
CultureInfo.CurrentCulture = culture;
CultureInfo.CurrentUICulture = culture;
}
// Call the next delegate/middleware in the pipeline
return next();
});
app.Run(async (context) =>
{
await context.Response.WriteAsync(
$"Hello {CultureInfo.CurrentCulture.DisplayName}");
});
}
}
참고 위의 Sample Code 는 middleware component 를 생성하것을 시연하는데 사용된다.
ASP.NET Core 의 내장 localization 에 관해서는 Globalization 과 Localization 을 참고하라.
예를 들어, http://localhost:7997/?culture=no 와 같이 culture(문화권 코드)를 전달하여 middleware 를 테스트하는 것이 가능하다.
다음 code 는 class 에 middleware delegate 가 Class 로 이동한다.
using Microsoft.AspNetCore.Http;
using System.Globalization;
using System.Threading.Tasks;
namespace Culture
{
public class RequestCultureMiddleware
{
private readonly RequestDelegate _next;
public RequestCultureMiddleware(RequestDelegate next)
{
_next = next;
}
public Task Invoke(HttpContext context)
{
var cultureQuery = context.Request.Query["culture"];
if (!string.IsNullOrWhiteSpace(cultureQuery))
{
var culture = new CultureInfo(cultureQuery);
CultureInfo.CurrentCulture = culture;
CultureInfo.CurrentUICulture = culture;
}
// Call the next delegate/middleware in the pipeline
return this._next(context);
}
}
}
다음 extension method 는 IApplicationBuilder 를 통해서 middleware 를 노출한다.:
using Microsoft.AspNetCore.Builder;
namespace Culture
{
public static class RequestCultureMiddlewareExtensions
{
public static IApplicationBuilder UseRequestCulture(
this IApplicationBuilder builder)
{
return builder.UseMiddleware<RequestCultureMiddleware>();
}
}
}
The following code calls the middleware from Configure:
public class Startup
{
public void Configure(IApplicationBuilder app)
{
app.UseRequestCulture();
app.Run(async (context) =>
{
await context.Response.WriteAsync(
$"Hello {CultureInfo.CurrentCulture.DisplayName}");
});
}
}
Middleware 는 Constructor 에 의존성(dependencies)를 노출함으로써 명시적 의존성 원칙(Explicit Dependencies Principle) 을 따라야한다.
Middleware 는 Application lifetime 당 한번 생성된다.
Request 내에서 Middleware와 함께 service 를 공유할 필요가 있다면 아래 Pre-request dependency 를 참고하라.
Middleware component 는 constructor parameter 를 사용하여 dependecy injection으로 부터 자신의 dependency 를 해결하는 것이 가능하다.
UseMiddleware<T> 는 추가 parameter 를 직접 허용하는 것도 가능하다.
Per-request dependencies
middleware 가 request 당 생성되는 것이 아닌 app startup 에 생성되었기 때문에 각 request 가 진행되는 동안 middleware constructor 가 사용하는 scoped lifetime service 는 다른 dependency-injected type 과 공유되지 않는다.
만약 scoped service 를 여러분이 생성한 middleware 와 다른 Type 간에 공유해야만 한다면
이 service 들을 Invoke method 의 Signature 에 추가하라.
Invoke method 는 dependency injection 에 의해 채워지는 추가 parameter 를 수락하는 것이 가능하다.
public class MyMiddleware
{
private readonly RequestDelegate _next;
public MyMiddleware(RequestDelegate next)
{
_next = next;
}
public async Task Invoke(HttpContext httpContext, IMyScopedService svc)
{
svc.MyProperty = 1000;
await _next(httpContext);
}
}
Resources
· Sample code used in this doc
· Migrating HTTP Modules to Middleware
· Application Startup
· Request Features
행복한 고수되십시요.
woojja ))*
\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
