Implementação do servidor Web HTTP.sys no ASP.NET CoreHTTP.sys web server implementation in ASP.NET Core

Por Tom Dykstra, Chris Ross e Luke LathamBy Tom Dykstra, Chris Ross, and Luke Latham

O HTTP.sys é um servidor Web para ASP.NET Core executado apenas no Windows.HTTP.sys is a web server for ASP.NET Core that only runs on Windows. O HTTP.sys é uma alternativa ao servidor Kestrel e oferece alguns recursos não disponibilizados pelo Kestrel.HTTP.sys is an alternative to Kestrel server and offers some features that Kestrel doesn't provide.

Importante

O HTTP.sys não é compatível com o Módulo do ASP.NET Core e não pode ser usado com IIS ou IIS Express.HTTP.sys isn't compatible with the ASP.NET Core Module and can't be used with IIS or IIS Express.

O HTTP.sys dá suporte aos seguintes recursos:HTTP.sys supports the following features:

  • Autenticação do WindowsWindows Authentication
  • Compartilhamento de portaPort sharing
  • HTTPS com SNIHTTPS with SNI
  • HTTP/2 sobre TLS (Windows 10 ou posterior)HTTP/2 over TLS (Windows 10 or later)
  • Transmissão direta de arquivoDirect file transmission
  • Cache de respostaResponse caching
  • WebSockets (Windows 8 ou posterior)WebSockets (Windows 8 or later)

Versões do Windows compatíveis:Supported Windows versions:

  • Windows 7 ou posteriorWindows 7 or later
  • Windows Server 2008 R2 ou posteriorWindows Server 2008 R2 or later

Exibir ou baixar código de exemplo (como baixar)View or download sample code (how to download)

Quando usar o HTTP.sysWhen to use HTTP.sys

O HTTP.sys é útil nas implantações em que:HTTP.sys is useful for deployments where:

  • É necessário expor o servidor diretamente à Internet sem usar o IIS.There's a need to expose the server directly to the Internet without using IIS.

    O HTTP.sys se comunica diretamente com a Internet

  • As implantações internas exigem um recurso que não está disponível no Kestrel, como a Autenticação do Windows.An internal deployment requires a feature not available in Kestrel, such as Windows Authentication.

    O HTTP.sys se comunica diretamente com a rede interna

O HTTP.sys é uma tecnologia madura que protege contra vários tipos de ataques e proporciona as propriedades de robustez, segurança e escalabilidade de um servidor Web completo.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. O próprio IIS é executado como um ouvinte HTTP sobre o HTTP.sys.IIS itself runs as an HTTP listener on top of HTTP.sys.

Compatibilidade com HTTP/2HTTP/2 support

O HTTP/2 estará habilitado para aplicativos ASP.NET Core se os seguintes requisitos básicos forem atendidos:HTTP/2 is enabled for ASP.NET Core apps if the following base requirements are met:

Se uma conexão HTTP/2 for estabelecida, HttpRequest.Protocol relatará HTTP/2.If an HTTP/2 connection is established, HttpRequest.Protocol reports HTTP/2.

Se uma conexão HTTP/2 for estabelecida, HttpRequest.Protocol relatará HTTP/1.1.If an HTTP/2 connection is established, HttpRequest.Protocol reports HTTP/1.1.

O HTTP/2 está habilitado por padrão.HTTP/2 is enabled by default. Se uma conexão HTTP/2 não tiver sido estabelecida, a conexão retornará para HTTP/1.1.If an HTTP/2 connection isn't established, the connection falls back to HTTP/1.1. Em uma versão futura do Windows, os sinalizadores de configuração de HTTP/2 estarão disponíveis e contarão com a capacidade de desabilitar o HTTP/2 com HTTP.sys.In a future release of Windows, HTTP/2 configuration flags will be available, including the ability to disable HTTP/2 with HTTP.sys.

Autenticação de modo kernel com KerberosKernel mode authentication with Kerberos

