HTTP.sys webbserverimplementering i ASP.NET Core

Note

Det här är inte den senaste versionen av den här artikeln. Den aktuella versionen finns i .NET 11-versionen av den här artikeln.

Av Tom Dykstra och Chris Ross

HTTP.sys är en webbserver för ASP.NET Core som bara körs på Windows. HTTP.sys är ett alternativ till Kestrel server och erbjuder vissa funktioner som Kestrel inte tillhandahåller. Den här artikeln förklarar när du ska använda HTTP.sys, hur du konfigurerar den och hur du inspekterar begäran och TLS-information.

Important

HTTP.sys är inte kompatibelt med modulen ASP.NET Core och kan inte användas med IIS eller IIS Express.

HTTP.sys stöder följande funktioner:

  • Windows-autentisering
  • Portdelning
  • HTTPS med SNI
  • HTTP/2 via TLS (Windows 10 eller senare)
  • HTTP/3 via TLS (Windows 11 eller senare)
  • Direkt filöverföring
  • Cachelagring av svar
  • WebSockets (Windows 8 eller senare)
  • Anpassningsbara säkerhetsbeskrivningar
  • Automatisk borttagning av minnespool

Operativsystemet måste stödja appens målversion av .NET. Mer information om Windows versioner som stöds finns i Installera .NET på Windows. Tillgängligheten för HTTP.sys på äldre Windows-versioner innebär inte att aktuella versioner av ASP.NET Core har stöd för dessa versioner. Enskilda funktioner kan ha ytterligare Windows krav enligt beskrivningen i följande avsnitt.

Visa eller ladda ned exempelkod (hur du laddar ned)

När du ska använda HTTP.sys

HTTP.sys är användbart för distributioner där:

  • Det finns ett behov av att exponera servern direkt för Internet utan att använda IIS.

    HTTP.sys kommunicerar direkt med internet

  • En intern distribution kräver att en funktion inte är tillgänglig i Kestrel. Mer information finns i Kestrel jämfört med HTTP.sys

    HTTP.sys kommunicerar direkt med det interna nätverket

HTTP.sys är en mogen teknik som skyddar mot många typer av attacker och ger robusthet, säkerhet och skalbarhet för en webbserver med fullständiga funktioner. Själva IIS körs som en HTTP-lyssnare ovanpå HTTP.sys.

HTTP/2-stöd

HTTP/2 är aktiverat för ASP.NET Core appar när följande grundläggande krav uppfylls:

Om en HTTP/2-anslutning upprättas rapporterar HttpRequest.ProtocolHTTP/2.

HTTP/2 är aktiverat som standard. Om en HTTP/2-anslutning inte har upprättats återgår anslutningen till HTTP/1.1. På Windows-versioner som stöder detta inaktiverar alternativet disablehttp2 för en netsh http SSL-certifikatbindning HTTP/2 för den bindningen. För tillgängliga alternativ, se netsh http.

HTTP/3-stöd

HTTP/3 är aktiverat för ASP.NET Core appar när följande grundläggande krav uppfylls:

  • Windows Server 2022/Windows 11 eller senare
  • En https url-bindning används.
  • Registernyckeln EnableHttp3 har angetts.

Föregående Windows 11 Build-versioner kan kräva användning av en Windows Insider version.

HTTP/3 identifieras som en uppgradering från HTTP/1.1 eller HTTP/2 via alt-svc-huvudet. Det innebär att den första begäran normalt använder HTTP/1.1 eller HTTP/2 innan den växlar till HTTP/3. Http.Sys lägger inte automatiskt till alt-svc-huvudet. Det måste läggas till av programmet. Följande kod är ett mellanprogramsexempel som lägger till alt-svc-svarsrubriken.

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

Placera föregående kod tidigt i pipelinen för begäran.

Http.Sys har också stöd för att skicka ett AltSvc HTTP/2-protokollmeddelande i stället för ett svarshuvud för att meddela klienten att HTTP/3 är tillgängligt. Se registernyckeln EnableAltSvc.

Note

