Delen via


HTTP.sys webserver-implementatie in ASP.NET Core

Notitie

Dit is niet de nieuwste versie van dit artikel. Zie de .NET 9-versie van dit artikelvoor de huidige release.

Waarschuwing

Deze versie van ASP.NET Core wordt niet meer ondersteund. Zie de .NET- en .NET Core-ondersteuningsbeleidvoor meer informatie. Zie de .NET 9-versie van dit artikelvoor de huidige release.

Belangrijk

Deze informatie heeft betrekking op een pre-releaseproduct dat aanzienlijk kan worden gewijzigd voordat het commercieel wordt uitgebracht. Microsoft geeft geen garanties, uitdrukkelijk of impliciet, met betrekking tot de informatie die hier wordt verstrekt.

Zie de .NET 9-versie van dit artikelvoor de huidige release.

Door Tom Dykstra en Chris Ross

HTTP.sys is een webserver voor ASP.NET Core die alleen in Windows wordt uitgevoerd. HTTP.sys is een alternatief voor Kestrel server en biedt enkele functies die Kestrel niet biedt.

Belangrijk

HTTP.sys is niet compatibel met de ASP.NET Core Module en kan niet worden gebruikt met IIS of IIS Express.

HTTP.sys ondersteunt de volgende functies:

  • Windows-verificatie
  • Poort delen
  • HTTPS met SNI
  • HTTP/2 via TLS (Windows 10 of hoger)
  • Directe bestandsoverdracht
  • Antwoordcaching
  • WebSockets (Windows 8 of hoger)

Ondersteunde Windows-versies:

  • Windows 7 of hoger
  • Windows Server 2008 R2 of hoger

Voorbeeldcode bekijken of downloaden (hoe te downloaden)

Wanneer gebruikt u HTTP.sys

HTTP.sys is handig voor implementaties waarbij:

  • Er is een noodzaak om de server rechtstreeks beschikbaar te maken op internet zonder IIS te gebruiken.

    HTTP.sys rechtstreeks communiceert met internet

  • Voor een interne implementatie is een functie vereist die niet beschikbaar is in Kestrel. Zie Kestrel versus HTTP.sys voor meer informatie

    HTTP.sys rechtstreeks communiceert met het interne netwerk

HTTP.sys is een volwassen technologie die beschermt tegen veel soorten aanvallen en die de robuustheid, beveiliging en schaalbaarheid van een volledig uitgeruste webserver biedt. IIS zelf wordt uitgevoerd als een HTTP-listener boven op HTTP.sys.

HTTP/2-ondersteuning

HTTP/2- is ingeschakeld voor ASP.NET Core-apps wanneer aan de volgende basisvereisten wordt voldaan:

  • Windows Server 2016/Windows 10 of hoger
  • Application-Layer ALPN--verbinding (Protocol Negotiation)
  • TLS 1.2- of hogerverbinding

Als er een HTTP/2-verbinding tot stand is gebracht, rapporteert HttpRequest.ProtocolHTTP/2.

HTTP/2 is standaard ingeschakeld. Als er geen HTTP/2-verbinding tot stand is gebracht, valt de verbinding terug op HTTP/1.1. In een toekomstige release van Windows zijn HTTP/2-configuratievlagmen beschikbaar, inclusief de mogelijkheid om HTTP/2 uit te schakelen met HTTP.sys.

HTTP/3-ondersteuning

HTTP/3- is ingeschakeld voor ASP.NET Core-apps wanneer aan de volgende basisvereisten wordt voldaan:

Voor de voorgaande versies van Windows 11 Build is mogelijk het gebruik van een Windows Insider-build vereist.

HTTP/3 wordt gedetecteerd als een upgrade van HTTP/1.1 of HTTP/2 via de alt-svc-header. Dat betekent dat de eerste aanvraag normaal gesproken HTTP/1.1 of HTTP/2 gebruikt voordat u overschakelt naar HTTP/3. Http.Sys voegt niet automatisch de alt-svc header toe. Deze moet worden toegevoegd door de toepassing. De volgende code is een middleware-voorbeeld waarmee de alt-svc antwoordheader wordt toegevoegd.

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

Plaats de voorgaande code vroeg in de aanvraagpijplijn.

Http.Sys biedt ook ondersteuning voor het verzenden van een Http/2-protocolbericht van AltSvc in plaats van een antwoordheader om de client op de hoogte te stellen dat HTTP/3 beschikbaar is. Zie de registersleutel EnableAltSvc. Hiervoor zijn netsh sslcert-bindingen vereist die hostnamen gebruiken in plaats van IP-adressen.

Verificatie in kernelmodus met Kerberos

HTTP.sys delegeert verificatie naar de kernelmodus met het Kerberos-verificatieprotocol. Verificatie van de gebruikersmodus wordt niet ondersteund met Kerberos en HTTP.sys. Het computeraccount moet worden gebruikt om het Kerberos-token/ticket dat is verkregen uit Active Directory te ontsleutelen en door de client door te sturen naar de server om de gebruiker te verifiëren. Registreer de SPN (Service Principal Name) voor de host, niet de gebruiker van de app.

Ondersteuning voor reactiebuffers in kernelmodus

In sommige scenario's kunnen grote hoeveelheden kleine schrijfbewerkingen met hoge latentie aanzienlijke invloed hebben op de prestaties van HTTP.sys. Dit heeft te maken met het ontbreken van een Pipe buffer in de HTTP.sys implementatie. Ter verbetering van de prestaties in deze scenario's wordt ondersteuning voor reactiebuffering opgenomen in HTTP.sys. Schakel buffering in door HttpSysOptions.EnableKernelResponseBuffering- in te stellen op true.

Reactiebuffering moet worden ingeschakeld door een app die synchrone I/O uitvoert of asynchrone I/O met niet meer dan één openstaande schrijfbewerking tegelijk. In deze scenario's kan reactiebuffering de doorvoer aanzienlijk verbeteren via verbindingen met hoge latentie.

Apps die gebruikmaken van asynchrone I/O en die mogelijk meerdere schrijfbewerkingen tegelijk hebben, moeten deze vlag niet gebruiken. Als u deze vlag inschakelt, kan dit leiden tot een hoger CPU- en geheugengebruik door HTTP.Sys.

HTTP.sys gebruiken

De ASP.NET Core-app configureren voor gebruik van HTTP.sys

Roep de UseHttpSys-extensiemethode aan bij het bouwen van de host, waarbij u eventuele vereiste HttpSysOptionsopgeeft. In het volgende voorbeeld worden opties ingesteld op de standaardwaarden:

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

Aanvullende HTTP.sys configuratie wordt afgehandeld via registerinstellingen.

