ASP.NET Core 웹 서버 구현이 Kestrel 소개Introduction to Kestrel web server implementation in ASP.NET Core

Tom Dykstra, Chris Ross, 및 Stephen HalterBy Tom Dykstra, Chris Ross, and Stephen Halter

Kestrel는 플랫폼 간 ASP.NET Core 웹 서버로 기반 libuv, 비동기 I/O 플랫폼 간 라이브러리입니다.Kestrel is a cross-platform web server for ASP.NET Core based on libuv, a cross-platform asynchronous I/O library. Kestrel은 ASP.NET Core 프로젝트 템플릿에서 기본적으로 포함 되는 웹 서버입니다.Kestrel is the web server that is included by default in ASP.NET Core project templates.

Kestrel은 다음과 같은 기능을 지원합니다.Kestrel supports the following features:

  • HTTPSHTTPS
  • 사용 하도록 설정 하는 데 사용 되는 불투명 업그레이드 WebsocketOpaque upgrade used to enable WebSockets
  • 고성능 Nginx 뒤에 대 한 Unix 소켓Unix sockets for high performance behind Nginx

Kestrel 모든 플랫폼 및 버전을 지 원하는.NET Core에서 지원 됩니다.Kestrel is supported on all platforms and versions that .NET Core supports.

Kestrel 역방향 프록시를 사용 하는 경우When to use Kestrel with a reverse proxy

Kestrel을 단독으로 사용하거나 IIS, Nginx 또는 Apache 같은 역방향 프록시 서버와 함께 사용할 수 있습니다.You can use Kestrel by itself or with a reverse proxy server, such as IIS, Nginx, or Apache. 역방향 프록시 서버는 인터넷에서 HTTP 요청을 수신하고 몇몇 사전 처리 후에 Kestrel에 전달합니다.A reverse proxy server receives HTTP requests from the Internet and forwards them to Kestrel after some preliminary handling.

Kestrel은 역방향 프록시 서버 없이 직접 인터넷과 통신합니다.

Kestrel은 IIS, Nginx 또는 Apache 같은 역방향 프록시 서버를 통해 간접적으로 인터넷과 통신합니다.

Kestrel이 내부 네트워크에만 노출되는 경우 역방향 프록시 서버를 사용하거나 사용하지 않는 구성을 사용할 수도 있습니다.Either configuration — with or without a reverse proxy server — can also be used if Kestrel is exposed only to an internal network.

역방향 프록시를 필요로 하는 시나리오에는 동일한 IP 및 단일 서버에서 실행 되는 포트를 공유 하는 여러 응용 프로그램이 있는 경우입니다.A scenario that requires a reverse proxy is when you have multiple applications that share the same IP and port running on a single server. 하지 않는 함께 작동 Kestrel 직접 Kestrel 동일한 IP 및 여러 프로세스 간에 포트 공유를 지원 하지 않습니다.That doesn't work with Kestrel directly because Kestrel doesn't support sharing the same IP and port between multiple processes. 포트에서 수신 하도록 Kestrel를 구성할 때 호스트 헤더에 관계 없이 해당 포트에 대 한 모든 트래픽을 처리 합니다.When you configure Kestrel to listen on a port, it handles all traffic for that port regardless of host header. 포트를 공유할 수 있는 역방향 프록시 해야 후 Kestrel에 고유 IP 및 포트에 전달 됩니다.A reverse proxy that can share ports must then forward to Kestrel on a unique IP and port.

역방향 프록시 서버는 필요 하지 않습니다, 경우에 하나를 사용 하 여 다른 이유로 좋은 적합할 수 있습니다.Even if a reverse proxy server isn't required, using one might be a good choice for other reasons:

  • 프로그램 노출 된 노출 영역을 제한할 수 있습니다.It can limit your exposed surface area.
  • 선택적 추가 계층을 구성 및 철저 한 방어를 제공합니다.It provides an optional additional layer of configuration and defense.
  • 기존 인프라와 잘 통합 될 수 있습니다.It might integrate better with existing infrastructure.
  • 부하 분산 및 SSL 설정을 간소화합니다.It simplifies load balancing and SSL set-up. 역방향 프록시 서버에만 필요한 SSL 인증서를 하 고 해당 서버가 일반 HTTP를 사용 하 여 내부 네트워크에 응용 프로그램 서버와 통신할 수 있습니다.Only your reverse proxy server requires an SSL certificate, and that server can communicate with your application servers on the internal network using plain HTTP.

