implémentation de serveur webHTTP.sys dans ASP.NET Core

Note

Ceci n’est pas la dernière version de cet article. Pour la version actuelle, consultez la version .NET 11 de cet article.

Par Tom Dykstra et Chris Ross

HTTP.sys est un serveur web pour ASP.NET Core qui s’exécute uniquement sur Windows. HTTP.sys est une alternative à Kestrel serveur et offre certaines fonctionnalités que Kestrel ne fournissent pas. Cet article explique quand utiliser HTTP.sys, comment le configurer et comment inspecter les informations de requête et TLS.

Important

HTTP.sys n'est pas compatible avec le module ASP.NET Core et ne peut pas être utilisé avec IIS ou IIS Express.

HTTP.sys prend en charge les fonctionnalités suivantes :

  • Authentification Windows
  • Partage de ports
  • HTTPS avec SNI
  • HTTP/2 via TLS (Windows 10 ou version ultérieure)
  • HTTP/3 via TLS (Windows 11 ou version ultérieure)
  • Transmission de fichier directe
  • Mise en cache des réponses
  • WebSockets (Windows 8 ou version ultérieure)
  • Descripteurs de sécurité personnalisables
  • Éviction automatique du pool de mémoire

Le système d’exploitation doit être pris en charge par la version cible de .NET de l’application. Pour connaître les versions Windows prises en charge, consultez Installer .NET sur Windows. La disponibilité de HTTP.sys sur les versions antérieures de Windows n'implique pas la prise en charge de ces versions par les versions actuelles ASP.NET Core. Les fonctionnalités individuelles peuvent avoir des exigences de Windows supplémentaires, comme décrit dans les sections suivantes.

Afficher ou télécharger un exemple de code (comment télécharger)

Quand utiliser HTTP.sys

HTTP.sys est utile pour les déploiements lorsque :

  • Il est nécessaire d’exposer directement le serveur à Internet sans passer par IIS.

    HTTP.sys communique directement avec Internet

  • Un déploiement interne nécessite une fonctionnalité non disponible dans Kestrel. Pour plus d’informations, consultez Kestrel versus HTTP.sys

    HTTP.sys communique directement avec le réseau interne

HTTP.sys est une technologie aboutie qui assure une protection contre de nombreux types d’attaques et offre la robustesse, la sécurité et l’extensibilité d’un serveur web haut de gamme. Pour sa part, IIS s’exécute en tant qu’écouteur HTTP sur HTTP.sys.

Assistance HTTP/2

HTTP/2 est activé pour les applications ASP.NET Core lorsque les exigences de base suivantes sont remplies :

Si une connexion HTTP/2 est établie, HttpRequest.Protocol retourne HTTP/2.

HTTP/2 est activé par défaut. Si une connexion HTTP/2 n’est pas établie, la connexion revient à HTTP/1.1. Sur Windows versions qui le prennent en charge, l’option disablehttp2 d’une netsh http liaison de certificat SSL désactive HTTP/2 pour cette liaison. Pour connaître les options disponibles, consultez netsh http.

Assistance HTTP/3

HTTP/3 est activé pour les applications ASP.NET Core lorsque les exigences de base suivantes sont remplies :

  • Windows Server 2022/Windows 11 ou version ultérieure
  • Une liaison d’URL https est utilisée.
  • La clé de Registre EnableHttp3 est définie.

Les versions de build Windows 11 précédentes peuvent nécessiter l’utilisation d’une build Windows Insider.

HTTP/3 est découvert comme une mise à niveau à partir de HTTP/1.1 ou HTTP/2 via l’en-tête alt-svc. Cela signifie que la première requête utilise normalement HTTP/1.1 ou HTTP/2 avant de passer à HTTP/3. Http.Sys n’ajoute pas automatiquement l’en-tête alt-svc, il doit être ajouté par l’application. Le code suivant est un exemple d’intergiciel qui ajoute l’en-tête de réponse alt-svc.

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

Placez le code précédent au début du pipeline de requête.

Http.Sys prend également en charge l’envoi d’un message de protocole HTTP/2 AltSvc plutôt qu’un en-tête de réponse pour avertir le client que HTTP/3 est disponible. Consultez la clé de Registre EnableAltSvc.

Note

Cela nécessite des liaisons netsh sslcert qui utilisent des noms d’hôte plutôt que des adresses IP. Remplacez par ipport les hostnameport commandes ci-dessous, puis remplacez netsh http add sslcert l’adresse IP par le nom d’hôte, par exemplewww.example.com. Il existe également un problème connu où l’utilisation hostnameport échoue, sauf si le certstorename paramètre est spécifié. Par défaut, utilisez certstorename=MY.

Authentification en mode noyau avec Kerberos

HTTP.sys délègue l’authentification en mode noyau avec le protocole d’authentification Kerberos. L’authentification en mode utilisateur n’est pas prise en charge avec Kerberos et HTTP.sys. Le compte d'ordinateur doit être utilisé pour déchiffrer le jeton/ticket Kerberos obtenu à partir de Active Directory et transféré par le client au serveur pour authentifier l'utilisateur. Inscrivez le nom de principal du service (SPN) pour l’hôte, et non l’utilisateur de l’application.

Activer le renforcement des jetons de liaison de canal (CBT)

Les jetons de liaison de canal (CBT) lient l’authentification Windows au canal TLS sous-jacent, ce qui aide à atténuer les attaques de relais NTLM et d’homme du milieu.

Configurez le renforcement CBT avec HttpAuthenticationHardeningLevel. Les valeurs disponibles HttpAuthenticationHardeningLevel sont les suivantes :

Value Behavior
Legacy N’applique pas la validation de la liaison de canal ou n’expose pas d’octets CBT à l’application.
Medium (valeur par défaut) Valide les TCC lorsque les clients les fournissent, mais autorise leur absence. Expose les octets CBT à l’application.
Strict Nécessite des CBTs sur les demandes authentifiées et rejette les demandes sans eux. Expose les octets CBT à l’application.

L’exemple suivant opte pour le Strict renforcement :

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

Si HTTP.sys ne peut pas appliquer Strict de renforcement, le démarrage du serveur échoue avec un HttpSysException. Avec Legacy ou Medium, un échec d’application du paramètre est journalisé et le démarrage se poursuit. La valeur configurée seule ne garantit pas que le système d’exploitation a appliqué le paramètre.

Warning

Strict le durcissement CBT peut entraîner l'échec de Authentification Windows pour les clients ou les proxys qui ne fournissent pas de CBT valide. Testez la compatibilité du client et la terminaison TLS dans votre environnement avant de l’activer en production.

Lors de la connexion à une file d’attente de requêtes existante, configurez le durcissement sur l’écouteur propriétaire du groupe d’URL. L’application d’attachement n’applique pas la configuration du groupe d’URL.

Pour accéder aux octets CBT, consultez Obtenir des jetons de liaison de canal.

Optez pour le renforcement CBT pour les points de terminaison HTTPS qui utilisent Authentification Windows en définissant le Microsoft.AspNetCore.Server.HttpSys.EnableCBTHardening commutateur AppContext sur true. Ce commutateur sélectionne le renforcement moyen, qui valide les CBT fournis, mais autorise leur absence.

Activez le commutateur dans le fichier runtimeconfig.template.json de votre projet :

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

Vous pouvez également définir le commutateur par programmation avant de générer l’hôte dans le Program fichier :

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

Warning

Le durcissement CBT est désactivé par défaut. L'activation peut entraîner l'échec de l'authentification Windows pour les clients ou les proxys qui ne prennent pas en charge la liaison de canaux. Testez soigneusement dans votre environnement avant de l’activer en production.

Prise en charge de la mise en mémoire tampon des réponses en mode noyau

Dans certains scénarios, des volumes élevés d’écritures de petite taille avec une latence élevée peuvent avoir un impact significatif sur les performances de HTTP.sys. Cet impact est dû à l’absence d’une mémoire tampon Pipe dans l’implémentation HTTP.sys. Pour améliorer les performances dans ces scénarios, la prise en charge de la mise en mémoire tampon de réponse est incluse dans HTTP.sys. Activez la mise en mémoire tampon en définissant EnableKernelResponseBuffering sur true. La mise en mémoire tampon de réponse doit être activée par une application qui effectue des E/S synchrones ou des E/S asynchrones avec pas plus d’une écriture en attente à la fois. Dans ces scénarios, la mise en mémoire tampon de réponse peut améliorer considérablement le débit sur les connexions à latence élevée.

Les applications qui utilisent des E/S asynchrones et qui peuvent avoir plusieurs écritures en attente à la fois ne doivent pas utiliser cet indicateur. L’activation de cet indicateur peut entraîner une utilisation plus élevée du processeur et de la mémoire par HTTP.Sys.

Comment utiliser HTTP.sys

Configurer l’application ASP.NET Core pour utiliser HTTP.sys

Appelez la méthode d’extension UseHttpSys au moment de générer l’hôte, en spécifiant les options HttpSysOptions nécessaires. L’exemple suivant définit les options sur leurs valeurs par défaut :

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

Le reste de la configuration de HTTP.sys est géré par le biais des paramètres du Registre.

Pour plus d’informations sur les options HTTP.sys, consultez HttpSysOptions.

Personnaliser les descripteurs de sécurité

Une file d’attente de requêtes dans HTTP.sys est une structure au niveau du noyau qui stocke temporairement les requêtes HTTP entrantes jusqu’à ce que votre application soit prête à les traiter. Gérez l’accès à la file d’attente de requêtes à l’aide de RequestQueueSecurityDescriptor. Définissez-le sur une GenericSecurityDescriptor instance lors de la configuration de votre serveur HTTP.sys.

En personnalisant le descripteur de sécurité, vous pouvez autoriser ou refuser un accès spécifique aux utilisateurs ou groupes spécifiques à la file d’attente de demandes. Cela est utile dans les scénarios où vous souhaitez restreindre ou déléguer HTTP.sys gestion des demandes au niveau du système d’exploitation.

Par exemple, le code suivant autorise tous les utilisateurs authentifiés, mais refuse aux invités :

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

La RequestQueueSecurityDescriptor propriété s’applique uniquement lors de la création d’une file d’attente de requêtes. La propriété n’affecte pas les files d’attente des requêtes existantes. Quand Attach est RequestQueueMode, il ouvre une file d’attente existante, les options au niveau de la file d’attente telles que RequestQueueSecurityDescriptor et RequestQueueLimit ne s’appliquent pas. En Attach mode, les paramètres de groupe d’URL, tels que les délais d’expiration et le renforcement de l’authentification, doivent être configurés par l’écouteur propriétaire du groupe d’URL et UrlPrefixes sont utilisés uniquement pour calculer PathBase. CreateOrAttach configure toujours son propre groupe d’URL et inscrit son UrlPrefixes, même quand la file d’attente existe déjà ; les paramètres des préfixes déjà inscrits par un autre écouteur restent contrôlés par cet écouteur.

MaxRequestBodySize

Taille maximale autorisée pour le corps d’une demande, en octets. Lorsque la valeur est définie sur null, la taille maximale du corps de la requête est illimitée. Cette limite est sans effet sur les connexions mises à niveau, qui sont illimitées.

La méthode recommandée pour remplacer la limite dans une application MVC ASP.NET Core pour une seule IActionResult consiste à utiliser l’attribut RequestSizeLimitAttribute sur une méthode d’action :

[RequestSizeLimit(100000000)]
public IActionResult MyActionMethod()

Une exception est levée si l’application tente de configurer la limite sur une demande dont l’application a commencé la lecture. La propriété IsReadOnly indique si la propriété MaxRequestBodySize est en lecture seule, et donc s’il est trop tard pour configurer la limite.

Si l’application doit remplacer MaxRequestBodySize par requête, utilisez 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);
});

Si vous utilisez Visual Studio, vérifiez que l'application n'est pas configurée pour exécuter IIS ou IIS Express.

Dans Visual Studio, le profil de lancement par défaut est pour IIS Express. Pour exécuter le projet en tant qu’application console, changez manuellement le profil sélectionné, comme dans la capture d’écran suivante :

Sélectionner le profil d’application console

