Implementacja serwera internetowego HTTP.sys w środowisku ASP.NET Core

  • Artykuł

Przez Tom Dykstra i Chris Ross

HTTP.sys to serwer internetowy dla platformy ASP.NET Core , który działa tylko w systemie Windows. HTTP.sys jest alternatywą dla Kestrel serwera i oferuje niektóre funkcje, które Kestrel nie zapewniają.

Ważne

Protokół HTTP.sys nie jest zgodny z modułem ASP.NET Core i nie może być używany z usługami IIS lub IIS Express.

Protokół HTTP.sys obsługuje następujące funkcje:

  • Uwierzytelnianie systemu Windows
  • Współużytkowanie portów
  • Protokół HTTPS z siecią SNI
  • PROTOKÓŁ HTTP/2 za pośrednictwem protokołu TLS (system Windows 10 lub nowszy)
  • Bezpośrednia transmisja plików
  • Buforowanie odpowiedzi
  • WebSockets (Windows 8 lub nowszy)

Obsługiwane wersje systemu Windows:

  • Windows 7 lub nowszy
  • Windows Server 2008 R2 lub nowszy

Wyświetl lub pobierz przykładowy kod (jak pobrać)

Kiedy należy używać protokołu HTTP.sys

Protokół HTTP.sys jest przydatny w przypadku wdrożeń, w których:

  • Istnieje potrzeba uwidocznienia serwera bezpośrednio w Internecie bez korzystania z usług IIS.

    HTTP.sys communicates directly with the Internet

  • Wdrożenie wewnętrzne wymaga funkcji niedostępnej w programie Kestrel. Aby uzyskać więcej informacji, zobacz Kestrel vs. HTTP.sys

    HTTP.sys communicates directly with the internal network

HTTP.sys to dojrzała technologia, która chroni przed wieloma typami ataków i zapewnia niezawodność, bezpieczeństwo i skalowalność pełnego serwera internetowego. Sam program IIS działa jako odbiornik HTTP na podstawie protokołu HTTP.sys.

Obsługa protokołu HTTP/2

Protokół HTTP/2 jest włączony dla aplikacji ASP.NET Core, gdy spełnione są następujące podstawowe wymagania:

Jeśli połączenie HTTP/2 zostanie nawiązane, httpRequest.Protocol zgłasza HTTP/2.

Protokół HTTP/2 jest domyślnie włączony. Jeśli połączenie HTTP/2 nie zostanie nawiązane, połączenie powróci do protokołu HTTP/1.1. W przyszłej wersji systemu Windows będą dostępne flagi konfiguracji HTTP/2, w tym możliwość wyłączenia protokołu HTTP/2 za pomocą protokołu HTTP.sys.

Obsługa protokołu HTTP/3

Protokół HTTP/3 jest włączony dla aplikacji ASP.NET Core, gdy spełnione są następujące podstawowe wymagania:

  • Windows Server 2022/Windows 11 lub nowszy
  • Jest https używane powiązanie adresu URL.
  • Ustawiono klucz rejestru EnableHttp3.

Poprzednie wersje kompilacji systemu Windows 11 mogą wymagać użycia kompilacji niejawnego testera systemu Windows.

Protokół HTTP/3 jest wykrywany jako uaktualnienie z protokołu HTTP/1.1 lub HTTP/2 za pośrednictwem nagłówka alt-svc . Oznacza to, że pierwsze żądanie zwykle będzie używać protokołu HTTP/1.1 lub HTTP/2 przed przełączeniem do protokołu HTTP/3. Protokół Http.Sys nie dodaje automatycznie nagłówka alt-svc — musi zostać dodany przez aplikację. Poniższy kod to przykład oprogramowania pośredniczącego, który dodaje alt-svc nagłówek odpowiedzi.

app.Use((context, next) =>
{
    context.Response.Headers.AltSvc = "h3=\":443\"";
    return next(context);
});

Umieść poprzedni kod na początku potoku żądania.

Http.Sys obsługuje również wysyłanie komunikatu protokołu HTTP/2 AltSvc zamiast nagłówka odpowiedzi w celu powiadomienia klienta o dostępności protokołu HTTP/3. Zobacz klucz rejestru EnableAltSvc. Wymaga to powiązań netsh sslcert, które używają nazw hostów, a nie adresów IP.

Uwierzytelnianie w trybie jądra przy użyciu protokołu Kerberos

Delegaty HTTP.sys do uwierzytelniania w trybie jądra przy użyciu protokołu uwierzytelniania Kerberos. Uwierzytelnianie w trybie użytkownika nie jest obsługiwane w przypadku protokołów Kerberos i HTTP.sys. Konto komputera musi służyć do odszyfrowywania tokenu protokołu Kerberos/biletu uzyskanego z usługi Active Directory i przekazywanego przez klienta do serwera w celu uwierzytelnienia użytkownika. Zarejestruj nazwę główną usługi (SPN) dla hosta, a nie użytkownika aplikacji.

Obsługa buforowania odpowiedzi w trybie jądra

W niektórych scenariuszach duże ilości małych zapisów z dużym opóźnieniem mogą spowodować znaczny wpływ na wydajność.HTTP.sys Ten wpływ jest spowodowany brakiem Pipe buforu w implementacji HTTP.sys . Aby zwiększyć wydajność w tych scenariuszach, obsługa buforowania odpowiedzi jest uwzględniana w systemie HTTP.sys. Włącz buforowanie, ustawiając wartość HttpSysOptions.EnableKernelResponseBuffering na true.

Buforowanie odpowiedzi powinno być włączone przez aplikację, która wykonuje synchroniczne operacje we/wy lub asynchroniczne operacje we/wy bez więcej niż jednego zaległego zapisu naraz. W tych scenariuszach buforowanie odpowiedzi może znacznie zwiększyć przepływność w przypadku połączeń o dużym opóźnieniu.

Aplikacje korzystające z asynchronicznych operacji we/wy, które mogą mieć więcej niż jeden zapis w danym momencie, nie powinny używać tej flagi. Włączenie tej flagi może spowodować wyższe użycie procesora CPU i pamięci przez HTTP.Sys.

Jak używać protokołu HTTP.sys

Konfigurowanie aplikacji ASP.NET Core do używania protokołu HTTP.sys

Wywołaj metodę UseHttpSys rozszerzenia podczas kompilowania hosta, określając dowolną wymaganą metodę HttpSysOptions. Poniższy przykład ustawia opcje na wartości domyślne:

using Microsoft.AspNetCore.Hosting.Server;
using Microsoft.AspNetCore.Hosting.Server.Features;
using Microsoft.AspNetCore.Http.Features;
using Microsoft.AspNetCore.Server.HttpSys;

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.UseHttpSys(options =>
{
    options.AllowSynchronousIO = false;
    options.Authentication.Schemes = AuthenticationSchemes.None;
    options.Authentication.AllowAnonymous = true;
    options.MaxConnections = null;
    options.MaxRequestBodySize = 30_000_000;
    options.UrlPrefixes.Add("http://localhost:5005");
});

builder.Services.AddRazorPages();

var app = builder.Build();

Dodatkowa konfiguracja HTTP.sys jest obsługiwana za pośrednictwem ustawień rejestru.

Aby uzyskać więcej informacji na temat opcji HTTP.sys, zobacz HttpSysOptions.

MaxRequestBodySize

Maksymalny dozwolony rozmiar dowolnej treści żądania w bajtach. Jeśli ustawiono wartość null, maksymalny rozmiar treści żądania jest nieograniczony. Ten limit nie ma wpływu na uaktualnione połączenia, które są zawsze nieograniczone.

Zalecaną metodą zastąpienia limitu w aplikacji IActionResult MVC core platformy ASP.NET jest użycie atrybutu RequestSizeLimitAttribute w metodzie akcji:

[RequestSizeLimit(100000000)]
public IActionResult MyActionMethod()

Zgłaszany jest wyjątek, jeśli aplikacja próbuje skonfigurować limit żądania po rozpoczęciu odczytywania żądania przez aplikację. Właściwość IsReadOnly może służyć do wskazania, czy MaxRequestBodySize właściwość jest w stanie tylko do odczytu, co oznacza, że jest za późno, aby skonfigurować limit.

