HTTP.sys ASP.NET Core 中的網頁伺服器實作

Note

這不是這篇文章的最新版本。 關於目前版本,請參閱本文的 .NET 11 版本。

作者:Tom Dykstra 和 Chris Ross

HTTP.sys 是一個只在 Windows 上運行的ASP.NET Core 的網頁伺服器。 HTTP.sys 是 Kestrel 伺服器的替代方案,可提供一些 Kestrel 未具備的功能。 本文說明何時使用 HTTP.sys、如何設定,以及如何檢查請求與 TLS 資訊。

Important

HTTP.sys 不相容於ASP.NET Core模組且無法搭配 IIS 或 IIS Express 使用。

HTTP.sys 支援下列功能:

  • Windows 認證
  • 埠共用
  • 使用 SNI 的 HTTPS
  • HTTP/2 經 TLS(Windows 10 或更新版本)
  • HTTP/3 通過 TLS(Windows 11 或更新版本)
  • 直接檔案傳輸
  • 回應快取處理
  • WebSockets(Windows 8 或更新版本)
  • 可自定義的安全性描述元
  • 自動記憶體集區驅逐

作業系統必須是應用程式目標 .NET 版本所支援的版本。 有關支援的 Windows 版本,請參見「在 Windows 上安裝 .NET」。 舊版Windows版本有 HTTP.sys,並不代表目前 ASP.NET Core版本會支援這些版本。 個別功能可能有額外的 Windows 需求,詳見以下章節。

查看或下載範例程式碼 (如何下載)

使用 HTTP.sys 的時機

HTTP.sys 在下列部署環境中非常有用:

  • 需要直接向網際網路公開伺服器而不使用 IIS。

    HTTP.sys 直接與網際網路通訊

  • 內部部署需要 Kestrel 中未提供的功能。 如需詳細資訊,請參閱 Kestrel 與 HTTP.sys

    HTTP.sys 直接與內部網路通訊

HTTP.sys 是成熟的技術,可抵禦許多種類的攻擊,並提供功能完整之網頁伺服器的穩固性、安全性及延展性。 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 版本中,netsh http SSL 憑證綁定上的 disablehttp2 選項會停用該綁定的 HTTP/2。 關於可用選項,請參見 netsh http。

HTTP/3 支援

當滿足以下基本需求時,ASP.NET Core 應用程式會啟用 HTTP/3:

前述Windows 11版本可能需要使用 Windows Insider 建置。

HTTP/3 被識別為從 HTTP/1.1 或 HTTP/2 的升級,透過 alt-svc 標頭。 這表示第一個要求通常會在切換至 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);
});

請將上述程式碼放置於要求管線的前端。

IIS 也支援傳送 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 數值如下:

價值 行為
Legacy 它不會強制通道綁定驗證,也不會向應用程式暴露 CBT 位元組。
Medium (預設) 當客戶提供CBT時,會驗證CBT,但允許不提供。 會將 CBT 位元組暴露給應用程式。
Strict 要求已驗證身分的請求必須附帶 CBT,且拒絕未附帶 CBT 的請求。 會將 CBT 位元組暴露給應用程式。

以下範例選擇啟用 Strict 強化:

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

如果 HTTP.sys 無法套用 Strict 硬化,伺服器啟動會失敗,並出現 HttpSysException。 若為 Legacy 或 Medium,若未能套用該設定,系統會記錄該失敗,且啟動程序會繼續。 僅有設定值並無法保證作業系統已套用該設定。

Warning

Strict硬化可能導致未提供有效 CBT 的客戶端或代理程式無法使用 Windows 驗證。 在正式環境中啟用 TLS 之前,先在你的環境中測試用戶端相容性和 TLS 終止。

當附加到現有的請求佇列時,請對擁有該 URL 群組的監聽器設定硬化。 附加應用程式不會套用 URL 群組設定。

關於 CBT 位元組的存取,請參見取得通道綁定權杖。

