Sterownik HTTP.sys implementacja serwera sieci web platformy ASP.NET CoreHTTP.sys web server implementation in ASP.NET Core

Przez Dykstra Tomasz, Roaming Krzysztof, i Luke LathamBy Tom Dykstra, Chris Ross, and Luke Latham

Uwaga

Ten temat dotyczy do platformy ASP.NET Core 2.0 lub nowszej.This topic applies to ASP.NET Core 2.0 or later. We wcześniejszych wersjach programu ASP.NET Core, nosi nazwę HTTP.sys WebListener.In earlier versions of ASP.NET Core, HTTP.sys is named WebListener.

Sterownik HTTP.sys jest serwera sieci web dla platformy ASP.NET Core systemem Windows.HTTP.sys is a web server for ASP.NET Core that only runs on Windows. Sterownik HTTP.sys stanowi alternatywę dla Kestrel i oferuje funkcje, które nie zapewnia Kestrel.HTTP.sys is an alternative to Kestrel and offers some features that Kestrel doesn't provide.

Ważne

Sterownik HTTP.sys jest niezgodny z moduł platformy ASP.NET Core i nie można używać z usług IIS lub usług IIS Express.HTTP.sys is incompatible with the ASP.NET Core Module and can't be used with IIS or IIS Express.

Sterownik HTTP.sys obsługuje następujące funkcje:HTTP.sys supports the following features:

  • Uwierzytelnianie systemu WindowsWindows Authentication
  • Udostępnianie portówPort sharing
  • Protokół HTTPS z SNIHTTPS with SNI
  • HTTP/2 za pośrednictwem protokołu TLS (system Windows 10 lub nowszy)HTTP/2 over TLS (Windows 10 or later)
  • Przekazywanie pliku bezpośredniegoDirect file transmission
  • Buforowanie odpowiedziResponse caching
  • Protokół WebSockets (z systemem Windows 8 lub nowszy)WebSockets (Windows 8 or later)

Obsługiwane wersje systemu Windows:Supported Windows versions:

  • Windows 7 lub nowszyWindows 7 or later
  • Windows Server 2008 R2 lub nowszyWindows Server 2008 R2 or later

Wyświetlić lub pobrać przykładowy kod (sposobu pobierania)View or download sample code (how to download)

Kiedy należy używać HTTP.sysWhen to use HTTP.sys

Sterownik HTTP.sys jest przydatne w przypadku wdrożeń gdzie:HTTP.sys is useful for deployments where:

  • Brak konieczności udostępnić server bezpośrednio do Internetu, nie za pomocą usług IIS.There's a need to expose the server directly to the Internet without using IIS.

    Sterownik HTTP.sys komunikuje się bezpośrednio z Internetem

  • Wewnętrznego wdrażania wymaga funkcji nie jest dostępna w Kestrel, takich jak uwierzytelniania systemu Windows.An internal deployment requires a feature not available in Kestrel, such as Windows Authentication.

    Sterownik HTTP.sys komunikuje się bezpośrednio z siecią wewnętrzną

Sterownik HTTP.sys jest dojrzała technologia, która chroni przed wiele rodzajów ataków i zapewnia niezawodność, zabezpieczeń i skalowalność serwera sieci web kompletne.HTTP.sys is mature technology that protects against many types of attacks and provides the robustness, security, and scalability of a full-featured web server. SAM działa jako odbiornik HTTP u góry pliku HTTP.sys.IIS itself runs as an HTTP listener on top of HTTP.sys.

Jak używać HTTP.sysHow to use HTTP.sys