Detta kräver netsh sslcert-bindningar som använder värdnamn i stället för IP-adresser. Ersätt ipport med hostnameport i netsh http add sslcert kommandona nedan och ersätt IP-adressen med värdnamnet, www.example.comtill exempel . Det finns också ett känt problem där användningen hostnameport misslyckas om inte parametern certstorename har angetts. Använd som standard certstorename=MY.

Autentisering i kernelläge med Kerberos

HTTP.sys delegerar till kernellägesautentisering med Kerberos-autentiseringsprotokollet. Autentisering i användarläge stöds inte med Kerberos och HTTP.sys. Datorkontot måste användas för att dekryptera Kerberos-token/-biljetten som hämtas från služba Active Directory och vidarebefordras av klienten till servern för att autentisera användaren. Registrera tjänstens huvudnamn (SPN) för värden, inte appens användare.

Aktivera härdning av kanalbindningstoken (CBT)

Kanalbindningstoken (CBT) kopplar Windows-autentiseringen till den underliggande TLS-kanalen, vilket hjälper till att mildra NTLM-relä- och man-in-the-middle-attacker.

Konfigurera CBT-härdning med HttpAuthenticationHardeningLevel. De tillgängliga HttpAuthenticationHardeningLevel värdena är:

Value Behavior
Legacy Tillämpar inte kanalbindningsverifiering eller exponerar CBT-byte för appen.
Medium (standardvärde) Validerar CBT när klienter tillhandahåller dem, men tillåter deras frånvaro. Exponerar CBT-byte för appen.
Strict Kräver CBT på autentiserade begäranden och avvisar begäranden utan dem. Exponerar CBT-byte för appen.

Följande exempel aktiverar Strict-härdning:

builder.WebHost.UseHttpSys(options =>
{
    options.HttpAuthenticationHardeningLevel =
        HttpAuthenticationHardeningLevel.Strict;
});

Om HTTP.sys inte kan tillämpa Strict härdning misslyckas serverstarten med en HttpSysException. Med Legacy eller Mediumloggas ett misslyckande med att tillämpa inställningen och starten fortsätter. Enbart det konfigurerade värdet garanterar inte att operativsystemet tillämpade inställningen.

Warning

Strict-härdning kan leda till att Windows authentication misslyckas för klienter eller proxyservrar som inte tillhandahåller en giltig KBT. Testa klientkompatibilitet och TLS-avslutning i din miljö innan du aktiverar den i produktion.

När du ansluter till en befintlig begärandekö konfigurerar du härdning på lyssnaren som äger URL-gruppen. Den anslutna appen tillämpar inte URL-gruppkonfiguration.

Mer information om åtkomst till CBT-byte finns i Hämta kanalbindningstoken.

Välj CBT-härdning för HTTPS-slutpunkter som använder Windows authentication genom att ange AppContext-växeln Microsoft.AspNetCore.Server.HttpSys.EnableCBTHardening till true. Den här växeln väljer medelhärdning, vilket validerar angivna CBT men tillåter deras frånvaro.

Aktivera växeln i projektets runtimeconfig.template.json fil:

{
  "configProperties": {
    "Microsoft.AspNetCore.Server.HttpSys.EnableCBTHardening": true
  }
}

Du kan också ange växeln programmatiskt innan du skapar värden i Program filen:

AppContext.SetSwitch("Microsoft.AspNetCore.Server.HttpSys.EnableCBTHardening", true);

Warning

CBT-härdning är inaktiverad som standard. Om du aktiverar det kan Windows authentication misslyckas för klienter eller proxyservrar som inte stöder kanalbindning. Testa noggrant i din miljö innan du aktiverar i produktion.

Stöd för buffring av svar i kärnläge

I vissa scenarier kan stora mängder små skrivningar med hög svarstid orsaka betydande prestandapåverkan för HTTP.sys. Den här effekten beror på att det inte finns någon Pipe buffert i HTTP.sys implementeringen. För att förbättra prestanda i dessa scenarier ingår stöd för svarsbuffertning i HTTP.sys. Aktivera buffring genom att ställa in EnableKernelResponseBuffering på true. Svarsbuffertning ska aktiveras av en app som utför synkron I/O eller asynkron I/O med högst en utestående skrivning i taget. I dessa scenarier kan svarsbuffertning avsevärt förbättra dataflödet över anslutningar med långa svarstider.

