Kommentar
Åtkomst till den här sidan kräver auktorisering. Du kan prova att logga in eller ändra kataloger.
Åtkomst till den här sidan kräver auktorisering. Du kan prova att ändra kataloger.
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.
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 ä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:
- Windows Server 2016/Windows 10 eller senare
- Application-Layer Protocol Negotiation (ALPN)-anslutning
- TLS 1.2 eller senare anslutning
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
httpsurl-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:
Konfigurera Windows Server
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.
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.
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.
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.
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:- UseUrls
-
urlskommandoradsargument -
ASPNETCORE_URLSmiljövariabel - UrlPrefixes
Följande kodexempel visar hur du använder UrlPrefixes med serverns lokala IP-adress
10.0.0.4på 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 iUseUrls/urls/ASPNETCORE_URLS. Därför är en fördel medUseUrls,urlsochASPNETCORE_URLSmiljö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 ärhttp://*:5000och något annat är bundet till port 5000 används inte den här bindningen. -
+är en specifik bindning. Om URL-prefixet ärhttp://+:5000används den här bindningen före andra port 5000-bindningar.
Mer information finns i UrlPrefix Strings.
Warning
Jokerteckenbindningar på toppnivå (
http://*:80/ochhttp://+: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_PORTSochHTTPS_PORTSär konfigurationsnycklar som anger lyssnarportarna för servrarna Kestrel och HTTP.sys. Du kan ange nycklarna som miljövariabler som definierats med prefixenDOTNET_ellerASPNETCORE_ange dem direkt via andra konfigurationsindata, till exempelappsettings.jsonfilen. 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;8081Konfigurationen 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_PORTSochHTTPS_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_PORTSochASPNETCORE_HTTPS_PORTSmiljövariabeln, som anger portarna för Kestrel/HTTP.sys slutpunktskonfiguration, med konfigurationsnyckelnHTTPS_PORTochASPNETCORE_HTTPS_PORTmiljö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.
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=UsersNä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>-
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:
-
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.
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.
-
propertyIdanger ett värde från den ursprungligaHTTP_REQUEST_PROPERTY-uppräkningen. -
qualifierinnehåller valfria egenskapsspecifika byte. En tom span skickas till Windows som en nullpekare. -
outputtar emot de ursprungliga byten. Anroparen måste tolka dem med hjälp av motsvarande inbyggda datastruktur. -
bytesReturnedinnehå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:
-
SupportsTrailersser till att trailers stöds för HTTP-svaret. -
DeclareTrailerlägger till det angivna trailernamnet iTrailer-svarshuvudet. Att deklarera ett svars släpvagnar är valfritt, men rekommenderas. OmDeclareTraileranropas måste det vara innan svarsrubrikerna skickas. -
AppendTrailerlä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.
Relaterat innehåll
- Aktivera Windows-autentisering med HTTP.sys
- HTTP Server-API
- HTTP.sys implementering i ASP.NET Core-repot (källkod)
- Värd
- Felsöka och debugga ASP.NET Core-projekt
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.
ASP.NET Core