透過將 Microsoft.AspNetCore.Server.HttpSys.EnableCBTHardening AppContext 開關設為 true 來啟用使用 Windows 驗證 的 HTTPS 端點的 CBT 強化。 此開關選擇中度硬化,以驗證所提供的 CBT,但允許未提供 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要求佇列時才會套用。 屬性不會影響現有的要求佇列。 當RequestQueueMode為Attach時,它會開啟現有佇列,因此佇列層級的選項(例如 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-NetFirewallRulePowerShell 指令碼來開啟防火牆埠口,讓流量能到達 HTTP.sys。 在下列命令和應用程式設定中,會使用連接埠 443。

  2. 部署到 Azure 虛擬機時,請開啟 Network Security Group 中的埠。 在下列命令和應用程式設定中,會使用連接埠 443。

  3. 視需要取得並安裝 X.509 憑證。

    在Windows時,使用 New-SelfSignedCertificate PowerShell cmdlet建立自簽憑證。 如需不支援的範例,請參閱 UpdateIISExpressSSLForChrome.ps1 \(英文\)。

    將自我簽署的憑證或 CA 簽署的憑證安裝在伺服器的 [本機電腦]>個人 存放區中。

  4. 若應用程式為依賴框架的部署,請從 .NET 下載安裝對應的 ASP.NET Core 執行環境與 .NET 執行環境。 伺服器上不需要 .NET SDK。 ASP.NET Core 並不以 .NET Framework 為目標。 關於安裝程式內容,請參見「選擇正確的執行時」。

    如果應用程式是自封式部署,則應用程式的部署中會包含執行階段。 不需要在伺服器上安裝任何架構。

  5. 設定應用程式中的 URL 和連接埠。

    預設情況下,ASP.NET Core 綁定在 http://localhost:5000。 若要設定 URL 首碼和連接埠,選項包括:

    下列程式碼範例示範如何使用 UrlPrefixes 搭配位於連接埠 443 的伺服器本機 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 節:主機和 :authority。

    大多數應用程式和容器的設定只定義一個監聽埠,例如 port 80,並未指定主機或路徑等其他限制。 HTTP_PORTS 以及 HTTPS_PORTS 是設定金鑰,用來指定 Kestrel 和 HTTP.sys 伺服器的監聽埠。 你可以將這些金鑰指定為使用 ASPNETCORE_ 或 DOTNET_ 前綴所定義的環境變數,或直接透過任何其他設定輸入來設定它們,例如 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_PORTS和 HTTPS_PORTS 配置鍵優先權較低。 如果其他網址或值直接在程式碼中設定,它們可能會覆蓋設定鍵。 使用伺服器專用的 HTTPS 機制分別配置憑證。

    Note

    不要將 ASPNETCORE_HTTPS_PORTS 組態索引鍵和 Kestrel 環境變數(它們會設定 HTTPS_PORT/HTTP.sys 端點組態的連接埠),與 組態索引鍵和 ASPNETCORE_HTTPS_PORT 環境變數(它們會設定 HTTPS_PORTS 的連接埠)混淆。

    這些組態索引鍵相當於最上層萬用字元繫結。 它們適用於開發和容器場景,但若在可能同時運行其他服務的電腦上執行時,請避免使用萬用字元。

  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 位址。 網址必須包含尾部斜線。
    • <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 裡:
      • 在應用程式的 方案總管 右鍵點擊,並選擇 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 位址回應。 在此範例中,是從網際網路透過伺服器的公用 IP 位址 104.214.79.47 連線至伺服器。

    在此範例中使用的是開發憑證。 在略過瀏覽器的未受信任憑證警告之後,頁面會安全地載入。

    瀏覽器視窗顯示應用程式的索引頁面已載入

Proxy 伺服器和負載均衡器應用情境

由 HTTP.sys 裝載且與來自網際網路或公司網路的請求進行交互作用的應用程式,在部署於 Proxy 伺服器和負載平衡器後端時,可能需要額外的配置。 欲了解更多資訊,請參閱 Configure ASP.NET Core 以支援代理伺服器與負載平衡器。

當處理同時帶有 Content-Length 標頭與 Transfer-Encoding 最終編碼為 chunked的標頭的請求時,HTTP.sys 會從應用程式中浮現的請求標頭中移除 Content-Length ,並在回應後自動關閉連線。 Proxy 不應傳送彼此衝突的請求訊息定界。 這種行為有助於防止請求走私;這並不代表每一個此類請求在到達應用程式前都會被拒絕。

檢查 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。

首先以空的 span 呼叫該方法,取得所需的緩衝區大小,然後分配緩衝區並重試:

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 包含可選的屬性特定位元組。 空區間會以空指標的形式傳送到 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 驗證強化。 回傳的位元組包含 Windows SEC_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 Build 22000 或更新版本,Windows Server 2022 版本 20348 或更新版本。
  • TLS 1.2 或更新版本連線。

Trailers

HTTP 尾部與 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 確保回應支援 trailer 標頭。
  • DeclareTrailer 將給定的 trailer 名稱加入 Trailer 回應標頭。 宣告回應的 trailers 是可選的,但建議使用。 如果呼叫 DeclareTrailer,則必須在傳送回應標頭之前進行。
  • AppendTrailer 會附加尾部。

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 metrics。

管理記憶體集區

除了透過剔除不必要的記憶體區塊來有效利用記憶體池外,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 版本的當前開發進度。 若要為特定發行版本選取標籤,請使用 切換分支或標籤 下拉式選單。