Zie HttpSysOptionsvoor meer informatie over HTTP.sys opties.

MaxRequestBodySize

De maximaal toegestane grootte van elke aanvraagbody in bytes. Wanneer deze is ingesteld op null, is de maximale grootte van de aanvraagbody onbeperkt. Deze limiet heeft geen invloed op bijgewerkte verbindingen, die altijd onbeperkt zijn.

De aanbevolen methode voor het overschrijven van de limiet in een ASP.NET Core MVC-app voor één IActionResult is het gebruik van het kenmerk RequestSizeLimitAttribute voor een actiemethode:

[RequestSizeLimit(100000000)]
public IActionResult MyActionMethod()

Er wordt een uitzondering gegenereerd als de app de limiet voor een aanvraag probeert te configureren nadat de app de aanvraag heeft gelezen. Een IsReadOnly eigenschap kan worden gebruikt om aan te geven of de eigenschap MaxRequestBodySize de status Alleen-lezen heeft, wat betekent dat het te laat is om de limiet te configureren.

Als de app MaxRequestBodySize voor elke aanvraag moet overschrijven, gebruikt u de 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);
});

Als u Visual Studio gebruikt, controleert u of de app niet is geconfigureerd voor het uitvoeren van IIS of IIS Express.

In Visual Studio is het standaardlanceringsprofiel voor IIS Express. Als u het project wilt uitvoeren als console-app, wijzigt u het geselecteerde profiel handmatig, zoals wordt weergegeven in de volgende schermopname:

console-app-profiel selecteren