O HTTP.sys delega à autenticação de modo kernel com o protocolo de autenticação Kerberos.HTTP.sys delegates to kernel mode authentication with the Kerberos authentication protocol. Não há suporte para autenticação de modo de usuário com o Kerberos e o HTTP.sys.User mode authentication isn't supported with Kerberos and HTTP.sys. A conta do computador precisa ser usada para descriptografar o token/tíquete do Kerberos que é obtido do Active Directory e encaminhado pelo cliente ao servidor para autenticar o usuário.The machine account must be used to decrypt the Kerberos token/ticket that's obtained from Active Directory and forwarded by the client to the server to authenticate the user. Registre o SPN (nome da entidade de serviço) do host, não do usuário do aplicativo.Register the Service Principal Name (SPN) for the host, not the user of the app.

Como usar o HTTP.sysHow to use HTTP.sys

Configurar o aplicativo ASP.NET Core para usar o HTTP.sysConfigure the ASP.NET Core app to use HTTP.sys

Uma referência de pacote no arquivo de projeto não é necessária ao usar o metapacote Microsoft. AspNetCore. app (NuGet.org).A package reference in the project file isn't required when using the Microsoft.AspNetCore.App metapackage (nuget.org). Se não estiver usando o metapacote Microsoft.AspNetCore.App, adicione uma referência do pacote a Microsoft.AspNetCore.Server.HttpSys.When not using the Microsoft.AspNetCore.App metapackage, add a package reference to Microsoft.AspNetCore.Server.HttpSys.

Chame o método de extensão UseHttpSys ao compilar o host, especificando qualquer HttpSysOptions necessária.Call the UseHttpSys extension method when building the host, specifying any required HttpSysOptions. O exemplo a seguir define as opções para seus valores padrão:The following example sets options to their default values:

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

A configuração adicional do HTTP.sys é tratada por meio das configurações do registro.Additional HTTP.sys configuration is handled through registry settings.

Opções do HTTP.sysHTTP.sys options

