在 ASP.NET Core 中的 HTTP.sys Web 服务器实现

Note

此版本不是本文的最新版本。 有关当前发行版,请参阅本文的 .NET 11 版本。

作者:Tom Dykstra 和 Chris Ross

HTTP.sys 是一个仅在 Windows 上运行、用于 ASP.NET Core 的 Web 服务器。 HTTP.sys 是 Kestrel 服务器的替代选择,提供了一些 Kestrel 不提供的功能。 本文介绍何时使用 HTTP.sys、如何对其进行配置以及如何检查请求和 TLS 信息。

Important

HTTP.sys 与 ASP.NET Core Module,不能与 IIS 或 IIS Express 一起使用。

HTTP.sys 支持以下功能:

  • Windows身份验证
  • 端口共享
  • 具有 SNI 的 HTTPS
  • HTTP/2 over TLS (Windows 10或更高版本)
  • HTTP/3 over TLS (Windows 11 或更高版本)
  • 直接文件传输
  • 响应缓存
  • WebSocket (Windows 8 或更高版本)
  • 可自定义的安全描述符
  • 自动内存池逐出

操作系统必须受应用的目标 .NET 版本支持。 有关受支持的Windows版本,请参阅在Windows上安装.NET。 较旧Windows版本中 HTTP.sys 的可用性并不意味着当前 ASP.NET Core版本支持这些版本。 各个功能可以有其他Windows要求,如以下部分所述。

查看或下载示例代码 (如何下载)

何时使用 HTTP.sys

HTTP.sys 对于以下情形的部署来说很有用:

  • 需要将服务器直接暴露到 Internet,而不使用 IIS。

    HTTP.sys 直接与 Internet 通信

  • 内部部署需要 Kestrel 中没有的功能。 有关详细信息,请参阅 Kestrel 与 HTTP.sys

    HTTP.sys 直接与内部网络通信

HTTP.sys 是一项成熟的技术,可以抵御多种攻击,并提供可靠、安全、可伸缩的全功能 Web 服务器。 IIS 本身作为 HTTP.sys 之上的 HTTP 侦听器运行。

HTTP/2 支持

满足以下基本要求时,将为 ASP.NET Core应用启用 HTTP/2:

如果已建立 HTTP/2 连接,HttpRequest.Protocol 会报告 HTTP/2。

默认情况下将启用 HTTP/2。 如果未建立 HTTP/2 连接,连接会回退到 HTTP/1.1。 在支持它的Windows版本中,disablehttp2SSL 证书绑定上的netsh http选项将禁用该绑定的 HTTP/2。 有关可用选项,请参阅 netsh http。

HTTP/3 支持

满足以下基本要求时,将为 ASP.NET Core应用启用 HTTP/3:

上述 Windows 11 预览版可能需要使用 Windows Insider 内部版本。

HTTP/3 是通过 alt-svc 标头作为从 HTTP/1.1 或 HTTP/2 的升级发现的。 这意味着,在切换到 HTTP/3 之前,第一个请求通常使用 HTTP/1.1 或 HTTP/2。 Http.Sys 不会自动添加 alt-svc 标头,它必须由应用程序添加。 以下代码是添加 alt-svc 响应头的中间件示例。

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

将前面的代码提前放在请求管道中。

Http.Sys 还支持发送 AltSvc HTTP/2 协议消息,而不是通过响应标头来通知客户端 HTTP/3 可用。 请参阅 EnableAltSvc 注册表项。

Note

这需要使用主机名而不是 IP 地址的 netsh sslcert 绑定。 在以下命令中,将ipport替换为hostnameport,然后将netsh http add sslcert命令中的 IP 地址替换为主机名,例如www.example.com。 还有一个已知问题是,使用hostnameport会失败,除非指定了certstorename参数。 默认情况下,使用 certstorename=MY。

对 Kerberos 进行内核模式身份验证

