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

作者：Tom Dykstra 和 Chris Ross

HTTP.sys 是只在 Windows 上執行的 ASP.NET Core 網頁伺服器。 HTTP.sys 是 Kestrel 伺服器的替代方案，可提供一些 Kestrel 未具備的功能。

重要

HTTP.sys 與 ASP.NET Core 模組不相容，且不能與 IIS 或 IIS Express 搭配使用。

HTTP.sys 支援下列功能：

• Windows 驗證
• 連接埠共用
• 使用 SNI 的 HTTPS
• 透過 TLS 的 HTTP/2 (Windows 10 或更新版本)
• 直接檔案傳輸
• 回應快取
• WebSocket (Windows 8 或更新版本)

支援的 Windows 版本：

• Windows 7 或更新版本
• Windows Server 2008 R2 或更新版本

檢視或下載範例程式碼 \(英文\) (如何下載)

使用 HTTP.sys 的時機

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

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

  

• 內部部署需要 Kestrel 中未提供的功能。 如需詳細資訊，請參閱 Windows 索引標籤中的 Kestrel 與HTTP.sys

  

HTTP.sys 是成熟的技術，可抵禦許多種類的攻擊，並提供功能完整之網頁伺服器的穩固性、安全性及延展性。 IIS 本身在 HTTP.sys 之上以 HTTP 接聽程式的形式執行。

HTTP/2 支援

如果符合下列基本需求，即可針對 ASP.NET Core 應用程式啟用 HTTP/2：

• Windows Server 2016/Windows 10 或更新版本
• Application-Layer Protocol Negotiation (ALPN) 連線
• TLS 1.2 或更新版本連線

如果已建立 HTTP/2 連線，HttpRequest.Protocol 會報告 HTTP/2。

HTTP/2 預設為啟用。 如果 HTTP/2 連線尚未建立，連線會退為 HTTP/1.1。 Windows 的未來版本會推出 HTTP/2 設定旗標，包括使用 HTTP.sys 來停用 HTTP/2 的功能。

HTTP/3 支援

如果符合下列基本需求，即可針對 ASP.NET Core 應用程式啟用 HTTP/3：

• Windows Server 2022/Windows 11 或更新版本
• 使用 https URL 繫結。
• 已設定 EnableHttp3 登錄機碼。

上述 Windows 11 組建版本可能需要使用 Windows 測試人員組建。

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

提早將上述程式碼放在要求管線中。

IIS 也支援傳送 AltSvc HTTP/2 通訊協定訊息 (而不是回應標頭)，來通知用戶端指出 HTTP/3 可供使用。 請參閱 EnableAltSvc 登錄機碼。 這需要使用主機名稱而非 IP 位址的 netsh sslcert 繫結。

使用 Kerberos 的核心模式驗證

HTTP.sys 使用 Kerberos 驗證通訊協定委派給核心模式驗證。 Kerberos 和 HTTP.sys 不支援使用者模式驗證。 必須使用電腦帳戶來解密 Kerberos 權杖/票證，該權杖/票證取自 Active Directory，並由用戶端將其轉送至伺服器來驗證使用者。 請註冊主機的服務主體名稱 (SPN)，而非應用程式的使用者。

支援核心模式回應緩衝

在某些情況下，具有高延遲的大量小型寫入可能會對 HTTP.sys 造成顯著的效能影響。 這項影響是因為 HTTP.sys 實作中缺少 Pipe 緩衝區。 為了提升這些案例中的效能，HTTP.sys 中包含了對回應緩衝的支援。 將 HttpSysOptions.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。

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 防火牆或 New-NetFirewallRule PowerShell Cmdlet 來開啟防火牆連接埠，以允許流量到達 HTTP.sys。 在下列命令和應用程式設定中，會使用連接埠 443。

2. 部署至 Azure VM 時，請在網路安全性群組中開啟連接埠。 在下列命令和應用程式設定中，會使用連接埠 443。

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

   在 Windows 上，請使用 New-SelfSignedCertificate PowerShell Cmdlet 來建立自我簽署的憑證。 如需不支援的範例，請參閱 UpdateIISExpressSSLForChrome.ps1 \(英文\)。

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

4. 如果應用程式是與架構相依的部署，請安裝 .NET Core、.NET Framework 或兩者 (如果應用程式是以 .NET Framework 為目標的 .NET Core 應用程式)。

   • .NET Core：如果應用程式需要 .NET Core，請從 .NET Core 下載取得並執行 .NET Core 執行階段安裝程式。 請勿在伺服器上安裝完整的 SDK。
   • .NET Framework：如果應用程式需要 .NET Framework，請參閱 .NET Framework 安裝指南。 安裝必要的 .NET Framework。 您可以從 .NET Core 下載頁面取得最新 .NET Framework 的安裝程式。

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

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

   ASP.NET Core 預設會繫結至 http://localhost:5000。 若要設定 URL 首碼和連接埠，選項包括：

   • UseUrls
   • urls 命令列引數
   • ASPNETCORE_URLS 環境變數
   • UrlPrefixes

   下列程式碼範例示範如何使用 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 字串。

   警告

   請勿使用最上層萬用字元繫結 (http://*:80/與 http://+:80)。 最上層萬用字元繫結會導致應用程式安全性弱點。 這對強式與弱式萬用字元皆適用。 請使用明確的主機名稱或 IP 位址，而不要使用萬用字元。 若您擁有整個父網域 (相對於有弱點的 *.com) 的控制權，則子網域萬用字元繫結 (例如 *.mysub.com) 便不構成安全性風險。 如需詳細資訊，請參閱 RFC 9110：第 7.2 節：主機和 :authority。

   應用程式和容器通常只被分配一個連接埠來接聽，例如埠 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_PORTS 和 HTTPS_PORTS 組態索引鍵的優先順序較低，會以直接在程式碼中提供的 URLS 或值覆寫。 憑證仍然需要透過 HTTPS 的伺服器專有機制來個別設定。

   這些組態索引鍵相當於最上層萬用字元繫結。 它們適用於開發和容器案例，但在可能也裝載了其他服務的電腦上執行時，請避免萬用字元。

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 中：
     • 在 [方案總管] 中的專案上按一下滑鼠右鍵，然後選取 [屬性]，以開啟應用程式的專案屬性。
     • 選取 [套件] 索引標籤。
     • 輸入您在 [標記] 欄位中建立的 GUID。
   • 不是使用 Visual Studio 時：

     • 開啟應用程式的專案檔。

     • 將 <PackageTags> 屬性搭配您所建立的 GUID 新增至新的或現有的 <PropertyGroup>：

       <PropertyGroup>
         <PackageTags>9412ee86-c21b-4eb8-bd89-f650fbf44931</PackageTags>
       </PropertyGroup>
       

   在以下範例中：

   • 伺服器的本機 IP 位址是 10.0.0.4。
   • 線上隨機 GUID 產生器會提供 appid 值。

   netsh http add sslcert 
       ipport=10.0.0.4:443 
       certhash=b66ee04419d4ee37464ab8785ff02449980eae10 
       appid="{9412ee86-c21b-4eb8-bd89-f650fbf44931}"
   

   已註冊憑證時，此工具會以 SSL Certificate successfully added 回應。

   若要刪除憑證註冊，請使用 delete sslcert 命令：

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

   以下是 netsh.exe 的參考文件：

   • 超文字傳輸通訊協定 (HTTP) 的 Netsh 命令
   • UrlPrefix 字串

8. 執行應用程式。

   使用 HTTP (不是 HTTPS) 搭配大於 1024 的連接埠號碼來繫結至 localhost 時，不需要系統管理員權限即可執行應用程式。 針對其他設定 (例如，使用本機 IP 位址或繫結至連接埠 443)，請使用系統管理員權限來執行應用程式。

   應用程式會在伺服器的公用 IP 位址回應。 在此範例中，是從網際網路透過伺服器的公用 IP 位址 104.214.79.47 連線至伺服器。

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

   

Proxy 伺服器和負載平衡器案例

如果是 HTTP.sys 所裝載且與來自網際網路或公司網路的要求進行互動的應用程式，在裝載於 Proxy 伺服器和負載平衡器後方時，可能需要額外的組態。 如需詳細資訊，請參閱設定 ASP.NET Core 以處理 Proxy 伺服器和負載平衡器。

使用 IHttpSysRequestTimingFeature 取得詳細的計時資訊

IHttpSysRequestTimingFeature 提供要求的詳細計時資訊：

• 時間戳記是使用 QueryPerformanceCounter 取得。
• 可透過 QueryPerformanceFrequency 取得時間戳記頻率。
• 計時的索引可以轉換成 HttpSysRequestTimingType，以了解計時代表的內容。
• 如果目前要求無法使用計時，此值可能是 0。

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 或更新版本連線。

結尾

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 確保回應支援結尾。
• DeclareTrailer 將指定的結尾名稱新增至 Trailer 回應標頭。 宣告回應的結尾是選用項目，但建議使用。 如果呼叫 DeclareTrailer，則必須在傳送回應標頭之前進行。
• AppendTrailer 會附加結尾。

Reset

重設允許伺服器重置具有指定錯誤碼的 HTTP/2 要求。 重設要求被視為已中止。

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

Reset 在上述程式碼範例中，指定 INTERNAL_ERROR 錯誤碼。 如需 HTTP/2 錯誤碼的詳細資訊，請瀏覽 HTTP/2 規格錯誤碼一節。

追蹤

如需如何從 HTTP.sys 取得追蹤的詳細資訊，請參閱 HTTP.sys 管理性案例 。

其他資源

• 使用 HTTP.sys 來啟用 Windows 驗證 \(機器翻譯\)
• HTTP 伺服器 API \(英文\)
• aspnet/HttpSysServer GitHub 存放庫 (原始程式碼) \(英文\)
• 主機
• 針對 ASP.NET Core 專案進行疑難排解和偵錯