PropriedadeProperty DescriçãoDescription PadrãoDefault
AllowSynchronousIOAllowSynchronousIO Controlar quando a Entrada/Saída síncrona deve ser permitida para HttpContext.Request.Body e HttpContext.Response.Body.Control whether synchronous input/output is allowed for the HttpContext.Request.Body and HttpContext.Response.Body. false
Authentication.AllowAnonymousAuthentication.AllowAnonymous Permitir solicitações anônimas.Allow anonymous requests. true
Authentication.SchemesAuthentication.Schemes Especificar os esquemas de autenticação permitidos.Specify the allowed authentication schemes. É possível modificar a qualquer momento antes de descartar o ouvinte.May be modified at any time prior to disposing the listener. Os valores são fornecidos pela enumeração AuthenticationSchemes: Basic, Kerberos, Negotiate, None e NTLM.Values are provided by the AuthenticationSchemes enum: Basic, Kerberos, Negotiate, None, and NTLM. None
EnableResponseCachingEnableResponseCaching Tentativa de cache do modo kernel para obtenção de respostas com cabeçalhos qualificados.Attempt kernel-mode caching for responses with eligible headers. A resposta pode não incluir Set-Cookie, Vary ou cabeçalhos Pragma.The response may not include Set-Cookie, Vary, or Pragma headers. Ela deve incluir um cabeçalho Cache-Control que seja public e um valor shared-max-age ou max-age, ou um cabeçalho Expires.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
MaxAccepts O número máximo de aceitações simultâneas.The maximum number of concurrent accepts. 5 × Ambiente.
ProcessorCount
5 × Environment.
ProcessorCount
MaxConnections O número máximo de conexões simultâneas a serem aceitas.The maximum number of concurrent connections to accept. Usar -1 como infinito.Use -1 for infinite. Usar null a fim de usar a configuração que abranja toda máquina do registro.Use null to use the registry's machine-wide setting. null
(ilimitado)(unlimited)
MaxRequestBodySize Confira a seção MaxRequestBodySize.See the MaxRequestBodySize section. 30.000.000 de bytes30000000 bytes
(28,6 MB)(~28.6 MB)
RequestQueueLimit O número máximo de solicitações que podem ser colocadas na fila.The maximum number of requests that can be queued. 10001000
RequestQueueMode Isso indica se o servidor é responsável por criar e configurar a fila de solicitações ou se deve ser anexado a uma fila existente.This indicates whether the server is responsible for creating and configuring the request queue, or if it should attach to an existing queue.
A maioria das opções de configuração existentes não se aplicam ao anexar a uma fila existente.Most existing configuration options do not apply when attaching to an existing queue.
RequestQueueMode.Create
RequestQueueName O nome da fila de solicitações de HTTP. sys.The name of the HTTP.sys request queue. null (fila anônima)null (Anonymous queue)
ThrowWriteExceptions Indica se as gravações do corpo da resposta que falham quando o cliente se desconecta devem gerar exceções ou serem concluídas normalmente.Indicate if response body writes that fail due to client disconnects should throw exceptions or complete normally. false
(concluir normalmente)(complete normally)
Timeouts Expor a configuração TimeoutManager do HTTP.sys, que também pode ser configurado no Registro.Expose the HTTP.sys TimeoutManager configuration, which may also be configured in the registry. Siga os links de API para saber mais sobre cada configuração, inclusive os valores padrão:Follow the API links to learn more about each setting, including default values:
UrlPrefixes Especifique o UrlPrefixCollection para registrar com o HTTP.sys.Specify the UrlPrefixCollection to register with HTTP.sys. A mais útil é UrlPrefixCollection.Add, que é usada para adicionar um prefixo à coleção.The most useful is UrlPrefixCollection.Add, which is used to add a prefix to the collection. É possível modificá-las a qualquer momento antes de descartar o ouvinte.These may be modified at any time prior to disposing the listener.
PropriedadeProperty DescriçãoDescription PadrãoDefault
AllowSynchronousIOAllowSynchronousIO Controlar quando a Entrada/Saída síncrona deve ser permitida para HttpContext.Request.Body e HttpContext.Response.Body.Control whether synchronous input/output is allowed for the HttpContext.Request.Body and HttpContext.Response.Body. false
Authentication.AllowAnonymousAuthentication.AllowAnonymous Permitir solicitações anônimas.Allow anonymous requests. true
Authentication.SchemesAuthentication.Schemes Especificar os esquemas de autenticação permitidos.Specify the allowed authentication schemes. É possível modificar a qualquer momento antes de descartar o ouvinte.May be modified at any time prior to disposing the listener. Os valores são fornecidos pela enumeração AuthenticationSchemes: Basic, Kerberos, Negotiate, None e NTLM.Values are provided by the AuthenticationSchemes enum: Basic, Kerberos, Negotiate, None, and NTLM. None
EnableResponseCachingEnableResponseCaching Tentativa de cache do modo kernel para obtenção de respostas com cabeçalhos qualificados.Attempt kernel-mode caching for responses with eligible headers. A resposta pode não incluir Set-Cookie, Vary ou cabeçalhos Pragma.The response may not include Set-Cookie, Vary, or Pragma headers. Ela deve incluir um cabeçalho Cache-Control que seja public e um valor shared-max-age ou max-age, ou um cabeçalho Expires.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
MaxAccepts O número máximo de aceitações simultâneas.The maximum number of concurrent accepts. 5 × Ambiente.
ProcessorCount
5 × Environment.
ProcessorCount
MaxConnections O número máximo de conexões simultâneas a serem aceitas.The maximum number of concurrent connections to accept. Usar -1 como infinito.Use -1 for infinite. Usar null a fim de usar a configuração que abranja toda máquina do registro.Use null to use the registry's machine-wide setting. null
(ilimitado)(unlimited)
MaxRequestBodySize Confira a seção MaxRequestBodySize.See the MaxRequestBodySize section. 30.000.000 de bytes30000000 bytes
(28,6 MB)(~28.6 MB)
RequestQueueLimit O número máximo de solicitações que podem ser colocadas na fila.The maximum number of requests that can be queued. 10001000
ThrowWriteExceptions Indica se as gravações do corpo da resposta que falham quando o cliente se desconecta devem gerar exceções ou serem concluídas normalmente.Indicate if response body writes that fail due to client disconnects should throw exceptions or complete normally. false
(concluir normalmente)(complete normally)
Timeouts Expor a configuração TimeoutManager do HTTP.sys, que também pode ser configurado no Registro.Expose the HTTP.sys TimeoutManager configuration, which may also be configured in the registry. Siga os links de API para saber mais sobre cada configuração, inclusive os valores padrão:Follow the API links to learn more about each setting, including default values:
UrlPrefixes Especifique o UrlPrefixCollection para registrar com o HTTP.sys.Specify the UrlPrefixCollection to register with HTTP.sys. A mais útil é UrlPrefixCollection.Add, que é usada para adicionar um prefixo à coleção.The most useful is UrlPrefixCollection.Add, which is used to add a prefix to the collection. É possível modificá-las a qualquer momento antes de descartar o ouvinte.These may be modified at any time prior to disposing the listener.
PropriedadeProperty DescriçãoDescription PadrãoDefault
AllowSynchronousIOAllowSynchronousIO Controlar quando a Entrada/Saída síncrona deve ser permitida para HttpContext.Request.Body e HttpContext.Response.Body.Control whether synchronous input/output is allowed for the HttpContext.Request.Body and HttpContext.Response.Body. true
Authentication.AllowAnonymousAuthentication.AllowAnonymous Permitir solicitações anônimas.Allow anonymous requests. true
Authentication.SchemesAuthentication.Schemes Especificar os esquemas de autenticação permitidos.Specify the allowed authentication schemes. É possível modificar a qualquer momento antes de descartar o ouvinte.May be modified at any time prior to disposing the listener. Os valores são fornecidos pela enumeração AuthenticationSchemes: Basic, Kerberos, Negotiate, None e NTLM.Values are provided by the AuthenticationSchemes enum: Basic, Kerberos, Negotiate, None, and NTLM. None
EnableResponseCachingEnableResponseCaching Tentativa de cache do modo kernel para obtenção de respostas com cabeçalhos qualificados.Attempt kernel-mode caching for responses with eligible headers. A resposta pode não incluir Set-Cookie, Vary ou cabeçalhos Pragma.The response may not include Set-Cookie, Vary, or Pragma headers. Ela deve incluir um cabeçalho Cache-Control que seja public e um valor shared-max-age ou max-age, ou um cabeçalho Expires.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
MaxAccepts O número máximo de aceitações simultâneas.The maximum number of concurrent accepts. 5 × Ambiente.
ProcessorCount
5 × Environment.
ProcessorCount
MaxConnections O número máximo de conexões simultâneas a serem aceitas.The maximum number of concurrent connections to accept. Usar -1 como infinito.Use -1 for infinite. Usar null a fim de usar a configuração que abranja toda máquina do registro.Use null to use the registry's machine-wide setting. null
(ilimitado)(unlimited)
MaxRequestBodySize Confira a seção MaxRequestBodySize.See the MaxRequestBodySize section. 30.000.000 de bytes30000000 bytes
(28,6 MB)(~28.6 MB)
RequestQueueLimit O número máximo de solicitações que podem ser colocadas na fila.The maximum number of requests that can be queued. 10001000
ThrowWriteExceptions Indica se as gravações do corpo da resposta que falham quando o cliente se desconecta devem gerar exceções ou serem concluídas normalmente.Indicate if response body writes that fail due to client disconnects should throw exceptions or complete normally. false
(concluir normalmente)(complete normally)
Timeouts Expor a configuração TimeoutManager do HTTP.sys, que também pode ser configurado no Registro.Expose the HTTP.sys TimeoutManager configuration, which may also be configured in the registry. Siga os links de API para saber mais sobre cada configuração, inclusive os valores padrão:Follow the API links to learn more about each setting, including default values:
UrlPrefixes Especifique o UrlPrefixCollection para registrar com o HTTP.sys.Specify the UrlPrefixCollection to register with HTTP.sys. A mais útil é UrlPrefixCollection.Add, que é usada para adicionar um prefixo à coleção.The most useful is UrlPrefixCollection.Add, which is used to add a prefix to the collection. É possível modificá-las a qualquer momento antes de descartar o ouvinte.These may be modified at any time prior to disposing the listener.