Appar som använder asynkron I/O och som kan ha mer än en skrivoperation samtidigt bör inte använda den här flaggan. Om du aktiverar den här flaggan kan det leda till högre processor- och minnesanvändning av HTTP.Sys.

Så här använder du HTTP.sys

Konfigurera ASP.NET Core-appen så att den använder HTTP.sys

Anropa UseHttpSys-tilläggsmetoden när du bygger värden och specificera alla nödvändiga HttpSysOptions. I följande exempel anges alternativ till deras standardvärden:

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();

Ytterligare HTTP.sys konfiguration hanteras via registerinställningar.

Mer information om HTTP.sys-alternativen hittar du i HttpSysOptions.

Anpassa säkerhetsbeskrivningar

En begärankö i HTTP.sys är en struktur på kernelnivå som tillfälligt lagrar inkommande HTTP-begäranden tills appen är redo att bearbeta dem. Hantera åtkomst till begärandekön med hjälp av RequestQueueSecurityDescriptor. Ange den till en GenericSecurityDescriptor instans när du konfigurerar din HTTP.sys-server.

Genom att anpassa säkerhetsbeskrivningen kan du tillåta eller neka specifika användare eller grupper åtkomst till begärandekön. Detta är användbart i scenarier där du vill begränsa eller delegera HTTP.sys begärandehantering på operativsystemnivå.

Följande kod tillåter till exempel alla autentiserade användare men nekar gäster:

using System.Security.AccessControl;
using System.Security.Principal;
using Microsoft.AspNetCore.Server.HttpSys;

// Create a new security descriptor
var securityDescriptor = new CommonSecurityDescriptor(isContainer: false, isDS: false, sddlForm: string.Empty);

// Create a discretionary access control list (DACL)
var dacl = new DiscretionaryAcl(isContainer: false, isDS: false, capacity: 2);
dacl.AddAccess(
    AccessControlType.Allow,
    new SecurityIdentifier(WellKnownSidType.AuthenticatedUserSid, null),
    -1,
    InheritanceFlags.None,
    PropagationFlags.None
);
dacl.AddAccess(
    AccessControlType.Deny,
    new SecurityIdentifier(WellKnownSidType.BuiltinGuestsSid, null),
    -1,
    InheritanceFlags.None,
    PropagationFlags.None
);

// Assign the DACL to the security descriptor
securityDescriptor.DiscretionaryAcl = dacl;

// Configure HTTP.sys options
var builder = WebApplication.CreateBuilder();
builder.WebHost.UseHttpSys(options =>
{
    options.RequestQueueSecurityDescriptor = securityDescriptor;
});

Egenskapen RequestQueueSecurityDescriptor gäller endast när du skapar en ny begärandekö. Egenskapen påverkar inte befintliga begärandeköer. När RequestQueueMode är Attach, öppnar den en befintlig kö, alternativ på könivå, till exempel RequestQueueSecurityDescriptor och RequestQueueLimit, gäller inte. I Attach läge måste URL-gruppinställningar, till exempel timeouter och autentiseringshärdning, konfigureras av lyssnaren som äger URL-gruppen och UrlPrefixes används endast för att beräkna PathBase. CreateOrAttach konfigurerar fortfarande en egen URL-grupp och registrerar dess UrlPrefixes, även när kön redan finns. Inställningar för prefix som redan har registrerats av en annan lyssnare styrs fortfarande av lyssnaren.

MaxRequestBodySize

Den maximala tillåtna storleken för alla begärandetexter i byte. När värdet är nullär den maximala storleken på begärandetexten obegränsad. Den här gränsen påverkar inte uppgraderade anslutningar, som alltid är obegränsade.

Den rekommenderade metoden för att åsidosätta gränsen i en ASP.NET Core MVC-app för en enda IActionResult är att använda attributet RequestSizeLimitAttribute på en åtgärdsmetod:

[RequestSizeLimit(100000000)]
public IActionResult MyActionMethod()