Windows Server configureren

  1. Bepaal de poorten die moeten worden geopend voor de app en gebruik Windows Firewall- of de New-NetFirewallRule PowerShell-cmdlet om firewallpoorten te openen zodat verkeer HTTP.syskan bereiken. In de volgende opdrachten en app-configuratie wordt poort 443 gebruikt.

  2. Wanneer u implementeert op een Virtuele Azure-machine, opent u de poorten in de netwerkbeveiligingsgroep. In de volgende opdrachten en app-configuratie wordt poort 443 gebruikt.

  3. U kunt indien nodig X.509-certificaten verkrijgen en installeren.

    Maak in Windows zelfondertekende certificaten met behulp van de New-SelfSignedCertificate PowerShell-cmdlet. Zie UpdateIISExpressSSLForChrome.ps1voor een niet-ondersteund voorbeeld.

    Installeer zelfondertekende of door CA ondertekende certificaten in het lokale computer van de server>Persoonlijke archief.

  4. Als de app een frameworkafhankelijke implementatie is, installeert u .NET Core, .NET Framework of beide (als de app een .NET Core-app is die is gericht op .NET Framework).

    • .NET Core-: Als de app .NET Core vereist, moet u het .NET Core Runtime-installatieprogramma ophalen en uitvoeren vanuit .NET Core Downloads. Installeer de volledige SDK niet op de server.
    • .NET Framework-: als voor de app .NET Framework is vereist, raadpleegt u de .NET Framework-installatiehandleiding. Installeer het vereiste .NET Framework. Het installatieprogramma voor het nieuwste .NET Framework is beschikbaar op de pagina .NET Core Downloads.

    Als de app een zelfstandige implementatie is, bevat de app de runtime in de implementatie. Er is geen frameworkinstallatie vereist op de server.

  5. Configureer URLs en poorten in de app.

    Standaard wordt ASP.NET Core gebonden aan http://localhost:5000. Voor het configureren van URL-voorvoegsels en poorten zijn onder andere de volgende opties:

    In het volgende codevoorbeeld ziet u hoe u UrlPrefixes gebruikt met het lokale IP-adres van de server 10.0.0.4 op poort 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();
    

    Een voordeel van UrlPrefixes is dat er direct een foutbericht wordt gegenereerd voor onjuist opgemaakte voorvoegsels.

    De instellingen in UrlPrefixes overschrijven UseUrls/urls/ASPNETCORE_URLS instellingen. Daarom is een voordeel van UseUrls, urlsen de omgevingsvariabele ASPNETCORE_URLS dat het gemakkelijker is om tussen Kestrel en HTTP.syste schakelen.

    HTTP.sys herkent twee typen jokertekens in URL-voorvoegsels:

    • * is een zwakke binding, ook wel een terugvalbinding genoemd. Als het URL-voorvoegsel is http://*:5000en iets anders is gebonden aan poort 5000, wordt deze binding niet gebruikt.
    • + is een sterke binding. Als het URL-voorvoegsel http://+:5000is, wordt deze binding gebruikt voor andere poort 5000-bindingen.

    Zie UrlPrefix-tekenreeksenvoor meer informatie.

    Waarschuwing

    Jokertekenbindingen op het hoogste niveau (http://*:80/ en http://+:80) mogen niet worden gebruikt. Jokertekenbindingen op het hoogste niveau creëren beveiligingskwetsbaarheden in applicaties. Dit geldt zowel voor sterke als zwakke jokertekens. Gebruik expliciete hostnamen of IP-adressen in plaats van jokertekens. Subdomeinbinding met wildcards (bijvoorbeeld *.mysub.com) vormt geen beveiligingsrisico als u de controle heeft over het gehele bovenliggende domein, in tegenstelling tot *.com, dat kwetsbaar is. Zie RFC 9110: Sectie 7.2: Host en :authorityvoor meer informatie.

    Apps en containers krijgen vaak alleen een poort om op te luisteren, zoals poort 80, zonder extra beperkingen, zoals host of pad. HTTP_PORTS en HTTPS_PORTS zijn configuratiesleutels waarmee de luisterpoorten voor de Kestrel- en HTTP.sys-servers worden opgegeven. Deze sleutels kunnen worden opgegeven als omgevingsvariabelen die zijn gedefinieerd met de DOTNET_ of ASPNETCORE_ voorvoegsels, of rechtstreeks worden opgegeven via andere configuratie-invoer, zoals appsettings.json. Elk is een door puntkomma's gescheiden lijst met poortwaarden, zoals wordt weergegeven in het volgende voorbeeld:

    ASPNETCORE_HTTP_PORTS=80;8080
    ASPNETCORE_HTTPS_PORTS=443;8081
    

    Het voorgaande voorbeeld is een afkorting voor de volgende configuratie, waarmee het schema (HTTP of HTTPS) en een host of IP wordt opgegeven.

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

    De HTTP_PORTS en HTTPS_PORTS configuratiesleutels hebben een lagere prioriteit en worden overschreven door URL's of waarden die rechtstreeks in code worden geleverd. Certificaten moeten nog steeds afzonderlijk worden geconfigureerd via serverspecifieke mechanica voor HTTPS.

    Deze configuratiesleutels zijn gelijk aan wildcardbindingen van het hoogste niveau. Ze zijn handig voor ontwikkelings- en containerscenario's, maar vermijd jokertekens bij het uitvoeren op een computer die ook andere services kan hosten.

  6. Url-voorvoegsels vooraf registreren op de server.

    Het ingebouwde hulpprogramma voor het configureren van HTTP.sys is netsh.exe. netsh.exe wordt gebruikt om URL-voorvoegsels te reserveren en X.509-certificaten toe te wijzen. Voor het hulpprogramma zijn beheerdersbevoegdheden vereist.

    Gebruik het hulpprogramma netsh.exe om URL's voor de app te registreren:

    netsh http add urlacl url=<URL> user=<USER>
    
    • <URL>: de volledig gekwalificeerde URL (Uniform Resource Locator). Gebruik geen wildcardbinding. Gebruik een geldige hostnaam of een lokaal IP-adres. De URL moet een afsluitende slash bevatten.
    • <USER>: hiermee geeft u de naam van de gebruiker of de gebruikersgroep op.

    In het volgende voorbeeld wordt het lokale IP-adres van de server 10.0.0.4:

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

    Wanneer een URL is geregistreerd, reageert het hulpprogramma met URL reservation successfully added.

    Als u een geregistreerde URL wilt verwijderen, gebruikt u de opdracht delete urlacl:

    netsh http delete urlacl url=<URL>
    
  7. X.509-certificaten registreren op de server.

    Gebruik het hulpprogramma netsh.exe om certificaten voor de app te registreren:

    netsh http add sslcert ipport=<IP>:<PORT> certhash=<THUMBPRINT> appid="{<GUID>}"
    
    • <IP>: hiermee geeft u het lokale IP-adres voor de binding op. Gebruik geen wildcardbinding. Gebruik een geldig IP-adres.
    • <PORT>: hiermee geeft u de poort voor de binding op.
    • <THUMBPRINT>: de vingerafdruk van het X.509-certificaat.
    • <GUID>: een door ontwikkelaars gegenereerde GUID die de app vertegenwoordigt voor informatieve doeleinden.

    Voor referentiedoeleinden slaat u de GUID in de app op als pakkettag:

    • In Visual Studio:
      • Open de projecteigenschappen van de app door met de rechtermuisknop op de app te klikken in Solution Explorer- en Eigenschappente selecteren.
      • Klik op het tabblad Pakket.
      • Voer de GUID in die u hebt gemaakt in het veld Tags.
    • Wanneer u Visual Studio niet gebruikt:
      • Open het projectbestand van de app.

      • Voeg een <PackageTags> eigenschap toe aan een nieuwe of bestaande <PropertyGroup> met de GUID die u hebt gemaakt:

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

    In het volgende voorbeeld:

    • Het lokale IP-adres van de server is 10.0.0.4.
    • Een online willekeurige GUID-generator biedt de waarde appid.
    netsh http add sslcert 
        ipport=10.0.0.4:443 
        certhash=b66ee04419d4ee37464ab8785ff02449980eae10 
        appid="{00001111-aaaa-2222-bbbb-3333cccc4444}"
    

    Wanneer een certificaat is geregistreerd, reageert het hulpprogramma met SSL Certificate successfully added.

    Als u een certificaatregistratie wilt verwijderen, gebruikt u de opdracht delete sslcert:

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

    Referentiedocumentatie voor netsh.exe:

  8. Voer de app uit.

    Beheerdersbevoegdheden zijn niet vereist om de app uit te voeren wanneer de app wordt gekoppeld aan localhost met behulp van HTTP (niet HTTPS) met een poortnummer dat groter is dan 1024. Voor andere configuraties (bijvoorbeeld met behulp van een lokaal IP-adres of binding met poort 443), voert u de app uit met beheerdersbevoegdheden.

    De app reageert op het openbare IP-adres van de server. In dit voorbeeld wordt de server bereikt vanaf internet op het openbare IP-adres van 104.214.79.47.

    In dit voorbeeld wordt een ontwikkelingscertificaat gebruikt. De pagina wordt veilig geladen nadat de waarschuwing over het niet-vertrouwde certificaat van de browser is overgeslagen.

    Browservenster toont de Indexpagina van de app geladen

Scenario's voor proxyserver en load balancer

Voor apps die worden gehost door HTTP.sys die communiceren met aanvragen van internet of een bedrijfsnetwerk, is mogelijk extra configuratie vereist bij het hosten achter proxyservers en load balancers. Zie ASP.NET Core configureren voor gebruik met proxyservers en load balancersvoor meer informatie.

Gedetailleerde timing-informatie ophalen met IHttpSysRequestTimingFeature

IHttpSysRequestTimingFeature biedt gedetailleerde tijdsinformatie voor aanvragen:

  • Tijdstempels worden verkregen met QueryPerformanceCounter.
  • De tijdstempelfrequentie kan worden verkregen via QueryPerformanceFrequency.
  • De index van de timing kan worden gecast naar HttpSysRequestTimingType om te begrijpen wat de timing inhoudt.
  • De waarde kan 0 zijn als de timing niet beschikbaar is voor de huidige aanvraag.
  • Vereist Windows 10 versie 2004, Windows Server 2022 of hoger.
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 haalt de tijdstempel voor het opgegeven tijdstype op:

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](/dotnet/api/microsoft.aspnetcore.server.httpsys.ihttpsysrequesttimingfeature.trygetelapsedtime) levert de verstreken tijd op tussen twee opgegeven tijdmetingen:

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

Geavanceerde HTTP/2-functies ter ondersteuning van gRPC

Aanvullende HTTP/2-functies in HTTP.sys ondersteunen gRPC, waaronder ondersteuning voor reactietrailers en het verzenden van resetframes.

Vereisten voor het uitvoeren van gRPC met HTTP.sys:

  • Windows 11 Build 22000 of hoger, Windows Server 2022 Build 20348 of hoger.
  • TLS 1.2- of hogerverbinding.

Trailers

HTTP-trailers zijn vergelijkbaar met HTTP-headers, behalve dat ze worden verzonden nadat de hoofdtekst van het antwoord is verzonden. Voor IIS en HTTP.sysworden alleen HTTP/2-antwoordtrailers ondersteund.

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

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

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

In de voorgaande voorbeeldcode:

  • SupportsTrailers zorgt ervoor dat trailers voor de respons worden ondersteund.
  • DeclareTrailer voegt de opgegeven trailernaam toe aan de Trailer antwoordheader. Het declareren van de aanhangwagens van een antwoord is optioneel, maar wordt aanbevolen. Als DeclareTrailer wordt aangeroepen, moet dit zijn voordat de antwoordheaders worden verzonden.
  • AppendTrailer voegt de trailer toe.

Opnieuw instellen

Met opnieuw instellen kan de server een HTTP/2-aanvraag opnieuw instellen met een opgegeven foutcode. Een resetverzoek wordt beschouwd als afgebroken.

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

Reset in het voorgaande codevoorbeeld geeft de INTERNAL_ERROR foutcode op. Ga voor meer informatie over HTTP/2-foutcodes naar de sectie met foutcodes van de HTTP/2-specificatie.

Tracering

Zie HTTP.sys Scenario's voor beheerbaarheidvoor informatie over het ophalen van traceringen uit HTTP.sys.

Aanvullende informatiebronnen

HTTP.sys is een webserver voor ASP.NET Core die alleen in Windows wordt uitgevoerd. HTTP.sys is een alternatief voor Kestrel server en biedt enkele functies die Kestrel niet biedt.

Belangrijk

HTTP.sys is niet compatibel met de ASP.NET Core Module en kan niet worden gebruikt met IIS of IIS Express.

HTTP.sys ondersteunt de volgende functies:

  • Windows-verificatie
  • Poort delen
  • HTTPS met SNI
  • HTTP/2 via TLS (Windows 10 of hoger)
  • Directe bestandsoverdracht
  • Antwoordcaching
  • WebSockets (Windows 8 of hoger)

Ondersteunde Windows-versies:

  • Windows 7 of hoger
  • Windows Server 2008 R2 of hoger

voorbeeldcode weergeven of downloaden (hoe te downloaden)

Wanneer gebruikt u HTTP.sys

HTTP.sys is handig voor implementaties waarbij:

  • Er is een noodzaak om de server rechtstreeks beschikbaar te maken op internet zonder IIS te gebruiken.

    HTTP.sys rechtstreeks communiceert met internet

  • Voor een interne implementatie is een functie vereist die niet beschikbaar is in Kestrel. Zie Kestrel versus HTTP.sys voor meer informatie

    HTTP.sys rechtstreeks communiceert met het interne netwerk

HTTP.sys is een volwassen technologie die beschermt tegen veel soorten aanvallen en die de robuustheid, beveiliging en schaalbaarheid van een volledig uitgeruste webserver biedt. IIS zelf wordt uitgevoerd als een HTTP-listener boven op HTTP.sys.

HTTP/2-ondersteuning

HTTP/2- is ingeschakeld voor ASP.NET Core-apps wanneer aan de volgende basisvereisten wordt voldaan:

  • Windows Server 2016/Windows 10 of hoger
  • Application-Layer ALPN--verbinding (Protocol Negotiation)
  • TLS 1.2- of hogerverbinding

Als er een HTTP/2-verbinding tot stand is gebracht, rapporteert HttpRequest.ProtocolHTTP/2.

HTTP/2 is standaard ingeschakeld. Als er geen HTTP/2-verbinding tot stand is gebracht, valt de verbinding terug op HTTP/1.1. In een toekomstige release van Windows zijn HTTP/2-configuratievlagmen beschikbaar, inclusief de mogelijkheid om HTTP/2 uit te schakelen met HTTP.sys.

HTTP/3-ondersteuning

HTTP/3- is ingeschakeld voor ASP.NET Core-apps wanneer aan de volgende basisvereisten wordt voldaan:

Voor de voorgaande versies van Windows 11 Build is mogelijk het gebruik van een Windows Insider-build vereist.

HTTP/3 wordt gedetecteerd als een upgrade van HTTP/1.1 of HTTP/2 via de alt-svc-header. Dat betekent dat de eerste aanvraag normaal gesproken HTTP/1.1 of HTTP/2 gebruikt voordat u overschakelt naar HTTP/3. Http.Sys voegt niet automatisch de alt-svc header toe. Deze moet worden toegevoegd door de toepassing. De volgende code is een middleware-voorbeeld waarmee de alt-svc antwoordheader wordt toegevoegd.

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

Plaats de voorgaande code vroeg in de aanvraagpijplijn.

Http.Sys biedt ook ondersteuning voor het verzenden van een Http/2-protocolbericht van AltSvc in plaats van een antwoordheader om de client op de hoogte te stellen dat HTTP/3 beschikbaar is. Bekijk de registersleutel EnableAltSvc. Hiervoor zijn netsh sslcert-bindingen vereist die hostnamen gebruiken in plaats van IP-adressen.

Verificatie in kernelmodus met Kerberos

HTTP.sys delegeert naar de kernelmodus-verificatie met het Kerberos-verificatieprotocol. Verificatie van de gebruikersmodus wordt niet ondersteund met Kerberos en HTTP.sys. Het computeraccount moet worden gebruikt om het Kerberos-token/ticket dat is verkregen uit Active Directory te ontsleutelen en door de client door te sturen naar de server om de gebruiker te verifiëren. Registreer de SPN (Service Principal Name) voor de host, niet de gebruiker van de app.

HTTP.sys gebruiken

De ASP.NET Core-app configureren voor gebruik van HTTP.sys

Roep de UseHttpSys-extensiemethode aan bij het bouwen van de host, waarbij u eventuele vereiste HttpSysOptionsopgeeft. In het volgende voorbeeld worden opties ingesteld op de standaardwaarden:

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

Aanvullende HTTP.sys configuratie wordt verwerkt via registerinstellingen.

Zie HttpSysOptionsvoor meer informatie over HTTP.sys opties.

MaxRequestBodySize

De maximaal toegestane grootte van elke aanvraagbody in bytes. Wanneer deze is ingesteld op null, is de maximale grootte van de aanvraagbody onbeperkt. Deze limiet heeft geen invloed op bijgewerkte verbindingen, die altijd onbeperkt zijn.

De aanbevolen methode voor het overschrijven van de limiet in een ASP.NET Core MVC-app voor één IActionResult is het gebruik van het kenmerk RequestSizeLimitAttribute voor een actiemethode:

[RequestSizeLimit(100000000)]
public IActionResult MyActionMethod()

Er wordt een uitzondering gegenereerd als de app de limiet voor een aanvraag probeert te configureren nadat de app de aanvraag heeft gelezen. Een IsReadOnly eigenschap kan worden gebruikt om aan te geven of de eigenschap MaxRequestBodySize de status Alleen-lezen heeft, wat betekent dat het te laat is om de limiet te configureren.

Als de app MaxRequestBodySize per verzoek moet overschrijven, gebruik dan de 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();
    });
}

Als u Visual Studio gebruikt, controleert u of de app niet is geconfigureerd voor het uitvoeren van IIS of IIS Express.

In Visual Studio is het standaardlanceringsprofiel voor IIS Express. Als u het project wilt uitvoeren als console-app, wijzigt u het geselecteerde profiel handmatig, zoals wordt weergegeven in de volgende schermopname:

console-app-profiel selecteren

Windows Server configureren

  1. Bepaal de poorten die moeten worden geopend voor de app en gebruik Windows Firewall- of de New-NetFirewallRule PowerShell-cmdlet om firewallpoorten te openen zodat verkeer HTTP.syskan bereiken. In de volgende opdrachten en app-configuratie wordt poort 443 gebruikt.

  2. Wanneer u implementeert op een Virtuele Azure-machine, opent u de poorten in de netwerkbeveiligingsgroep. In de volgende opdrachten en app-configuratie wordt poort 443 gebruikt.

  3. U kunt indien nodig X.509-certificaten verkrijgen en installeren.

    Maak in Windows zelfondertekende certificaten met behulp van de New-SelfSignedCertificate PowerShell-cmdlet. Zie UpdateIISExpressSSLForChrome.ps1voor een niet-ondersteund voorbeeld.

    Installeer zelfondertekende of door een CA ondertekende certificaten in de lokale computer van de server>persoonlijke opslag.

  4. Als de app een frameworkafhankelijke implementatie is, installeert u .NET Core, .NET Framework of beide (als de app een .NET Core-app is die is gericht op .NET Framework).

    • .NET Core-: Als de app .NET Core vereist, moet u het .NET Core Runtime--installatieprogramma downloaden en uitvoeren van .NET Core Downloads. Installeer de volledige SDK niet op de server.
    • .NET Framework-: als voor de app .NET Framework is vereist, raadpleegt u de .NET Framework-installatiehandleiding. Installeer het vereiste .NET Framework. Het installatieprogramma voor het nieuwste .NET Framework is beschikbaar op de pagina .NET Core Downloads.

    Als de app een zelfstandige implementatieis, bevat de app de runtime in zijn implementatie. Er is geen frameworkinstallatie vereist op de server.

  5. Configureer URL's en poorten in de app.

    Standaard wordt ASP.NET Core gebonden aan http://localhost:5000. Voor het configureren van URL-voorvoegsels en poorten zijn onder andere de volgende opties:

    In het volgende codevoorbeeld ziet u hoe u UrlPrefixes gebruikt met het lokale IP-adres van de server 10.0.0.4 op poort 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>();
            });
    

    Een voordeel van UrlPrefixes is dat er direct een foutbericht wordt gegenereerd voor onjuist opgemaakte voorvoegsels.

    De instellingen in UrlPrefixes overschrijven UseUrls/urls/ASPNETCORE_URLS instellingen. Daarom is een voordeel van UseUrls, urlsen de omgevingsvariabele ASPNETCORE_URLS dat het gemakkelijker is om tussen Kestrel en HTTP.syste schakelen.

    HTTP.sys maakt gebruik van de URLPrefix-tekenreeksindelingen van de HTTP Server-API.

    Waarschuwing

    Jokertekenbindingen op het hoogste niveau (http://*:80/ en http://+:80) mogen niet worden gebruikt. Jokerteken-bindingen op het hoogste niveau creëren beveiligingskwetsbaarheden in apps. Dit geldt zowel voor sterke als zwakke jokertekens. Gebruik expliciete hostnamen of IP-adressen in plaats van jokertekens. Jokertekenbinding van subdomeinen (bijvoorbeeld *.mysub.com) is geen beveiligingsrisico als u het hele bovenliggende domein beheert (in tegenstelling tot *.com, dat kwetsbaar is). Zie RFC 9110: Sectie 7.2: Host en :authorityvoor meer informatie.

  6. Url-voorvoegsels vooraf registreren op de server.

    Het ingebouwde hulpprogramma voor het configureren van HTTP.sys is netsh.exe. netsh.exe wordt gebruikt om URL-voorvoegsels te reserveren en X.509-certificaten toe te wijzen. Voor het hulpprogramma zijn beheerdersbevoegdheden vereist.

    Gebruik het hulpprogramma netsh.exe om URL's voor de app te registreren:

    netsh http add urlacl url=<URL> user=<USER>
    
    • <URL>: de volledig gekwalificeerde URL (Uniform Resource Locator). Gebruik geen wildcard-binding. Gebruik een geldige hostnaam of een lokaal IP-adres. De URL moet een afsluitende slash bevatten.
    • <USER>: hiermee geeft u de naam van de gebruiker of de gebruikersgroep op.

    In het volgende voorbeeld wordt het lokale IP-adres van de server 10.0.0.4:

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

    Wanneer een URL is geregistreerd, reageert het hulpprogramma met URL reservation successfully added.

    Als u een geregistreerde URL wilt verwijderen, gebruikt u de opdracht delete urlacl:

    netsh http delete urlacl url=<URL>
    
  7. X.509-certificaten registreren op de server.

    Gebruik het hulpprogramma netsh.exe om certificaten voor de app te registreren:

    netsh http add sslcert ipport=<IP>:<PORT> certhash=<THUMBPRINT> appid="{<GUID>}"
    
    • <IP>: hiermee geeft u het lokale IP-adres voor de binding op. Gebruik geen wildcard-binding. Gebruik een geldig IP-adres.
    • <PORT>: hiermee geeft u de poort voor de binding op.
    • <THUMBPRINT>: de vingerafdruk van het X.509-certificaat.
    • <GUID>: een door ontwikkelaars gegenereerde GUID die de app vertegenwoordigt voor informatieve doeleinden.

    Voor referentiedoeleinden slaat u de GUID in de app op als pakkettag:

    • In Visual Studio:
      • Open de projecteigenschappen van de app door met de rechtermuisknop op de app te klikken in Solution Explorer- en Eigenschappente selecteren.
      • Selecteer het tabblad Pakket.
      • Voer de GUID in die u hebt gemaakt in het veld Tags.
    • Wanneer u Visual Studio niet gebruikt:
      • Open het projectbestand van de app.

      • Voeg een <PackageTags> eigenschap toe aan een nieuwe of bestaande <PropertyGroup> met de GUID die u hebt gemaakt:

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

    In het volgende voorbeeld:

    • Het lokale IP-adres van de server is 10.0.0.4.
    • Een online willekeurige GUID-generator biedt de appid waarde.
    netsh http add sslcert 
        ipport=10.0.0.4:443 
        certhash=b66ee04419d4ee37464ab8785ff02449980eae10 
        appid="{00001111-aaaa-2222-bbbb-3333cccc4444}"
    

    Wanneer een certificaat is geregistreerd, reageert het hulpprogramma met SSL Certificate successfully added.

    Als u een certificaatregistratie wilt verwijderen, gebruikt u de opdracht delete sslcert:

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

    Referentiedocumentatie voor netsh.exe:

  8. Voer de app uit.

    Beheerdersbevoegdheden zijn niet vereist om de app uit te voeren wanneer de app wordt gekoppeld aan localhost met behulp van HTTP (niet HTTPS) met een poortnummer dat groter is dan 1024. Voor andere configuraties (bijvoorbeeld met behulp van een lokaal IP-adres of binding met poort 443), voert u de app uit met beheerdersbevoegdheden.

    De app reageert op het openbare IP-adres van de server. In dit voorbeeld wordt de server bereikt vanaf internet op het openbare IP-adres van 104.214.79.47.

    In dit voorbeeld wordt een ontwikkelingscertificaat gebruikt. De pagina wordt veilig geladen nadat de waarschuwing over het niet-vertrouwde certificaat van de browser is overgeslagen.

    browservenster dat de Index-pagina van de app laadt

Scenario's voor proxyserver en load balancer

Voor apps die worden gehost door HTTP.sys die communiceren met aanvragen van internet of een bedrijfsnetwerk, is mogelijk extra configuratie vereist bij het hosten achter proxyservers en load balancers. Zie ASP.NET Core configureren voor gebruik met proxyservers en load balancersvoor meer informatie.

Geavanceerde HTTP/2-functies ter ondersteuning van gRPC

Aanvullende HTTP/2-functies in HTTP.sys ondersteunen gRPC, waaronder ondersteuning voor responstrailers en het verzenden van resetframes.

Vereisten voor het uitvoeren van gRPC met HTTP.sys:

  • Windows 11 Build 22000 of hoger, Windows Server 2022 Build 20348 of hoger.
  • TLS 1.2- of hogerverbinding.

Aanhangwagens

HTTP-trailers zijn vergelijkbaar met HTTP-headers, behalve dat ze worden verzonden nadat de hoofdtekst van het antwoord is verzonden. Voor IIS en HTTP.sysworden alleen HTTP/2-antwoordtrailers ondersteund.

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

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

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

In de voorgaande voorbeeldcode:

  • SupportsTrailers zorgt ervoor dat trailers worden ondersteund voor de reactie.
  • DeclareTrailer voegt de opgegeven trailernaam toe aan de Trailer antwoordheader. Het declareren van de aanhangwagens van een antwoord is optioneel, maar wordt aanbevolen. Als DeclareTrailer wordt aangeroepen, moet dit zijn voordat de antwoordheaders worden verzonden.
  • AppendTrailer voegt de trailer toe.

Resetten

Met opnieuw instellen kan de server een HTTP/2-aanvraag opnieuw instellen met een opgegeven foutcode. Een verzoek om te resetten wordt als afgebroken beschouwd.

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

Reset in het voorgaande codevoorbeeld geeft de INTERNAL_ERROR foutcode op. Ga voor meer informatie over HTTP/2-foutcodes naar de sectie met foutcodes van de HTTP/2-specificatie.

Aanvullende informatiebronnen

HTTP.sys is een webserver voor ASP.NET Core die alleen in Windows wordt uitgevoerd. HTTP.sys is een alternatief voor Kestrel server en biedt enkele functies die Kestrel niet biedt.

Belangrijk

HTTP.sys is niet compatibel met de ASP.NET Core Module en kan niet worden gebruikt met IIS of IIS Express.

HTTP.sys ondersteunt de volgende functies:

  • Windows-verificatie
  • Poort delen
  • HTTPS met SNI
  • HTTP/2 via TLS (Windows 10 of hoger)
  • Directe bestandsoverdracht
  • Antwoordcaching
  • WebSockets (Windows 8 of hoger)

Ondersteunde Windows-versies:

  • Windows 7 of hoger
  • Windows Server 2008 R2 of hoger

Voorbeeldcode bekijken of downloaden (hoe te downloaden)

Wanneer gebruikt u HTTP.sys

HTTP.sys is handig voor implementaties waarbij:

  • Er is een noodzaak om de server rechtstreeks beschikbaar te maken op internet zonder IIS te gebruiken.

    HTTP.sys rechtstreeks communiceert met internet

  • Voor een interne implementatie is een functie vereist die niet beschikbaar is in Kestrel. Zie Kestrel versus HTTP.sys voor meer informatie

    HTTP.sys rechtstreeks communiceert met het interne netwerk

HTTP.sys is een volwassen technologie die beschermt tegen veel soorten aanvallen en die de robuustheid, beveiliging en schaalbaarheid van een volledig uitgeruste webserver biedt. IIS zelf wordt uitgevoerd als een HTTP-listener boven op HTTP.sys.

HTTP/2-ondersteuning

HTTP/2- is ingeschakeld voor ASP.NET Core-apps als aan de volgende basisvereisten wordt voldaan:

Als er een HTTP/2-verbinding tot stand is gebracht, rapporteert HttpRequest.ProtocolHTTP/2.

HTTP/2 is standaard ingeschakeld. Als er geen HTTP/2-verbinding tot stand is gebracht, valt de verbinding terug op HTTP/1.1. In een toekomstige release van Windows zijn HTTP/2-configuratievlagmen beschikbaar, inclusief de mogelijkheid om HTTP/2 uit te schakelen met HTTP.sys.

Verificatie in kernelmodus met Kerberos

HTTP.sys delegeert naar kernelmodusverificatie met het Kerberos-verificatieprotocol. Verificatie van de gebruikersmodus wordt niet ondersteund met Kerberos en HTTP.sys. Het computeraccount moet worden gebruikt om het Kerberos-token/ticket dat is verkregen uit Active Directory te ontsleutelen en door de client door te sturen naar de server om de gebruiker te verifiëren. Registreer de SPN (Service Principal Name) voor de host, niet de gebruiker van de app.

HTTP.sys gebruiken

De ASP.NET Core-app configureren voor gebruik van HTTP.sys

Roep de UseHttpSys-extensiemethode aan bij het bouwen van de host, waarbij u eventuele vereiste HttpSysOptionsopgeeft. In het volgende voorbeeld worden opties ingesteld op de standaardwaarden:

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

Aanvullende HTTP.sys configuratie wordt afgehandeld via registerinstellingen.

HTTP.sys opties

Eigenschap Beschrijving Verstek
AllowSynchronousIO Bepalen of synchrone invoer/uitvoer is toegestaan voor de HttpContext.Request.Body en HttpContext.Response.Body. false
Authentication.AllowAnonymous Anonieme aanvragen toestaan. true
Authentication.Schemes Geef de toegestane verificatieschema's op. Kan op elk gewenst moment worden gewijzigd voordat de listener wordt ontbonden. Waarden worden opgegeven door de AuthenticationSchemes-: Basic, Kerberos, Negotiate, Noneen NTLM. None
EnableResponseCaching Probeer kernel-modus caching voor antwoorden met geschikte headers. Het antwoord bevat mogelijk geen Set-Cookie, Varyof Pragma headers. Het moet een Cache-Control-koptekst bevatten die public is en een shared-max-age- of max-age-waarde, of een Expires-koptekst. true
Http503Verbosity Het gedrag van HTTP.sys bij het afwijzen van aanvragen vanwege beperkingslimieten. Http503VerbosityLevel.
Basic
MaxAccepts Het maximale aantal gelijktijdige acceptaties. 5 × Omgeving.
ProcessorCount
MaxConnections Het maximum aantal gelijktijdige verbindingen dat moet worden geaccepteerd. Gebruik -1 voor oneindig. Gebruik null om de computerbrede instelling van het register te gebruiken. null
machine-breed
instelling)
MaxRequestBodySize Zie de sectie MaxRequestBodySize. 30000000 bytes
(~28,6 MB)
RequestQueueLimit Het maximum aantal aanvragen dat in de wachtrij kan worden geplaatst. 1000
RequestQueueMode Dit geeft aan of de server verantwoordelijk is voor het maken en configureren van de aanvraagwachtrij, of dat deze moet worden gekoppeld aan een bestaande wachtrij.
De meeste bestaande configuratieopties zijn niet van toepassing bij het koppelen aan een bestaande wachtrij.
RequestQueueMode.Create
RequestQueueName De naam van de HTTP.sys aanvraagwachtrij. null (anonieme wachtrij)
ThrowWriteExceptions Geef aan of schrijfbewerkingen die mislukken als gevolg van verbroken verbindingen van de client uitzonderingen moeten genereren of normaal moeten worden voltooid. false
(normaal voltooien)
Timeouts Maak de HTTP.sys TimeoutManager-configuratie beschikbaar, die ook in het register kan worden geconfigureerd. Volg de API-koppelingen voor meer informatie over elke instelling, inclusief standaardwaarden:
UrlPrefixes Geef UrlPrefixCollection op om te registreren bij HTTP.sys. Het handigste is UrlPrefixCollection.Add, dat wordt gebruikt om een voorvoegsel toe te voegen aan de verzameling. Deze kunnen op elk gewenst moment worden gewijzigd voordat de listener wordt ontbonden.

MaxRequestBodySize-

De maximaal toegestane grootte van elke aanvraagbody in bytes. Wanneer deze is ingesteld op null, is de maximale grootte van de aanvraagbody onbeperkt. Deze limiet heeft geen invloed op bijgewerkte verbindingen, die altijd onbeperkt zijn.

De aanbevolen methode voor het overschrijven van de limiet in een ASP.NET Core MVC-app voor één IActionResult is het gebruik van het kenmerk RequestSizeLimitAttribute voor een actiemethode:

[RequestSizeLimit(100000000)]
public IActionResult MyActionMethod()

Er wordt een uitzondering gegenereerd als de app de limiet voor een aanvraag probeert te configureren nadat de app de aanvraag heeft gelezen. Een IsReadOnly eigenschap kan worden gebruikt om aan te geven of de eigenschap MaxRequestBodySize de status Alleen-lezen heeft, wat betekent dat het te laat is om de limiet te configureren.

Als de app MaxRequestBodySize voor elke aanvraag moet overschrijven, gebruikt u de 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();
    });
}

Als u Visual Studio gebruikt, controleert u of de app niet is geconfigureerd voor het uitvoeren van IIS of IIS Express.

In Visual Studio is het standaardlanceringsprofiel voor IIS Express. Als u het project wilt uitvoeren als console-app, wijzigt u het geselecteerde profiel handmatig, zoals wordt weergegeven in de volgende schermafbeelding:

console-app-profiel selecteren

Windows Server configureren

  1. Bepaal de poorten die moeten worden geopend voor de app en gebruik Windows Firewall- of de New-NetFirewallRule PowerShell-cmdlet om firewallpoorten te openen zodat verkeer HTTP.syskan bereiken. In de volgende opdrachten en app-configuratie wordt poort 443 gebruikt.

  2. Wanneer u implementeert op een Virtuele Azure-machine, opent u de poorten in de netwerkbeveiligingsgroep. In de volgende opdrachten en app-configuratie wordt poort 443 gebruikt.

  3. U kunt indien nodig X.509-certificaten verkrijgen en installeren.

    Maak in Windows zelfondertekende certificaten met behulp van de New-SelfSignedCertificate PowerShell-cmdlet. Zie UpdateIISExpressSSLForChrome.ps1voor een niet-ondersteund voorbeeld.

    Installeer zelfondertekende of door CA ondertekende certificaten in het lokale computer van de server>Persoonlijke archief.

  4. Als de app een frameworkafhankelijke implementatie is, installeert u .NET Core, .NET Framework of beide (als de app een .NET Core-app is die is gericht op .NET Framework).

    • .NET Core-: Als de app .NET Core vereist, moet u het .NET Core Runtime-installatieprogramma ophalen en uitvoeren vanuit .NET Core Downloads. Installeer de volledige SDK niet op de server.
    • .NET Framework-: als voor de app .NET Framework is vereist, raadpleegt u de .NET Framework-installatiehandleiding. Installeer het vereiste .NET Framework. Het installatieprogramma voor het nieuwste .NET Framework is beschikbaar op de pagina .NET Core Downloads.

    Als de app een zelfstandige implementatie is, bevat de app de runtime als onderdeel van de implementatie. Er is geen frameworkinstallatie vereist op de server.

  5. Configureer URL's en poorten in de app.

    Standaard wordt ASP.NET Core gebonden aan http://localhost:5000. Voor het configureren van URL-voorvoegsels en poorten zijn onder andere de volgende opties:

    In het volgende codevoorbeeld ziet u hoe u UrlPrefixes gebruikt met het lokale IP-adres van de server 10.0.0.4 op poort 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>();
            });
    

    Een voordeel van UrlPrefixes is dat er direct een foutbericht wordt gegenereerd voor onjuist opgemaakte voorvoegsels.

    De instellingen in UrlPrefixes overschrijven UseUrls/urls/ASPNETCORE_URLS instellingen. Daarom is een voordeel van UseUrls, urlsen de omgevingsvariabele ASPNETCORE_URLS dat het gemakkelijker is om tussen Kestrel en HTTP.syste schakelen.

    HTTP.sys maakt gebruik van de URLPrefix-tekenreeksindelingen van de HTTP Server-API.

    Waarschuwing

    Jokertekenbindingen op het hoogste niveau ( en ) moeten niet worden gebruikt. Wildcardbindingen op topniveau creëren veiligheidskwetsbaarheden in apps. Dit geldt zowel voor sterke als zwakke jokertekens. Gebruik expliciete hostnamen of IP-adressen in plaats van jokertekens. Subdomeinbinding met jokertekens (bijvoorbeeld *.mysub.com) is geen veiligheidsrisico als u het gehele bovenliggende domein beheert (in tegenstelling tot *.comdat kwetsbaar is). Zie RFC 9110: Sectie 7.2: Host en :authorityvoor meer informatie.

  6. Url-voorvoegsels vooraf registreren op de server.

    Het ingebouwde hulpprogramma voor het configureren van HTTP.sys is netsh.exe. netsh.exe wordt gebruikt om URL-voorvoegsels te reserveren en X.509-certificaten toe te wijzen. Voor het hulpprogramma zijn beheerdersbevoegdheden vereist.

    Gebruik het hulpprogramma netsh.exe om URL's voor de app te registreren:

    netsh http add urlacl url=<URL> user=<USER>
    
    • <URL>: de volledig gekwalificeerde URL (Uniform Resource Locator). Gebruik geen wildcardkoppeling. Gebruik een geldige hostnaam of een lokaal IP-adres. De URL moet een afsluitende slash bevatten.
    • <USER>: hiermee geeft u de naam van de gebruiker of de gebruikersgroep op.

    In het volgende voorbeeld wordt het lokale IP-adres van de server 10.0.0.4:

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

    Wanneer een URL is geregistreerd, reageert het hulpprogramma met URL reservation successfully added.

    Als u een geregistreerde URL wilt verwijderen, gebruikt u de opdracht delete urlacl:

    netsh http delete urlacl url=<URL>
    
  7. X.509-certificaten registreren op de server.

    Gebruik het hulpprogramma netsh.exe om certificaten voor de app te registreren:

    netsh http add sslcert ipport=<IP>:<PORT> certhash=<THUMBPRINT> appid="{<GUID>}"
    
    • <IP>: hiermee geeft u het lokale IP-adres voor de binding op. Gebruik geen wildcard-verbinding. Gebruik een geldig IP-adres.
    • <PORT>: hiermee geeft u de poort voor de binding op.
    • <THUMBPRINT>: de vingerafdruk van het X.509-certificaat.
    • <GUID>: een door ontwikkelaars gegenereerde GUID die de app vertegenwoordigt voor informatieve doeleinden.

    Voor referentiedoeleinden slaat u de GUID in de app op als pakkettag:

    • In Visual Studio:
      • Open de projecteigenschappen van de app door met de rechtermuisknop op de app te klikken in Solution Explorer- en Eigenschappente selecteren.
      • Selecteer het tabblad Pakket.
      • Voer de GUID in die u hebt gemaakt in het veld Tags.
    • Wanneer u Visual Studio niet gebruikt:
      • Open het projectbestand van de app.

      • Voeg een <PackageTags> eigenschap toe aan een nieuwe of bestaande <PropertyGroup> met de GUID die u hebt gemaakt:

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

    In het volgende voorbeeld:

    • Het lokale IP-adres van de server is 10.0.0.4.
    • Een online willekeurig gegenereerde GUID-generator biedt de appid-waarde.
    netsh http add sslcert 
        ipport=10.0.0.4:443 
        certhash=b66ee04419d4ee37464ab8785ff02449980eae10 
        appid="{00001111-aaaa-2222-bbbb-3333cccc4444}"
    

    Wanneer een certificaat is geregistreerd, reageert het hulpprogramma met SSL Certificate successfully added.

    Als u een certificaatregistratie wilt verwijderen, gebruikt u de opdracht delete sslcert:

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

    Referentiedocumentatie voor netsh.exe:

  8. Voer de app uit.

    Beheerdersbevoegdheden zijn niet vereist om de app uit te voeren wanneer de app wordt gekoppeld aan localhost met behulp van HTTP (niet HTTPS) met een poortnummer dat groter is dan 1024. Voor andere configuraties (bijvoorbeeld met behulp van een lokaal IP-adres of binding met poort 443), voert u de app uit met beheerdersbevoegdheden.

    De app reageert op het openbare IP-adres van de server. In dit voorbeeld wordt de server bereikt vanaf internet op het openbare IP-adres van 104.214.79.47.

    In dit voorbeeld wordt een ontwikkelingscertificaat gebruikt. De pagina wordt veilig geladen nadat de waarschuwing over het niet-vertrouwde certificaat van de browser is overgeslagen.

    Browservenster met de Index-pagina van de app geladen