MaxRequestBodySizeMaxRequestBodySize

O tamanho máximo permitido em bytes para todos os corpos de solicitação.The maximum allowed size of any request body in bytes. Quando é definido como null, o tamanho máximo do corpo da solicitação é ilimitado.When set to null, the maximum request body size is unlimited. Esse limite não afeta as conexões atualizadas que são sempre ilimitadas.This limit has no effect on upgraded connections, which are always unlimited.

O método recomendado para substituir o limite em um aplicativo ASP.NET Core MVC para um único IActionResult é usar o atributo RequestSizeLimitAttribute em um método de ação: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()

Uma exceção é gerada quando o aplicativo tenta configurar o limite de uma solicitação, depois que o aplicativo inicia a leitura da solicitação.An exception is thrown if the app attempts to configure the limit on a request after the app has started reading the request. É possível usar uma propriedade IsReadOnly para indicar se a propriedade MaxRequestBodySize está no estado somente leitura, o que significa que é tarde demais para configurar o limite.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.

Se o aplicativo precisar substituir MaxRequestBodySize mediante solicitação, use o IHttpMaxRequestBodySizeFeature:If the app should override MaxRequestBodySize per-request, use the 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();
    });
}
public void Configure(IApplicationBuilder app, IHostingEnvironment 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.UseHsts();
    }

    // Enable HTTPS Redirection Middleware when hosting the app securely.
    //app.UseHttpsRedirection();
    app.UseStaticFiles();
    app.UseCookiePolicy();
    app.UseMvc();
}