Jeśli aplikacja powinna zastąpić MaxRequestBodySize żądanie, użyj polecenia IHttpMaxRequestBodySizeFeature:

app.Use((context, next) =>
{
    context.Features.GetRequiredFeature<IHttpMaxRequestBodySizeFeature>()
                                             .MaxRequestBodySize = 10 * 1024;

    var server = context.RequestServices
        .GetRequiredService<IServer>();
    var serverAddressesFeature = server.Features
                                 .GetRequiredFeature<IServerAddressesFeature>();

    var addresses = string.Join(", ", serverAddressesFeature.Addresses);

    var loggerFactory = context.RequestServices
        .GetRequiredService<ILoggerFactory>();
    var logger = loggerFactory.CreateLogger("Sample");

    logger.LogInformation("Addresses: {addresses}", addresses);

    return next(context);
});

Jeśli używasz programu Visual Studio, upewnij się, że aplikacja nie jest skonfigurowana do uruchamiania usług IIS lub IIS Express.

W programie Visual Studio domyślnym profilem uruchamiania jest usługa IIS Express. Aby uruchomić projekt jako aplikację konsolową, ręcznie zmień wybrany profil, jak pokazano na poniższym zrzucie ekranu:

Select console app profile

Konfigurowanie systemu Windows Server

  1. Określ porty, które mają być otwarte dla aplikacji, i użyj zapory systemu Windows lub polecenia cmdlet New-NetFirewallRule programu PowerShell, aby otworzyć porty zapory, aby zezwolić na ruch do protokołu HTTP.sys. W poniższych poleceniach i konfiguracji aplikacji jest używany port 443.

  2. Podczas wdrażania na maszynie wirtualnej platformy Azure otwórz porty w sieciowej grupie zabezpieczeń. W poniższych poleceniach i konfiguracji aplikacji jest używany port 443.

  3. W razie potrzeby uzyskaj i zainstaluj certyfikaty X.509.

    W systemie Windows utwórz certyfikaty z podpisem własnym przy użyciu polecenia cmdlet New-SelfSignedCertificate programu PowerShell. Aby zapoznać się z nieobsługiwanym przykładem, zobacz UpdateIISExpressSSLForChrome.ps1.

    Zainstaluj certyfikaty z podpisem własnym lub z podpisem urzędu certyfikacji w magazynie osobistym komputera>lokalnego serwera.

  4. Jeśli aplikacja jest wdrożeniem zależnym od platformy, zainstaluj platformę .NET Core, .NET Framework lub obie te elementy (jeśli aplikacja jest aplikacją platformy .NET Core przeznaczoną dla platformy .NET Framework).

    • .NET Core: jeśli aplikacja wymaga platformy .NET Core, uzyskaj i uruchom instalator środowiska uruchomieniowego platformy .NET Core z programu .NET Core Downloads. Nie instaluj pełnego zestawu SDK na serwerze.
    • .NET Framework: jeśli aplikacja wymaga programu .NET Framework, zobacz przewodnik instalacji programu .NET Framework. Zainstaluj wymagany program .NET Framework. Instalator najnowszej wersji programu .NET Framework jest dostępny na stronie pliki do pobrania platformy .NET Core.

    Jeśli aplikacja jest wdrożeniem samodzielnym, aplikacja zawiera środowisko uruchomieniowe we wdrożeniu. Na serwerze nie jest wymagana instalacja platformy.

  5. Skonfiguruj adresy URL i porty w aplikacji.

    Domyślnie ASP.NET Core wiąże się z .http://localhost:5000 Aby skonfigurować prefiksy adresów URL i porty, opcje obejmują:

    • UseUrls
    • urls argument wiersza polecenia
    • ASPNETCORE_URLS zmienna środowiskowa
    • UrlPrefixes

    W poniższym przykładzie kodu pokazano, jak używać UrlPrefixes z lokalnym adresem 10.0.0.4 IP serwera na porcie 443:

    var builder = WebApplication.CreateBuilder(args);

builder.WebHost.UseHttpSys(options =>
{
    options.UrlPrefixes.Add("https://10.0.0.4:443");
});

builder.Services.AddRazorPages();

var app = builder.Build();

    UrlPrefixes Zaletą jest to, że komunikat o błędzie jest generowany natychmiast dla nieprawidłowo sformatowanych prefiksów.

    Ustawienia w UrlPrefixes ustawieniach zastępowania/UseUrlsurls/ASPNETCORE_URLS. W związku z tym zaletą zmiennej środowiskowej UseUrls, urlsi ASPNETCORE_URLS jest to, że łatwiej jest przełączać się między Kestrel i HTTP.sys.

    Protokół HTTP.sys używa formatów ciągów UrlPrefix interfejsu API serwera HTTP.

    Ostrzeżenie

    Nie należy używać powiązań z symbolami wieloznacznymi najwyższego poziomu (http://*:80/ i http://+:80). Powiązania z symbolami wieloznacznymi najwyższego poziomu tworzą luki w zabezpieczeniach aplikacji. Dotyczy to zarówno silnych, jak i słabych symboli wieloznacznych. Użyj jawnych nazw hostów lub adresów IP, a nie symboli wieloznacznych. Powiązanie wieloznaczne poddomeny (na przykład *.mysub.com) nie jest zagrożeniem bezpieczeństwa, jeśli kontrolujesz całą domenę nadrzędną (w przeciwieństwie do *.com, która jest podatna na zagrożenia). Aby uzyskać więcej informacji, zobacz RFC 9110: Sekcja 7.2: Host i :authority.

    Aplikacje i kontenery często otrzymują tylko port do nasłuchiwania, na przykład port 80, bez dodatkowych ograniczeń, takich jak host lub ścieżka. HTTP_PORTS i HTTPS_PORTS to klucze konfiguracji, które określają porty nasłuchiwania dla Kestrel serwerów i HTTP.sys. Te klucze można określić jako zmienne środowiskowe zdefiniowane za pomocą DOTNET_ prefiksów lub ASPNETCORE_ lub określone bezpośrednio za pomocą innych danych wejściowych konfiguracji, takich jak appsettings.json. Każda z nich jest rozdzieloną średnikami listą wartości portów, jak pokazano w poniższym przykładzie:

    ASPNETCORE_HTTP_PORTS=80;8080
ASPNETCORE_HTTPS_PORTS=443;8081

    Powyższy przykład jest skrócony dla następującej konfiguracji, która określa schemat (HTTP lub HTTPS) i dowolny host lub adres IP.

    ASPNETCORE_URLS=http://*:80/;http://*:8080/;https://*:443/;https://*:8081/

    Klucze konfiguracji HTTP_PORTS i HTTPS_PORTS mają niższy priorytet i są zastępowane przez adresy URL lub wartości podane bezpośrednio w kodzie. Certyfikaty nadal muszą być konfigurowane oddzielnie za pośrednictwem mechaniki specyficznej dla serwera dla protokołu HTTPS.

    Te klucze konfiguracji są równoważne powiązaniom symboli wieloznacznych najwyższego poziomu. Są one wygodne w scenariuszach tworzenia i kontenera, ale unikaj symboli wieloznacznych podczas uruchamiania na maszynie, która może również hostować inne usługi.

  6. Wstępne wyrejestrowanie prefiksów adresów URL na serwerze.

    Wbudowane narzędzie do konfigurowania protokołu HTTP.sys to netsh.exe. Netsh.exe służy do rezerwowania prefiksów adresów URL i przypisywania certyfikatów X.509. Narzędzie wymaga uprawnień administratora.

    Użyj narzędzia netsh.exe, aby zarejestrować adresy URL aplikacji:

    netsh http add urlacl url=<URL> user=<USER>
    • <URL>: w pełni kwalifikowany ujednolicony lokalizator zasobów (URL). Nie używaj powiązania z symbolami wieloznacznymi. Użyj prawidłowej nazwy hosta lub lokalnego adresu IP. Adres URL musi zawierać ukośnik końcowy.
    • <USER>: określa nazwę użytkownika lub grupy użytkowników.

    W poniższym przykładzie lokalny adres IP serwera to 10.0.0.4:

    netsh http add urlacl url=https://10.0.0.4:443/ user=Users

    Po zarejestrowaniu adresu URL narzędzie odpowiada za pomocą URL reservation successfully addedpolecenia .

    Aby usunąć zarejestrowany adres URL, użyj delete urlacl polecenia :

    netsh http delete urlacl url=<URL>

  7. Zarejestruj certyfikaty X.509 na serwerze.

    Użyj narzędzia netsh.exe, aby zarejestrować certyfikaty dla aplikacji:

    netsh http add sslcert ipport=<IP>:<PORT> certhash=<THUMBPRINT> appid="{<GUID>}"
    • <IP>: określa lokalny adres IP powiązania. Nie używaj powiązania z symbolami wieloznacznymi. Użyj prawidłowego adresu IP.
    • <PORT>: określa port powiązania.
    • <THUMBPRINT>: odcisk palca certyfikatu X.509.
    • <GUID>: identyfikator GUID wygenerowany przez dewelopera reprezentujący aplikację do celów informacyjnych.

    Do celów referencyjnych zapisz identyfikator GUID w aplikacji jako tag pakietu:

    • W programie Visual Studio:
      • Otwórz właściwości projektu aplikacji, klikając prawym przyciskiem myszy aplikację w Eksplorator rozwiązań i wybierając pozycję Właściwości.
      • Wybierz kartę Pakiet .
      • Wprowadź identyfikator GUID utworzony w polu Tagi .
    • Jeśli nie używasz programu Visual Studio:

      • Otwórz plik projektu aplikacji.

      • <PackageTags> Dodaj właściwość do nowej lub istniejącej <PropertyGroup> z utworzonym identyfikatorem GUID:

        <PropertyGroup>
  <PackageTags>9412ee86-c21b-4eb8-bd89-f650fbf44931</PackageTags>
</PropertyGroup>

    W poniższym przykładzie:

    • Lokalny adres IP serwera to 10.0.0.4.
    • Generator losowego identyfikatora appid GUID w trybie online zapewnia wartość .
    netsh http add sslcert 
    ipport=10.0.0.4:443 
    certhash=b66ee04419d4ee37464ab8785ff02449980eae10 
    appid="{9412ee86-c21b-4eb8-bd89-f650fbf44931}"

    Po zarejestrowaniu certyfikatu narzędzie odpowiada za pomocą SSL Certificate successfully addedpolecenia .

    Aby usunąć rejestrację certyfikatu, użyj delete sslcert polecenia :

    netsh http delete sslcert ipport=<IP>:<PORT>

    Dokumentacja referencyjna pliku netsh.exe:

  8. Uruchom aplikację.

    uprawnienia Administracja istratora nie są wymagane do uruchamiania aplikacji w przypadku powiązania z hostem lokalnym przy użyciu protokołu HTTP (a nie HTTPS) z numerem portu większym niż 1024. W przypadku innych konfiguracji (na przykład przy użyciu lokalnego adresu IP lub powiązania z portem 443) uruchom aplikację z uprawnieniami administratora.

    Aplikacja odpowiada na publiczny adres IP serwera. W tym przykładzie serwer jest osiągany z Internetu pod jego publicznym adresem IP .104.214.79.47

    W tym przykładzie używany jest certyfikat dewelopera. Strona jest ładowana bezpiecznie po przekazaniu niezaufanego certyfikatu przeglądarki.

    Browser window showing the app's Index page loaded

Scenariusze dotyczące serwera proxy i modułu równoważenia obciążenia

W przypadku aplikacji hostowanych przez protokół HTTP.sys, które współdziałają z żądaniami z Internetu lub sieci firmowej, w przypadku hostowania serwerów proxy i modułów równoważenia obciążenia może być wymagana dodatkowa konfiguracja. Aby uzyskać więcej informacji, zobacz Konfigurowanie platformy ASP.NET Core pod kątem pracy z serwerami proxy i modułami równoważenia obciążenia.

Uzyskiwanie szczegółowych informacji o chronometrażu za pomocą funkcji IHttpSysRequestTimingFeature

IHttpSysRequestTimingFeature zawiera szczegółowe informacje o chronometrażu dla żądań:

using Microsoft.AspNetCore.Http.Features;
using Microsoft.AspNetCore.Server.HttpSys;

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.UseHttpSys();

var app = builder.Build();

app.Use((context, next) =>
{
    var feature = context.Features.GetRequiredFeature<IHttpSysRequestTimingFeature>();
    
    var loggerFactory = context.RequestServices.GetRequiredService<ILoggerFactory>();
    var logger = loggerFactory.CreateLogger("Sample");

    var timestamps = feature.Timestamps;

    for (var i = 0; i < timestamps.Length; i++)
    {
        var timestamp = timestamps[i];
        var timingType = (HttpSysRequestTimingType)i;

        logger.LogInformation("Timestamp {timingType}: {timestamp}",
                                          timingType, timestamp);
    }

    return next(context);
});

app.MapGet("/", () => Results.Ok());

app.Run();

IHttpSysRequestTimingFeature.TryGetTimestamp pobiera znacznik czasu dla podanego typu chronometrażu:

using Microsoft.AspNetCore.Http.Features;
using Microsoft.AspNetCore.Server.HttpSys;
var builder = WebApplication.CreateBuilder(args);

builder.WebHost.UseHttpSys();

var app = builder.Build();

app.Use((context, next) =>
{
    var feature = context.Features.GetRequiredFeature<IHttpSysRequestTimingFeature>();

    var loggerFactory = context.RequestServices.GetRequiredService<ILoggerFactory>();
    var logger = loggerFactory.CreateLogger("Sample");

    var timingType = HttpSysRequestTimingType.RequestRoutingEnd;

    if (feature.TryGetTimestamp(timingType, out var timestamp))
    {
        logger.LogInformation("Timestamp {timingType}: {timestamp}",
                                          timingType, timestamp);
    }
    else
    {
        logger.LogInformation("Timestamp {timingType}: not available for the "
                                           + "current request",    timingType);
    }

    return next(context);
});

app.MapGet("/", () => Results.Ok());

app.Run();

IHttpSysRequestTimingFeature.TryGetElapsedTime daje upłynął czas między dwoma określonymi chronometrażami:

using Microsoft.AspNetCore.Http.Features;
using Microsoft.AspNetCore.Server.HttpSys;

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.UseHttpSys();

var app = builder.Build();

app.Use((context, next) =>
{
    var feature = context.Features.GetRequiredFeature<IHttpSysRequestTimingFeature>();

    var loggerFactory = context.RequestServices.GetRequiredService<ILoggerFactory>();
    var logger = loggerFactory.CreateLogger("Sample");

    var startingTimingType = HttpSysRequestTimingType.RequestRoutingStart;
    var endingTimingType = HttpSysRequestTimingType.RequestRoutingEnd;

    if (feature.TryGetElapsedTime(startingTimingType, endingTimingType, out var elapsed))
    {
        logger.LogInformation(
            "Elapsed time {startingTimingType} to {endingTimingType}: {elapsed}",
            startingTimingType,
            endingTimingType,
            elapsed);
    }
    else
    {
        logger.LogInformation(
            "Elapsed time {startingTimingType} to {endingTimingType}:"
            + " not available for the current request.",
            startingTimingType,
            endingTimingType);
    }

    return next(context);
});

app.MapGet("/", () => Results.Ok());

app.Run();

Zaawansowane funkcje HTTP/2 do obsługi gRPC

Dodatkowe funkcje HTTP/2 w protokole HTTP.sys obsługują protokół gRPC, w tym obsługę przyczep odpowiedzi i wysyłanie ramek resetowania.

Wymagania dotyczące uruchamiania usługi gRPC za pomocą protokołu HTTP.sys:

  • Windows 11 Build 22000 lub nowszy, Windows Server 2022 Build 20348 lub nowszy.
  • Połączenie TLS 1.2 lub nowsze.

Przyczepy

Przyczepy HTTP są podobne do nagłówków HTTP, z wyjątkiem wysyłanych po wysłaniu treści odpowiedzi. W przypadku usług IIS i HTTP.sys obsługiwane są tylko przyczepy odpowiedzi HTTP/2.

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

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

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

W poprzednim przykładowym kodzie:

  • SupportsTrailers zapewnia, że przyczepy są obsługiwane w odpowiedzi.
  • DeclareTrailer dodaje daną nazwę przyczepy do nagłówka Trailer odpowiedzi. Deklarowanie przyczep odpowiedzi jest opcjonalne, ale zalecane. Jeśli DeclareTrailer jest wywoływana, musi to być przed wysłaniem nagłówków odpowiedzi.
  • AppendTrailer dołącza przyczepę.

Reset

Resetowanie umożliwia serwerowi zresetowanie żądania HTTP/2 z określonym kodem błędu. Żądanie resetowania jest uznawane za przerwane.

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

Reset w poprzednim przykładzie kodu określa kod błędu INTERNAL_ERROR . Aby uzyskać więcej informacji na temat kodów błędów HTTP/2, odwiedź sekcję kod błędu specyfikacji HTTP/2.

Dodatkowe zasoby

HTTP.sys to serwer internetowy dla platformy ASP.NET Core , który działa tylko w systemie Windows. HTTP.sys jest alternatywą dla Kestrel serwera i oferuje niektóre funkcje, które Kestrel nie zapewniają.

Ważne

Protokół HTTP.sys nie jest zgodny z modułem ASP.NET Core i nie może być używany z usługami IIS lub IIS Express.

Protokół HTTP.sys obsługuje następujące funkcje:

  • Uwierzytelnianie systemu Windows
  • Współużytkowanie portów
  • Protokół HTTPS z siecią SNI
  • PROTOKÓŁ HTTP/2 za pośrednictwem protokołu TLS (system Windows 10 lub nowszy)
  • Bezpośrednia transmisja plików
  • Buforowanie odpowiedzi
  • WebSockets (Windows 8 lub nowszy)

Obsługiwane wersje systemu Windows:

  • Windows 7 lub nowszy
  • Windows Server 2008 R2 lub nowszy

Wyświetl lub pobierz przykładowy kod (jak pobrać)

Kiedy należy używać protokołu HTTP.sys

Protokół HTTP.sys jest przydatny w przypadku wdrożeń, w których:

  • Istnieje potrzeba uwidocznienia serwera bezpośrednio w Internecie bez korzystania z usług IIS.

    HTTP.sys communicates directly with the Internet

  • Wdrożenie wewnętrzne wymaga funkcji niedostępnej w programie Kestrel. Aby uzyskać więcej informacji, zobacz Kestrel vs. HTTP.sys

    HTTP.sys communicates directly with the internal network

HTTP.sys to dojrzała technologia, która chroni przed wieloma typami ataków i zapewnia niezawodność, bezpieczeństwo i skalowalność pełnego serwera internetowego. Sam program IIS działa jako odbiornik HTTP na podstawie protokołu HTTP.sys.

Obsługa protokołu HTTP/2

Protokół HTTP/2 jest włączony dla aplikacji ASP.NET Core, gdy spełnione są następujące podstawowe wymagania:

Jeśli połączenie HTTP/2 zostanie nawiązane, httpRequest.Protocol zgłasza HTTP/2.

Protokół HTTP/2 jest domyślnie włączony. Jeśli połączenie HTTP/2 nie zostanie nawiązane, połączenie powróci do protokołu HTTP/1.1. W przyszłej wersji systemu Windows będą dostępne flagi konfiguracji HTTP/2, w tym możliwość wyłączenia protokołu HTTP/2 za pomocą protokołu HTTP.sys.

Obsługa protokołu HTTP/3

Protokół HTTP/3 jest włączony dla aplikacji ASP.NET Core, gdy spełnione są następujące podstawowe wymagania:

  • Windows Server 2022/Windows 11 lub nowszy
  • Jest https używane powiązanie adresu URL.
  • Ustawiono klucz rejestru EnableHttp3.

Poprzednie wersje kompilacji systemu Windows 11 mogą wymagać użycia kompilacji niejawnego testera systemu Windows.

Protokół HTTP/3 jest wykrywany jako uaktualnienie z protokołu HTTP/1.1 lub HTTP/2 za pośrednictwem nagłówka alt-svc . Oznacza to, że pierwsze żądanie zwykle będzie używać protokołu HTTP/1.1 lub HTTP/2 przed przełączeniem do protokołu HTTP/3. Protokół Http.Sys nie dodaje automatycznie nagłówka alt-svc — musi zostać dodany przez aplikację. Poniższy kod to przykład oprogramowania pośredniczącego, który dodaje alt-svc nagłówek odpowiedzi.

app.Use((context, next) =>
{
    context.Response.Headers.AltSvc = "h3=\":443\"";
    return next(context);
});

Umieść poprzedni kod na początku potoku żądania.

Http.Sys obsługuje również wysyłanie komunikatu protokołu HTTP/2 AltSvc zamiast nagłówka odpowiedzi w celu powiadomienia klienta o dostępności protokołu HTTP/3. Zobacz klucz rejestru EnableAltSvc. Wymaga to powiązań netsh sslcert, które używają nazw hostów, a nie adresów IP.

Uwierzytelnianie w trybie jądra przy użyciu protokołu Kerberos

Delegaty HTTP.sys do uwierzytelniania w trybie jądra przy użyciu protokołu uwierzytelniania Kerberos. Uwierzytelnianie w trybie użytkownika nie jest obsługiwane w przypadku protokołów Kerberos i HTTP.sys. Konto komputera musi służyć do odszyfrowywania tokenu protokołu Kerberos/biletu uzyskanego z usługi Active Directory i przekazywanego przez klienta do serwera w celu uwierzytelnienia użytkownika. Zarejestruj nazwę główną usługi (SPN) dla hosta, a nie użytkownika aplikacji.

Jak używać protokołu HTTP.sys

Konfigurowanie aplikacji ASP.NET Core do używania protokołu HTTP.sys

Wywołaj metodę UseHttpSys rozszerzenia podczas kompilowania hosta, określając dowolną wymaganą metodę HttpSysOptions. Poniższy przykład ustawia opcje na wartości domyślne:

public static IHostBuilder CreateHostBuilder(string[] args) =>
    Host.CreateDefaultBuilder(args)
        .ConfigureWebHostDefaults(webBuilder =>
        {
            webBuilder.UseHttpSys(options =>
            {
                options.AllowSynchronousIO = false;
                options.Authentication.Schemes = AuthenticationSchemes.None;
                options.Authentication.AllowAnonymous = true;
                options.MaxConnections = null;
                options.MaxRequestBodySize = 30000000;
                options.UrlPrefixes.Add("http://localhost:5005");
            });
            webBuilder.UseStartup<Startup>();
        });

Dodatkowa konfiguracja HTTP.sys jest obsługiwana za pośrednictwem ustawień rejestru.

Aby uzyskać więcej informacji na temat opcji HTTP.sys, zobacz HttpSysOptions.

MaxRequestBodySize

Maksymalny dozwolony rozmiar dowolnej treści żądania w bajtach. Jeśli ustawiono wartość null, maksymalny rozmiar treści żądania jest nieograniczony. Ten limit nie ma wpływu na uaktualnione połączenia, które są zawsze nieograniczone.

Zalecaną metodą zastąpienia limitu w aplikacji IActionResult MVC core platformy ASP.NET jest użycie atrybutu RequestSizeLimitAttribute w metodzie akcji:

[RequestSizeLimit(100000000)]
public IActionResult MyActionMethod()

Zgłaszany jest wyjątek, jeśli aplikacja próbuje skonfigurować limit żądania po rozpoczęciu odczytywania żądania przez aplikację. Właściwość IsReadOnly może służyć do wskazania, czy MaxRequestBodySize właściwość jest w stanie tylko do odczytu, co oznacza, że jest za późno, aby skonfigurować limit.

Jeśli aplikacja powinna zastąpić MaxRequestBodySize żądanie, użyj polecenia IHttpMaxRequestBodySizeFeature:

public void Configure(IApplicationBuilder app, IWebHostEnvironment env, 
    ILogger<Startup> logger, IServer server)
{
    app.Use(async (context, next) =>
    {
        context.Features.Get<IHttpMaxRequestBodySizeFeature>()
            .MaxRequestBodySize = 10 * 1024;

        var serverAddressesFeature = 
            app.ServerFeatures.Get<IServerAddressesFeature>();
        var addresses = string.Join(", ", serverAddressesFeature?.Addresses);

        logger.LogInformation("Addresses: {Addresses}", addresses);

        await next.Invoke();
    });

    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
    }
    else
    {
        app.UseExceptionHandler("/Error");
    }

    app.UseStaticFiles();
    app.UseRouting();

    app.UseEndpoints(endpoints =>
    {
        endpoints.MapRazorPages();
    });
}