Kestrel ASP.NET Core 응용 프로그램에서 사용 하는 방법How to use Kestrel in ASP.NET Core apps

Microsoft.AspNetCore.Server.Kestrel 패키지에 포함 되어는 Microsoft.AspNetCore.All metapackage합니다.The Microsoft.AspNetCore.Server.Kestrel package is included in the Microsoft.AspNetCore.All metapackage.

ASP.NET Core 프로젝트 템플릿은 기본적으로 Kestrel를 사용합니다.ASP.NET Core project templates use Kestrel by default. Program.cs, 템플릿 코드 호출 CreateDefaultBuilder, 되는 호출 UseKestrel 내부적입니다.In Program.cs, the template code calls CreateDefaultBuilder, which calls UseKestrel behind the scenes.

public static void Main(string[] args)
{
    BuildWebHost(args).Run();
}

public static IWebHost BuildWebHost(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .UseStartup<Startup>()
        .UseKestrel(options =>
        {
            options.Listen(IPAddress.Loopback, 5000);
            options.Listen(IPAddress.Loopback, 5001, listenOptions =>
            {
                listenOptions.UseHttps("testCert.pfx", "testPassword");
            });
        })
        .Build();

Kestrel 옵션을 구성 해야 할 경우 호출 UseKestrelProgram.cs 다음 예제와 같이:If you need to configure Kestrel options, call UseKestrel in Program.cs as shown in the following example:

public static void Main(string[] args)
{
    BuildWebHost(args).Run();
}

public static IWebHost BuildWebHost(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .UseStartup<Startup>()
        .UseKestrel(options =>
        {
            options.Listen(IPAddress.Loopback, 5000);
            options.Listen(IPAddress.Loopback, 5001, listenOptions =>
            {
                listenOptions.UseHttps("testCert.pfx", "testPassword");
            });
        })
        .Build();

Kestrel 옵션Kestrel options

Kestrel 웹 서버에는 인터넷 연결 배포에 특히 유용한 제약 조건 구성 옵션이 있습니다.The Kestrel web server has constraint configuration options that are especially useful in Internet-facing deployments. 다음은 몇 제한을 설정할 수 있습니다.Here are some of the limits you can set:

  • 최대 클라이언트 연결Maximum client connections
  • 최대 요청 본문 크기Maximum request body size
  • 최소 요청 본문 데이터 속도Minimum request body data rate

이러한 제약 조건 및의 다른 설정의 Limits 의 속성은 KestrelServerOptions 클래스.You set these constraints and others in the Limits property of the KestrelServerOptions class. Limits 의 인스턴스를 보유 하는 속성은 KestrelServerLimits 클래스입니다.The Limits property holds an instance of the KestrelServerLimits class.

최대 클라이언트 연결Maximum client connections

다음 코드를 사용 하는 전체 응용 프로그램에 대 한 열려 있는 동시 TCP 연결의 최대 수를 설정할 수 있습니다.The maximum number of concurrent open TCP connections can be set for the entire application with the following code:

.UseKestrel(options =>
{
    options.Limits.MaxConcurrentConnections = 100;
    options.Limits.MaxConcurrentUpgradedConnections = 100;
    options.Limits.MaxRequestBodySize = 10 * 1024;
    options.Limits.MinRequestBodyDataRate =
        new MinDataRate(bytesPerSecond: 100, gracePeriod: TimeSpan.FromSeconds(10));
    options.Limits.MinResponseDataRate =
        new MinDataRate(bytesPerSecond: 100, gracePeriod: TimeSpan.FromSeconds(10));
    options.Listen(IPAddress.Loopback, 5000);
    options.Listen(IPAddress.Loopback, 5001, listenOptions =>
    {
        listenOptions.UseHttps("testCert.pfx", "testPassword");
    });
})

다른 프로토콜 (예를 들어 Websocket 요청)에서 HTTP 또는 HTTPS에서 업그레이드 된 연결에 대 한 별도 제한이 있습니다.There's a separate limit for connections that have been upgraded from HTTP or HTTPS to another protocol (for example, on a WebSockets request). 에 따라 계산 되지 않습니다 연결이 업그레이드 되는 MaxConcurrentConnections 제한 합니다.After a connection is upgraded, it isn't counted against the MaxConcurrentConnections limit.

연결의 최대 수는 기본적으로 무제한 (null).The maximum number of connections is unlimited (null) by default.

최대 요청 본문 크기Maximum request body size

기본 최대 요청 본문 크기는 약 28.6 m B 인 30,000,000 바이트입니다.The default maximum request body size is 30,000,000 bytes, which is approximately 28.6MB.

사용 하는 ASP.NET Core MVC 응용 프로그램에 대 한도 무시 하는 권장된 방법은 RequestSizeLimit 작업 메서드에 특성:The recommended way to override the limit in an ASP.NET Core MVC app is to use the RequestSizeLimit attribute on an action method:

[RequestSizeLimit(100000000)]
public IActionResult MyActionMethod()

전체 응용 프로그램을 모든 요청에 대 한 제약 조건을 구성 하는 방법을 보여 주는 예제는 다음과 같습니다.Here's an example that shows how to configure the constraint for the entire application, every request:

.UseKestrel(options =>
{
    options.Limits.MaxConcurrentConnections = 100;
    options.Limits.MaxConcurrentUpgradedConnections = 100;
    options.Limits.MaxRequestBodySize = 10 * 1024;
    options.Limits.MinRequestBodyDataRate =
        new MinDataRate(bytesPerSecond: 100, gracePeriod: TimeSpan.FromSeconds(10));
    options.Limits.MinResponseDataRate =
        new MinDataRate(bytesPerSecond: 100, gracePeriod: TimeSpan.FromSeconds(10));
    options.Listen(IPAddress.Loopback, 5000);
    options.Listen(IPAddress.Loopback, 5001, listenOptions =>
    {
        listenOptions.UseHttps("testCert.pfx", "testPassword");
    });
})

미들웨어의 특정 요청에 설정을 재정의할 수 있습니다.You can override the setting on a specific request in middleware:

app.Run(async (context) =>
{
    context.Features.Get<IHttpMaxRequestBodySizeFeature>()
        .MaxRequestBodySize = 10 * 1024;
    context.Features.Get<IHttpMinRequestBodyDataRateFeature>()
        .MinDataRate = new MinDataRate(bytesPerSecond: 100, gracePeriod: TimeSpan.FromSeconds(10));
    context.Features.Get<IHttpMinResponseDataRateFeature>()
        .MinDataRate = new MinDataRate(bytesPerSecond: 100, gracePeriod: TimeSpan.FromSeconds(10));

응용 프로그램 요청 읽기 시작 된 후 요청에 대 한 제한을 구성 하려고 하면 예외가 throw 됩니다.An exception is thrown if you try to configure the limit on a request after the application has started reading the request. IsReadOnly 를 알려 주는 속성 경우는 MaxRequestBodySize 제한을 구성 하려면에 너무 늦었습니다 의미 속성은 읽기 전용 상태에서입니다.There's an IsReadOnly property that tells you if the MaxRequestBodySize property is in read-only state, meaning it's too late to configure the limit.

최소 요청 본문 데이터 속도Minimum request body data rate

Kestrel은 데이터 제공 되는 경우는 지정 된 비율에 바이트 수/초 1 초 마다 확인 합니다.Kestrel checks every second if data is coming in at the specified rate in bytes/second. 속도가 최소 아래로 떨어지면, 연결 시간이 초과 됩니다. 유예 기간은 Kestrel 최소;까지 해당 전송 속도 높이기 위해 클라이언트에 제공 하는 시간 이 시간 동안 속도 확인 하지 않습니다.If the rate drops below the minimum, the connection is timed out. The grace period is the amount of time that Kestrel gives the client to increase its send rate up to the minimum; the rate is not checked during that time. 유예 기간에 TCP 느린 시작으로 인해 느린 속도로 데이터 보내는 처음 연결을 삭제 하지 않도록 하는 데 도움이 됩니다.The grace period helps avoid dropping connections that are initially sending data at a slow rate due to TCP slow-start.

기본 최소 속도 240 바이트/초가 고 5 초의 유예 기간입니다.The default minimum rate is 240 bytes/second, with a 5 second grace period.

최소 속도 응답에도 적용 됩니다.A minimum rate also applies to the response. 요청 제한 및 응답 용량 한도 설정 하는 코드는 것을 제외 하 고 동일 RequestBody 또는 Response 속성 및 인터페이스 이름에 있습니다.The code to set the request limit and the response limit is the same except for having RequestBody or Response in the property and interface names.

여기에 최소 데이터 속도 구성 하는 방법을 보여 주는 예제는 Program.cs:Here's an example that shows how to configure the minimum data rates in Program.cs:

.UseKestrel(options =>
{
    options.Limits.MaxConcurrentConnections = 100;
    options.Limits.MaxConcurrentUpgradedConnections = 100;
    options.Limits.MaxRequestBodySize = 10 * 1024;
    options.Limits.MinRequestBodyDataRate =
        new MinDataRate(bytesPerSecond: 100, gracePeriod: TimeSpan.FromSeconds(10));
    options.Limits.MinResponseDataRate =
        new MinDataRate(bytesPerSecond: 100, gracePeriod: TimeSpan.FromSeconds(10));
    options.Listen(IPAddress.Loopback, 5000);
    options.Listen(IPAddress.Loopback, 5001, listenOptions =>
    {
        listenOptions.UseHttps("testCert.pfx", "testPassword");
    });
})

미들웨어에서 요청에 따라 속도 구성할 수 있습니다.You can configure the rates per request in middleware:

app.Run(async (context) =>
{
    context.Features.Get<IHttpMaxRequestBodySizeFeature>()
        .MaxRequestBodySize = 10 * 1024;
    context.Features.Get<IHttpMinRequestBodyDataRateFeature>()
        .MinDataRate = new MinDataRate(bytesPerSecond: 100, gracePeriod: TimeSpan.FromSeconds(10));
    context.Features.Get<IHttpMinResponseDataRateFeature>()
        .MinDataRate = new MinDataRate(bytesPerSecond: 100, gracePeriod: TimeSpan.FromSeconds(10));

다른 Kestrel 옵션에 대 한 내용은 다음 클래스를 참조 하십시오.For information about other Kestrel options, see the following classes:

끝점 구성Endpoint configuration

기본적으로 ASP.NET Core을 바인딩합니다 http://localhost:5000합니다.By default ASP.NET Core binds to http://localhost:5000. URL 접두사 및 호출 하 여에서 수신 하도록 Kestrel에 대 한 포트 구성 Listen 또는 ListenUnixSocket 에 대 한 메서드 KestrelServerOptions합니다.You configure URL prefixes and ports for Kestrel to listen on by calling Listen or ListenUnixSocket methods on KestrelServerOptions. (UseUrls, urls 명령줄 인수 및 ASPNETCORE_URLS 환경 변수 에서도 작동 하지만 제한이 명시 된 이 문서의 뒷부분에 나오는.)(UseUrls, the urls command-line argument, and the ASPNETCORE_URLS environment variable also work but have the limitations noted later in this article.)

TCP 소켓에 바인딩Bind to a TCP socket

Listen 메서드는 TCP 소켓을 바인딩하고 옵션 람다는 SSL 인증서를 구성할 수 있습니다.The Listen method binds to a TCP socket, and an options lambda lets you configure an SSL certificate:

public static void Main(string[] args)
{
    BuildWebHost(args).Run();
}

public static IWebHost BuildWebHost(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .UseStartup<Startup>()
        .UseKestrel(options =>
        {
            options.Listen(IPAddress.Loopback, 5000);
            options.Listen(IPAddress.Loopback, 5001, listenOptions =>
            {
                listenOptions.UseHttps("testCert.pfx", "testPassword");
            });
        })
        .Build();

어떻게이 예에서는 SSL을 특정 끝점에 대 한 사용 하 여 구성 확인 ListenOptions합니다.Notice how this example configures SSL for a particular endpoint by using ListenOptions. 특정 끝점에 대 한 다른 Kestrel 설정을 구성 하는 동일한 API를 사용할 수 있습니다.You can use the same API to configure other Kestrel settings for particular endpoints.

Windows에서 자체 서명 된 SSL 인증서를 생성 하기 위한 PowerShell cmdlet을 사용할 수 있습니다 New-selfsignedcertificate합니다.For generating self-signed SSL certificates on Windows, you can use the PowerShell cmdlet New-SelfSignedCertificate. 쉽게 자체 서명 된 인증서를 생성 하는 타사 도구에 대 한 참조 SelfCert합니다.For a third-party tool that makes it easier for you to generate self-signed certificates, see SelfCert.

MacOS 및 Linux에서 만들 수 있습니다를 사용 하 여 자체 서명 된 인증서를 OpenSSL합니다.On macOS and Linux you can create a self-signed certificate using OpenSSL.

Unix 소켓에 바인딩Bind to a Unix socket

이 예제에 나와 있는 것 처럼에 향상 된 성능을 얻으려면 Nginx, Unix 소켓에서 수신할 수 있습니다.:You can listen on a Unix socket for improved performance with Nginx, as shown in this example:

.UseKestrel(options =>
{
    options.ListenUnixSocket("/tmp/kestrel-test.sock");
    options.ListenUnixSocket("/tmp/kestrel-test.sock", listenOptions =>
    {
        listenOptions.UseHttps("testCert.pfx", "testpassword");
    });
})

포트 0Port 0

포트 번호 0을 지정 하면 Kestrel는 동적으로 사용 가능한 포트를 바인딩합니다.If you specify port number 0, Kestrel dynamically binds to an available port. 다음 예제에서는 Kestrel 실제로 런타임에 바인딩할 포트를 확인 하는 방법을 보여 줍니다.The following example shows how to determine which port Kestrel actually bound to at runtime:

public void Configure(IApplicationBuilder app, ILoggerFactory loggerFactory)
{
    var serverAddressesFeature = app.ServerFeatures.Get<IServerAddressesFeature>();

    app.UseStaticFiles();

    app.Run(async (context) =>
    {
        context.Response.ContentType = "text/html";
        await context.Response
            .WriteAsync("<p>Hosted by Kestrel</p>");

        if (serverAddressesFeature != null)
        {
            await context.Response
                .WriteAsync("<p>Listening on the following addresses: " +
                    string.Join(", ", serverAddressesFeature.Addresses) +
                    "</p>");
        }

        await context.Response.WriteAsync($"<p>Request URL: {context.Request.GetDisplayUrl()}<p>");
    });
}

UseUrls 제한 사항UseUrls limitations

호출 하 여 끝점을 구성할 수 있습니다는 UseUrls 메서드 또는 사용 하는 urls ASPNETCORE_URLS 환경 변수나 명령줄 인수입니다.You can configure endpoints by calling the UseUrls method or using the urls command-line argument or the ASPNETCORE_URLS environment variable. 이러한 메서드는 코드 Kestrel 아닌 서버와 작동 하도록 하려는 경우 유용 합니다.These methods are useful if you want your code to work with servers other than Kestrel. 그러나 이러한 제한을 고려해 야 합니다.However, be aware of these limitations:

  • 이러한 방법으로 SSL을 사용할 수 없습니다.You can't use SSL with these methods.
  • 둘 다 사용 하는 경우는 Listen 메서드 및 UseUrls, Listen 끝점 재정의 UseUrls 끝점입니다.If you use both the Listen method and UseUrls, the Listen endpoints override the UseUrls endpoints.

IIS에 대 한 끝점 구성Endpoint configuration for IIS

IIS를 사용 하는 경우 IIS에 대 한 URL 바인딩을 재정의 중 하나를 호출 하 여 설정할 수 있는 모든 바인딩에 Listen 또는 UseUrls합니다.If you use IIS, the URL bindings for IIS override any bindings that you set by calling either Listen or UseUrls. 자세한 내용은 참조 ASP.NET Core 모듈 소개합니다.For more information, see Introduction to ASP.NET Core Module.

URL 접두사URL prefixes

호출 하는 경우 UseUrls 하거나 사용 하 여는 urls 명령줄 인수나 ASPNETCORE_URLS 환경 변수 URL 접두사는 다음 형식 중 하나일 수 있습니다.If you call UseUrls or use the urls command-line argument or ASPNETCORE_URLS environment variable, the URL prefixes can be in any of the following formats.

HTTP URL 접두사만 사용할 수 있습니다. Kestrel URL 바인딩을 사용 하 여 구성할 때 SSL을 지원 하지 않습니다 UseUrls합니다.Only HTTP URL prefixes are valid; Kestrel does not support SSL when you configure URL bindings by using UseUrls.

  • IPv4 주소와 포트 번호IPv4 address with port number

    http://65.55.39.10:80/
    

    0.0.0.0은 특별 한 경우로 모든 IPv4 주소를 바인딩합니다.0.0.0.0 is a special case that binds to all IPv4 addresses.

  • 포트 번호가 있는 IPv6 주소IPv6 address with port number

    http://[0:0:0:0:0:ffff:4137:270a]:80/ 
    

    [:]는 i p v 4에 해당 하는 IPv6 0.0.0.0입니다.[::] is the IPv6 equivalent of IPv4 0.0.0.0.

  • 호스트 이름과 포트 번호Host name with port number

    http://contoso.com:80/
    http://*:80/
    

    호스트 이름, *, 고 +, 특별 한 되지 않습니다.Host names, *, and +, are not special. IP 주소 또는 "localhost"를 인식 하지 않은 모든 항목은 모든 IPv4 및 IPv6 Ip에 바인딩합니다.Anything that is not a recognized IP address or "localhost" will bind to all IPv4 and IPv6 IPs. 서로 다른 호스트 이름을 같은 포트에서 서로 다른 ASP.NET Core 응용 프로그램에 바인딩할 필요 사용 HTTP.sys 또는 IIS, Nginx, 또는 Apache 같은 역방향 프록시 서버.If you need to bind different host names to different ASP.NET Core applications on the same port, use HTTP.sys or a reverse proxy server such as IIS, Nginx, or Apache.

  • 포트 번호 또는 루프백 ip 포트 번호로 "Localhost" 이름"Localhost" name with port number or loopback IP with port number

    http://localhost:5000/
    http://127.0.0.1:5000/
    http://[::1]:5000/
    

    localhost 를 지정, Kestrel IPv4 및 IPv6 모두 루프백 인터페이스에 바인딩합니다.When localhost is specified, Kestrel tries to bind to both IPv4 and IPv6 loopback interfaces. 요청 된 포트는 루프백 인터페이스 중 하나에 다른 서비스에서 사용 중인 경우 Kestrel 시작 되지 않습니다.If the requested port is in use by another service on either loopback interface, Kestrel fails to start. 루프백 인터페이스 중 하나 사용할 수 없으면 다른 이유로 대부분 IPv6 지원 되지 않기 때문에 일반적으로, Kestrel 경고를 기록 합니다.If either loopback interface is unavailable for any other reason (most commonly because IPv6 is not supported), Kestrel logs a warning.

다음 단계Next steps

자세한 내용은 다음 리소스를 참조하세요.For more information, see the following resources: