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

作者:Tom DykstraChris 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。

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

  • 內部部署需要中無法使用的功能 Kestrel 。 如需詳細資訊,請參閱 Kestrel vs. 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 的未來版本會推出 HTTP/2 設定旗標,包括使用 HTTP.sys 來停用 HTTP/2 的功能。

HTTP/3 支援

當符合下列基本需求時,會為 ASP.NET Core 的應用程式啟用HTTP/3

  • WindowsServer 2022/Windows 11 或更新版本
  • https使用 url 系結。
  • 已設定 EnableHttp3 登錄機

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

從 HTTP/1.1 或透過標頭的 HTTP/2 升級時,會探索 HTTP/3 alt-svc 。 這表示第一個要求通常會使用 HTTP/1.1 或 HTTP/2,然後才切換至 HTTP/3。 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登錄機碼。 請注意,這需要使用主機名稱而非 IP 位址的 netsh sslcert 系結。

使用 Kerberos 的核心模式驗證

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

如何使用 HTTP.sys

設定 ASP.NET Core 應用程式使用 HTTP.sys

建置主機時,呼叫 UseHttpSys 擴充方法,並指定任何必要的 HttpSysOptions。 下列範例會將選項設定為它們的預設值:

public static IHostBuilder CreateHostBuilder(string[] args) =>
    Host.CreateDefaultBuilder(args)
        .ConfigureWebHostDefaults(webBuilder =>
        {
            webBuilder.UseHttpSys(options =>
            {
                options.AllowSynchronousIO = false;
                options.Authentication.Schemes = AuthenticationSchemes.None;
                options.Authentication.AllowAnonymous = true;
                options.MaxConnections = null;
                options.MaxRequestBodySize = 30000000;
                options.UrlPrefixes.Add("http://localhost:5005");
            });
            webBuilder.UseStartup<Startup>();
        });

其他的 HTTP.sys 設定則透過登錄設定處理。

HTTP.sys 選項

屬性 描述 預設
AllowSynchronousIO 控制是否允許 HttpContext.Request.BodyHttpContext.Response.Body 同步輸出/輸入。 false
Authentication.AllowAnonymous 允許匿名要求。 true
Authentication.Schemes 指定允許的驗證配置。 處置接聽程式之前可隨時修改。 值是由 AuthenticationSchemes 列舉提供: Basic 、、 Kerberos NegotiateNoneNTLM None
EnableResponseCaching 針對含有合格標頭的回應嘗試核心模式快取。 回應可能不包含 Set-CookieVaryPragma 標頭。 它必須包含為 publicCache-Control 標頭,且有 shared-max-agemax-age 值,或是 Expires 標頭。 true
Http503Verbosity 因為節流狀況而拒絕要求時的 HTTP.sys 行為。 Http503VerbosityLevel。
基本
MaxAccepts 可同時接受的數目上限。 5 × Environment.
ProcessorCount
MaxConnections 可接受的同時連線數量上限。 使用 -1 為無限多個。 使用 null 以使用登錄之整個電腦的設定。 null
(全電腦
設定)
MaxRequestBodySize 請參閱 MaxRequestBodySize 小節。 30000000 位元組
(~28.6 MB)
RequestQueueLimit 可以加入佇列的最大要求數目。 1000
RequestQueueMode 這會指出伺服器是否負責建立和設定要求佇列,或是否應該附加至現有的佇列。
附加至現有的佇列時,大部分現有的設定選項都不適用。
RequestQueueMode.Create
RequestQueueName HTTP.sys 要求佇列的名稱。 null (匿名佇列)
ThrowWriteExceptions 指出若回應本文因為用戶端中斷連線而寫入失敗時,應擲回例外狀況或正常完成。 false
(正常完成)
Timeouts 公開 HTTP.sys TimeoutManager 設定,這也可在登錄中設定。 API 連結可提供包括預設值在內每個設定的詳細資訊:
UrlPrefixes 指定 UrlPrefixCollection 以向 HTTP.sys 註冊。 最有用的是 UrlPrefixCollection.Add ,它是用來將前置詞加入至集合。 處置接聽程式之前可隨時修改這些內容。

MaxRequestBodySize

任何要求所允許的大小上限 (以位元組為單位)。 當設定為 null 時,要求主體大小上限為無限制。 此限制對升級連線不會有任何影響,因為其一律為無限制。

在 ASP.NET Core MVC 應用程式中針對單一 IActionResult 覆寫限制的建議方式,是在動作方法上使用 RequestSizeLimitAttribute 屬性:

[RequestSizeLimit(100000000)]
public IActionResult MyActionMethod()

如果應用程式已開始讀取要求之後,才嘗試設定要求的限制,則會擲回例外狀況。 IsReadOnly 屬性可用來指出 MaxRequestBodySize 屬性是否處於唯讀狀態,代表要設定限制已經太遲。

如果應用程式應該覆寫每個要求的 MaxRequestBodySize,請使用 IHttpMaxRequestBodySizeFeature

public void Configure(IApplicationBuilder app, IWebHostEnvironment env, 
    ILogger<Startup> logger, IServer server)
{
    app.Use(async (context, next) =>
    {
        context.Features.Get<IHttpMaxRequestBodySizeFeature>()
            .MaxRequestBodySize = 10 * 1024;

        var serverAddressesFeature = 
            app.ServerFeatures.Get<IServerAddressesFeature>();
        var addresses = string.Join(", ", serverAddressesFeature?.Addresses);

        logger.LogInformation("Addresses: {Addresses}", addresses);

        await next.Invoke();
    });

    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
    }
    else
    {
        app.UseExceptionHandler("/Error");
    }

    app.UseStaticFiles();
    app.UseRouting();

    app.UseEndpoints(endpoints =>
    {
        endpoints.MapRazorPages();
    });
}

如果您使用 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 首碼和連接埠,選項包括:

    下列程式碼範例示範如何使用 UrlPrefixes 搭配位於連接埠 443 的伺服器本機 IP 位址 10.0.0.4

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseHttpSys(options =>
                {
                    options.UrlPrefixes.Add("https://10.0.0.4:443");
                });
                webBuilder.UseStartup<Startup>();
            });
    

    UrlPrefixes 的優點是針對錯誤格式的前置詞會立即產生錯誤訊息。

    UrlPrefixes 中的設定會覆寫 UseUrls/urls/ASPNETCORE_URLS 設定。 因此,、 UseUrls urlsASPNETCORE_URLS 環境變數的優點是可以更輕鬆地在 Kestrel 和 HTTP.sys 之間切換。

    HTTP.sys 使用 HTTP Server API UrlPrefix 字串格式

    警告

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

  6. 在伺服器上預先註冊 URL 首碼。

    用來設定 HTTP.sys 的內建工具是 netsh.exenetsh.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 的參考文件:

  8. 執行應用程式。

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

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

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

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

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

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

支援 gRPC 的 Advanced HTTP/2 功能

HTTP.sys 中的額外 HTTP/2 功能支援 gRPC,包括對回應結尾和傳送重設框架的支援。

使用 HTTP.sys 執行 gRPC 的需求:

  • Windows 10、OS 組建19041.508 或更新版本
  • TLS 1.2 或更新版本連線

預告片

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 是只在 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。

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

  • 內部部署需要中無法使用的功能 Kestrel 。 如需詳細資訊,請參閱 Kestrel vs. 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 的未來版本會推出 HTTP/2 設定旗標,包括使用 HTTP.sys 來停用 HTTP/2 的功能。

使用 Kerberos 的核心模式驗證

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

如何使用 HTTP.sys

設定 ASP.NET Core 應用程式使用 HTTP.sys

建置主機時,呼叫 UseHttpSys 擴充方法,並指定任何必要的 HttpSysOptions。 下列範例會將選項設定為它們的預設值:

public static IHostBuilder CreateHostBuilder(string[] args) =>
    Host.CreateDefaultBuilder(args)
        .ConfigureWebHostDefaults(webBuilder =>
        {
            webBuilder.UseHttpSys(options =>
            {
                options.AllowSynchronousIO = false;
                options.Authentication.Schemes = AuthenticationSchemes.None;
                options.Authentication.AllowAnonymous = true;
                options.MaxConnections = null;
                options.MaxRequestBodySize = 30000000;
                options.UrlPrefixes.Add("http://localhost:5005");
            });
            webBuilder.UseStartup<Startup>();
        });

其他的 HTTP.sys 設定則透過登錄設定處理。

HTTP.sys 選項

屬性 描述 預設
AllowSynchronousIO 控制是否允許 HttpContext.Request.BodyHttpContext.Response.Body 同步輸出/輸入。 false
Authentication.AllowAnonymous 允許匿名要求。 true
Authentication.Schemes 指定允許的驗證配置。 處置接聽程式之前可隨時修改。 值是由 AuthenticationSchemes 列舉提供: Basic 、、 Kerberos NegotiateNoneNTLM None
EnableResponseCaching 針對含有合格標頭的回應嘗試核心模式快取。 回應可能不包含 Set-CookieVaryPragma 標頭。 它必須包含為 publicCache-Control 標頭,且有 shared-max-agemax-age 值,或是 Expires 標頭。 true
Http503Verbosity 因為節流狀況而拒絕要求時的 HTTP.sys 行為。 Http503VerbosityLevel。
基本
MaxAccepts 可同時接受的數目上限。 5 × Environment.
ProcessorCount
MaxConnections 可接受的同時連線數量上限。 使用 -1 為無限多個。 使用 null 以使用登錄之整個電腦的設定。 null
(全電腦
設定)
MaxRequestBodySize 請參閱 MaxRequestBodySize 小節。 30000000 位元組
(~28.6 MB)
RequestQueueLimit 可以加入佇列的最大要求數目。 1000
RequestQueueMode 這會指出伺服器是否負責建立和設定要求佇列,或是否應該附加至現有的佇列。
附加至現有的佇列時,大部分現有的設定選項都不適用。
RequestQueueMode.Create
RequestQueueName HTTP.sys 要求佇列的名稱。 null (匿名佇列)
ThrowWriteExceptions 指出若回應本文因為用戶端中斷連線而寫入失敗時,應擲回例外狀況或正常完成。 false
(正常完成)
Timeouts 公開 HTTP.sys TimeoutManager 設定,這也可在登錄中設定。 API 連結可提供包括預設值在內每個設定的詳細資訊:
UrlPrefixes 指定 UrlPrefixCollection 以向 HTTP.sys 註冊。 最有用的是 UrlPrefixCollection.Add ,它是用來將前置詞加入至集合。 處置接聽程式之前可隨時修改這些內容。

MaxRequestBodySize

任何要求所允許的大小上限 (以位元組為單位)。 當設定為 null 時,要求主體大小上限為無限制。 此限制對升級連線不會有任何影響,因為其一律為無限制。

在 ASP.NET Core MVC 應用程式中針對單一 IActionResult 覆寫限制的建議方式,是在動作方法上使用 RequestSizeLimitAttribute 屬性:

[RequestSizeLimit(100000000)]
public IActionResult MyActionMethod()

如果應用程式已開始讀取要求之後,才嘗試設定要求的限制,則會擲回例外狀況。 IsReadOnly 屬性可用來指出 MaxRequestBodySize 屬性是否處於唯讀狀態,代表要設定限制已經太遲。

如果應用程式應該覆寫每個要求的 MaxRequestBodySize,請使用 IHttpMaxRequestBodySizeFeature

public void Configure(IApplicationBuilder app, IWebHostEnvironment env, 
    ILogger<Startup> logger, IServer server)
{
    app.Use(async (context, next) =>
    {
        context.Features.Get<IHttpMaxRequestBodySizeFeature>()
            .MaxRequestBodySize = 10 * 1024;

        var serverAddressesFeature = 
            app.ServerFeatures.Get<IServerAddressesFeature>();
        var addresses = string.Join(", ", serverAddressesFeature?.Addresses);

        logger.LogInformation("Addresses: {Addresses}", addresses);

        await next.Invoke();
    });

    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
    }
    else
    {
        app.UseExceptionHandler("/Error");
    }

    app.UseStaticFiles();
    app.UseRouting();

    app.UseEndpoints(endpoints =>
    {
        endpoints.MapRazorPages();
    });
}

如果您使用 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 首碼和連接埠,選項包括:

    下列程式碼範例示範如何使用 UrlPrefixes 搭配位於連接埠 443 的伺服器本機 IP 位址 10.0.0.4

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseHttpSys(options =>
                {
                    options.UrlPrefixes.Add("https://10.0.0.4:443");
                });
                webBuilder.UseStartup<Startup>();
            });
    

    UrlPrefixes 的優點是針對錯誤格式的前置詞會立即產生錯誤訊息。

    UrlPrefixes 中的設定會覆寫 UseUrls/urls/ASPNETCORE_URLS 設定。 因此,、 UseUrls urlsASPNETCORE_URLS 環境變數的優點是可以更輕鬆地在 Kestrel 和 HTTP.sys 之間切換。

    HTTP.sys 使用 HTTP Server API UrlPrefix 字串格式

    警告

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

  6. 在伺服器上預先註冊 URL 首碼。

    用來設定 HTTP.sys 的內建工具是 netsh.exenetsh.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 的參考文件:

  8. 執行應用程式。

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

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

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

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

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

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

支援 gRPC 的 Advanced HTTP/2 功能

HTTP.sys 中的額外 HTTP/2 功能支援 gRPC,包括對回應結尾和傳送重設框架的支援。

使用 HTTP.sys 執行 gRPC 的需求:

  • Windows 10、OS 組建19041.508 或更新版本
  • TLS 1.2 或更新版本連線

預告片

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 規格錯誤碼一節

其他資源