Konfigurowanie aplikacji platformy ASP.NET Core korzystanie z pliku HTTP.sysConfigure the ASP.NET Core app to use HTTP.sys

  1. Odwołanie pakietu w pliku projektu nie jest wymagane, korzystając z Microsoft.AspNetCore.All metapackage (nuget.org) (platformy ASP.NET Core w wersji 2.0 lub nowszej).A package reference in the project file isn't required when using the Microsoft.AspNetCore.All metapackage (nuget.org) (ASP.NET Core 2.0 or later). Korzystając z nie Microsoft.AspNetCore.All metapackage, Dodaj odwołanie do pakietu Microsoft.AspNetCore.Server.HttpSys.When not using the Microsoft.AspNetCore.All metapackage, add a package reference to Microsoft.AspNetCore.Server.HttpSys.

  2. Wywołanie UseHttpSys — metoda rozszerzenia podczas kompilowania hosta sieci web, określając każdego wymaganego opcje HTTP.sys:Call the UseHttpSys extension method when building the web host, specifying any required HTTP.sys options:

    public static IWebHost BuildWebHost(string[] args) =>
        WebHost.CreateDefaultBuilder(args)
            .UseStartup<Startup>()
            .UseHttpSys(options =>
            {
                // The following options are set to default values.
                options.Authentication.Schemes = AuthenticationSchemes.None;
                options.Authentication.AllowAnonymous = true;
                options.MaxConnections = null;
                options.MaxRequestBodySize = 30000000;
                options.UrlPrefixes.Add("http://localhost:5000");
            })
            .Build();
    

    Obsługiwane przez sterownik HTTP.sys dodatkowe czynności konfiguracyjne ustawień rejestru.Additional HTTP.sys configuration is handled through registry settings.

    Opcje HTTP.sysHTTP.sys options

    WłaściwośćProperty OpisDescription DomyślnyDefault
    AllowSynchronousIOAllowSynchronousIO Kontrolowanie, czy synchroniczne we/wy jest dozwolone dla HttpContext.Request.Body i HttpContext.Response.Body.Control whether synchronous input/output is allowed for the HttpContext.Request.Body and HttpContext.Response.Body. true
    Authentication.AllowAnonymousAuthentication.AllowAnonymous Zezwalaj na anonimowe żądania.Allow anonymous requests. true
    Authentication.SchemesAuthentication.Schemes Określ schematy uwierzytelniania dozwolonych.Specify the allowed authentication schemes. Może być modyfikowany w dowolnym momencie przed disposing odbiornika.May be modified at any time prior to disposing the listener. Wartości są dostarczane przez wyliczenia AuthenticationSchemes: Basic, Kerberos, Negotiate, None, i NTLM.Values are provided by the AuthenticationSchemes enum: Basic, Kerberos, Negotiate, None, and NTLM. None
    EnableResponseCachingEnableResponseCaching Próba trybu jądra buforowanie odpowiedzi z kwalifikujących się nagłówków.Attempt kernel-mode caching for responses with eligible headers. Odpowiedź nie może zawierać Set-Cookie, Vary, lub Pragma nagłówków.The response may not include Set-Cookie, Vary, or Pragma headers. Musi on zawierać Cache-Control nagłówka to jest public i shared-max-age lub max-age wartość, lub Expires nagłówka.It must include a Cache-Control header that's public and either a shared-max-age or max-age value, or an Expires header. true
    MaxAcceptsMaxAccepts Maksymalna liczba równoczesnych akceptuje.The maximum number of concurrent accepts. 5 × środowiska.
    ProcessorCount
    5 × Environment.
    ProcessorCount
    maxConnectionsMaxConnections Maksymalna liczba jednoczesnych połączeń, aby zaakceptować.The maximum number of concurrent connections to accept. Użyj -1 = nieskończoność.Use -1 for infinite. Użyj null do używania ustawienia komputera.Use null to use the registry's machine-wide setting. null
    (unlimited)(unlimited)
    MaxRequestBodySizeMaxRequestBodySize Zobacz MaxRequestBodySize sekcji.See the MaxRequestBodySize section. 30000000 bajtów30000000 bytes
    (~28.6 MB)(~28.6 MB)
    RequestQueueLimitRequestQueueLimit Maksymalna liczba żądań, które mogą być umieszczone w kolejce.The maximum number of requests that can be queued. 10001000
    ThrowWriteExceptionsThrowWriteExceptions Wskazać, czy operacji zapisu treści odpowiedzi, które zakończy się niepowodzeniem z powodu klienta połączenie powinno zgłaszają wyjątki, czy zakończone normalnie.Indicate if response body writes that fail due to client disconnects should throw exceptions or complete normally. false
    (zazwyczaj ukończenia)(complete normally)
    Limity czasuTimeouts Udostępnianie pliku HTTP.sys TimeoutManager konfigurację, która może być również skonfigurowane w rejestrze.Expose the HTTP.sys TimeoutManager configuration, which may also be configured in the registry. Skorzystaj z łączy interfejsu API, aby dowiedzieć się więcej na temat każdego ustawienia, łącznie z wartościami domyślnymi:Follow the API links to learn more about each setting, including default values:
    UrlPrefixesUrlPrefixes Określ UrlPrefixCollection można zarejestrować przy użyciu składnika HTTP.sys.Specify the UrlPrefixCollection to register with HTTP.sys. Najbardziej przydatne jest UrlPrefixCollection.Add, który służy do dodania do kolekcji prefiksu.The most useful is UrlPrefixCollection.Add, which is used to add a prefix to the collection. Te mogą zostać zmodyfikowane w dowolnym momencie przed disposing odbiornika.These may be modified at any time prior to disposing the listener.

    MaxRequestBodySizeMaxRequestBodySize

    Maksymalny dozwolony rozmiar żadnych treści żądania w bajtach.The maximum allowed size of any request body in bytes. Jeśli wartość null, żądanie maksymalny rozmiar treści jest nieograniczony.When set to null, the maximum request body size is unlimited. To ograniczenie nie ma wpływu na uaktualnionym połączeń, które są zawsze nieograniczone.This limit has no effect on upgraded connections, which are always unlimited.

    Zalecaną metodą do zastąpienia limitu w aplikacji ASP.NET Core MVC z jednym IActionResult jest użycie RequestSizeLimitAttribute atrybutu metody akcji:The recommended method to override the limit in an ASP.NET Core MVC app for a single IActionResult is to use the RequestSizeLimitAttribute attribute on an action method:

    [RequestSizeLimit(100000000)]
    public IActionResult MyActionMethod()
    

    Jeśli aplikacja próbuje skonfigurować limit na żądanie, po uruchomieniu aplikacji odczytu żądania, jest zgłaszany wyjątek.An exception is thrown if the app attempts to configure the limit on a request after the app has started reading the request. IsReadOnly Właściwości można wskazać, czy MaxRequestBodySize właściwość jest w stanie tylko do odczytu, co oznacza jest za późno skonfigurować limit.An IsReadOnly property can be used to indicate if the MaxRequestBodySize property is in a read-only state, meaning it's too late to configure the limit.

    Jeśli aplikacja powinny zastępować MaxRequestBodySize na żądanie, użyj IHttpMaxRequestBodySizeFeature:If the app should override MaxRequestBodySize per-request, use the IHttpMaxRequestBodySizeFeature:

    public void Configure(IApplicationBuilder app, IHostingEnvironment env, 
        ILogger<Startup> logger)
    {
        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}");
    
            await next.Invoke();
        });
    
        if (env.IsDevelopment())
        {
            app.UseDeveloperExceptionPage();
            app.UseDatabaseErrorPage();
        }
        else
        {
            app.UseExceptionHandler("/Error");
        }
    
        app.UseStaticFiles();
        app.UseMvc();
    }
    
  3. Jeśli używasz programu Visual Studio, upewnij się, że aplikacja nie jest skonfigurowana do uruchamiania usług IIS lub usług IIS Express.If using Visual Studio, make sure the app isn't configured to run IIS or IIS Express.

    W programie Visual Studio domyślnego profilu uruchamiania jest dla usług IIS Express.In Visual Studio, the default launch profile is for IIS Express. Aby uruchomić projekt jako aplikację konsoli, ręcznie zmienić wybranego profilu, jak pokazano na poniższym zrzucie ekranu:To run the project as a console app, manually change the selected profile, as shown in the following screen shot:

    Wybierz profil aplikacji konsoli