Configurer Windows Server

  1. Déterminez les ports à ouvrir pour l’application et utilisez Windows Firewall ou le New-NetFirewallRule Applet de commande PowerShell pour ouvrir des ports de pare-feu afin d’autoriser le trafic à atteindre HTTP.sys. Dans les commandes et la configuration de l’application suivantes, le port 443 est utilisé.

  2. Lors du déploiement sur une machine virtuelle Azure, ouvrez les ports dans le groupe de sécurité Network Security Group. Dans les commandes et la configuration de l’application suivantes, le port 443 est utilisé.

  3. Obtenez et installez des certificats X.509, si nécessaire.

    Sur Windows, créez des certificats auto-signés à l’aide de l’applet de commande PowerShell New-SelfSignedCertificate. Vous trouverez un exemple non pris en charge sur la page UpdateIISExpressSSLForChrome.ps1.

    Installez des certificats auto-signés ou signés par l’autorité de certification dans le répertoire Ordinateur Local>Personnel du serveur.

  4. Si l’application est un déploiement dépendant du framework, installez les ASP.NET Core Runtime et .NET Runtime correspondants à partir de .NET Downloads. Le sdk .NET n'est pas obligatoire sur le serveur. ASP.NET Core ne cible pas .NET Framework. Pour connaître le contenu du programme d’installation, consultez Choisir le runtime approprié.

    Si l’application est un déploiement autonome, elle inclut le runtime dans son déploiement. Aucune installation de framework n’est requise sur le serveur.

  5. Configurez les ports et les URL de l’application.

    Par défaut, ASP.NET Core lie à http://localhost:5000. Pour configurer les ports et les préfixes d’URL, il existe plusieurs possibilités :

    • UseUrls
    • urls argument de ligne de commande
    • ASPNETCORE_URLS variable d’environnement
    • UrlPrefixes

    L’exemple de code suivant montre comment utiliser UrlPrefixes avec l’adresse IP locale du serveur 10.0.0.4 sur le 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();
    

    UrlPrefixes présente l’avantage de générer immédiatement un message d’erreur en cas de préfixe mal formé.

    Les paramètres de UrlPrefixes remplacent les paramètres UseUrls/urls/ASPNETCORE_URLS. Par conséquent, un avantage de UseUrls, urls et de la variable d’environnement ASPNETCORE_URLS est qu’il est plus facile de basculer entre Kestrel et HTTP.sys.

    HTTP.sys reconnaît deux types de cartes génériques dans les préfixes des URL :

    • * est une liaison faible, également appelée liaison de secours. Si le préfixe de l’URL est http://*:5000 et qu’autre chose est lié au port 5000, cette liaison ne va pas être utilisée.
    • + est une liaison prioritaire. Si le préfixe de l’URL est http://+:5000, cette liaison est utilisée avant les autres liaisons au port 5000.

    Pour plus d’informations, consultez UrlPrefix Strings.

    Warning

    Les liaisons génériques de niveau supérieur (http://*:80/ et http://+:80) ne doivent pas être utilisées. Les liaisons génériques de niveau supérieur créent des failles de sécurité dans l’application. Cela s’applique aux caractères génériques forts et faibles. Utilisez des noms d’hôte ou des adresses IP explicites plutôt que des caractères génériques. Une liaison générique de sous-domaine (par exemple, *.mysub.com) ne constitue pas un risque de sécurité si vous contrôlez le domaine parent en entier (par opposition à *.com, qui est vulnérable). Pour plus d’informations, consultez RFC 9110 : Section 7.2 : Hôte et :authority.

    La plupart des configurations pour les applications et les conteneurs définissent uniquement un port pour l’écoute, comme le port 80, sans spécifier d’autres contraintes comme l’hôte ou le chemin d’accès. HTTP_PORTS et HTTPS_PORTS sont des clés de configuration qui spécifient les ports d’écoute pour les serveurs Kestrel et HTTP.sys. Vous pouvez spécifier les clés en tant que variables d’environnement définies avec les DOTNET_ ou ASPNETCORE_ préfixes, ou les définir directement via n’importe quelle autre entrée de configuration, telle que le appsettings.json fichier. Chaque configuration est une liste délimitée par des points-virgules de valeurs de port, comme illustré dans l’exemple suivant :

    ASPNETCORE_HTTP_PORTS=80;8080
    ASPNETCORE_HTTPS_PORTS=443;8081
    

    La configuration de l’exemple est abrégée pour la spécification suivante, qui définit le schéma (HTTP ou HTTPS) et tout hôte ou adresse IP :

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

    Les clés de configuration HTTPS_PORTS et HTTP_PORTS sont moins prioritaires. Si d’autres URL ou valeurs sont définies directement dans le code, elles peuvent remplacer les clés de configuration. Configurez des certificats séparément à l’aide de mécanismes spécifiques au serveur pour HTTPS.

    Note

    Ne confondez pas la clé de configuration ASPNETCORE_HTTPS_PORTS et la variable d’environnement HTTPS_PORTS, qui définissent les ports de la configuration du point de terminaison Kestrel/HTTP.sys, avec la clé de configuration ASPNETCORE_HTTPS_PORT et la variable d’environnement HTTPS_PORT, qui définissent le port du middleware de redirection vers HTTPS.

    Ces clés de configuration sont équivalentes aux liaisons génériques de niveau supérieur. Elles sont pratiques pour le développement et les scénarios de conteneur, mais évitent les caractères génériques lors de l’exécution sur un ordinateur qui peut également héberger d’autres services.

  6. Préenregistrez les préfixes d’URL sur le serveur.

    L’outil intégré pour configurer HTTP.sys est netsh.exe. netsh.exe est utilisé pour réserver des préfixes d’URL et affecter des certificats X.509. L’outil requiert des privilèges Administrateur.

    Utilisez l’outil netsh.exe pour enregistrer les URL pour l’application :

    netsh http add urlacl url=<URL> user=<USER>
    
    • <URL>: URL (Uniform Resource Locator) complet. N’utilisez pas une liaison de caractère générique. Utilisez un nom d’hôte ou une adresse IP locale valide. L’URL doit inclure une barre oblique de fin.
    • <USER>: spécifie le nom de l’utilisateur ou du groupe d’utilisateurs.

    Dans l’exemple suivant, l’adresse IP locale du serveur est 10.0.0.4 :

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

    Lorsqu’une URL est inscrite, l’outil répond avec URL reservation successfully added.

    Pour supprimer une URL inscrite, utilisez la commande delete urlacl :

    netsh http delete urlacl url=<URL>
    
  7. Inscrivez les certificats X.509 sur le serveur.

    Utilisez l’outil netsh.exe pour enregistrer les certificats pour l’application :

    netsh http add sslcert ipport=<IP>:<PORT> certhash=<THUMBPRINT> appid="{<GUID>}"
    
    • <IP>: spécifie l’adresse IP locale pour le binding. N’utilisez pas une liaison de caractère générique. Utilisez une adresse IP valide.
    • <PORT> : spécifie le port pour la liaison.
    • <THUMBPRINT>: empreinte numérique du certificat X.509.
    • <GUID>: GUID généré par le développeur pour représenter l’application à des fins d’information.

    À titre de référence, stockez le GUID dans l’application en tant que balise de package :

    • Dans Visual Studio :
      • Ouvrez les propriétés du projet de l'application en cliquant avec le bouton droit sur l'application dans Explorateur de solutions et en sélectionnant Properties.
      • Sélectionnez l’onglet Package.
      • Entrez le GUID que vous avez créé dans le champ Balises.
    • Quand vous n’utilisez pas Visual Studio :
      • Ouvrez le fichier de projet de l'application.

      • Ajoutez une propriété <PackageTags> à un <PropertyGroup> nouveau ou existant avec le GUID que vous avez créé :

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

    Dans l’exemple suivant :

    • L’adresse IP locale du serveur est 10.0.0.4.
    • Un générateur de GUID aléatoire en ligne fournit la valeur appid.
    netsh http add sslcert
        ipport=10.0.0.4:443
        certhash=b66ee04419d4ee37464ab8785ff02449980eae10
        appid="{00001111-aaaa-2222-bbbb-3333cccc4444}"
    

    Lorsqu’un certificat est inscrit, l’outil répond avec SSL Certificate successfully added.

    Pour supprimer l’inscription d’un certificat, utilisez la commande delete sslcert :

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

    Documentation de référence de netsh.exe :

  8. Exécutez l'application.

    Exécutez l’application sous l’identité autorisée par la réservation d’URL. Les privilèges d’administrateur sont requis pour configurer les réservations d’URL et les liaisons de certificat, mais ne sont pas nécessaires pour exécuter une application dont l’identité dispose des autorisations d’espace de noms nécessaires. La liaison à une adresse IP locale ou au port 443 ne nécessite pas par elle-même un processus d’application avec élévation de privilèges. Pour plus d’informations, consultez réservations d’espaces de noms, inscriptions et routage.

    L’application répond à l’adresse IP publique du serveur. Dans cet exemple, le serveur est contacté à partir d’Internet à son adresse IP publique 104.214.79.47.

    Un certificat de développement est utilisé dans cet exemple. La page est chargée en toute sécurité après le contournement de l’avertissement de certificat non approuvé du navigateur.

    Fenêtre du navigateur montrant la page Index de l’application chargée

Scénarios avec un serveur proxy et un équilibreur de charge

Pour les applications hébergées par HTTP.sys qui interagissent avec les demandes provenant d’Internet ou d’un réseau d’entreprise, une configuration supplémentaire peut être nécessaire en cas d’hébergement derrière des serveurs proxy et des équilibreurs de charge. Pour plus d’informations, consultez Configure ASP.NET Core pour travailler avec des serveurs proxy et des équilibreurs de charge.

Lors du traitement d’une requête avec un Content-Length en-tête et un Transfer-Encoding en-tête dont le codage final est chunked, HTTP.sys supprime les Content-Length en-têtes de requête exposés à l’application et ferme la connexion après avoir répondu par défaut. Les proxys ne doivent pas envoyer une délimitation des requêtes contradictoire. Ce comportement permet d’empêcher la contrebande de demandes ; il n’implique pas que chaque demande de ce type soit rejetée avant d’atteindre l’application.

Inspecter les propriétés TLS et de requête

HTTP.sys expose les fonctionnalités de requête pour inspecter les informations TLS. La disponibilité dépend de la requête, de la version Windows et de la configuration HTTP.sys.

Obtenir la suite de chiffrement TLS négociée

ITlsHandshakeFeature expose la suite de chiffrement négociée via sa propriété NegotiatedCipherSuite pour HTTP.sys. La fonctionnalité n’est pas disponible pour une requête non TLS. La propriété peut être null si Windows ne prend pas en charge la requête ou la requête échoue.

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.");
}

