Kestrel веб-сервер в ASP.NET Core

Note

Это не последняя версия этой статьи. В текущей версии см. версию .NET 10 этой статьи.

Авторы: Том Дикстра (Tom Dykstra), Крис Росс (Chris Ross) и Стивен Хальтер (Stephen Halter)

Kestrel — это кроссплатформенный веб-сервер для ASP.NET Core. Kestrel — это рекомендуемый сервер для ASP.NET Core, и он настроен по умолчанию в шаблонах проектов ASP.NET Core.

KestrelК функциям относятся:

  • Kestrel Кроссплатформенный: кроссплатформенный веб-сервер, работающий в Windows, Linux и macOS.
  • Высокая производительность:Kestrel оптимизирована для эффективной обработки большого количества одновременных подключений.
  • Легковесный: оптимизирован для работы в средах с ограниченными ресурсами, таких как контейнеры и устройства периферии.
  • Повышенная защита:Kestrel поддерживает HTTPS и усилена для защиты от уязвимостей веб-сервера.
  • Поддержка расширенных протоколов:Kestrel поддерживает общие веб-протоколы, в том числе:
  • Интеграция с ASP.NET Core: бесшовная интеграция с другими компонентами ASP.NET Core, такими как конвейер промежуточного слоя, внедрение зависимостей и система конфигурации.
  • Гибкие рабочие нагрузки: Kestrel поддерживает множество рабочих нагрузок:
    • ASP.NET платформы приложений, такие как минимальные API, MVC, Razor страницы, SignalRBlazorи gRPC.
    • Создание обратного прокси-сервера с помощью YARP.
  • Расширяемость: настройка Kestrel с помощью конфигурации, посредством промежуточного слоя и пользовательских транспортов.
  • Диагностика производительности:Kestrel предоставляет встроенные функции диагностика производительности, такие как ведение журнала и метрики.
  • Управление памятью:Kestrel включает функции для эффективного управления памятью. Дополнительные сведения см. в разделе "Управление памятью".Kestrel

Get started

Шаблоны проектов ASP.NET Core используют Kestrel по умолчанию, если они не хостятся в IIS. В следующем созданном шаблоном файле Program.csметод WebApplication.CreateBuilder вызывает UseKestrel внутренне:

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

app.MapGet("/", () => "Hello World!");

app.Run();

Дополнительные сведения о настройке WebApplication и WebApplicationBuilder см. в кратком справочнике по минимальным API.

Дополнительные ресурсы

Kestrel — это кроссплатформенный веб-сервер для ASP.NET Core. Kestrel — это рекомендуемый сервер для ASP.NET Core, и он настроен по умолчанию в шаблонах проектов ASP.NET Core.

Функции Kestrel включают:

  • Kestrel Кроссплатформенный: кроссплатформенный веб-сервер, работающий в Windows, Linux и macOS.
  • Высокая производительность:Kestrel оптимизирована для эффективной обработки большого количества одновременных подключений.
  • Легковесный: оптимизирован для работы в средах с ограниченными ресурсами, например контейнерах и периферийных устройствах.
  • Усиленная безопасность:Kestrel поддерживает HTTPS и защищена от уязвимостей веб-сервера.
  • Поддержка расширенных протоколов:Kestrel поддерживает общие веб-протоколы, в том числе:
  • Интеграция с ASP.NET Core: плавная интеграция с другими компонентами ASP.NET Core, такими как конвейер промежуточного слоя, внедрение зависимостей и система конфигурации.
  • Гибкие рабочие нагрузки: Kestrel поддерживает множество нагрузок:
    • ASP.NET платформы приложений, такие как минимальные API, MVC, Razor страницы, SignalRBlazorи gRPC.
    • Создание обратного прокси-сервера с помощью YARP.
  • Расширяемость: кастомизация Kestrel с помощью конфигурации, промежуточного слоя и пользовательских транспортов.
  • Диагностика производительности:Kestrel предоставляет встроенные функции диагностика производительности, такие как ведение журнала и метрики.

Get started

Шаблоны проектов ASP.NET Core используют Kestrel по умолчанию, если они не размещены в IIS. В следующем созданном шаблоном файле Program.csметод WebApplication.CreateBuilder вызывает UseKestrel внутренне:

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

app.MapGet("/", () => "Hello World!");

app.Run();

Дополнительные сведения о настройке WebApplication и WebApplicationBuilder см. в кратком справочнике по минимальным API.

Поведение с подключенным отладчиком

Следующие ограничения времени ожидания и скорости не применяются при присоединении отладчика к Kestrel процессу:

Дополнительные ресурсы

Kestrel — это кроссплатформенный веб-сервер для ASP.NET Core. Kestrel является веб-сервером, который включен в шаблоны проектов ASP.NET Core и по умолчанию активирован в них.

Kestrel поддерживает следующие сценарии:

  • HTTPS
  • HTTP/2 (за исключением macOS†)
  • Непрозрачное обновление для поддержки WebSocket
  • Сокеты UNIX для высокой производительности в работе с Nginx

†HTTP/2 будет поддерживаться для macOS в будущих выпусках.

Kestrel поддерживается на всех платформах и версиях, поддерживаемых .NET.

Get started

Шаблоны проектов ASP.NET Core используют Kestrel по умолчанию, если они не размещены в IIS. В следующем созданном шаблоном файле Program.csметод WebApplication.CreateBuilder вызывает UseKestrel внутренне:

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

app.MapGet("/", () => "Hello World!");

app.Run();

Дополнительные сведения о настройке WebApplication и WebApplicationBuilder см. в кратком справочнике по минимальным API.

Поведение с подключённым отладчиком

Следующие ограничения времени ожидания и скорости не применяются при присоединении отладчика к Kestrel процессу:

Дополнительные ресурсы

Kestrel — это кроссплатформенный веб-сервер для ASP.NET Core. Kestrel — это веб-сервер, который по умолчанию включен и активирован в шаблонах проектов ASP.NET Core.

Kestrel поддерживает следующие сценарии:

  • HTTPS
  • HTTP/2 (за исключением macOS†)
  • Непрозрачное обновление для поддержки WebSocket
  • Сокеты UNIX для повышения производительности при работе за Nginx

†HTTP/2 будет поддерживаться для macOS в будущих выпусках.

Kestrel поддерживается на всех платформах и версиях, поддерживаемых .NET.

Просмотреть или скачать образец кода (описание загрузки)

Get started

Шаблоны проектов ASP.NET Core используют Kestrel по умолчанию, если они не хостятся в IIS. В Program.cs метод ConfigureWebHostDefaults вызывает UseKestrel:

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

public static IHostBuilder CreateHostBuilder(string[] args) =>
    Host.CreateDefaultBuilder(args)
        .ConfigureWebHostDefaults(webBuilder =>
        {
            webBuilder.UseStartup<Startup>();
        });

Дополнительные сведения о создании узла см. в разделах Настройка узла и Параметры построителя по умолчанию статьи Универсальный узел .NET в ASP.NET Core.

Дополнительные ресурсы

Kestrel — это кроссплатформенный веб-сервер для ASP.NET Core. Kestrel — это веб-сервер, который по умолчанию включается в шаблоны проектов ASP.NET Core.

Kestrel поддерживает следующие сценарии:

  • HTTPS
  • Непрозрачное обновление для поддержки WebSocket
  • Сокеты UNIX для повышения производительности при работе за Nginx
  • HTTP/2 (за исключением macOS†)

†HTTP/2 будет поддерживаться для macOS в будущих выпусках.

Kestrel поддерживается на всех платформах и версиях, поддерживаемых .NET.

Просмотреть или скачать образец кода (описание загрузки)

Поддержка HTTP/2