Konfigurowanie systemu Windows ServerConfigure Windows Server

  1. Jeśli aplikacja jest wdrożenia zależne od framework, zainstaluj oprogramowanie .NET Core i .NET Framework (jeśli jest to aplikacja .NET Core docelowy program .NET Framework).If the app is a framework-dependent deployment, install .NET Core, .NET Framework, or both (if the app is a .NET Core app targeting the .NET Framework).

  2. Skonfiguruj adresy URL i portów dla aplikacji.Configure URLs and ports for the app.

    Domyślnie program ASP.NET Core wiąże http://localhost:5000.By default, ASP.NET Core binds to http://localhost:5000. Aby skonfigurować prefiksy URL i portów, są następujące opcje przy użyciu:To configure URL prefixes and ports, options include using:

    Poniższy przykładowy kod przedstawia sposób użycia UrlPrefixes:The following code example shows how to use UrlPrefixes:

    public static IWebHost BuildWebHost(string[] args) =>
        WebHost.CreateDefaultBuilder(args)
            .UseStartup<Startup>()
            .UseHttpSys(options =>
            {
                // The following options are set to default values.
                options.Authentication.Schemes = AuthenticationSchemes.None;
                options.Authentication.AllowAnonymous = true;
                options.MaxConnections = null;
                options.MaxRequestBodySize = 30000000;
                options.UrlPrefixes.Add("http://localhost:5000");
            })
            .Build();
    

    Zaletą UrlPrefixes jest natychmiast wygenerowany komunikat o błędzie dla prefiksów niewłaściwie sformatowany.An advantage of UrlPrefixes is that an error message is generated immediately for improperly formatted prefixes.

    Ustawienia w UrlPrefixes zastąpienia UseUrls / urls / ASPNETCORE_URLS ustawienia.The settings in UrlPrefixes override UseUrls/urls/ASPNETCORE_URLS settings. W związku z tym zaletą UseUrls, urlsi ASPNETCORE_URLS zmiennej środowiskowej, jest łatwiejsze w celu przełączania się między Kestrel i sterownik HTTP.sys.Therefore, an advantage of UseUrls, urls, and the ASPNETCORE_URLS environment variable is that it's easier to switch between Kestrel and HTTP.sys. Aby uzyskać więcej informacji na temat UseUrls, urls, i ASPNETCORE_URLS, zobacz hostingu.For more information on UseUrls, urls, and ASPNETCORE_URLS, see Hosting.

    Korzysta z pliku HTTP.sys formaty ciągu UrlPrefix interfejsu API serwera HTTP.HTTP.sys uses the HTTP Server API UrlPrefix string formats.

    Ostrzeżenie

    Powiązania najwyższego poziomu symbolu wieloznacznego (http://*:80/ i http://+:80) powinien nie można użyć.Top-level wildcard bindings (http://*:80/ and http://+:80) should not be used. Powiązania wieloznaczny najwyższego poziomu można otwarcie luk w zabezpieczeniach aplikacji.Top-level wildcard bindings can open up your app to security vulnerabilities. Dotyczy to zarówno silne i słabe symboli wieloznacznych.This applies to both strong and weak wildcards. Użyj nazwy hostów jawne zamiast symboli wieloznacznych.Use explicit host names rather than wildcards. Powiązanie symbolu wieloznacznego domeny podrzędnej (na przykład *.mysub.com) nie ma to zagrożenie bezpieczeństwa, jeśli kontrolować domeny nadrzędnej całego (w przeciwieństwie do *.com, której występuje).Subdomain wildcard binding (for example, *.mysub.com) doesn't have this security risk if you control the entire parent domain (as opposed to *.com, which is vulnerable). Zobacz rfc7230 sekcji-5.4 Aby uzyskać więcej informacji.See rfc7230 section-5.4 for more information.

  3. Preregister prefiksów URL do powiązania do pliku HTTP.sys i konfigurowanie certyfikatów x.509.Preregister URL prefixes to bind to HTTP.sys and set up x.509 certificates.

    Jeśli adres URL prefiksy nie są preregistered w systemie Windows, uruchom aplikację z uprawnieniami administratora.If URL prefixes aren't preregistered in Windows, run the app with administrator privileges. Jedynym wyjątkiem jest podczas wiązania z hostem lokalnym przy użyciu protokołu HTTP (a nie HTTPS) z większą niż 1024 numeru portu.The only exception is when binding to localhost using HTTP (not HTTPS) with a port number greater than 1024. W takim przypadku uprawnienia administratora nie są wymagane.In that case, administrator privileges aren't required.

    1. Wbudowane narzędzie do konfigurowania HTTP.sys jest netsh.exe.The built-in tool for configuring HTTP.sys is netsh.exe. netsh.exe służy do zarezerwowania prefiksy URL i przypisać certyfikatów X.509.netsh.exe is used to reserve URL prefixes and assign X.509 certificates. Narzędzie wymaga uprawnień administratora.The tool requires administrator privileges.

      W poniższym przykładzie przedstawiono poleceń do zarezerwowania prefiksy URL porty 80 i 443:The following example shows the commands to reserve URL prefixes for ports 80 and 443:

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

      Poniższy przykład pokazuje, jak można przypisać certyfikat X.509:The following example shows how to assign an X.509 certificate:

      netsh http add sslcert ipport=0.0.0.0:443 certhash=MyCertHash_Here appid={00000000-0000-0000-0000-000000000000}"
      

      Odwołanie dokumentacji netsh.exe:Reference documentation for netsh.exe:

    2. Tworzenie certyfikatów X.509 z podpisem własnym, jeśli jest to wymagane.Create self-signed X.509 certificates, if required.

      W systemie Windows, można tworzyć certyfikaty z podpisem własnym za pomocą polecenia cmdlet programu PowerShell nowy SelfSignedCertificate.On Windows, self-signed certificates can be created using the New-SelfSignedCertificate PowerShell cmdlet. Na przykład nieobsługiwany zobacz UpdateIISExpressSSLForChrome.ps1.For an unsupported example, see UpdateIISExpressSSLForChrome.ps1.

      System macOS, Linux i Windows, można utworzyć certyfikatów przy użyciu OpenSSL.On macOS, Linux, and Windows, certificates can be created using OpenSSL.

  4. Otwórz porty zapory, aby zezwolić na ruch do pliku HTTP.sys.Open firewall ports to allow traffic to reach HTTP.sys. Użyj netsh.exe lub poleceń cmdlet programu PowerShell.Use netsh.exe or PowerShell cmdlets.

Serwer proxy i scenariuszy usługi równoważenia obciążeniaProxy server and load balancer scenarios

Dla aplikacji hostowanych przez rozszerzenie HTTP.sys, współpracujące z żądaniami z Internetu lub sieci firmowej dodatkowa konfiguracja może być wymagane, gdy hosting za serwerów proxy i moduły równoważenia obciążenia.For apps hosted by HTTP.sys that interact with requests from the Internet or a corporate network, additional configuration might be required when hosting behind proxy servers and load balancers. Aby uzyskać więcej informacji, zobacz Konfigurowanie platformy ASP.NET Core do pracy z serwerów proxy i moduły równoważenia obciążenia.For more information, see Configure ASP.NET Core to work with proxy servers and load balancers.

Dodatkowe zasobyAdditional resources