Jeśli używasz programu Visual Studio, upewnij się, że aplikacja nie jest skonfigurowana do uruchamiania usług IIS lub IIS Express.

W programie Visual Studio domyślnym profilem uruchamiania jest usługa IIS Express. Aby uruchomić projekt jako aplikację konsolową, ręcznie zmień wybrany profil, jak pokazano na poniższym zrzucie ekranu:

Select console app profile

Konfigurowanie systemu Windows Server

  1. Określ porty, które mają być otwarte dla aplikacji, i użyj zapory systemu Windows lub polecenia cmdlet New-NetFirewallRule programu PowerShell, aby otworzyć porty zapory, aby zezwolić na ruch do protokołu HTTP.sys. W poniższych poleceniach i konfiguracji aplikacji jest używany port 443.

  2. Podczas wdrażania na maszynie wirtualnej platformy Azure otwórz porty w sieciowej grupie zabezpieczeń. W poniższych poleceniach i konfiguracji aplikacji jest używany port 443.

  3. W razie potrzeby uzyskaj i zainstaluj certyfikaty X.509.

    W systemie Windows utwórz certyfikaty z podpisem własnym przy użyciu polecenia cmdlet New-SelfSignedCertificate programu PowerShell. Aby zapoznać się z nieobsługiwanym przykładem, zobacz UpdateIISExpressSSLForChrome.ps1.

    Zainstaluj certyfikaty z podpisem własnym lub z podpisem urzędu certyfikacji w magazynie osobistym komputera>lokalnego serwera.

  4. Jeśli aplikacja jest wdrożeniem zależnym od platformy, zainstaluj platformę .NET Core, .NET Framework lub obie te elementy (jeśli aplikacja jest aplikacją platformy .NET Core przeznaczoną dla platformy .NET Framework).

    • .NET Core: jeśli aplikacja wymaga platformy .NET Core, uzyskaj i uruchom instalator środowiska uruchomieniowego platformy .NET Core z programu .NET Core Downloads. Nie instaluj pełnego zestawu SDK na serwerze.
    • .NET Framework: jeśli aplikacja wymaga programu .NET Framework, zobacz przewodnik instalacji programu .NET Framework. Zainstaluj wymagany program .NET Framework. Instalator najnowszej wersji programu .NET Framework jest dostępny na stronie pliki do pobrania platformy .NET Core.

    Jeśli aplikacja jest wdrożeniem samodzielnym, aplikacja zawiera środowisko uruchomieniowe we wdrożeniu. Na serwerze nie jest wymagana instalacja platformy.

  5. Skonfiguruj adresy URL i porty w aplikacji.

    Domyślnie ASP.NET Core wiąże się z .http://localhost:5000 Aby skonfigurować prefiksy adresów URL i porty, opcje obejmują:

    • UseUrls
    • urls argument wiersza polecenia
    • ASPNETCORE_URLS zmienna środowiskowa
    • UrlPrefixes

    W poniższym przykładzie kodu pokazano, jak używać UrlPrefixes z lokalnym adresem 10.0.0.4 IP serwera na porcie 443:

    public static IHostBuilder CreateHostBuilder(string[] args) =>
    Host.CreateDefaultBuilder(args)
        .ConfigureWebHostDefaults(webBuilder =>
        {
            webBuilder.UseHttpSys(options =>
            {
                options.UrlPrefixes.Add("https://10.0.0.4:443");
            });
            webBuilder.UseStartup<Startup>();
        });

    UrlPrefixes Zaletą jest to, że komunikat o błędzie jest generowany natychmiast dla nieprawidłowo sformatowanych prefiksów.

    Ustawienia w UrlPrefixes ustawieniach zastępowania/UseUrlsurls/ASPNETCORE_URLS. W związku z tym zaletą zmiennej środowiskowej UseUrls, urlsi ASPNETCORE_URLS jest to, że łatwiej jest przełączać się między Kestrel i HTTP.sys.

    Protokół HTTP.sys używa formatów ciągów UrlPrefix interfejsu API serwera HTTP.

    Ostrzeżenie

    Nie należy używać powiązań z symbolami wieloznacznymi najwyższego poziomu (http://*:80/ i http://+:80). Powiązania z symbolami wieloznacznymi najwyższego poziomu tworzą luki w zabezpieczeniach aplikacji. Dotyczy to zarówno silnych, jak i słabych symboli wieloznacznych. Użyj jawnych nazw hostów lub adresów IP, a nie symboli wieloznacznych. Powiązanie wieloznaczne poddomeny (na przykład *.mysub.com) nie jest zagrożeniem bezpieczeństwa, jeśli kontrolujesz całą domenę nadrzędną (w przeciwieństwie do *.com, która jest podatna na zagrożenia). Aby uzyskać więcej informacji, zobacz RFC 9110: Sekcja 7.2: Host i :authority.

  6. Wstępne wyrejestrowanie prefiksów adresów URL na serwerze.

    Wbudowane narzędzie do konfigurowania protokołu HTTP.sys to netsh.exe. Netsh.exe służy do rezerwowania prefiksów adresów URL i przypisywania certyfikatów X.509. Narzędzie wymaga uprawnień administratora.

    Użyj narzędzia netsh.exe, aby zarejestrować adresy URL aplikacji:

    netsh http add urlacl url=<URL> user=<USER>
    • <URL>: w pełni kwalifikowany ujednolicony lokalizator zasobów (URL). Nie używaj powiązania z symbolami wieloznacznymi. Użyj prawidłowej nazwy hosta lub lokalnego adresu IP. Adres URL musi zawierać ukośnik końcowy.
    • <USER>: określa nazwę użytkownika lub grupy użytkowników.

    W poniższym przykładzie lokalny adres IP serwera to 10.0.0.4:

    netsh http add urlacl url=https://10.0.0.4:443/ user=Users

    Po zarejestrowaniu adresu URL narzędzie odpowiada za pomocą URL reservation successfully addedpolecenia .

    Aby usunąć zarejestrowany adres URL, użyj delete urlacl polecenia :

    netsh http delete urlacl url=<URL>

  7. Zarejestruj certyfikaty X.509 na serwerze.

    Użyj narzędzia netsh.exe, aby zarejestrować certyfikaty dla aplikacji:

    netsh http add sslcert ipport=<IP>:<PORT> certhash=<THUMBPRINT> appid="{<GUID>}"
    • <IP>: określa lokalny adres IP powiązania. Nie używaj powiązania z symbolami wieloznacznymi. Użyj prawidłowego adresu IP.
    • <PORT>: określa port powiązania.
    • <THUMBPRINT>: odcisk palca certyfikatu X.509.
    • <GUID>: identyfikator GUID wygenerowany przez dewelopera reprezentujący aplikację do celów informacyjnych.

    Do celów referencyjnych zapisz identyfikator GUID w aplikacji jako tag pakietu:

    • W programie Visual Studio:
      • Otwórz właściwości projektu aplikacji, klikając prawym przyciskiem myszy aplikację w Eksplorator rozwiązań i wybierając pozycję Właściwości.
      • Wybierz kartę Pakiet .
      • Wprowadź identyfikator GUID utworzony w polu Tagi .
    • Jeśli nie używasz programu Visual Studio:

      • Otwórz plik projektu aplikacji.

      • <PackageTags> Dodaj właściwość do nowej lub istniejącej <PropertyGroup> z utworzonym identyfikatorem GUID:

        <PropertyGroup>
  <PackageTags>9412ee86-c21b-4eb8-bd89-f650fbf44931</PackageTags>
</PropertyGroup>

    W poniższym przykładzie:

    • Lokalny adres IP serwera to 10.0.0.4.
    • Generator losowego identyfikatora appid GUID w trybie online zapewnia wartość .
    netsh http add sslcert 
    ipport=10.0.0.4:443 
    certhash=b66ee04419d4ee37464ab8785ff02449980eae10 
    appid="{9412ee86-c21b-4eb8-bd89-f650fbf44931}"

    Po zarejestrowaniu certyfikatu narzędzie odpowiada za pomocą SSL Certificate successfully addedpolecenia .

    Aby usunąć rejestrację certyfikatu, użyj delete sslcert polecenia :

    netsh http delete sslcert ipport=<IP>:<PORT>

    Dokumentacja referencyjna pliku netsh.exe:

  8. Uruchom aplikację.

    uprawnienia Administracja istratora nie są wymagane do uruchamiania aplikacji w przypadku powiązania z hostem lokalnym przy użyciu protokołu HTTP (a nie HTTPS) z numerem portu większym niż 1024. W przypadku innych konfiguracji (na przykład przy użyciu lokalnego adresu IP lub powiązania z portem 443) uruchom aplikację z uprawnieniami administratora.

    Aplikacja odpowiada na publiczny adres IP serwera. W tym przykładzie serwer jest osiągany z Internetu pod jego publicznym adresem IP .104.214.79.47

    W tym przykładzie używany jest certyfikat dewelopera. Strona jest ładowana bezpiecznie po przekazaniu niezaufanego certyfikatu przeglądarki.

    Browser window showing the app's Index page loaded

Scenariusze dotyczące serwera proxy i modułu równoważenia obciążenia

W przypadku aplikacji hostowanych przez protokół HTTP.sys, które współdziałają z żądaniami z Internetu lub sieci firmowej, w przypadku hostowania serwerów proxy i modułów równoważenia obciążenia może być wymagana dodatkowa konfiguracja. Aby uzyskać więcej informacji, zobacz Konfigurowanie platformy ASP.NET Core pod kątem pracy z serwerami proxy i modułami równoważenia obciążenia.

Zaawansowane funkcje HTTP/2 do obsługi gRPC

Dodatkowe funkcje HTTP/2 w protokole HTTP.sys obsługują protokół gRPC, w tym obsługę przyczep odpowiedzi i wysyłanie ramek resetowania.

Wymagania dotyczące uruchamiania usługi gRPC za pomocą protokołu HTTP.sys:

  • Windows 11 Build 22000 lub nowszy, Windows Server 2022 Build 20348 lub nowszy.
  • Połączenie TLS 1.2 lub nowsze.

Przyczepy

Przyczepy HTTP są podobne do nagłówków HTTP, z wyjątkiem wysyłanych po wysłaniu treści odpowiedzi. W przypadku usług IIS i HTTP.sys obsługiwane są tylko przyczepy odpowiedzi HTTP/2.

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

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

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

W poprzednim przykładowym kodzie:

  • SupportsTrailers zapewnia, że przyczepy są obsługiwane w odpowiedzi.
  • DeclareTrailer dodaje daną nazwę przyczepy do nagłówka Trailer odpowiedzi. Deklarowanie przyczep odpowiedzi jest opcjonalne, ale zalecane. Jeśli DeclareTrailer jest wywoływana, musi to być przed wysłaniem nagłówków odpowiedzi.
  • AppendTrailer dołącza przyczepę.

Reset

Resetowanie umożliwia serwerowi zresetowanie żądania HTTP/2 z określonym kodem błędu. Żądanie resetowania jest uznawane za przerwane.

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

Reset w poprzednim przykładzie kodu określa kod błędu INTERNAL_ERROR . Aby uzyskać więcej informacji na temat kodów błędów HTTP/2, odwiedź sekcję kod błędu specyfikacji HTTP/2.

Dodatkowe zasoby

HTTP.sys to serwer internetowy dla platformy ASP.NET Core , który działa tylko w systemie Windows. HTTP.sys jest alternatywą dla Kestrel serwera i oferuje niektóre funkcje, które Kestrel nie zapewniają.

Ważne

Protokół HTTP.sys nie jest zgodny z modułem ASP.NET Core i nie może być używany z usługami IIS lub IIS Express.

Protokół HTTP.sys obsługuje następujące funkcje:

  • Uwierzytelnianie systemu Windows
  • Współużytkowanie portów
  • Protokół HTTPS z siecią SNI
  • PROTOKÓŁ HTTP/2 za pośrednictwem protokołu TLS (system Windows 10 lub nowszy)
  • Bezpośrednia transmisja plików
  • Buforowanie odpowiedzi
  • WebSockets (Windows 8 lub nowszy)

Obsługiwane wersje systemu Windows:

  • Windows 7 lub nowszy
  • Windows Server 2008 R2 lub nowszy

Wyświetl lub pobierz przykładowy kod (jak pobrać)

Kiedy należy używać protokołu HTTP.sys

Protokół HTTP.sys jest przydatny w przypadku wdrożeń, w których:

  • Istnieje potrzeba uwidocznienia serwera bezpośrednio w Internecie bez korzystania z usług IIS.

    HTTP.sys communicates directly with the Internet

  • Wdrożenie wewnętrzne wymaga funkcji niedostępnej w programie Kestrel. Aby uzyskać więcej informacji, zobacz Kestrel vs. HTTP.sys

    HTTP.sys communicates directly with the internal network

HTTP.sys to dojrzała technologia, która chroni przed wieloma typami ataków i zapewnia niezawodność, bezpieczeństwo i skalowalność pełnego serwera internetowego. Sam program IIS działa jako odbiornik HTTP na podstawie protokołu HTTP.sys.

Obsługa protokołu HTTP/2

Protokół HTTP/2 jest włączony dla aplikacji ASP.NET Core, jeśli spełnione są następujące podstawowe wymagania:

Jeśli połączenie HTTP/2 zostanie nawiązane, httpRequest.Protocol zgłasza HTTP/2.

Protokół HTTP/2 jest domyślnie włączony. Jeśli połączenie HTTP/2 nie zostanie nawiązane, połączenie powróci do protokołu HTTP/1.1. W przyszłej wersji systemu Windows będą dostępne flagi konfiguracji HTTP/2, w tym możliwość wyłączenia protokołu HTTP/2 za pomocą protokołu HTTP.sys.

Uwierzytelnianie w trybie jądra przy użyciu protokołu Kerberos

Delegaty HTTP.sys do uwierzytelniania w trybie jądra przy użyciu protokołu uwierzytelniania Kerberos. Uwierzytelnianie w trybie użytkownika nie jest obsługiwane w przypadku protokołów Kerberos i HTTP.sys. Konto komputera musi służyć do odszyfrowywania tokenu protokołu Kerberos/biletu uzyskanego z usługi Active Directory i przekazywanego przez klienta do serwera w celu uwierzytelnienia użytkownika. Zarejestruj nazwę główną usługi (SPN) dla hosta, a nie użytkownika aplikacji.

Jak używać protokołu HTTP.sys

Konfigurowanie aplikacji ASP.NET Core do używania protokołu HTTP.sys

Wywołaj metodę UseHttpSys rozszerzenia podczas kompilowania hosta, określając dowolną wymaganą metodę HttpSysOptions. Poniższy przykład ustawia opcje na wartości domyślne:

public static IHostBuilder CreateHostBuilder(string[] args) =>
    Host.CreateDefaultBuilder(args)
        .ConfigureWebHostDefaults(webBuilder =>
        {
            webBuilder.UseHttpSys(options =>
            {
                options.AllowSynchronousIO = false;
                options.Authentication.Schemes = AuthenticationSchemes.None;
                options.Authentication.AllowAnonymous = true;
                options.MaxConnections = null;
                options.MaxRequestBodySize = 30000000;
                options.UrlPrefixes.Add("http://localhost:5005");
            });
            webBuilder.UseStartup<Startup>();
        });

Dodatkowa konfiguracja HTTP.sys jest obsługiwana za pośrednictwem ustawień rejestru.

Opcje HTTP.sys

Właściwości opis Domyślna
AllowSynchronousIO Określ, czy dane wejściowe/wyjściowe synchroniczne są dozwolone dla parametrów HttpContext.Request.Body i HttpContext.Response.Body. false
Authentication.AllowAnonymous Zezwalaj na żądania anonimowe. true
Authentication.Schemes Określ dozwolone schematy uwierzytelniania. Może być modyfikowany w dowolnym momencie przed ujawnieniem odbiornika. Wartości są dostarczane przez wyliczenie AuthenticationSchemes: Basic, , KerberosNegotiate, Nonei NTLM. None
EnableResponseCaching Spróbuj buforowania w trybie jądra dla odpowiedzi z odpowiednimi nagłówkami. Odpowiedź może nie zawierać Set-Cookienagłówków , Varylub Pragma . Musi zawierać Cache-Control nagłówek, który jest public albo wartością shared-max-age , max-age albo nagłówkiem Expires . true
Http503Verbosity Zachowanie HTTP.sys podczas odrzucania żądań z powodu warunków ograniczania przepustowości. Http503VerbosityLevel.
Podstawowe
MaxAccepts Maksymalna liczba akceptowanych współbieżnych wartości. 5 × Środowisko.
ProcessorCount
MaxConnections Maksymalna liczba współbieżnych połączeń do zaakceptowania. Użyj dla -1 nieskończoności. Użyj null polecenia , aby użyć ustawienia całego rejestru. null
(dla całej maszyny)
ustawienie)
MaxRequestBodySize Zobacz sekcję MaxRequestBodySize . 30000000 bajtów
(~28,6 MB)
RequestQueueLimit Maksymalna liczba żądań, które można kolejkować. 1000
RequestQueueMode Wskazuje to, czy serwer jest odpowiedzialny za tworzenie i konfigurowanie kolejki żądań, czy też należy dołączyć go do istniejącej kolejki.
Większość istniejących opcji konfiguracji nie ma zastosowania podczas dołączania do istniejącej kolejki.		 RequestQueueMode.Create
RequestQueueName Nazwa kolejki żądań HTTP.sys. null (Kolejka anonimowa)
ThrowWriteExceptions Wskaż, czy treść odpowiedzi zapisuje, które kończą się niepowodzeniem z powodu rozłączeń klienta, powinny zgłaszać wyjątki lub zakończyć normalnie. false
(ukończone normalnie)
Timeouts Uwidocznij konfigurację HTTP.sys TimeoutManager , która może być również skonfigurowana w rejestrze. Skorzystaj z linków interfejsu API, aby dowiedzieć się więcej o każdym ustawieniu, w tym wartościach domyślnych:
UrlPrefixes Określ element do zarejestrowania UrlPrefixCollection w pliku HTTP.sys. Najbardziej przydatna jest funkcja UrlPrefixCollection.Add, która służy do dodawania prefiksu do kolekcji. Mogą one być modyfikowane w dowolnym momencie przed rozdysponowaniem odbiornika.