HTTP.sys 通过 Kerberos 身份验证协议委托给内核模式身份验证。 Kerberos 和 HTTP.sys 不支持用户模式身份验证。 计算机帐户必须用于解密从Active Directory获取的 Kerberos 令牌/票证,并由客户端转发到服务器以对用户进行身份验证。 注册主机的服务主体名称 (SPN),而不是应用的用户。

启用通道绑定令牌 (CBT) 强化

通道绑定令牌(CBT)将Windows 身份验证绑定到基础 TLS 通道,这有助于缓解 NTLM 中继和中间人攻击。

使用 HttpAuthenticationHardeningLevel 配置 CBT 强化。 可用 HttpAuthenticationHardeningLevel 值为:

Value Behavior
Legacy 不强制实施通道绑定验证或向应用公开 CBT 字节。
Medium(默认值) 在客户端提供 CBT 时验证 CBT,但也允许不提供 CBT。 向应用公开 CBT 字节。
Strict 要求经过身份验证的请求提供 CBT,并拒绝没有 CBT 的请求。 向应用公开 CBT 字节。

以下示例选择启用 Strict 强化:

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

如果 HTTP.sys 无法应用Strict强化,则服务器启动失败并出现 HttpSysException。 使用 Medium 或 Legacy 时,会记录应用该设置失败的情况,并且启动会继续。 仅配置的值不能保证操作系统应用了设置。

Warning

Strict 强化可能会导致未提供有效 CBT 的客户端或代理的 Windows 身份验证 失败。 在生产环境中启用该功能之前,请先在您的环境中测试客户端兼容性和 TLS 终止。

附加到现有请求队列时,在拥有 URL 组的侦听器上配置强化。 附加应用不应用 URL 组配置。

有关访问 CBT 字节的信息,请参阅 “获取通道绑定令牌”。

选择加入对使用 Windows 身份验证 的 HTTPS 终结点进行 CBT 强化,方法是将 Microsoft.AspNetCore.Server.HttpSys.EnableCBTHardening AppContext 开关设置为 true。 此开关选择中等强化,它验证提供的 CBT,但允许其缺席。

请在项目的 runtimeconfig.template.json 文件中启用此功能选项:

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

或者,在 Program 文件中,在生成主机之前,以编程方式设置开关:

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

Warning

默认情况下,CBT 强化是关闭的。 启用此功能可能会导致 Windows 身份验证失败,特别是在不支持通道绑定的客户端或代理中。 在生产环境中启用之前,请在您的环境中进行彻底测试。

对内核模式响应缓冲的支持

在某些场景下,高延迟的大量小型写入可能会对 HTTP.sys 造成重大的性能影响。 这种影响是由于 Pipe 实现中缺少 HTTP.sys 缓冲区。 为了在这些场景中提高性能,HTTP.sys 中包含了对响应缓冲的支持。 通过将 EnableKernelResponseBuffering 设置为 true 来启用缓冲。 响应缓冲应由执行同步 I/O 或异步 I/O 且一次不超过一个未完成写入的应用来启用。 在这些方案中,响应缓冲可以在高延迟连接上显著提高吞吐量。

使用异步 I/O 且一次可能有多个未完成的写入的应用不应使用此标志。 通过 HTTP.Sys 启用此标志可能会导致 CPU 和内存使用率升高。

如何使用 HTTP.sys

将 ASP.NET Core应用配置为使用 HTTP.sys

生成主机时调用 UseHttpSys 扩展方法,指定所有必需的 HttpSysOptions。 以下示例将选项设置为其默认值:

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

通过注册表设置处理其他 HTTP.sys 配置。

有关 HTTP.sys 选项的详细信息,请参阅 HttpSysOptions。

自定义安全描述符

HTTP.sys 中的 请求队列 是一种内核级结构,可以临时存储传入的 HTTP 请求,直到应用准备好处理这些请求。 使用 RequestQueueSecurityDescriptor 管理对请求队列的访问。 配置 HTTP.sys 服务器时,将其设置为 GenericSecurityDescriptor 实例。

通过自定义安全描述符,可以允许或拒绝对请求队列的特定用户或组的访问权限。 在希望在操作系统级别限制或委托 HTTP.sys 请求处理的情况下,这非常有用。

例如,以下代码允许所有经过身份验证的用户,但拒绝来宾:

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

仅当创建新请求队列时,该 RequestQueueSecurityDescriptor 属性才适用。 该属性不会影响现有请求队列。 当 Attach 为 RequestQueueMode 时,它会打开现有队列,因此队列级选项(例如 RequestQueueSecurityDescriptor 和 RequestQueueLimit)都不适用。 在 Attach 模式下,URL 组设置(如超时和身份验证强化)必须由拥有 URL 组的侦听器配置,并且 UrlPrefixes 仅用于计算 PathBase。 CreateOrAttach 仍配置自己的 URL 组并注册其 UrlPrefixes,即使队列已存在;其他侦听器已注册的前缀的设置仍由该侦听器控制。

MaxRequestBodySize

允许的请求正文的最大大小(以字节计)。 当设置为 null 时,最大请求正文大小不受限制。 此限制不会影响升级后的连接,这始终不受限制。

在 ASP.NET Core MVC 应用中覆盖单个 IActionResult 限制的建议方法是对操作方法使用 RequestSizeLimitAttribute 属性:

[RequestSizeLimit(100000000)]
public IActionResult MyActionMethod()

如果在应用开始读取请求后尝试配置请求限制,则会引发异常。 IsReadOnly 属性可用于指示 MaxRequestBodySize 属性是否处于只读状态。只读状态意味着已经太迟了,无法配置限制。

如果应用应替代每个请求的 MaxRequestBodySize,请使用 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);
});

如果使用Visual Studio,请确保应用未配置为运行 IIS 或 IIS Express。

在Visual Studio中,默认启动配置文件适用于 IIS Express。 若要作为控制台应用运行该项目,请手动更改所选配置文件,如以下屏幕截图中所示:

选择控制台应用配置文件