Протокол HTTP/2 доступен для приложений ASP.NET Core, если выполнены следующие базовые требования:

  • Операционная система†
    • Windows Server 2016 либо Windows 10 или более поздних версий‡
    • Linux с OpenSSL 1.0.2 или более поздней версии (например, Ubuntu 16.04 или более поздней версии)
  • Требуемая версия .NET Framework: .NET Core версии 2.2 или более поздней
  • Соединение согласования протокола уровня приложений (ALPN).
  • Подключение TLS 1.2 или более поздней версии

†HTTP/2 будет поддерживаться для macOS в будущих выпусках. ‡Kestrel имеет ограниченную поддержку HTTP/2 в Windows Server 2012 R2 и Windows 8.1. Поддержка ограничена из-за небольшого числа поддерживаемых комплектов шифров TLS, доступных для этих операционных систем. Для обеспечения безопасности TLS-подключений может потребоваться сертификат, созданный с использованием алгоритма ECDSA.

Если установлено подключение HTTP/2, HttpRequest.Protocol возвращает HTTP/2.

Начиная с версии .NET Core 3.0 протокол HTTP/2 по умолчанию включен. Дополнительные сведения о конфигурации см. в разделах, посвященных параметрам Kestrel и ListenOptions.Protocols.

Когда использовать Kestrel с обратным прокси-сервером

Kestrel можно использовать самостоятельно или с обратным прокси-сервером. Обратный прокси-сервер получает HTTP-запросы из сети и пересылает их в Kestrel. Примеры обратных прокси-серверов:

Kestrel используется в качестве граничного (с выходом в Интернет) веб-сервера:

Kestrel подключается напрямую к Интернету без обратного прокси-сервера

Kestrel используется в конфигурации обратного прокси-сервера.

Kestrel взаимодействует косвенно с Интернетом через обратный прокси-сервер, например IIS, Nginx или Apache.

Любая из этих конфигураций — с обратным прокси-сервером и без него — является поддерживаемой конфигурацией для размещения.

Kestrel, используемый в качестве граничного сервера без обратного прокси-сервера, не поддерживает совместное использование одних и тех же IP-адреса и порта несколькими процессами. Когда Kestrel настроен на прослушивание порта, Kestrel обрабатывает весь трафик для этого порта независимо от заголовков запросов Host. Обратный прокси-сервер, который может совместно использовать порты, также может пересылать запросы в Kestrel с уникальными IP-адресом и портом.

Даже если обратный прокси-сервер не требуется, его использование может оказаться удобным.

Обратный прокси-сервер:

  • Может ограничить область видимой поверхности размещенных сервером приложений.
  • Предоставьте дополнительный уровень конфигурации и глубокой кибербезопасности.
  • Может лучше интегрироваться с существующей инфраструктурой.
  • Упрощает настройку балансировки нагрузки и безопасных подключений (HTTPS). Сертификат X.509 требуется только обратному прокси-серверу, а сам этот сервер может обмениваться данными с серверами приложения во внутренней сети по обычному протоколу HTTP.

Warning

Для размещения в конфигурации обратного прокси требуется настройка промежуточного ПО для перенаправленных заголовков.

Kestrel в приложениях ASP.NET Core

Шаблоны проектов ASP.NET Core используют Kestrel по умолчанию. В Program.cs метод ConfigureWebHostDefaults вызывает UseKestrel:

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

public static IHostBuilder CreateHostBuilder(string[] args) =>
    Host.CreateDefaultBuilder(args)
        .ConfigureWebHostDefaults(webBuilder =>
        {
            webBuilder.UseStartup<Startup>();
        });

Дополнительные сведения о создании узла см. в разделах Настройка узла и Параметры построителя по умолчанию статьи Универсальный узел .NET в ASP.NET Core.

Чтобы задать дополнительную конфигурацию после вызова ConfigureWebHostDefaults, используйте ConfigureKestrel:

public static IHostBuilder CreateHostBuilder(string[] args) =>
    Host.CreateDefaultBuilder(args)
        .ConfigureWebHostDefaults(webBuilder =>
        {
            webBuilder.ConfigureKestrel(serverOptions =>
            {
                // Set properties and call methods on options
            })
            .UseStartup<Startup>();
        });

Kestrel параметры

Веб-сервер Kestrel имеет ограничивающие параметры конфигурации, которые удобно использовать в развертываниях с выходом в Интернет.

Задать ограничения для свойства Limits в классе KestrelServerOptions. Свойство Limits содержит экземпляр класса KestrelServerLimits.

В следующих примерах используется пространство имен Microsoft.AspNetCore.Server.Kestrel.Core.

using Microsoft.AspNetCore.Server.Kestrel.Core;

В примерах, приведенных далее в этой статье, параметры Kestrel настраиваются в коде C#. Параметры Kestrel можно также задать с помощью поставщика конфигурации. Например, поставщик конфигурации файла может загрузить конфигурацию Kestrel из файла appsettings.json или appsettings.{Environment}.json:

{
  "Kestrel": {
    "Limits": {
      "MaxConcurrentConnections": 100,
      "MaxConcurrentUpgradedConnections": 100
    },
    "DisableStringReuse": true
  }
}

Note

KestrelServerOptions и конфигурация конечных точек может настраиваться с помощью поставщиков конфигурации. Оставшаяся конфигурация Kestrel должна настраиваться в коде C#.

Воспользуйтесь одним из перечисленных ниже подходов.

  • Настройте Kestrel в Startup.ConfigureServices:

    1. Внедрение экземпляра IConfiguration в класс Startup. В следующем примере предполагается, что введенная конфигурация назначается свойству Configuration.

    2. В Startup.ConfigureServices загрузите раздел конфигурации Kestrel в конфигурацию Kestrel:

      using Microsoft.Extensions.Configuration

public class Startup
{
    public Startup(IConfiguration configuration)
    {
        Configuration = configuration;
    }

    public IConfiguration Configuration { get; }

    public void ConfigureServices(IServiceCollection services)
    {
        services.Configure<KestrelServerOptions>(
            Configuration.GetSection("Kestrel"));
    }

    public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
    {
        ...
    }
}

  • Настройте Kestrel при сборке хоста:

    В Program.cs загрузите раздел конфигурации Kestrel в конфигурацию Kestrel:

    // using Microsoft.Extensions.DependencyInjection;

public static IHostBuilder CreateHostBuilder(string[] args) =>
    Host.CreateDefaultBuilder(args)
        .ConfigureServices((context, services) =>
        {
            services.Configure<KestrelServerOptions>(
                context.Configuration.GetSection("Kestrel"));
        })
        .ConfigureWebHostDefaults(webBuilder =>
        {
            webBuilder.UseStartup<Startup>();
        });

Оба предыдущих подхода работают с любым поставщиком конфигурации.

Время ожидания в режиме поддержания активности

KeepAliveTimeout

Получает или задает keep-alive тайм-аут. Значение по умолчанию — 2 минуты.

webBuilder.ConfigureKestrel(serverOptions =>
{
    serverOptions.Limits.MaxConcurrentConnections = 100;
    serverOptions.Limits.MaxConcurrentUpgradedConnections = 100;
    serverOptions.Limits.MaxRequestBodySize = 10 * 1024;
    serverOptions.Limits.MinRequestBodyDataRate =
        new MinDataRate(bytesPerSecond: 100, 
            gracePeriod: TimeSpan.FromSeconds(10));
    serverOptions.Limits.MinResponseDataRate =
        new MinDataRate(bytesPerSecond: 100, 
            gracePeriod: TimeSpan.FromSeconds(10));
    serverOptions.Listen(IPAddress.Loopback, 5000);
    serverOptions.Listen(IPAddress.Loopback, 5001, 
        listenOptions =>
        {
            listenOptions.UseHttps("testCert.pfx", 
                "testPassword");
        });
    serverOptions.Limits.KeepAliveTimeout = 
        TimeSpan.FromMinutes(2);
    serverOptions.Limits.RequestHeadersTimeout = 
        TimeSpan.FromMinutes(1);
})