MaxRequestBodySize

Maksymalny dozwolony rozmiar dowolnej treści żądania w bajtach. Jeśli ustawiono wartość null, maksymalny rozmiar treści żądania jest nieograniczony. Ten limit nie ma wpływu na uaktualnione połączenia, które są zawsze nieograniczone.

Zalecaną metodą zastąpienia limitu w aplikacji IActionResult MVC core platformy ASP.NET jest użycie atrybutu RequestSizeLimitAttribute w metodzie akcji:

[RequestSizeLimit(100000000)]
public IActionResult MyActionMethod()

Zgłaszany jest wyjątek, jeśli aplikacja próbuje skonfigurować limit żądania po rozpoczęciu odczytywania żądania przez aplikację. Właściwość IsReadOnly może służyć do wskazania, czy MaxRequestBodySize właściwość jest w stanie tylko do odczytu, co oznacza, że jest za późno, aby skonfigurować limit.

Jeśli aplikacja powinna zastąpić MaxRequestBodySize żądanie, użyj polecenia IHttpMaxRequestBodySizeFeature:

public void Configure(IApplicationBuilder app, IWebHostEnvironment env, 
    ILogger<Startup> logger, IServer server)
{
    app.Use(async (context, next) =>
    {
        context.Features.Get<IHttpMaxRequestBodySizeFeature>()
            .MaxRequestBodySize = 10 * 1024;

        var serverAddressesFeature = 
            app.ServerFeatures.Get<IServerAddressesFeature>();
        var addresses = string.Join(", ", serverAddressesFeature?.Addresses);

        logger.LogInformation("Addresses: {Addresses}", addresses);

        await next.Invoke();
    });

    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
    }
    else
    {
        app.UseExceptionHandler("/Error");
    }

    app.UseStaticFiles();
    app.UseRouting();

    app.UseEndpoints(endpoints =>
    {
        endpoints.MapRazorPages();
    });
}