Lire le TLS ClientHello

Utilisez TryGetTlsClientHello pour récupérer les octets bruts du TLS ClientHello à la demande. La configuration du service HTTPS doit activer HTTP_SERVICE_CONFIG_SSL_FLAG_ENABLE_CACHE_CLIENT_HELLO. La configuration de ASP.NET Core pour utiliser HTTP.sys n'active pas cet indicateur natif. Voir HttpSetServiceConfiguration et HTTP_SERVICE_CONFIG_ID.

Appelez d’abord la méthode avec une étendue vide pour obtenir la taille de mémoire tampon requise, puis allouez une mémoire tampon et réessayez :

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

Interroger d’autres propriétés de requête natives

TryGetRequestProperty expose HttpQueryRequestProperty pour des propriétés de requête natives arbitraires.

  • propertyId identifie une valeur de l’énumération native HTTP_REQUEST_PROPERTY .
  • qualifier contient des octets facultatifs spécifiques à la propriété. Un span vide est passé à Windows en tant que pointeur null.
  • output reçoit les octets natifs. L’appelant doit les interpréter à l’aide de la structure de données native correspondante.
  • bytesReturned contient les octets écrits en cas de réussite. En cas d’échec dû à un tampon insuffisant, la création de rapports de taille requise dépend de la propriété native. Pour les propriétés de taille fixe, allouez une mémoire tampon dimensionnée pour la structure native correspondante au lieu de supposer qu’une requête de mémoire tampon vide signale la taille requise.