Максимальное число клиентских подключений

MaxConcurrentConnections MaxConcurrentUpgradedConnections

Максимальное число одновременно открытых подключений TCP для всего приложения можно задать с помощью следующего кода:

webBuilder.ConfigureKestrel(serverOptions =>
{
    serverOptions.Limits.MaxConcurrentConnections = 100;
    serverOptions.Limits.MaxConcurrentUpgradedConnections = 100;
    serverOptions.Limits.MaxRequestBodySize = 10 * 1024;
    serverOptions.Limits.MinRequestBodyDataRate =
        new MinDataRate(bytesPerSecond: 100, 
            gracePeriod: TimeSpan.FromSeconds(10));
    serverOptions.Limits.MinResponseDataRate =
        new MinDataRate(bytesPerSecond: 100, 
            gracePeriod: TimeSpan.FromSeconds(10));
    serverOptions.Listen(IPAddress.Loopback, 5000);
    serverOptions.Listen(IPAddress.Loopback, 5001, 
        listenOptions =>
        {
            listenOptions.UseHttps("testCert.pfx", 
                "testPassword");
        });
    serverOptions.Limits.KeepAliveTimeout = 
        TimeSpan.FromMinutes(2);
    serverOptions.Limits.RequestHeadersTimeout = 
        TimeSpan.FromMinutes(1);
})

Существует отдельный предел по подключениям, измененным с HTTP или HTTPS на другой протокол (например, по запросу WebSocket). После обновления подключение не учитывается в пределе MaxConcurrentConnections.

webBuilder.ConfigureKestrel(serverOptions =>
{
    serverOptions.Limits.MaxConcurrentConnections = 100;
    serverOptions.Limits.MaxConcurrentUpgradedConnections = 100;
    serverOptions.Limits.MaxRequestBodySize = 10 * 1024;
    serverOptions.Limits.MinRequestBodyDataRate =
        new MinDataRate(bytesPerSecond: 100, 
            gracePeriod: TimeSpan.FromSeconds(10));
    serverOptions.Limits.MinResponseDataRate =
        new MinDataRate(bytesPerSecond: 100, 
            gracePeriod: TimeSpan.FromSeconds(10));
    serverOptions.Listen(IPAddress.Loopback, 5000);
    serverOptions.Listen(IPAddress.Loopback, 5001, 
        listenOptions =>
        {
            listenOptions.UseHttps("testCert.pfx", 
                "testPassword");
        });
    serverOptions.Limits.KeepAliveTimeout = 
        TimeSpan.FromMinutes(2);
    serverOptions.Limits.RequestHeadersTimeout = 
        TimeSpan.FromMinutes(1);
})

По умолчанию максимальное число подключений не ограничено (null).

Maximum request body size (Максимальный размер текста запроса)

MaxRequestBodySize

По умолчанию максимальный размер текста запроса составляет 30 000 000 байт, что примерно соответствует 28,6 МБ.

Чтобы переопределить это ограничение в приложении MVC ASP.NET Core, мы рекомендуем использовать атрибут RequestSizeLimitAttribute в методе действия:

[RequestSizeLimit(100000000)]
public IActionResult MyActionMethod()

Приведенный ниже пример показывает, как настроить ограничение для приложения и каждого запроса:

webBuilder.ConfigureKestrel(serverOptions =>
{
    serverOptions.Limits.MaxConcurrentConnections = 100;
    serverOptions.Limits.MaxConcurrentUpgradedConnections = 100;
    serverOptions.Limits.MaxRequestBodySize = 10 * 1024;
    serverOptions.Limits.MinRequestBodyDataRate =
        new MinDataRate(bytesPerSecond: 100, 
            gracePeriod: TimeSpan.FromSeconds(10));
    serverOptions.Limits.MinResponseDataRate =
        new MinDataRate(bytesPerSecond: 100, 
            gracePeriod: TimeSpan.FromSeconds(10));
    serverOptions.Listen(IPAddress.Loopback, 5000);
    serverOptions.Listen(IPAddress.Loopback, 5001, 
        listenOptions =>
        {
            listenOptions.UseHttps("testCert.pfx", 
                "testPassword");
        });
    serverOptions.Limits.KeepAliveTimeout = 
        TimeSpan.FromMinutes(2);
    serverOptions.Limits.RequestHeadersTimeout = 
        TimeSpan.FromMinutes(1);
})

Переопределите параметр для конкретного запроса в посредствующем ПО.