Jeśli używasz programu Visual Studio, upewnij się, że aplikacja nie jest skonfigurowana do uruchamiania usług IIS lub IIS Express.

W programie Visual Studio domyślnym profilem uruchamiania jest usługa IIS Express. Aby uruchomić projekt jako aplikację konsolową, ręcznie zmień wybrany profil, jak pokazano na poniższym zrzucie ekranu:

Select console app profile

Konfigurowanie systemu Windows Server

  1. Określ porty, które mają być otwarte dla aplikacji, i użyj zapory systemu Windows lub polecenia cmdlet New-NetFirewallRule programu PowerShell, aby otworzyć porty zapory, aby zezwolić na ruch do protokołu HTTP.sys. W poniższych poleceniach i konfiguracji aplikacji jest używany port 443.

  2. Podczas wdrażania na maszynie wirtualnej platformy Azure otwórz porty w sieciowej grupie zabezpieczeń. W poniższych poleceniach i konfiguracji aplikacji jest używany port 443.

  3. W razie potrzeby uzyskaj i zainstaluj certyfikaty X.509.

    W systemie Windows utwórz certyfikaty z podpisem własnym przy użyciu polecenia cmdlet New-SelfSignedCertificate programu PowerShell. Aby zapoznać się z nieobsługiwanym przykładem, zobacz UpdateIISExpressSSLForChrome.ps1.

    Zainstaluj certyfikaty z podpisem własnym lub z podpisem urzędu certyfikacji w magazynie osobistym komputera>lokalnego serwera.

  4. Jeśli aplikacja jest wdrożeniem zależnym od platformy, zainstaluj platformę .NET Core, .NET Framework lub obie te elementy (jeśli aplikacja jest aplikacją platformy .NET Core przeznaczoną dla platformy .NET Framework).

    • .NET Core: jeśli aplikacja wymaga platformy .NET Core, uzyskaj i uruchom instalator środowiska uruchomieniowego platformy .NET Core z programu .NET Core Downloads. Nie instaluj pełnego zestawu SDK na serwerze.
    • .NET Framework: jeśli aplikacja wymaga programu .NET Framework, zobacz przewodnik instalacji programu .NET Framework. Zainstaluj wymagany program .NET Framework. Instalator najnowszej wersji programu .NET Framework jest dostępny na stronie pliki do pobrania platformy .NET Core.

    Jeśli aplikacja jest wdrożeniem samodzielnym, aplikacja zawiera środowisko uruchomieniowe we wdrożeniu. Na serwerze nie jest wymagana instalacja platformy.

  5. Skonfiguruj adresy URL i porty w aplikacji.

    Domyślnie ASP.NET Core wiąże się z .http://localhost:5000 Aby skonfigurować prefiksy adresów URL i porty, opcje obejmują:

    • UseUrls
    • urls argument wiersza polecenia
    • ASPNETCORE_URLS zmienna środowiskowa
    • UrlPrefixes

    W poniższym przykładzie kodu pokazano, jak używać UrlPrefixes z lokalnym adresem 10.0.0.4 IP serwera na porcie 443:

    public static IHostBuilder CreateHostBuilder(string[] args) =>
    Host.CreateDefaultBuilder(args)
        .ConfigureWebHostDefaults(webBuilder =>
        {
            webBuilder.UseHttpSys(options =>
            {
                options.UrlPrefixes.Add("https://10.0.0.4:443");
            });
            webBuilder.UseStartup<Startup>();
        });

    UrlPrefixes Zaletą jest to, że komunikat o błędzie jest generowany natychmiast dla nieprawidłowo sformatowanych prefiksów.

    Ustawienia w UrlPrefixes ustawieniach zastępowania/UseUrlsurls/ASPNETCORE_URLS. W związku z tym zaletą zmiennej środowiskowej UseUrls, urlsi ASPNETCORE_URLS jest to, że łatwiej jest przełączać się między Kestrel i HTTP.sys.

    Protokół HTTP.sys używa formatów ciągów UrlPrefix interfejsu API serwera HTTP.

    Ostrzeżenie

    Nie należy używać powiązań z symbolami wieloznacznymi najwyższego poziomu (http://*:80/ i http://+:80). Powiązania z symbolami wieloznacznymi najwyższego poziomu tworzą luki w zabezpieczeniach aplikacji. Dotyczy to zarówno silnych, jak i słabych symboli wieloznacznych. Użyj jawnych nazw hostów lub adresów IP, a nie symboli wieloznacznych. Powiązanie wieloznaczne poddomeny (na przykład *.mysub.com) nie jest zagrożeniem bezpieczeństwa, jeśli kontrolujesz całą domenę nadrzędną (w przeciwieństwie do *.com, która jest podatna na zagrożenia). Aby uzyskać więcej informacji, zobacz RFC 9110: Sekcja 7.2: Host i :authority.

  6. Wstępne wyrejestrowanie prefiksów adresów URL na serwerze.

    Wbudowane narzędzie do konfigurowania protokołu HTTP.sys to netsh.exe. Netsh.exe służy do rezerwowania prefiksów adresów URL i przypisywania certyfikatów X.509. Narzędzie wymaga uprawnień administratora.

    Użyj narzędzia netsh.exe, aby zarejestrować adresy URL aplikacji:

    netsh http add urlacl url=<URL> user=<USER>
    • <URL>: w pełni kwalifikowany ujednolicony lokalizator zasobów (URL). Nie używaj powiązania z symbolami wieloznacznymi. Użyj prawidłowej nazwy hosta lub lokalnego adresu IP. Adres URL musi zawierać ukośnik końcowy.
    • <USER>: określa nazwę użytkownika lub grupy użytkowników.

    W poniższym przykładzie lokalny adres IP serwera to 10.0.0.4:

    netsh http add urlacl url=https://10.0.0.4:443/ user=Users

    Po zarejestrowaniu adresu URL narzędzie odpowiada za pomocą URL reservation successfully addedpolecenia .

    Aby usunąć zarejestrowany adres URL, użyj delete urlacl polecenia :

    netsh http delete urlacl url=<URL>

  7. Zarejestruj certyfikaty X.509 na serwerze.

    Użyj narzędzia netsh.exe, aby zarejestrować certyfikaty dla aplikacji:

    netsh http add sslcert ipport=<IP>:<PORT> certhash=<THUMBPRINT> appid="{<GUID>}"
    • <IP>: określa lokalny adres IP powiązania. Nie używaj powiązania z symbolami wieloznacznymi. Użyj prawidłowego adresu IP.
    • <PORT>: określa port powiązania.
    • <THUMBPRINT>: odcisk palca certyfikatu X.509.
    • <GUID>: identyfikator GUID wygenerowany przez dewelopera reprezentujący aplikację do celów informacyjnych.

    Do celów referencyjnych zapisz identyfikator GUID w aplikacji jako tag pakietu:

    • W programie Visual Studio:
      • Otwórz właściwości projektu aplikacji, klikając prawym przyciskiem myszy aplikację w Eksplorator rozwiązań i wybierając pozycję Właściwości.
      • Wybierz kartę Pakiet .
      • Wprowadź identyfikator GUID utworzony w polu Tagi .
    • Jeśli nie używasz programu Visual Studio:

      • Otwórz plik projektu aplikacji.

      • <PackageTags> Dodaj właściwość do nowej lub istniejącej <PropertyGroup> z utworzonym identyfikatorem GUID:

        <PropertyGroup>
  <PackageTags>9412ee86-c21b-4eb8-bd89-f650fbf44931</PackageTags>
</PropertyGroup>

    W poniższym przykładzie:

    • Lokalny adres IP serwera to 10.0.0.4.
    • Generator losowego identyfikatora appid GUID w trybie online zapewnia wartość .
    netsh http add sslcert 
    ipport=10.0.0.4:443 
    certhash=b66ee04419d4ee37464ab8785ff02449980eae10 
    appid="{9412ee86-c21b-4eb8-bd89-f650fbf44931}"

    Po zarejestrowaniu certyfikatu narzędzie odpowiada za pomocą SSL Certificate successfully addedpolecenia .

    Aby usunąć rejestrację certyfikatu, użyj delete sslcert polecenia :

    netsh http delete sslcert ipport=<IP>:<PORT>

    Dokumentacja referencyjna pliku netsh.exe:

  8. Uruchom aplikację.

    uprawnienia Administracja istratora nie są wymagane do uruchamiania aplikacji w przypadku powiązania z hostem lokalnym przy użyciu protokołu HTTP (a nie HTTPS) z numerem portu większym niż 1024. W przypadku innych konfiguracji (na przykład przy użyciu lokalnego adresu IP lub powiązania z portem 443) uruchom aplikację z uprawnieniami administratora.

    Aplikacja odpowiada na publiczny adres IP serwera. W tym przykładzie serwer jest osiągany z Internetu pod jego publicznym adresem IP .104.214.79.47

    W tym przykładzie używany jest certyfikat dewelopera. Strona jest ładowana bezpiecznie po przekazaniu niezaufanego certyfikatu przeglądarki.

    Browser window showing the app's Index page loaded

Scenariusze dotyczące serwera proxy i modułu równoważenia obciążenia

W przypadku aplikacji hostowanych przez protokół HTTP.sys, które współdziałają z żądaniami z Internetu lub sieci firmowej, w przypadku hostowania serwerów proxy i modułów równoważenia obciążenia może być wymagana dodatkowa konfiguracja. Aby uzyskać więcej informacji, zobacz Konfigurowanie platformy ASP.NET Core pod kątem pracy z serwerami proxy i modułami równoważenia obciążenia.

Zaawansowane funkcje HTTP/2 do obsługi gRPC

Dodatkowe funkcje HTTP/2 w protokole HTTP.sys obsługują protokół gRPC, w tym obsługę przyczep odpowiedzi i wysyłanie ramek resetowania.

Wymagania dotyczące uruchamiania usługi gRPC za pomocą protokołu HTTP.sys:

  • Windows 10, kompilacja systemu operacyjnego 19041.508 lub nowsza
  • Połączenie TLS 1.2 lub nowsze

Przyczepy

Przyczepy HTTP są podobne do nagłówków HTTP, z wyjątkiem wysyłanych po wysłaniu treści odpowiedzi. W przypadku usług IIS i HTTP.sys obsługiwane są tylko przyczepy odpowiedzi HTTP/2.

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

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

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

W poprzednim przykładowym kodzie:

  • SupportsTrailers zapewnia, że przyczepy są obsługiwane w odpowiedzi.
  • DeclareTrailer dodaje daną nazwę przyczepy do nagłówka Trailer odpowiedzi. Deklarowanie przyczep odpowiedzi jest opcjonalne, ale zalecane. Jeśli DeclareTrailer jest wywoływana, musi to być przed wysłaniem nagłówków odpowiedzi.
  • AppendTrailer dołącza przyczepę.

Reset

Resetowanie umożliwia serwerowi zresetowanie żądania HTTP/2 z określonym kodem błędu. Żądanie resetowania jest uznawane za przerwane.

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

Reset w poprzednim przykładzie kodu określa kod błędu INTERNAL_ERROR . Aby uzyskać więcej informacji na temat kodów błędów HTTP/2, odwiedź sekcję kod błędu specyfikacji HTTP/2.

Dodatkowe zasoby