L’exemple suivant interroge la propriété TLS ClientHello via l’API à usage général. Elle nécessite la même configuration de mise en cache ClientHello native que 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);

Obtenir des jetons de liaison de canal

TryGetChannelBindingBytes fournit l’accès aux octets de liaison de canal TLS :

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 prend en charge ChannelBindingKind.Endpoint, correspondant à la tls-server-end-point liaison définie par RFC 5929. D’autres types de liaison retournent false. Un jeton indisponible renvoie également false. L’exposition CBT nécessite que le Medium ou Strictle renforcement de l’authentification soit appliqué par HTTP.sys.

La récupération d’octets CBT n’authentifie pas à elle seule une requête et n’impose pas le renforcement Strict. Les octets retournés contiennent la structure Windows SEC_CHANNEL_BINDINGS et ses données de liaison, pas seulement un hachage de certificat.

Obtenir des informations détaillées sur le minutage avec IHttpSysRequestTimingFeature

IHttpSysRequestTimingFeature fournit des informations de minutage détaillées pour les demandes :

  • Les horodatages sont obtenus à l’aide de QueryPerformanceCounter.
  • La fréquence d’horodatage peut être obtenue via QueryPerformanceFrequency.
  • L’index du minutage peut être converti en HttpSysRequestTimingType pour savoir ce que représente le minutage.
  • La valeur peut être 0 si le minutage n’est pas disponible pour la requête actuelle.
  • Nécessite Windows 10 version 2004, Windows Server 2022 ou ultérieure.
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 récupère l’horodatage pour le type de minutage fourni :

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 génère le temps écoulé entre deux minutages spécifiés :

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