app.Run(async (context) =>
{
    context.Features.Get<IHttpMaxRequestBodySizeFeature>()
        .MaxRequestBodySize = 10 * 1024;

    var minRequestRateFeature = 
        context.Features.Get<IHttpMinRequestBodyDataRateFeature>();
    var minResponseRateFeature = 
        context.Features.Get<IHttpMinResponseDataRateFeature>();

    if (minRequestRateFeature != null)
    {
        minRequestRateFeature.MinDataRate = new MinDataRate(
            bytesPerSecond: 100, gracePeriod: TimeSpan.FromSeconds(10));
    }

    if (minResponseRateFeature != null)
    {
        minResponseRateFeature.MinDataRate = new MinDataRate(
            bytesPerSecond: 100, gracePeriod: TimeSpan.FromSeconds(10));
    }

Если приложение пытается настроить ограничение для запроса после того, как оно начало считывать запрос, возникает исключение. Существует свойство IsReadOnly, которое указывает, что свойство MaxRequestBodySize находится в режиме только для чтения, что уже слишком поздно для настройки ограничения.

При запуске приложения вне процесса, который обслуживает модуль ASP.NET Core, ограничение на размер текста запроса Kestrel будет отключено, так как оно уже задается IIS.

Minimum request body data rate (Минимальная скорость передачи данных в тексте запроса)

MinRequestBodyDataRate MinResponseDataRate

Kestrel каждую секунду проверяет, поступают ли данные с указанной скоростью в байтах в секунду. Если скорость падает ниже минимума, для подключения истекает время ожидания. Льготный период — это время, которое Kestrel предоставляет клиенту для увеличения скорости отправки до минимального уровня; в течение этого периода скорость не проверяется. Льготный период помогает избежать разрыва соединений, которые первоначально отправляют данные с небольшой скоростью из-за медленного запуска TCP.

Минимальная скорость по умолчанию составляет 240 байт/с, льготный период равен 5 секундам.

Минимальная норма также применяется к ответу. Код для задания лимита запросов и лимита откликов различается только наличием RequestBody или Response в именах свойств и интерфейсов.

Ниже приведен пример, в который показано, как настроить минимальные показатели данных в Program.cs:

webBuilder.ConfigureKestrel(serverOptions =>
{
    serverOptions.Limits.MaxConcurrentConnections = 100;
    serverOptions.Limits.MaxConcurrentUpgradedConnections = 100;
    serverOptions.Limits.MaxRequestBodySize = 10 * 1024;
    serverOptions.Limits.MinRequestBodyDataRate =
        new MinDataRate(bytesPerSecond: 100, 
            gracePeriod: TimeSpan.FromSeconds(10));
    serverOptions.Limits.MinResponseDataRate =
        new MinDataRate(bytesPerSecond: 100, 
            gracePeriod: TimeSpan.FromSeconds(10));
    serverOptions.Listen(IPAddress.Loopback, 5000);
    serverOptions.Listen(IPAddress.Loopback, 5001, 
        listenOptions =>
        {
            listenOptions.UseHttps("testCert.pfx", 
                "testPassword");
        });
    serverOptions.Limits.KeepAliveTimeout = 
        TimeSpan.FromMinutes(2);
    serverOptions.Limits.RequestHeadersTimeout = 
        TimeSpan.FromMinutes(1);
})

Переопределите ограничения минимальной скорости для каждого запроса в ПО промежуточного слоя:

app.Run(async (context) =>
{
    context.Features.Get<IHttpMaxRequestBodySizeFeature>()
        .MaxRequestBodySize = 10 * 1024;

    var minRequestRateFeature = 
        context.Features.Get<IHttpMinRequestBodyDataRateFeature>();
    var minResponseRateFeature = 
        context.Features.Get<IHttpMinResponseDataRateFeature>();

    if (minRequestRateFeature != null)
    {
        minRequestRateFeature.MinDataRate = new MinDataRate(
            bytesPerSecond: 100, gracePeriod: TimeSpan.FromSeconds(10));
    }

    if (minResponseRateFeature != null)
    {
        minResponseRateFeature.MinDataRate = new MinDataRate(
            bytesPerSecond: 100, gracePeriod: TimeSpan.FromSeconds(10));
    }

Возможности IHttpMinResponseDataRateFeature, указанные в предыдущем примере, отсутствуют в HttpContext.Features для запросов HTTP/2, так как изменение ограничений скорости для каждого запроса не поддерживается для HTTP/2 из-за поддержки протокола мультиплексирования запроса. Однако IHttpMinRequestBodyDataRateFeature все еще присутствует в HttpContext.Features для запросов HTTP/2, потому что ограничение скорости чтения все еще может быть полностью отключено для каждого отдельного запроса, задав параметр IHttpMinRequestBodyDataRateFeature.MinDataRate значением null, даже для запроса HTTP/2. При попытке чтения IHttpMinRequestBodyDataRateFeature.MinDataRate или при попытке задать для него значение, отличное от null, при запросе HTTP/2 будет выброшено исключение NotSupportedException.

Ограничения скорости на уровне сервера, которые настроены с помощью KestrelServerOptions.Limits, по-прежнему применяются к подключениям HTTP/1.x и HTTP/2.

Таймаут для заголовков запросов

RequestHeadersTimeout

Получает или задает максимальное время, которое сервер уделяет получению заголовков запросов. Значение по умолчанию — 30 секунд.

webBuilder.ConfigureKestrel(serverOptions =>
{
    serverOptions.Limits.MaxConcurrentConnections = 100;
    serverOptions.Limits.MaxConcurrentUpgradedConnections = 100;
    serverOptions.Limits.MaxRequestBodySize = 10 * 1024;
    serverOptions.Limits.MinRequestBodyDataRate =
        new MinDataRate(bytesPerSecond: 100, 
            gracePeriod: TimeSpan.FromSeconds(10));
    serverOptions.Limits.MinResponseDataRate =
        new MinDataRate(bytesPerSecond: 100, 
            gracePeriod: TimeSpan.FromSeconds(10));
    serverOptions.Listen(IPAddress.Loopback, 5000);
    serverOptions.Listen(IPAddress.Loopback, 5001, 
        listenOptions =>
        {
            listenOptions.UseHttps("testCert.pfx", 
                "testPassword");
        });
    serverOptions.Limits.KeepAliveTimeout = 
        TimeSpan.FromMinutes(2);
    serverOptions.Limits.RequestHeadersTimeout = 
        TimeSpan.FromMinutes(1);
})

Максимальное число потоков на подключение

Http2.MaxStreamsPerConnection ограничивает количество параллельных потоков запросов для одного соединения HTTP/2. Потоки сверх этого числа будут отклонены.

webBuilder.ConfigureKestrel(serverOptions =>
{
    serverOptions.Limits.Http2.MaxStreamsPerConnection = 100;
});

Значение по умолчанию — 100.

Размер таблицы заголовка

Декодер HPACK распаковывает заголовки HTTP для подключений HTTP/2. Http2.HeaderTableSize ограничивает размер таблицы сжатия заголовка, которую использует декодер HPACK. Это значение указывается в октетах и должно быть больше нуля (0).

webBuilder.ConfigureKestrel(serverOptions =>
{
    serverOptions.Limits.Http2.HeaderTableSize = 4096;
});

Значение по умолчанию — 4096.

Максимальный размер кадра

Http2.MaxFrameSize указывает максимально допустимый размер полезных данных в кадре подключения HTTP/2, получаемых или отправляемых сервером. Это значение указывается в октетах и должно находиться в пределах от 2^14 (16 384) до 2^24-1 (16 777 215).

webBuilder.ConfigureKestrel(serverOptions =>
{
    serverOptions.Limits.Http2.MaxFrameSize = 16384;
});

Значение по умолчанию — 2^14 (16 384).

Максимальный размер заголовка запроса

Http2.MaxRequestHeaderFieldSize указывает максимально допустимый размер значений заголовка запроса (в октетах). Это ограничение применяется к имени и значению в их сжатых и несжатых представлениях. Значение должно быть больше нуля.

webBuilder.ConfigureKestrel(serverOptions =>
{
    serverOptions.Limits.Http2.MaxRequestHeaderFieldSize = 8192;
});

Значение по умолчанию — 8 192.

Размер окна начального подключения

Http2.InitialConnectionWindowSize указывает максимальное значение данных тела запроса (в байтах), буферизируемое сервером за один раз, для всех запросов (потоков) на каждое соединение. Размеры запросов также ограничиваются параметром Http2.InitialStreamWindowSize. Значение должно быть больше или равно 65 535 и меньше 2^31 (2 147 483 648).

webBuilder.ConfigureKestrel(serverOptions =>
{
    serverOptions.Limits.Http2.InitialConnectionWindowSize = 131072;
});

Значение по умолчанию — 128 КБ (131 072).

Размер окна начального потока

Http2.InitialStreamWindowSize указывает максимальное значение данных тела запроса (в байтах), буферизируемое сервером за один раз, для каждого запроса (потока). Размеры запросов также ограничиваются параметром Http2.InitialConnectionWindowSize. Значение должно быть больше или равно 65 535 и меньше 2^31 (2 147 483 648).

webBuilder.ConfigureKestrel(serverOptions =>
{
    serverOptions.Limits.Http2.InitialStreamWindowSize = 98304;
});

Значение по умолчанию — 96 КБ (98 304).

Trailers

Трейлеры HTTP похожи на заголовки HTTP, за исключением того, что они отправляются после отправки текста ответа. Для IIS и HTTP.sys поддерживаются только трейлеры ответов HTTP/2.

if (httpContext.Response.SupportsTrailers())
{
    httpContext.Response.DeclareTrailer("trailername");	

    // Write body
    httpContext.Response.WriteAsync("Hello world");

    httpContext.Response.AppendTrailer("trailername", "TrailerValue");
}

В приведенном выше примере кода:

  • SupportsTrailers обеспечивает поддержку трейлеров для ответа;
  • DeclareTrailer добавляет заданное имя трейлера в заголовок ответа Trailer. Объявлять трейлеры ответа необязательно, но рекомендуется. Вызов DeclareTrailer должен производиться перед отправкой заголовков ответа.
  • AppendTrailer добавляет трейлер.

Reset

Функция сброса позволяет серверу отменить запрос HTTP/2 с указанным кодом ошибки. Запрос на сброс считается отменённым.

var resetFeature = httpContext.Features.Get<IHttpResetFeature>();
resetFeature.Reset(errorCode: 2);

Reset в предыдущем примере кода задает код ошибки INTERNAL_ERROR. Дополнительные сведения о кодах ошибок HTTP/2 см. в соответствующем разделе спецификации HTTP/2.

Синхронный ввод-вывод

AllowSynchronousIO определяет, разрешены ли синхронные операции ввода-вывода для запроса и ответа. Значение по умолчанию — false.

Warning

Выполнение большого числа заблокированных операций синхронного ввода-вывода может привести к перегрузке пула потоков и зависанию приложения. Включайте AllowSynchronousIO, только если вы используете библиотеку, которая не поддерживает асинхронные операции ввода-вывода.

В примере ниже включаются синхронные операции ввода-вывода:

webBuilder.ConfigureKestrel(serverOptions =>
{
    serverOptions.AllowSynchronousIO = true;
})

Сведения о других параметрах и ограничениях Kestrel см. в следующих разделах:

Конфигурация конечной точки

По умолчанию платформа ASP.NET Core привязана к:

  • http://localhost:5000
  • https://localhost:5001 (если присутствует локальный сертификат разработки)

Укажите URL-адреса с помощью следующих параметров:

  • Переменная среды ASPNETCORE_URLS.
  • Аргумент командной строки --urls.
  • Ключ конфигурации узла urls.
  • Метод расширения UseUrls.

Значение, указанное с помощью этих подходов, может быть одной или несколькими конечными точками HTTP и HTTPS (HTTPS при наличии сертификата по умолчанию). Настройте значение в виде списка с разделением точкой с запятой (например, "Urls": "http://localhost:8000;http://localhost:8001").

Дополнительные сведения о таких подходах см. в разделах URL-адреса сервера и Переопределение конфигурации.

Сертификат разработки создается, когда:

В некоторых браузерах требуется явное разрешение доверять локальному сертификату разработки.

Шаблоны проектов настраивают приложения так, чтобы они запускались на базе HTTPS по умолчанию и включали поддержку перенаправления HTTPS и HSTS.

Вызовите методы Listen или ListenUnixSocket из KestrelServerOptions, чтобы настроить префиксы URL-адресов и порты для Kestrel.

UseUrls, аргумент командной строки --urls, ключ конфигурации узла urls и переменная среды ASPNETCORE_URLS тоже работают, однако на них распространяются ограничения, указанные далее в этой статье (для конфигурации конечной точки HTTPS требуется сертификат по умолчанию).

Конфигурация KestrelServerOptions:

Настроить параметры по умолчанию для конечной точки (Action<ListenOptions>)

Указывает конфигурацию Action для выполнения каждой заданной конечной точки. Повторные вызовы ConfigureEndpointDefaults приведут к тому, что предыдущие Action будут заменены последним указанным Action.

webBuilder.ConfigureKestrel(serverOptions =>
{
    serverOptions.ConfigureEndpointDefaults(listenOptions =>
    {
        // Configure endpoint defaults
    });
});

Note

К конечным точкам, созданным путем вызова Listenперед вызовом ConfigureEndpointDefaults, не будут применяться значения по умолчанию.

ConfigureHttpsDefaults(Action<HttpsConnectionAdapterOptions>)

Указывает конфигурацию Action для выполнения каждой конечной точки HTTPS. Повторные вызовы ConfigureHttpsDefaults приведут к тому, что предыдущие Action будут заменены последним указанным Action.

webBuilder.ConfigureKestrel(serverOptions =>
{
    serverOptions.ConfigureHttpsDefaults(listenOptions =>
    {
        // certificate is an X509Certificate2
        listenOptions.ServerCertificate = certificate;
    });
});

Note

К конечным точкам, созданным путем вызова Listenперед вызовом ConfigureHttpsDefaults, не будут применяться значения по умолчанию.

Configure(IConfiguration)

Создает загрузчик конфигурации для настройки Kestrel, который принимает IConfiguration в качестве входных данных. Для Kestrel конфигурация должна быть ограничена разделом конфигурации.

ListenOptions.UseHttps

Настройте Kestrel для использования протокола HTTPS.

Расширения ListenOptions.UseHttps:

  • UseHttps: настройте Kestrel для использования протокола HTTPS с сертификатом по умолчанию. Создает исключение, если сертификат по умолчанию не настроен.
  • UseHttps(string fileName)
  • UseHttps(string fileName, string password)
  • UseHttps(string fileName, string password, Action<HttpsConnectionAdapterOptions> configureOptions)
  • UseHttps(StoreName storeName, string subject)
  • UseHttps(StoreName storeName, string subject, bool allowInvalid)
  • UseHttps(StoreName storeName, string subject, bool allowInvalid, StoreLocation location)
  • UseHttps(StoreName storeName, string subject, bool allowInvalid, StoreLocation location, Action<HttpsConnectionAdapterOptions> configureOptions)
  • UseHttps(X509Certificate2 serverCertificate)
  • UseHttps(X509Certificate2 serverCertificate, Action<HttpsConnectionAdapterOptions> configureOptions)
  • UseHttps(Action<HttpsConnectionAdapterOptions> configureOptions)

Параметры ListenOptions.UseHttps:

  • filename — это путь и имя файла сертификата, связанного с каталогом, где находятся файлы содержимого приложения.
  • password — это пароль для доступа к данным сертификата X.509.
  • configureOptions — это Action для настройки HttpsConnectionAdapterOptions. Возвращает ListenOptions.
  • storeName — это хранилище сертификатов, из которого выполняется загрузка сертификата.
  • subject — это имя субъекта для сертификата.
  • allowInvalid указывает, следует ли учитывать недопустимые сертификаты, например, самоподписанные сертификаты.
  • location — это расположение хранилища, из которого загружается сертификат.
  • serverCertificate — это сертификат X.509.

В рабочей среде необходимо явно настроить HTTPS. Как минимум необходимо указать сертификат по умолчанию.

Поддерживаемые конфигурации, описанные далее:

  • Конфигурация отсутствует
  • Замена сертификата по умолчанию из конфигурации
  • Изменение значений по умолчанию в коде

Конфигурация отсутствует

Kestrel прослушивает порты http://localhost:5000 и https://localhost:5001 (если доступен сертификат по умолчанию).

Замена сертификата по умолчанию из конфигурации

CreateDefaultBuilder по умолчанию вызывает Configure(context.Configuration.GetSection("Kestrel")), чтобы загрузить конфигурацию Kestrel. Для Kestrel доступна схема конфигурации настроек приложения HTTPS по умолчанию. Настройте несколько конечных точек, включая URL-адреса и сертификаты для использования, либо из файла на диске, либо из хранилища сертификатов.

В следующем примере appsettings.json:

  • Установите для AllowInvalid значение true, чтобы разрешить использование недопустимых сертификатов (например, самозаверяющих сертификатов).
  • Любая конечная точка HTTPS, которая не указывает сертификат (HttpsDefaultCert в следующем примере), будет использовать сертификат, определенный в разделе Сертификаты>По умолчанию, или сертификат разработки.
{
  "Kestrel": {
    "Endpoints": {
      "Http": {
        "Url": "http://localhost:5000"
      },
      "HttpsInlineCertFile": {
        "Url": "https://localhost:5001",
        "Certificate": {
          "Path": "<path to .pfx file>",
          "Password": "<certificate password>"
        }
      },
      "HttpsInlineCertStore": {
        "Url": "https://localhost:5002",
        "Certificate": {
          "Subject": "<subject; required>",
          "Store": "<certificate store; required>",
          "Location": "<location; defaults to CurrentUser>",
          "AllowInvalid": "<true or false; defaults to false>"
        }
      },
      "HttpsDefaultCert": {
        "Url": "https://localhost:5003"
      },
      "Https": {
        "Url": "https://*:5004",
        "Certificate": {
          "Path": "<path to .pfx file>",
          "Password": "<certificate password>"
        }
      }
    },
    "Certificates": {
      "Default": {
        "Path": "<path to .pfx file>",
        "Password": "<certificate password>"
      }
    }
  }
}

Вместо использования параметров Path и Password для узла сертификата можно указать сертификат с помощью полей хранилища сертификатов. Например, сертификат из раздела Сертификаты>По умолчанию можно указать следующим образом:

"Default": {
  "Subject": "<subject; required>",
  "Store": "<cert store; required>",
  "Location": "<location; defaults to CurrentUser>",
  "AllowInvalid": "<true or false; defaults to false>"
}

Заметки о схеме:

  • В имена конечных точек регистр не учитывается. Например, HTTPS и Https являются допустимыми.
  • Параметр Url является обязательным для каждой конечной точки. Формат этого параметра такой же, как для параметра конфигурации Urls верхнего уровня, только он ограничен одиночным значением.
  • Эти конечные точки заменяют конечные точки, определенные в конфигурации Urls верхнего уровня, а не дополняют их. Конечные точки, определенные в коде через Listen, объединяются с конечными точками, определенными в разделе конфигурации.
  • Раздел Certificate является необязательным. Если раздел Certificate не указан, используются значения по умолчанию, определенные в предыдущих сценариях. Если значений по умолчанию нет, сервер выдает исключение и не запускается.
  • Раздел Certificate поддерживает сертификаты Path–Password и Subject–Store.
  • Таким образом, можно определить любое количество конечных точек, если это не приводит к конфликту портов.
  • options.Configure(context.Configuration.GetSection("{SECTION}")) возвращает KestrelConfigurationLoader с методом .Endpoint(string name, listenOptions => { }), который может использоваться в качестве дополнения для параметров настроенной конечной точки:
webBuilder.UseKestrel((context, serverOptions) =>
{
    serverOptions.Configure(context.Configuration.GetSection("Kestrel"))
        .Endpoint("HTTPS", listenOptions =>
        {
            listenOptions.HttpsOptions.SslProtocols = SslProtocols.Tls12;
        });
});

Можно обратиться напрямую к KestrelServerOptions.ConfigurationLoader, чтобы и далее выполнять итерацию с существующим загрузчиком, например, предоставленным CreateDefaultBuilder.

  • Раздел конфигурации для каждой конечной точки доступен в параметрах в методе Endpoint, чтобы можно было прочитать пользовательские параметры.
  • Можно загрузить несколько конфигураций, снова вызвав options.Configure(context.Configuration.GetSection("{SECTION}")) с другим разделом. Используется только последняя конфигурация, если явным образом не вызвать Load в предыдущих экземплярах. Метапакет не вызывает Load, чтобы можно было заменить его раздел конфигурации по умолчанию.
  • KestrelConfigurationLoader повторяет семейство API Listen из KestrelServerOptions в виде перегрузок Endpoint, позволяя настраивать конечные точки кода и конфигурации в одном месте. Эти перегрузки не используют имена и используют только параметры по умолчанию из конфигурации.

Изменение значений по умолчанию в коде

Можно использовать ConfigureEndpointDefaults и ConfigureHttpsDefaults для изменения параметров по умолчанию для ListenOptions и HttpsConnectionAdapterOptions, включая переопределение сертификата по умолчанию, указанного в предыдущем сценарии. Необходимо вызвать ConfigureEndpointDefaults и ConfigureHttpsDefaults, прежде чем настраивать конечные точки.

webBuilder.ConfigureKestrel(serverOptions =>
{
    serverOptions.ConfigureEndpointDefaults(listenOptions =>
    {
        // Configure endpoint defaults
    });

    serverOptions.ConfigureHttpsDefaults(listenOptions =>
    {
        listenOptions.SslProtocols = SslProtocols.Tls12;
    });
});

Поддержка для SNI в Kestrel

Можно использовать указание имени сервера (SNI) для размещения нескольких доменов в одном IP-адресе и порте. Для использования SNI клиент отправляет имя узла для безопасного сеанса серверу во время подтверждения TLS, чтобы сервер предоставил правильный сертификат. Клиент использует предоставленный сертификат для зашифрованного соединения с сервером во время безопасного сеанса, который следует после подтверждения TLS.

Kestrel поддерживает SNI через обратный вызов ServerCertificateSelector. Функция обратного вызова используется один раз за подключение, чтобы приложение проверило имя узла и выбрало соответствующий сертификат.

Поддержка SNI требует:

  • Запуск на целевой платформе netcoreapp2.1 или более поздней версии. При net461 или позже выполняется обратный вызов, но name всегда равен null. name также имеет значение null, если клиент не предоставляет параметр имени узла при TLS рукопожатии.
  • Все веб-сайты выполняются на одном и том же экземпляре Kestrel. Kestrel не поддерживает совместное использование одного и того же IP-адреса и порта на нескольких экземплярах без обратного прокси.
webBuilder.ConfigureKestrel(serverOptions =>
{
    serverOptions.ListenAnyIP(5005, listenOptions =>
    {
        listenOptions.UseHttps(httpsOptions =>
        {
            var localhostCert = CertificateLoader.LoadFromStoreCert(
                "localhost", "My", StoreLocation.CurrentUser,
                allowInvalid: true);
            var exampleCert = CertificateLoader.LoadFromStoreCert(
                "example.com", "My", StoreLocation.CurrentUser,
                allowInvalid: true);
            var subExampleCert = CertificateLoader.LoadFromStoreCert(
                "sub.example.com", "My", StoreLocation.CurrentUser,
                allowInvalid: true);
            var certs = new Dictionary<string, X509Certificate2>(
                StringComparer.OrdinalIgnoreCase);
            certs["localhost"] = localhostCert;
            certs["example.com"] = exampleCert;
            certs["sub.example.com"] = subExampleCert;

            httpsOptions.ServerCertificateSelector = (connectionContext, name) =>
            {
                if (name != null && certs.TryGetValue(name, out var cert))
                {
                    return cert;
                }

                return exampleCert;
            };
        });
    });
});

Ведение журнала подключений

Вызовите UseConnectionLogging, чтобы выдать журналы уровня отладки для обмена данными на уровне байтов в рамках подключения. Ведение журнала подключения полезно для устранения неполадок, связанных с низкоуровневым взаимодействием, например при TLS-шифровании и работе за прокси-серверами. Если UseConnectionLogging поместить перед UseHttps, в журнале регистрируется зашифрованный трафик. Если UseConnectionLogging поместить после UseHttps, в журнале регистрируется расшифрованный трафик.

webBuilder.ConfigureKestrel(serverOptions =>
{
    serverOptions.Listen(IPAddress.Any, 8000, listenOptions =>
    {
        listenOptions.UseConnectionLogging();
    });
});

Привязка к TCP-сокету

Метод Listen выполняет привязку к TCP-сокету, а лямбда-выражение параметров позволяет настроить конфигурацию сертификата X.509:

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

public static IHostBuilder CreateHostBuilder(string[] args) =>
    Host.CreateDefaultBuilder(args)
        .ConfigureWebHostDefaults(webBuilder =>
        {
            webBuilder.ConfigureKestrel(serverOptions =>
            {
                serverOptions.Listen(IPAddress.Loopback, 5000);
                serverOptions.Listen(IPAddress.Loopback, 5001, 
                    listenOptions =>
                    {
                        listenOptions.UseHttps("testCert.pfx", 
                            "testPassword");
                    });
            })
            .UseStartup<Startup>();
        });

В этом примере настраивается HTTPS для конечной точки с помощью ListenOptions. С помощью этого API можно настроить и другие параметры Kestrel для отдельных конечных точек.

На Windows самозаверяющий сертификат можно создать с помощью командлета New-SelfSignedCertificate PowerShell. Неподдерживаемый пример см. в файле сертификата UpdateIISExpressSSLForChrome.ps1 на GitHub.

В macOS, Linux и Windows можно создавать сертификаты с помощью OpenSSL.

Привязка к сокету UNIX

Прослушивайте Unix-сокет с помощью ListenUnixSocket, чтобы повысить производительность с Nginx, как показано в примере ниже:

webBuilder.ConfigureKestrel(serverOptions =>
{
    serverOptions.ListenUnixSocket("/tmp/kestrel-test.sock");
    serverOptions.ListenUnixSocket("/tmp/kestrel-test.sock", 
        listenOptions =>
        {
            listenOptions.UseHttps("testCert.pfx", 
                "testpassword");
        });
})
  • В файле конфигурации Nginx установите для записи server>location>proxy_pass значение http://unix:/tmp/{KESTREL SOCKET}:/;. {KESTREL SOCKET} — это имя сокета, предоставленного для ListenUnixSocket (как kestrel-test.sock в предыдущем примере).
  • Убедитесь, что сокет доступен для записи Nginx (например, chmod go+w /tmp/kestrel-test.sock).

Порт 0

Если указать номер порта 0, Kestrel будет динамически привязан к доступному порту. В следующем примере показано, как определить, к какому порту фактически привязан Kestrel во время выполнения:

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

    app.UseStaticFiles();

    app.Run(async (context) =>
    {
        context.Response.ContentType = "text/html";
        await context.Response
            .WriteAsync("<!DOCTYPE html><html lang=\"en\"><head>" +
                "<title></title></head><body><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>");
    });
}

Когда приложение выполняется, в выходных данных в окне консоли указывается динамический порт, по которому можно связаться с приложением:

Listening on the following addresses: http://127.0.0.1:48508

Limitations

Настройте конечные точки с помощью следующих подходов:

  • UseUrls
  • Аргументы командной строки --urls.
  • Ключ конфигурации узла urls.
  • Переменная среды ASPNETCORE_URLS.

Эти методы удобны, если нужно, чтобы код работал с серверами, отличающимися от Kestrel. Не забывайте о следующих ограничениях.

  • С этими подходами нельзя использовать HTTPS, если в конфигурации конечной точки HTTPS не предоставлен сертификат по умолчанию (например, с помощью конфигурации KestrelServerOptions или файла конфигурации, как показано выше в этом разделе).
  • Если подходы Listen и UseUrls используются одновременно, конечные точки Listen переопределяют конечные точки UseUrls.

Конфигурация конечной точки IIS

При использовании IIS привязки URL-адресов для IIS задаются элементами Listen или UseUrls, которые переопределяют привязки. Дополнительные сведения см. в статье Модуль ASP.NET Core.

ListenOptions.Protocols

Свойство Protocols устанавливает протоколы HTTP (HttpProtocols), разрешенные для конечной точки подключения или для сервера. Присвойте значение свойству Protocols из перечисления HttpProtocols.

Значение перечисления HttpProtocols Допустимый протокол подключения
Http1 Только HTTP/1.1. Можно использовать с протоколом TLS или без него.
Http2 Только HTTP/2. Может использоваться без TLS только в том случае, если клиент поддерживает режим предварительного знания.
Http1AndHttp2 HTTP/1.1 и HTTP/2. Для использования HTTP/2 требуется, чтобы клиент выбрал HTTP/2 в ходе согласования протокола уровня приложений (ALPN); в противном случае, по умолчанию используется HTTP/1.1.

Значение ListenOptions.Protocols по умолчанию для любой конечной точки равно HttpProtocols.Http1AndHttp2.

Ограничения TLS для HTTP/2:

  • TSL 1.2 или более поздней версии.
  • Отключено повторное согласование
  • Сжатие отключено
  • Минимальные размеры эфемерного обмена ключами
    • эллиптическая кривая Диффи — Хелмана (ECDHE) [RFC4492]: не менее 224 бит;
    • конечное поле Диффи — Хелмана (DHE) [TLS12]: не менее 2048 бит;
  • Набор шифров не запрещен.

По умолчанию поддерживается TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 [TLS-ECDHE] с эллиптической кривой P-256 [FIPS186].

Следующий пример разрешает подключения HTTP/1.1 и HTTP/2 через порт 8000. Эти подключения шифруются по протоколу TLS с использованием предоставленного сертификата:

webBuilder.ConfigureKestrel(serverOptions =>
{
    serverOptions.Listen(IPAddress.Any, 8000, listenOptions =>
    {
        listenOptions.UseHttps("testCert.pfx", "testPassword");
    });
});

При необходимости, используйте ПО промежуточного слоя подключения для фильтрации подтверждений TLS для каждого соединения по конкретным шифрам.

Следующий пример вызывает NotSupportedException для любого алгоритма шифрования, который не поддерживается приложением. Также можно определить и сравнить ITlsHandshakeFeature.CipherAlgorithm со списком приемлемых наборов шифров.

При использовании алгоритма шифрования CipherAlgorithmType.Null шифрование не используется.

// using System.Net;
// using Microsoft.AspNetCore.Connections;

webBuilder.ConfigureKestrel(serverOptions =>
{
    serverOptions.Listen(IPAddress.Any, 8000, listenOptions =>
    {
        listenOptions.UseHttps("testCert.pfx", "testPassword");
        listenOptions.UseTlsFilter();
    });
});

using System;
using System.Security.Authentication;
using Microsoft.AspNetCore.Connections.Features;

namespace Microsoft.AspNetCore.Connections
{
    public static class TlsFilterConnectionMiddlewareExtensions
    {
        public static IConnectionBuilder UseTlsFilter(
            this IConnectionBuilder builder)
        {
            return builder.Use((connection, next) =>
            {
                var tlsFeature = connection.Features.Get<ITlsHandshakeFeature>();

                if (tlsFeature.CipherAlgorithm == CipherAlgorithmType.Null)
                {
                    throw new NotSupportedException("Prohibited cipher: " +
                        tlsFeature.CipherAlgorithm);
                }

                return next();
            });
        }
    }
}

Фильтрацию соединений также можно настроить с помощью лямбды IConnectionBuilder:

// using System;
// using System.Net;
// using System.Security.Authentication;
// using Microsoft.AspNetCore.Connections;
// using Microsoft.AspNetCore.Connections.Features;

webBuilder.ConfigureKestrel(serverOptions =>
{
    serverOptions.Listen(IPAddress.Any, 8000, listenOptions =>
    {
        listenOptions.UseHttps("testCert.pfx", "testPassword");
        listenOptions.Use((context, next) =>
        {
            var tlsFeature = context.Features.Get<ITlsHandshakeFeature>();

            if (tlsFeature.CipherAlgorithm == CipherAlgorithmType.Null)
            {
                throw new NotSupportedException(
                    $"Prohibited cipher: {tlsFeature.CipherAlgorithm}");
            }

            return next();
        });
    });
});

В Linux для фильтрации рукопожатий TLS для каждого соединения можно использовать CipherSuitesPolicy.

// using System.Net.Security;
// using Microsoft.AspNetCore.Hosting;
// using Microsoft.AspNetCore.Server.Kestrel.Core;
// using Microsoft.Extensions.DependencyInjection;
// using Microsoft.Extensions.Hosting;

webBuilder.ConfigureKestrel(serverOptions =>
{
    serverOptions.ConfigureHttpsDefaults(listenOptions =>
    {
        listenOptions.OnAuthenticate = (context, sslOptions) =>
        {
            sslOptions.CipherSuitesPolicy = new CipherSuitesPolicy(
                new[]
                {
                    TlsCipherSuite.TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,
                    TlsCipherSuite.TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,
                    // ...
                });
        };
    });
});

Выбор протокола из конфигурации

CreateDefaultBuilder по умолчанию вызывает serverOptions.Configure(context.Configuration.GetSection("Kestrel")), чтобы загрузить конфигурацию Kestrel.

В следующем примере appsettings.json для всех конечных точек устанавливается протокол подключения по умолчанию HTTP/1.1:

{
  "Kestrel": {
    "EndpointDefaults": {
      "Protocols": "Http1"
    }
  }
}

В следующем примере appsettings.json для отдельной конечной точки устанавливается протокол подключения HTTP/1.1:

{
  "Kestrel": {
    "Endpoints": {
      "HttpsDefaultCert": {
        "Url": "https://localhost:5001",
        "Protocols": "Http1"
      }
    }
  }
}

Указанные в коде протоколы переопределяют значения, заданные в конфигурации.

Префиксы URL-адресов

Если вы используете UseUrls, аргумент командной строки --urls, ключ конфигурации узла urls или переменную среды ASPNETCORE_URLS, префиксы URL-адресов могут иметь любой из указанных ниже форматов.

Допустимы только префиксы URL-адресов HTTP. Kestrel не поддерживает HTTP при настройке привязок URL-адресов с помощью UseUrls.

  • IPv4-адрес с номером порта

    http://65.55.39.10:80/

    0.0.0.0 является особым случаем, который связывается со всеми IPv4-адресами.

  • IPv6-адрес с номером порта

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

    [::] является IPv6-аналогом IPv4-адреса 0.0.0.0.

  • Имя узла с номером порта

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

    Имена узлов, * и +, не имеют особого значения. Все, что не распознается как допустимый IP-адрес или localhost, привязывается ко всем IP-адресам IPv4 и IPv6. Чтобы привязать разные имена узлов к разным приложениям ASP.NET Core по одному порту, используйте HTTP.sys или обратный прокси-сервер, такой как IIS, Nginx или Apache.

    Warning

    Для размещения в конфигурации обратного прокси-сервера требуется конфигурация промежуточного ПО заголовков пересылки.

  • Имя узла localhost с номером порта или локальный IP-адрес с номером порта

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

    Если указать localhost, Kestrel попытается привязаться к интерфейсам обратной связи IPv4 и IPv6. Если запрошенный порт уже используется другой службой на одном из интерфейсов обратной связи, Kestrel не сможет запуститься. Если один из интерфейсов обратной петли недоступен по любой другой причине (чаще всего из-за отсутствия поддержки IPv6), Kestrel выдаст предупреждение.

Фильтрация хостов

Хотя Kestrel поддерживает конфигурации с использованием префиксов, например http://example.com:5000, Kestrel в основном не учитывает имя узла. Хост localhost является особым случаем, который используется для связывания с адресами обратной связи. Любой хост, кроме конкретного IP-адреса, автоматически привязывается ко всем общедоступным IP-адресам. Заголовки Host не проверяются.

В качестве обходного решения используйте программное обеспечение промежуточного слоя фильтрации хостов. ПО промежуточного слоя фильтрации узлов предоставляется пакетом Microsoft.AspNetCore.HostFiltering, который неявно предоставляется для приложений ASP.NET Core. Промежуточное ПО добавляется с помощью CreateDefaultBuilder, который вызывает AddHostFiltering:

public class Program
{
    public static void Main(string[] args)
    {
        CreateWebHostBuilder(args).Build().Run();
    }

    public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
        WebHost.CreateDefaultBuilder(args)
            .UseStartup<Startup>();
}

Промежуточное ПО фильтрации узлов отключено по умолчанию. Чтобы включить ПО промежуточного слоя, определите ключ AllowedHosts в appsettings.json/appsettings.{Environment}.json. Значение представляет собой разделенный точками с запятой список имен узлов без номеров портов:

appsettings.json:

{
  "AllowedHosts": "example.com;localhost"
}

Note

Промежуточное программное обеспечение для перенаправления заголовков также имеет параметр AllowedHosts. Промежуточное ПО для пересылки заголовков и промежуточное ПО для фильтрации узлов имеют схожие функции для разных сценариев. Настройка AllowedHosts в ПО промежуточного слоя перенаправленных заголовков подходит для случаев, когда заголовок Host не сохраняется при переадресации запросов с помощью обратного прокси-сервера или балансировщика нагрузки. Параметр AllowedHosts с промежуточным ПО фильтрации узлов применим, когда Kestrel используется в качестве публичного пограничного сервера или если заголовок Host пересылается напрямую.

Дополнительные сведения о посреднике перенаправления заголовков см. в разделе Настройка ASP.NET Core для работы с прокси-серверами и подсистемами балансировки нагрузки.

Конфигурация транспорта Libuv

Для проектов, где требуется использовать Libuv (UseLibuv):

  • Добавьте зависимость для пакета Microsoft.AspNetCore.Server.Kestrel.Transport.Libuv в файл проекта приложения:

    <PackageReference Include="Microsoft.AspNetCore.Server.Kestrel.Transport.Libuv"
                  Version="{VERSION}" />

  • Позвоните UseLibuv на IWebHostBuilder:

    public class Program
{
    public static void Main(string[] args)
    {
        CreateHostBuilder(args).Build().Run();
    }

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseLibuv();
                webBuilder.UseStartup<Startup>();
            });
}

Завершение обработки запросов HTTP/1.1

Открытие HTTP-соединений занимает много времени. Для протокола HTTPS это также требует больших ресурсов. Поэтому Kestrel пытается повторно использовать подключения по протоколу HTTP/1.1. Чтобы разрешить повторное использование соединения, текст запроса должен быть полностью использован. Приложение не всегда обрабатывает тело запроса, например запросы типа POST, когда сервер возвращает ответ с перенаправлением или 404. В случае перенаправления POST:

  • Возможно, клиент уже отправил часть данных POST.
  • Сервер записывает ответ 301.
  • Соединение нельзя использовать для нового запроса, пока не будут полностью прочитаны данные POST из предыдущего текста запроса.
  • Kestrel пытается очистить текст запроса. Очистка текста запроса означает чтение и отмену данных без их обработки.

Процесс очистки позволяет найти баланс между возможностью повторного использования соединения и временем, которое требуется для очистки оставшихся данных:

  • Время ожидания очистки составляет 5 секунд. Этот параметр нельзя изменить.
  • Если все данные, указанные в заголовке Content-Length или Transfer-Encoding, не были считаны до истечения времени ожидания, соединение закрывается.

Иногда может потребоваться немедленно завершить запрос до или после записи ответа. Например, клиенты могут иметь ограничения на данные, поэтому ограничение передаваемых данных может иметь приоритет. В таких случаях для завершения запроса вызовите HttpContext.Abort из контроллера, страницы Razor или ПО промежуточного слоя.

Вызов Abort имеет определенные недостатки.

  • Создание новых подключений может выполняться очень медленно и требовать много ресурсов.
  • Нет никакой гарантии, что клиент прочитал ответ перед закрытием соединения.
  • Вызов Abort следует использовать редко и только для серьезных, а не распространенных ошибок.
    • Вызывайте Abort, только когда нужно решить конкретную проблему. Например, вызовите Abort, если вредоносные клиенты пытаются выполнить операцию POST с данными или если в клиентском коде есть ошибка, вызывающая большие или многочисленные запросы.
    • Не вызывайте Abort для распространенных ошибок, таких как HTTP 404 (не найдено).

Вызов HttpResponse.CompleteAsync перед вызовом Abort гарантирует, что сервер завершит запись ответа. Однако поведение клиента непредсказуемо, и он может не прочитать ответ до того, как подключение будет прервано.

Этот процесс отличается для HTTP/2, так как протокол поддерживает прерывание отдельных потоков запросов без закрытия соединения. Тайм-аут на очистку длительностью пять секунд не применяется. Если после выполнения ответа остаются непрочтенные данные тела запроса, сервер отправляет кадр HTTP/2 RST. Дополнительные кадры данных текста запроса игнорируются.

Если возможно, клиентам лучше использовать Expect: 100-continue заголовок запроса и ждать ответа сервера перед началом отправки тела запроса. Это дает клиенту возможность проверить ответ и прервать операцию перед отправкой ненужных данных.

Дополнительные ресурсы

  • Last updated on