Quando usar o Visual Studio, verifique se que o aplicativo está configurado para executar o IIS ou IIS Express.If using Visual Studio, make sure the app isn't configured to run IIS or IIS Express.

No Visual Studio, o perfil de inicialização padrão destina-se ao IIS Express.In Visual Studio, the default launch profile is for IIS Express. Para executar o projeto como um aplicativo de console, altere manualmente o perfil selecionado, conforme mostrado na captura de tela a seguir:To run the project as a console app, manually change the selected profile, as shown in the following screen shot:

Selecionar o perfil do aplicativo de console

Configurar o Windows ServerConfigure Windows Server

  1. Determine as portas que serão abertas para o aplicativo e use o Firewall do Windows ou o cmdlet do PowerShell New-NetFirewallRule para abrir as portas de firewall e permitir que o tráfego chegue até o HTTP.sys.Determine the ports to open for the app and use Windows Firewall or the New-NetFirewallRule PowerShell cmdlet to open firewall ports to allow traffic to reach HTTP.sys. Nos seguintes comandos e configuração de aplicativo, a porta 443 é usada.In the following commands and app configuration, port 443 is used.

  2. Ao implantar em uma VM do Azure, abra as portas no Grupo de Segurança de Rede.When deploying to an Azure VM, open the ports in the Network Security Group. Nos seguintes comandos e configuração de aplicativo, a porta 443 é usada.In the following commands and app configuration, port 443 is used.

  3. Obtenha e instale os certificados X.509, se precisar.Obtain and install X.509 certificates, if required.

    No Windows, crie certificados autoassinados, usando o cmdlet do PowerShell New-SelfSignedCertificate.On Windows, create self-signed certificates using the New-SelfSignedCertificate PowerShell cmdlet. Para ver um exemplo sem suporte, confira UpdateIISExpressSSLForChrome.ps1.For an unsupported example, see UpdateIISExpressSSLForChrome.ps1.

    Instale certificados autoassinados ou assinados pela AC no repositório Computador Local > Pessoal do servidor.Install either self-signed or CA-signed certificates in the server's Local Machine > Personal store.

  4. Se o aplicativo for uma implantação dependente de estrutura, instale o .NET Core, o .NET Framework ou ambos (caso o aplicativo .NET Core seja direcionado ao .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).

    • .NET Core – Se o aplicativo exigir o .NET Core, obtenha e execute o instalador do Tempo de Execução do .NET Core em Downloads do .NET Core..NET Core – If the app requires .NET Core, obtain and run the .NET Core Runtime installer from .NET Core Downloads. Não instale o SDK completo no servidor.Don't install the full SDK on the server.
    • .NET framework – Se o aplicativo exigir o .NET Framework, confira o Guia de instalação do .NET Framework..NET Framework – If the app requires .NET Framework, see the .NET Framework installation guide. Instale o .NET Framework necessário.Install the required .NET Framework. O instalador do .NET Framework mais recente está disponível na página Downloads do .NET Core.The installer for the latest .NET Framework is available from the .NET Core Downloads page.

    Se o aplicativo for uma implantação autocontida, ele incluirá o tempo de execução em sua implantação.If the app is a self-contained deployment, the app includes the runtime in its deployment. Nenhuma instalação do framework é necessária no servidor.No framework installation is required on the server.

  5. Configure URLs e portas no aplicativo.Configure URLs and ports in the app.

    Por padrão, o ASP.NET Core é associado a http://localhost:5000.By default, ASP.NET Core binds to http://localhost:5000. Para configurar portas e prefixos de URL, as opções incluem:To configure URL prefixes and ports, options include:

    • UseUrls
    • O argumento de linha de comando urlsurls command-line argument
    • A variável de ambiente ASPNETCORE_URLSASPNETCORE_URLS environment variable
    • UrlPrefixes

    O exemplo de código a seguir mostra como usar UrlPrefixes com o endereço IP local do servidor 10.0.0.4 na porta 443:The following code example shows how to use UrlPrefixes with the server's local IP address 10.0.0.4 on port 443:

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>();
        });