Scenario's voor proxyserver en load balancer

Voor apps die worden gehost door HTTP.sys die communiceren met aanvragen van internet of een bedrijfsnetwerk, is mogelijk extra configuratie vereist bij het hosten achter proxyservers en load balancers. Zie ASP.NET Core configureren voor gebruik met proxyservers en load balancersvoor meer informatie.

Geavanceerde HTTP/2-functies ter ondersteuning van gRPC

Aanvullende HTTP/2-functies in HTTP.sys ondersteunen gRPC, inclusief ondersteuning voor antwoordtrailers en het verzenden van resetframes.

Vereisten voor het uitvoeren van gRPC met HTTP.sys:

  • Windows 10, OS Build 19041.508 of hoger
  • TLS 1.2- of hogerverbinding

Trailers

HTTP-trailers zijn vergelijkbaar met HTTP-headers, behalve dat ze worden verzonden nadat de hoofdtekst van het antwoord is verzonden. Voor IIS en HTTP.sysworden alleen HTTP/2-antwoordtrailers ondersteund.

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

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

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

In de voorgaande voorbeeldcode:

  • SupportsTrailers zorgt ervoor dat trailers worden ondersteund bij het antwoord.
  • DeclareTrailer voegt de opgegeven trailernaam toe aan de Trailer antwoordheader. Het declareren van de aanhangwagens van een antwoord is optioneel, maar wordt aanbevolen. Als DeclareTrailer wordt aangeroepen, moet dit zijn voordat de antwoordheaders worden verzonden.
  • AppendTrailer voegt de trailer toe.

Herstellen

Met opnieuw instellen kan de server een HTTP/2-aanvraag opnieuw instellen met een opgegeven foutcode. Een resetverzoek wordt als afgebroken beschouwd.

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

Reset in het voorgaande codevoorbeeld geeft de INTERNAL_ERROR foutcode op. Ga voor meer informatie over HTTP/2-foutcodes naar de sectie met foutcodes van de HTTP/2-specificatie.

Aanvullende informatiebronnen