Fonctionnalités HTTP/2 avancées pour prendre en charge gRPC

Des fonctionnalités HTTP/2 supplémentaires dans HTTP.sys prennent en charge gRPC, notamment la prise en charge des codes de fin de réponse et l’envoi de trames de réinitialisation.

Configuration requise pour exécuter gRPC avec HTTP.sys :

  • Windows 11 Build 22000 ou version ultérieure, Windows Server 2022 Build 20348 ou version ultérieure.
  • TLS 1.2 ou connexion ultérieure.

Trailers

Les codes de fin HTTP sont similaires aux en-têtes HTTP, sauf qu’ils sont envoyés après l’envoi du corps de la réponse. Pour IIS et HTTP.sys, seuls les codes de fin de réponse HTTP/2 sont pris en charge.

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

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

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

Dans l’exemple de code précédent :

  • SupportsTrailers garantit que les trailers sont pris en charge pour la réponse.
  • DeclareTrailer ajoute le nom du trailer donné à l’en-tête de réponse Trailer. La déclaration des codes de fin d’une réponse est facultative, mais recommandée. Si DeclareTrailer est appelé, cela doit se faire avant l'envoi des en-têtes de réponse.
  • AppendTrailer ajoute le code de fin.

Reset

La réinitialisation permet au serveur de réinitialiser une requête HTTP/2 avec un code d’erreur spécifié. Une requête de réinitialisation est considérée comme abandonnée.

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

Reset dans l’exemple de code précédent spécifie le code d’erreur INTERNAL_ERROR . Pour plus d’informations sur les codes d’erreur HTTP/2, consultez la section du code d’erreur de spécification HTTP/2 HTTP/2.

Tracing

Pour plus d’informations sur l’obtention de traces à partir de HTTP.sys, consultez Scénarios de gestion de HTTP.sys.

Expulsion automatique du pool de mémoire

Les pools de mémoire utilisés par Kestrel, IIS et HTTP.sys suppriment automatiquement les blocs de mémoire lorsque l’application est inactive ou sous faible charge. La fonctionnalité s’exécute automatiquement et n’a pas besoin d’être activée ou configurée manuellement.

Dans les versions de .NET antérieures à 10, la mémoire allouée par le pool reste réservée, même si elle n’est pas utilisée. Cette fonctionnalité d’éviction automatique réduit l’utilisation globale de la mémoire et aide les applications à rester réactives sous différentes charges de travail.

Utiliser les métriques de pool de mémoire

Le pool de mémoire par défaut utilisé par les implémentations de serveur ASP.NET Core inclut des métriques, qui peuvent être utilisées pour surveiller et analyser les modèles d’utilisation de la mémoire. Les métriques se trouvent sous le nom "Microsoft.AspNetCore.MemoryPool".

Pour plus d’informations sur les métriques et leur utilisation, consultez ASP.NET Core métriques.

Gérer les pools de mémoire

Outre l'utilisation efficace des pools de mémoire en supprimant les blocs de mémoire inutiles, ASP.NET Core fournit un IMemoryPoolFactory intégré et une implémentation. Elle rend l’implémentation disponible pour votre application via l’injection de dépendances.

L’exemple de code suivant montre un service en arrière-plan simple qui utilise l’implémentation de fabrique de pool de mémoire intégrée pour créer des pools de mémoire. Ces pools bénéficient de la fonctionnalité d’éviction automatique :

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

Pour utiliser votre propre fabrique de pool de mémoire, créez une classe qui implémente IMemoryPoolFactory et enregistrez-la avec l’injection de dépendances, comme dans l’exemple suivant. Les pools de mémoire créés de cette façon ne bénéficient pas de la fonctionnalité d’éviction automatique, sauf si vous implémentez une logique d’éviction similaire dans votre fabrique personnalisée :

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

Lorsque vous utilisez un pool de mémoire, tenez compte des spécificités du MaxBufferSize.

Note

Les liens de documentation vers la source de référence .NET chargent généralement la branche par défaut du référentiel, qui représente le développement actuel pour la prochaine version de .NET. Pour sélectionner une balise pour une version spécifique, utilisez la liste déroulante Échanger les branches ou les balises.