Ett undantag utlöses om appen försöker konfigurera gränsen för en begäran när appen har börjat läsa begäran. En IsReadOnly-egenskap kan användas för att indikera om MaxRequestBodySize-egenskapen är i ett skrivskyddat läge, vilket betyder att det är för sent att konfigurera gränsen.

Om appen ska åsidosätta MaxRequestBodySize för varje begäran använder du 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);
});

Om du använder Visual Studio kontrollerar du att appen inte är konfigurerad för att köra IIS eller IIS Express.

I Visual Studio är standardstartprofilen för IIS Express. Om du vill köra projektet som en konsolapp ändrar du den valda profilen manuellt, enligt följande skärmbild:

Välj konsolappprofil

Konfigurera Windows Server

  1. Fastställa vilka portar som ska öppnas för appen och använd Windows Firewall eller New-NetFirewallRule PowerShell-cmdlet för att öppna brandväggsportar så att trafik kan nå HTTP.sys. I följande kommandon och appkonfiguration används port 443.

  2. När du distribuerar till en Azure virtuell dator öppnar du portarna i säkerhetsgruppen Network. I följande kommandon och appkonfiguration används port 443.

  3. Hämta och installera X.509-certifikat om det behövs.

    På Windows skapar du självsignerade certifikat med hjälp av cmdleten New-SelfSignedCertificate PowerShell. Ett exempel som inte stöds finns i UpdateIISExpressSSLForChrome.ps1.

    Installera antingen självsignerade eller CA-signerade certifikat i serverns local machine>Personal store.

  4. Om appen är en ramverksberoende distribution installerar du matchande ASP.NET Core Runtime och .NET Runtime från .NET Downloads. .NET SDK krävs inte på servern. ASP.NET Core riktar sig inte mot .NET Framework. Information om installationsinnehåll finns i Välj rätt körningsmiljö.

    Om appen är en fristående distributioninkluderar appen körmiljön i sin distribution. Ingen ramverksinstallation krävs på servern.

  5. Konfigurera URL:er och portar i appen.

    Som standard binder ASP.NET Core till http://localhost:5000. Om du vill konfigurera URL-prefix och portar inkluderar alternativen:

    Följande kodexempel visar hur du använder UrlPrefixes med serverns lokala IP-adress 10.0.0.4 på port 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();
    

    En fördel med UrlPrefixes är att ett felmeddelande genereras omedelbart för felaktigt formaterade prefix.

    Inställningarna i UrlPrefixes åsidosätter inställningarna i UseUrls/urls/ASPNETCORE_URLS. Därför är en fördel med UseUrls, urlsoch ASPNETCORE_URLS miljövariabeln att det är enklare att växla mellan Kestrel och HTTP.sys.

    HTTP.sys identifierar två typer av jokertecken i URL-prefix:

    • * är en svag bindning, även kallad reservbindning. Om URL-prefixet är http://*:5000och något annat är bundet till port 5000 används inte den här bindningen.
    • + är en specifik bindning. Om URL-prefixet är http://+:5000används den här bindningen före andra port 5000-bindningar.

    Mer information finns i UrlPrefix Strings.

    Warning

    Jokerteckenbindningar på toppnivå (http://*:80/ och http://+:80) bör inte användas. Jokerteckenbindningar på toppnivå skapar sårbarheter för appsäkerhet. Detta gäller både starka och svaga jokertecken. Använd explicita värdnamn eller IP-adresser i stället för jokertecken. Jokerteckenbindning för underdomäner (till exempel *.mysub.com) är inte en säkerhetsrisk om du kontrollerar hela den överordnade domänen (till skillnad från *.com, som är sårbar). Mer information finns i RFC 9110: Avsnitt 7.2: Värd och :utfärdare.

    De flesta konfigurationer för appar och containrar definierar endast en port för att lyssna, till exempel port 80, utan att specificera andra begränsningar som värd eller sökväg. HTTP_PORTS och HTTPS_PORTS är konfigurationsnycklar som anger lyssnarportarna för servrarna Kestrel och HTTP.sys. Du kan ange nycklarna som miljövariabler som definierats med prefixen DOTNET_ eller ASPNETCORE_ ange dem direkt via andra konfigurationsindata, till exempel appsettings.json filen. Varje konfiguration är en semikolonavgränsad lista med portvärden, som du ser i följande exempel:

    ASPNETCORE_HTTP_PORTS=80;8080
    ASPNETCORE_HTTPS_PORTS=443;8081
    

    Konfigurationen i exemplet är kortfattad för följande specifikation, som definierar schemat (HTTP eller HTTPS) och alla värdar eller IP-adresser:

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

    Konfigurationsnycklarna HTTP_PORTS och HTTPS_PORTS är lägre prioritet. Om andra URL:er eller värden anges direkt i kod kan de åsidosätta konfigurationsnycklarna. Konfigurera certifikat separat med hjälp av serverspecifika mekaniker för HTTPS.

    Note

    Blanda inte ihop konfigurationsnyckeln HTTPS_PORTS och ASPNETCORE_HTTPS_PORTS miljövariabeln, som anger portarna för Kestrel/HTTP.sys slutpunktskonfiguration, med konfigurationsnyckeln HTTPS_PORT och ASPNETCORE_HTTPS_PORT miljövariabeln, som anger porten för HTTPS-omdirigering mellanprogram.

    Dessa konfigurationsnycklar motsvarar jokerteckenbindningar på toppnivå. De är praktiska för utvecklings- och containerscenarier, men undvik jokertecken när de körs på en dator som också kan vara värd för andra tjänster.

  6. Förregistrera URL-prefix på servern.

    Det inbyggda verktyget för att konfigurera HTTP.sys är netsh.exe. netsh.exe används för att reservera URL-prefix och tilldela X.509-certifikat. Verktyget kräver administratörsbehörighet.

    Använd verktyget netsh.exe för att registrera URL:er för appen:

    netsh http add urlacl url=<URL> user=<USER>
    
    • <URL>: Den fullständigt kvalificerade enhetliga resurslokaliseraren (URL). Använd inte en jokerteckenbindning. Använd ett giltigt värdnamn eller en lokal IP-adress. URL:en måste innehålla ett avslutande snedstreck.
    • <USER>: Anger användarens eller användargruppens namn.

    I följande exempel är serverns lokala IP-adress 10.0.0.4:

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

    När en URL registreras svarar verktyget med URL reservation successfully added.

    Om du vill ta bort en registrerad URL använder du kommandot delete urlacl:

    netsh http delete urlacl url=<URL>
    
  7. Registrera X.509-certifikat på servern.

    Använd verktyget netsh.exe för att registrera certifikat för appen:

    netsh http add sslcert ipport=<IP>:<PORT> certhash=<THUMBPRINT> appid="{<GUID>}"
    
    • <IP>: Anger den lokala IP-adressen för bindningen. Använd inte en jokerteckenbindning. Använd en giltig IP-adress.
    • <PORT>: Anger porten för bindningen.
    • <THUMBPRINT>: Tumavtrycket för X.509-certifikatet.
    • <GUID>: Ett utvecklargenererat GUID som representerar appen i informationssyfte.

    I referenssyfte lagrar du GUID i appen som en pakettagg:

    • I Visual Studio:
      • Öppna appens projektegenskaper genom att högerklicka på appen i Prieskumník riešení och välja Egenskaper.
      • Välj fliken Paket.
      • Ange GUID:et som du skapade i fältet Taggar.
    • När du inte använder Visual Studio:
      • Öppna appens projektfil.

      • Lägg till en <PackageTags>-egenskap i en ny eller befintlig <PropertyGroup> med det GUID som du skapade:

        <PropertyGroup>
          <PackageTags>00001111-aaaa-2222-bbbb-3333cccc4444</PackageTags>
        </PropertyGroup>
        

    I följande exempel:

    • Serverns lokala IP-adress är 10.0.0.4.
    • En slumpmässig GUID-generator online ger värdet appid.
    netsh http add sslcert
        ipport=10.0.0.4:443
        certhash=b66ee04419d4ee37464ab8785ff02449980eae10
        appid="{00001111-aaaa-2222-bbbb-3333cccc4444}"
    

    När ett certifikat har registrerats svarar verktyget med SSL Certificate successfully added.

    Om du vill ta bort en certifikatregistrering använder du kommandot delete sslcert:

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

    Referensdokumentation för netsh.exe:

  8. Kör appen.

    Kör appen under den identitet som är auktoriserad för URL-reservationen. Administratörsbehörigheter krävs för att konfigurera URL-reservationer och certifikatbindningar, men krävs inte för att köra en app vars identitet har nödvändiga namnområdesbehörigheter. Bindning till en lokal IP-adress eller port 443 kräver inte i sig en process med förhöjda behörigheter. Mer information finns i Namnområdesreservationer, registreringar och routning.

    Appen svarar på serverns offentliga IP-adress. I det här exemplet nås servern från Internet på dess offentliga IP-adress 104.214.79.47.

    Ett utvecklingscertifikat används i det här exemplet. Sidan laddas säkert efter att ha kringgått webbläsarens varning om ett ej betrott certifikat.

    Webbläsarfönster som visar appens indexsida inläst

Scenarier för proxyserver och lastbalanserare

För appar som hanteras av HTTP.sys som interagerar med begäranden från Internet eller ett företagsnätverk kan ytterligare konfiguration krävas när du är värd för proxyservrar och lastbalanserare. Mer information finns i Konfigurera ASP.NET Core att fungera med proxyservrar och lastbalanserare.

När du bearbetar en begäran med både ett Content-Length huvud och ett Transfer-Encoding huvud vars slutliga kodning är chunkedHTTP.sys tar bort Content-Length från begärandehuvudena som visas i appen och stänger anslutningen efter att ha svarat som standard. Proxyservrar bör inte skicka motstridiga raminställningar för begäran. Det här beteendet hjälper till att förhindra smuggling av begäranden. Det innebär inte att varje sådan begäran avvisas innan den når appen.

Granska egenskaper för TLS och begäran

HTTP.sys exponerar begärandefunktioner för att inspektera TLS-information. Tillgänglighet beror på begäran, Windows version och HTTP.sys konfiguration.

Hämta den förhandlade TLS-chiffersviten

ITlsHandshakeFeature exponerar den förhandlade chiffersviten via sin NegotiatedCipherSuite-egenskap för HTTP.sys. Funktionen är inte tillgänglig för en icke-TLS-begäran. Egenskapen kan vara null om Windows inte stöder frågan eller om frågan misslyckas.

var handshake = context.Features.Get<ITlsHandshakeFeature>();
if (handshake?.NegotiatedCipherSuite is { } cipherSuite)
{
    logger.LogInformation("Negotiated TLS cipher suite: {CipherSuite}", cipherSuite);
}
else
{
    logger.LogInformation("The negotiated TLS cipher suite isn't available.");
}

Läs TLS ClientHello

Använd TryGetTlsClientHello för att hämta råa TLS ClientHello-byte på begäran. HTTPS-tjänstkonfigurationen måste ha HTTP_SERVICE_CONFIG_SSL_FLAG_ENABLE_CACHE_CLIENT_HELLO aktiverat. Att konfigurera ASP.NET Core för att använda HTTP.sys aktiverar inte den här inbyggda flaggan. Se HttpSetServiceConfiguration och HTTP_SERVICE_CONFIG_ID.

Anropa först metoden med ett tomt intervall för att hämta den nödvändiga buffertstorleken och allokera sedan en buffert och försök igen:

var feature = context.Features.GetRequiredFeature<IHttpSysRequestPropertyFeature>();
_ = feature.TryGetTlsClientHello(Span<byte>.Empty, out var requiredSize);

var pooled = requiredSize <= 1024 ? ArrayPool<byte>.Shared.Rent(requiredSize) : null;
var buffer = pooled ?? new byte[requiredSize];
try
{
    if (!feature.TryGetTlsClientHello(buffer, out var bytesReturned))
    {
        throw new InvalidOperationException(
            $"The TLS ClientHello buffer must be resized to {bytesReturned} bytes.");
    }

    logger.LogInformation("Retrieved {ByteCount} TLS ClientHello bytes.", bytesReturned);
}
finally
{
    if (pooled is not null)
    {
        ArrayPool<byte>.Shared.Return(pooled);
    }
}

Fråga efter andra egenskaper för interna förfrågningar

TryGetRequestProperty exponerar HttpQueryRequestProperty för godtyckliga interna begäransegenskaper.

  • propertyId anger ett värde från den ursprungliga HTTP_REQUEST_PROPERTY-uppräkningen.
  • qualifier innehåller valfria egenskapsspecifika byte. En tom span skickas till Windows som en nullpekare.
  • output tar emot de ursprungliga byten. Anroparen måste tolka dem med hjälp av motsvarande inbyggda datastruktur.
  • bytesReturned innehåller byten som skrivits vid lyckat resultat. Vid ett fel med otillräcklig buffert beror rapporteringen av den obligatoriska storleken på den nativa egenskapen. För egenskaper med fast storlek allokerar du en buffert som är dimensionerad för den motsvarande inbyggda struktur i stället för att anta att en tom buffertfråga rapporterar den storlek som krävs.

I följande exempel hämtas egenskapen TLS ClientHello via API:et för allmänt bruk. Det kräver samma inbyggda cachelagringskonfiguration för ClientHello som TryGetTlsClientHello:

const int HttpRequestPropertyTlsClientHello = 11;
var feature = context.Features.GetRequiredFeature<IHttpSysRequestPropertyFeature>();
_ = feature.TryGetRequestProperty(
    HttpRequestPropertyTlsClientHello, qualifier: default, output: default,
    out var requiredSize);
var buffer = new byte[requiredSize];

if (!feature.TryGetRequestProperty(
    HttpRequestPropertyTlsClientHello, qualifier: default, output: buffer,
    out var bytesReturned))
{
    throw new InvalidOperationException(
        $"The request property buffer must be resized to {bytesReturned} bytes.");
}

logger.LogInformation("Retrieved {ByteCount} native request property bytes.", bytesReturned);

Hämta kanalbindningstoken

TryGetChannelBindingBytes ger åtkomst till TLS-kanalbindningsbyte:

var tls = context.Features.Get<ITlsConnectionFeature>();
if (tls is not null &&
    tls.TryGetChannelBindingBytes(ChannelBindingKind.Endpoint, out var token))
{
    logger.LogInformation("TLS endpoint binding contains {ByteCount} bytes.", token.Length);
}
else
{
    logger.LogInformation("TLS endpoint channel binding isn't available.");
}

HTTP.sys stöder ChannelBindingKind.Endpoint, vilket motsvarar bindningen tls-server-end-point som definieras av RFC 5929. Andra bindningstyper returnerar false. Ett otillgängligt token returnerar false också. CBT-exponering kräver Medium eller Strictautentiseringshärdning som tillämpas av HTTP.sys.

Att hämta CBT-byte autentiserar inte i sig en begäran eller framtvingar Strict härdning. De returnerade byteen innehåller Windows SEC_CHANNEL_BINDINGS struktur och dess bindningsdata, inte bara en certifikathash.

Få detaljerad tidsinformation med IHttpSysRequestTimingFeature

IHttpSysRequestTimingFeature innehåller detaljerad tidsinformation för begäranden:

  • Tidsstämplar hämtas med hjälp av QueryPerformanceCounter.
  • Tidsstämpelfrekvensen kan hämtas via QueryPerformanceFrequency.
  • Indexet för tidsinställningen kan överföras till HttpSysRequestTimingType för att veta vad tidpunkten representerar.
  • Värdet kan vara 0 om tidpunkten inte är tillgänglig för den aktuella begäran.
  • Kräver Windows 10 version 2004, Windows Server 2022 eller senare.
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 hämtar tidsstämpeln för den angivna tidskategorin:

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 ger den förflutna tiden mellan två angivna tidpunkter:

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();

Avancerade HTTP/2-funktioner för att stödja gRPC

Ytterligare HTTP/2-funktioner i HTTP.sys stöder gRPC, inklusive stöd för svarstrailer och sändning av återställningsramar.

Krav för att köra gRPC med HTTP.sys:

  • Windows 11 Build 22000 eller senare Windows Server 2022 Build 20348 eller senare.
  • TLS 1.2 eller senare anslutning.

Trailers

HTTP-trailers liknar HTTP-huvuden, förutom att de skickas efter att svarstexten har skickats. För IIS och HTTP.sysstöds endast HTTP/2-svarstrailer.

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

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

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

I föregående exempelkod:

  • SupportsTrailers ser till att trailers stöds för HTTP-svaret.
  • DeclareTrailer lägger till det angivna trailernamnet i Trailer-svarshuvudet. Att deklarera ett svars släpvagnar är valfritt, men rekommenderas. Om DeclareTrailer anropas måste det vara innan svarsrubrikerna skickas.
  • AppendTrailer lägger till trailer.

Reset

Med återställning kan servern återställa en HTTP/2-begäran med en angiven felkod. En återställningsbegäran anses avbruten.

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

Reset I föregående kodexempel anges INTERNAL_ERROR felkoden. Mer information om HTTP/2-felkoder finns i avsnittet HTTP/2-specifikationsfelkod.

Tracing

Information om hur du hämtar spårningar från HTTP.sysfinns i HTTP.sys Hanterbarhetsscenarier.

Automatisk borttagning från minnespoolen

Minnespoolerna som används av Kestrel, IIS och HTTP.sys avlägsnar automatiskt minnesblock när programmet är inaktivt eller under låg belastning. Funktionen körs automatiskt och behöver inte aktiveras eller konfigureras manuellt.

I versioner av .NET tidigare än 10 förblir minne som allokerats av poolen reserverat, även om det inte används. Den här funktionen för automatisk borttagning minskar den totala minnesanvändningen och hjälper program att hålla sig responsiva under varierande arbetsbelastningar.

Använd mått för minnespooler

Standardminnespoolen som används av ASP.NET Core serverimplementeringar innehåller mått som kan användas för att övervaka och analysera minnesanvändningsmönster. Mätvärdena finns under namnet "Microsoft.AspNetCore.MemoryPool".

Information om mått och hur du använder dem finns i ASP.NET Core mått.

Hantera minnespooler

Förutom att använda minnespooler effektivt genom att avlägsna onödiga minnesblock tillhandahåller ASP.NET Core en inbyggd IMemoryPoolFactory och en implementering. Det gör implementeringen tillgänglig för ditt program via beroendeinmatning.

I följande kodexempel visas en enkel bakgrundstjänst som använder den inbyggda implementeringen av minnespoolfabriken för att skapa minnespooler. Dessa pooler drar nytta av funktionen för automatisk borttagning:

public class MyBackgroundService : BackgroundService
{
    private readonly MemoryPool<byte> _memoryPool;

    public MyBackgroundService(IMemoryPoolFactory<byte> factory)
    {
        _memoryPool = factory.Create();
    }

    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        while (!stoppingToken.IsCancellationRequested)
        {
            try
            {
                await Task.Delay(20, stoppingToken);
                // do work that needs memory
                // consider checking _memoryPool.MaxBufferSize
                var rented = _memoryPool.Rent(100);
                rented.Dispose();
            }
            catch (OperationCanceledException)
            {
                return;
            }
        }
    }
}

Om du vill använda en anpassad minnespoolfabrik skapar du en klass som implementerar IMemoryPoolFactory och registrerar den med beroendeinmatning, som i följande exempel. Minnespooler som skapats på det här sättet drar inte nytta av funktionen för automatisk borttagning om du inte implementerar liknande borttagningslogik i din anpassade fabrik:

services.AddSingleton<IMemoryPoolFactory<byte>,
CustomMemoryPoolFactory>();

public class CustomMemoryPoolFactory : IMemoryPoolFactory<byte>
{
    public MemoryPool<byte> Create()
    {
        // Return a custom MemoryPool implementation
        // or the default, as is shown here.
        return MemoryPool<byte>.Shared;
    }
}

När du använder en minnespool bör du vara medveten om poolens MaxBufferSize.

Note

Dokumentationslänkar till .NET-referenskällan läser vanligtvis in lagringsplatsens standardgren, vilket representerar den aktuella utvecklingen för nästa version av .NET. Om du vill välja en tagg för en specifik version använder du listrutan Välj bland grenar eller taggar.