配置Windows Server

  1. 确定要为应用打开的端口,并使用 Windows Firewall 或 New-NetFirewallRule PowerShell cmdlet 打开防火墙端口以允许流量到达 HTTP.sys。 在以下命令和应用配置中,使用的是端口 443。

  2. 部署到 Azure VM 时,请在 Network 安全组中打开端口。 在以下命令和应用配置中,使用的是端口 443。

  3. 如果需要,获取并安装 X.509 证书。

    在Windows上,使用 New-SelfSignedCertificate PowerShell cmdlet 创建自签名证书。 有关不支持的示例,请参阅 UpdateIISExpressSSLForChrome.ps1。

    在服务器的“本地计算机”>“个人”存储中,安装自签名证书或 CA 签名证书。

  4. 如果应用是依赖于框架的部署,请从.NET 下载安装匹配的 ASP.NET Core Runtime 和 .NET Runtime。 服务器上不需要.NET SDK。 ASP.NET Core 不以 .NET Framework 为目标框架。 有关安装程序内容,请参阅 “选择正确的运行时”。

    如果应用是独立式部署,应用在部署中包含运行时。 无需在服务器上安装任何框架。

  5. 在应用中配置 URL 和端口。

    默认情况下,ASP.NET Core绑定到 http://localhost:5000。 若要配置 URL 前缀和端口,可采用以下方法:

    下面的代码示例展示了如何在端口 443 上使用 UrlPrefixes 和服务器的本地 IP 地址 10.0.0.4:

    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 的一个优点是会为格式不正确的前缀立即生成一条错误消息。

    UrlPrefixes 中的设置替代 UseUrls/urls/ASPNETCORE_URLS 设置。 因此,UseUrls、urls 和 ASPNETCORE_URLS 环境变量的一个优点是在 Kestrel 和 HTTP.sys 之间切换变得更加容易。

    HTTP.sys 可以识别 URL 前缀中的两种通配符:

    • * 是 弱绑定,也称为 回退绑定。 如果 URL 前缀为 http://*:5000,而其他内容绑定到端口 5000,则不会使用此绑定。
    • + 是一个 强绑定。 如果 URL 前缀为 http://+:5000,此绑定将在其他端口 5000 绑定之前使用。

    有关详细信息,请参阅 UrlPrefix 字符串。

    Warning

    顶级通配符绑定(http://*:80/ 和 http://+:80)不应该使用。 顶级通配符绑定会带来应用安全漏洞。 此行为同时适用于强通配符和弱通配符。 请使用显式主机名或 IP 地址,而不是通配符。 如果可控制整个父域(相对于易受攻击的 *.mysub.com),子域通配符绑定(例如,*.com)不会构成安全风险。 有关详细信息,请参阅 RFC 9110:第 7.2 节:托管和授权。

    应用和容器的大多数配置仅定义用于侦听的端口,例如端口 80,而无需指定主机或路径等其他约束。 HTTP_PORTS 和 HTTPS_PORTS 是用于指定 Kestrel 和 HTTP.sys 服务器侦听端口的配置键。 可以将密钥指定为使用 DOTNET_ 或 ASPNETCORE_ 前缀定义的环境变量,或通过任何其他配置输入(如 appsettings.json 文件)直接设置它们。 每个配置都是以分号分隔的端口值列表,如以下示例所示:

    ASPNETCORE_HTTP_PORTS=80;8080
    ASPNETCORE_HTTPS_PORTS=443;8081
    

    示例中的配置是以下规范的简写,它定义了方案(HTTP 或 HTTPS)以及任何主机或 IP:

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

    和HTTP_PORTSHTTPS_PORTS配置键的优先级较低。 如果其他 URL 或值直接在代码中设置,则可以替代配置键。 使用特定于服务器的 HTTPS 机制单独配置证书。

    Note

    不要将用于设置 Kestrel/HTTP.sys 终结点配置端口的 HTTPS_PORTS 配置键和 ASPNETCORE_HTTPS_PORTS 环境变量,与用于设置 HTTPS 重定向中间件端口的 HTTPS_PORT 配置键和 ASPNETCORE_HTTPS_PORT 环境变量混淆。

    这些配置键等同于顶级通配符绑定。 对于开发和容器环境来说,它们很方便,但在运行可能还托管了其他服务的计算机上时请避免使用通配符。

  6. 在服务器上预注册 URL 前缀。

    用于配置 HTTP.sys 的内置工具为 netsh.exe。 netsh.exe 用于保留 URL 前缀并分配 X.509 证书。 此工具需要管理员特权。

    使用 netsh.exe 工具为应用注册 URL:

    netsh http add urlacl url=<URL> user=<USER>
    
    • <URL>:完全限定的统一资源定位符(URL)。 不要使用通配符绑定。 请使用有效主机名或本地 IP 地址。 URL 必须包含尾部斜杠。
    • <USER>:指定用户或用户组名称。

    在以下示例中,服务器的本地 IP 地址是 10.0.0.4:

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

    在 URL 注册之后,工具返回 URL reservation successfully added。

    若要删除已注册的 URL,请使用 delete urlacl 命令:

    netsh http delete urlacl url=<URL>
    
  7. 在服务器上注册 X.509 证书。

    使用 netsh.exe 工具为应用注册证书:

    netsh http add sslcert ipport=<IP>:<PORT> certhash=<THUMBPRINT> appid="{<GUID>}"
    
    • <IP>:指定绑定的本地 IP 地址。 不要使用通配符绑定。 请使用有效 IP 地址。
    • <PORT>:指定绑定的端口。
    • <THUMBPRINT>:X.509 证书指纹。
    • <GUID>:开发人员生成的 GUID,用于仅供参考地表示应用。

    为了便于参考,将 GUID 作为包标记存储在应用中:

    • 在 Visual Studio:
      • 通过在 解决方案资源管理器0 中右键单击应用并选择 Properties 打开应用的项目属性。
      • 选择“包”选项卡。
      • 在“标记”字段中输入您创建的 GUID。
    • 不使用Visual Studio时:
      • 打开应用的项目文件。

      • 使用已创建的 GUID,将 <PackageTags> 属性添加到新的或现有的 <PropertyGroup>:

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

    在以下示例中:

    • 服务器的本地 IP 地址是 10.0.0.4。
    • 联机随机 GUID 生成器提供 appid 值。
    netsh http add sslcert
        ipport=10.0.0.4:443
        certhash=b66ee04419d4ee37464ab8785ff02449980eae10
        appid="{00001111-aaaa-2222-bbbb-3333cccc4444}"
    

    在证书注册后,工具响应返回 SSL Certificate successfully added。

    若要删除证书注册,请使用 delete sslcert 命令:

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

    netsh.exe 的参考文档:

  8. 运行应用。

    在 URL 预留授权的标识下运行应用。 需要管理员权限才能配置 URL 预留和证书绑定,但运行其标识具有必要命名空间权限的应用不需要管理员权限。 绑定到本地 IP 地址或端口 443 本身不需要提升的应用程序进程。 有关详细信息,请参阅 命名空间预留、注册和路由。

    应用在服务器的公共 IP 地址处响应。 示例中,通过 Internet 上的公共 IP 地址 104.214.79.47 来接入服务器。

    此示例使用的是开发证书。 在绕过浏览器的不受信任证书警告后,页面安全加载。

    显示应用的“索引”页已加载的浏览器窗口

代理服务器和负载均衡器方案

如果应用由 HTTP.sys 托管并且与来自 Internet 或公司网络的请求进行交互,当在代理服务器和负载均衡器后托管时,可能需要其他配置。 有关详细信息,请参阅 配置 ASP.NET Core以使用代理服务器和负载均衡器。

处理同时包含 Content-Length 标头和最终编码为 Transfer-Encoding 的 chunked 标头的请求时,HTTP.sys 会从提供给应用程序的请求标头中删除 Content-Length,并默认在响应后关闭连接。 代理不应发送相互冲突的请求定界方式。 此行为有助于防止请求走私;这并不意味着在到达应用之前,会拒绝每个此类请求。

检查 TLS 和请求属性

HTTP.sys 公开用于检查 TLS 信息的请求功能。 可用性取决于请求、Windows 版本和 HTTP.sys 配置。

获取协商的 TLS 密码套件

ITlsHandshakeFeature 通过它的 NegotiatedCipherSuite 属性为 HTTP.sys 公开协商的密码套件。 此功能不适用于非 TLS 请求。 如果 Windows 不支持该查询或查询失败,则该属性可以为 null。

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

读取 TLS ClientHello

使用 TryGetTlsClientHello 按需检索原始 TLS ClientHello 字节。 HTTPS 服务配置必须启用 HTTP_SERVICE_CONFIG_SSL_FLAG_ENABLE_CACHE_CLIENT_HELLO。 将 ASP.NET Core配置为使用 HTTP.sys 不会启用此本机标志。 请参阅 HttpSetServiceConfiguration 和 HTTP_SERVICE_CONFIG_ID。

首先调用具有空跨度的方法以获取所需的缓冲区大小,然后分配缓冲区并重试:

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

查询其他本机请求属性

TryGetRequestProperty 为任意本机请求属性公开 HttpQueryRequestProperty。

  • propertyId 标识本机 HTTP_REQUEST_PROPERTY 枚举中的值。
  • qualifier 包含可选的特定于属性的字节。 空 span 作为 null 指针传递给 Windows。
  • output 接收原生字节。 调用方必须使用相应的本机数据结构来解释它们。
  • bytesReturned 包含成功时写入的字节。 在缓冲区不足而失败时,所需大小的报告取决于本机属性。 对于固定大小属性,请为相应的本机结构分配缓冲区大小,而不是假设空缓冲区查询报告所需的大小。

以下示例通过常规用途 API 查询 TLS ClientHello 属性。 它需要与 TryGetTlsClientHello 相同的本机 ClientHello 缓存配置:

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

获取通道绑定令牌

TryGetChannelBindingBytes 提供对 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 支持 ChannelBindingKind.Endpoint,对应于由 RFC 5929 定义的 tls-server-end-point 绑定。 其他绑定类型返回 false。 不可用的令牌也返回 false。 CBT 公开需要由 HTTP.sys 应用 Medium 或Strict身份验证强化。

检索 CBT 字节本身不会对请求进行身份验证,也不会强制实施 Strict 加固。 返回的字节包含WindowsSEC_CHANNEL_BINDINGS结构及其绑定数据,而不仅仅是证书哈希。

使用 IHttpSysRequestTimingFeature 获取详细的时间信息

IHttpSysRequestTimingFeature 提供了请求的详细计时信息:

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 检索提供的计时类型的时间戳:

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 返回两个指定计时之间的已用时间:

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

用于支持 gRPC 的高级 HTTP/2 功能

HTTP.sys 中的其他 HTTP/2 功能支持 gRPC,包括对响应尾部和发送重置帧的支持。

使用 HTTP.sys 运行 gRPC 的要求:

  • Windows 11 版本 22000 或更高版本,Windows Server 2022 版本 20348 或更高版本。
  • TLS 1.2 或更高版本的连接。

Trailers

HTTP 尾部字段类似于 HTTP 标头字段,不同的是它们是在发送响应正文之后才发送的。 IIS 和 HTTP.sys 仅支持 HTTP/2 响应尾部字段。

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

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

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

在前面的示例代码中:

  • SupportsTrailers 确保响应支持尾部。
  • DeclareTrailer 将给定的尾部名称添加到 Trailer 响应标头。 虽然并不是必须要声明响应尾部,但是建议这样做。 如果要调用 DeclareTrailer,则必须在发送响应标头之前进行此操作。
  • AppendTrailer 追加尾随标头。

Reset

通过“Reset”,服务器可以使用指定的错误代码重置 HTTP/2 请求。 重置请求被视为中止。

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

Reset 在前面的代码示例中指定 INTERNAL_ERROR 错误代码。 有关 HTTP/2 错误代码的详细信息,请访问“HTTP/2 规范错误代码”部分。

Tracing

有关如何从 HTTP.sys 获取跟踪的信息,请参阅 HTTP.sys 可管理性方案。

从内存池自动移除

当应用程序空闲或负载不足时,IIS 和 HTTP.sys 使用的 Kestrel内存池会自动逐出内存块。 该功能会自动运行,无需手动启用或配置。

在 10 之前的 .NET 版本中,池所分配的内存仍被保留,即使未使用时也是如此。 这种自动逐出功能可减少总体内存使用率,并帮助应用程序在不同工作负荷下保持响应。

使用内存池指标

ASP.NET Core服务器实现使用的默认内存池包括指标,可用于监视和分析内存使用模式。 指标位于"Microsoft.AspNetCore.MemoryPool"名称下。

有关指标及其用法的信息,请参阅ASP.NET Core指标。

管理内存池

除了通过逐出不需要的内存块来有效使用内存池外,ASP.NET Core还提供内置的 IMemoryPoolFactory 和实现。 它通过依赖项注入使实现可供应用程序使用。

下面的代码示例演示了一个简单的后台服务,该服务使用内置的内存池工厂实现来创建内存池。 这些池受益于自动逐出功能:

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

若要使用自定义内存池工厂,请创建一个实现 IMemoryPoolFactory 并将其注册到依赖项注入的类,如以下示例所示。 以这种方式创建的内存池不会受益于自动逐出功能,除非在自定义工厂中实现类似的逐出逻辑:

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

使用内存池时,请注意池的 MaxBufferSize。

Note

指向 .NET 引用源的文档链接通常会加载存储库的默认分支,该分支代表正在进行的 .NET 下一版本的开发。 若要为特定版本选择标签,请使用“切换分支或标签”下拉菜单。