public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .UseStartup<Startup>()
        .UseHttpSys(options =>
        {
            options.UrlPrefixes.Add("https://10.0.0.4:443");
        });

Uma vantagem de usar UrlPrefixes é que uma mensagem de erro é gerada imediatamente no caso de prefixos formatados de forma incorreta.An advantage of UrlPrefixes is that an error message is generated immediately for improperly formatted prefixes.

As configurações de UrlPrefixes substituem as configurações UseUrls/urls/ASPNETCORE_URLS.The settings in UrlPrefixes override UseUrls/urls/ASPNETCORE_URLS settings. Portanto, uma vantagem de usar UseUrls, urls e a variável de ambiente ASPNETCORE_URLS é que fica mais fácil alternar entre o Kestrel e o 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.

O HTTP.sys usa os formatos de cadeia de caracteres UrlPrefix da API do Servidor HTTP.HTTP.sys uses the HTTP Server API UrlPrefix string formats.

Aviso

Associações de curinga de nível superior (http://*:80/ e http://+:80) não devem ser usadas.Top-level wildcard bindings (http://*:80/ and http://+:80) should not be used. Associações de curinga de nível superior criam vulnerabilidades de segurança no aplicativo.Top-level wildcard bindings create app security vulnerabilities. Isso se aplica a curingas fortes e fracos.This applies to both strong and weak wildcards. Use nomes de host explícitos ou endereços IP em vez de curingas.Use explicit host names or IP addresses rather than wildcards. Associações de curinga de subdomínio (por exemplo, *.mysub.com) não serão um risco à segurança se você controlar todo o domínio pai (ao contrário de *.com, o qual é vulnerável).Subdomain wildcard binding (for example, *.mysub.com) isn't a security risk if you control the entire parent domain (as opposed to *.com, which is vulnerable). Para saber mais, confira RFC 7230: Seção 5.4: Host.For more information, see RFC 7230: Section 5.4: Host.

  1. Pré-registre os prefixos de URL no servidor.Preregister URL prefixes on the server.

    O netsh.exe é a ferramenta interna destinada a configurar o HTTP.sys.The built-in tool for configuring HTTP.sys is netsh.exe. Com o netsh.exe, é possível reservar prefixos de URL e atribuir certificados X.509.netsh.exe is used to reserve URL prefixes and assign X.509 certificates. A ferramenta exige privilégios de administrador.The tool requires administrator privileges.

    Use a ferramenta netsh.exe para registrar as URLs do aplicativo:Use the netsh.exe tool to register URLs for the app:

    netsh http add urlacl url=<URL> user=<USER>
    
    • <URL> – A URL (Uniform Resource Locator) totalmente qualificada.<URL> – The fully qualified Uniform Resource Locator (URL). Não use uma associação de curinga.Don't use a wildcard binding. Use um nome de host válido ou o endereço IP local.Use a valid hostname or local IP address. A URL deve incluir uma barra à direita.The URL must include a trailing slash.
    • <USER> – Especifica o nome de usuário ou do grupo de usuários.<USER> – Specifies the user or user-group name.

    No exemplo a seguir, o endereço IP local do servidor é 10.0.0.4:In the following example, the local IP address of the server is 10.0.0.4:

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

    Quando uma URL é registrada, a ferramenta responde com URL reservation successfully added.When a URL is registered, the tool responds with URL reservation successfully added.

    Para excluir uma URL registrada, use o comando delete urlacl:To delete a registered URL, use the delete urlacl command:

    netsh http delete urlacl url=<URL>
    
  2. Registre certificados X.509 no servidor.Register X.509 certificates on the server.

    Use a ferramenta netsh.exe para registrar certificados do aplicativo:Use the netsh.exe tool to register certificates for the app:

    netsh http add sslcert ipport=<IP>:<PORT> certhash=<THUMBPRINT> appid="{<GUID>}"
    
    • <IP> – Especifica o endereço IP local para a associação.<IP> – Specifies the local IP address for the binding. Não use uma associação de curinga.Don't use a wildcard binding. Use um endereço IP válido.Use a valid IP address.
    • <PORT> – Especifica a porta da associação.<PORT> – Specifies the port for the binding.
    • <THUMBPRINT> – A impressão digital do certificado X.509.<THUMBPRINT> – The X.509 certificate thumbprint.
    • <GUID> – Um GUID gerado pelo desenvolvedor para representar o aplicativo para fins informativos.<GUID> – A developer-generated GUID to represent the app for informational purposes.

    Para fins de referência, armazene o GUID no aplicativo como uma marca de pacote:For reference purposes, store the GUID in the app as a package tag:

    • No Visual Studio:In Visual Studio:
      • Abra as propriedades do projeto do aplicativo, clicando com o botão direito do mouse no aplicativo no Gerenciador de Soluções e selecionando Propriedades.Open the app's project properties by right-clicking on the app in Solution Explorer and selecting Properties.
      • Selecione a guia Pacote.Select the Package tab.
      • Insira o GUID que você criou no campo Marcas.Enter the GUID that you created in the Tags field.
    • Quando não estiver usando o Visual Studio:When not using Visual Studio:
      • Abra o arquivo de projeto do aplicativo.Open the app's project file.

      • Adicione uma propriedade <PackageTags> a um <PropertyGroup> novo ou existente com o GUID que você criou:Add a <PackageTags> property to a new or existing <PropertyGroup> with the GUID that you created:

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

    No exemplo a seguir:In the following example:

    • O endereço IP local do servidor é 10.0.0.4.The local IP address of the server is 10.0.0.4.
    • Um gerador GUID aleatório online fornece o valor appid.An online random GUID generator provides the appid value.
    netsh http add sslcert 
        ipport=10.0.0.4:443 
        certhash=b66ee04419d4ee37464ab8785ff02449980eae10 
        appid="{9412ee86-c21b-4eb8-bd89-f650fbf44931}"
    

    Quando um certificado é registrado, a ferramenta responde com SSL Certificate successfully added.When a certificate is registered, the tool responds with SSL Certificate successfully added.

    Para excluir um registro de certificado, use o comando delete sslcert:To delete a certificate registration, use the delete sslcert command:

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

    Documentação de referência do netsh.exe:Reference documentation for netsh.exe:

  3. Execute o aplicativo.Run the app.

    Não é necessário ter privilégios de administrador para executar o aplicativo ao associar ao localhost usando HTTP (não HTTPS) com um número de porta maior do que 1024.Administrator privileges aren't required to run the app when binding to localhost using HTTP (not HTTPS) with a port number greater than 1024. Para outras configurações (por exemplo, usar um endereço IP local ou associação à porta 443), execute o aplicativo com privilégios de administrador.For other configurations (for example, using a local IP address or binding to port 443), run the app with administrator privileges.

    O aplicativo responde no endereço IP público do servidor.The app responds at the server's public IP address. Neste exemplo, o servidor é acessado pela Internet como seu endereço IP público de 104.214.79.47.In this example, the server is reached from the Internet at its public IP address of 104.214.79.47.

    Um certificado de desenvolvimento é usado neste exemplo.A development certificate is used in this example. A página é carregada com segurança após ignorar o aviso de certificado não confiável do navegador.The page loads securely after bypassing the browser's untrusted certificate warning.

    Janela do navegador mostrando a página de Índice do aplicativo carregada

Servidor proxy e cenários de balanceador de cargaProxy server and load balancer scenarios

Para aplicativos hospedados pelo HTTP.sys que interagem com solicitações da Internet ou de uma rede corporativa, podem ser necessárias configurações adicionais ao hospedar atrás de balanceadores de carga e de servidores proxy.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. Para obter mais informações, veja Configurar o ASP.NET Core para trabalhar com servidores proxy e balanceadores de carga.For more information, see Configure ASP.NET Core to work with proxy servers and load balancers.

Recursos adicionaisAdditional resources