Host da Web do ASP.NET CoreASP.NET Core Web Host

Por Luke LathamBy Luke Latham

Aplicativos ASP.NET Core configuram e inicializam um host.ASP.NET Core apps configure and launch a host. O host é responsável pelo gerenciamento de tempo de vida e pela inicialização do aplicativo.The host is responsible for app startup and lifetime management. No mínimo, o host configura um servidor e um pipeline de processamento de solicitações.At a minimum, the host configures a server and a request processing pipeline. Este tópico aborda o Host da Web ASP.NET Core (IWebHostBuilder), que é útil para hospedagem de aplicativos Web.This topic covers the ASP.NET Core Web Host (IWebHostBuilder), which is useful for hosting web apps. Para cobertura do Host Genérico .NET (IHostBuilder), veja Host Genérico .NET.For coverage of the .NET Generic Host (IHostBuilder), see Host Genérico .NET.

Configurar um hostSet up a host

Crie um host usando uma instância do IWebHostBuilder.Create a host using an instance of IWebHostBuilder. Normalmente, isso é feito no ponto de entrada do aplicativo, o método Main.This is typically performed in the app's entry point, the Main method. Em modelos de projeto, Main está localizado em Program.cs.In the project templates, Main is located in Program.cs. Um Program.cs típico chama CreateDefaultBuilder para começar a configurar um host:A typical Program.cs calls CreateDefaultBuilder to start setting up a host:

public class Program
{
    public static void Main(string[] args)
    {
        CreateWebHostBuilder(args).Build().Run();
    }

    public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
        WebHost.CreateDefaultBuilder(args)
            .UseStartup<Startup>();
}

CreateDefaultBuilder executa as seguintes tarefas:CreateDefaultBuilder performs the following tasks:

A configuração definida por CreateDefaultBuilder pode ser substituída e aumentada por ConfigureAppConfiguration, ConfigureLogging e outros métodos, bem como os métodos de extensão de IWebHostBuilder.The configuration defined by CreateDefaultBuilder can be overridden and augmented by ConfigureAppConfiguration, ConfigureLogging, and other methods and extension methods of IWebHostBuilder. Veja a seguir alguns exemplos:A few examples follow:

  • ConfigureAppConfiguration é usado para especificar IConfiguration adicionais para o aplicativo.ConfigureAppConfiguration is used to specify additional IConfiguration for the app. A seguinte chamada de ConfigureAppConfiguration adiciona um delegado para incluir a configuração do aplicativo no arquivo appsettings.xml.The following ConfigureAppConfiguration call adds a delegate to include app configuration in the appsettings.xml file. ConfigureAppConfiguration pode ser chamado várias vezes.ConfigureAppConfiguration may be called multiple times. Observe que essa configuração não se aplica ao host (por exemplo, URLs de servidor ou de ambiente).Note that this configuration doesn't apply to the host (for example, server URLs or environment). Consulte a seção Valores de configuração de Host.See the Host configuration values section.

    WebHost.CreateDefaultBuilder(args)
        .ConfigureAppConfiguration((hostingContext, config) =>
        {
            config.AddXmlFile("appsettings.xml", optional: true, reloadOnChange: true);
        })
        ...
    
  • A seguinte chamada de ConfigureLogging adiciona um delegado para configurar o nível de log mínimo (SetMinimumLevel) como LogLevel.Warning.The following ConfigureLogging call adds a delegate to configure the minimum logging level (SetMinimumLevel) to LogLevel.Warning. Essa configuração substitui as configurações em appsettings.Development.json (LogLevel.Debug) e appsettings.Production.json (LogLevel.Error) configuradas por CreateDefaultBuilder.This setting overrides the settings in appsettings.Development.json (LogLevel.Debug) and appsettings.Production.json (LogLevel.Error) configured by CreateDefaultBuilder. ConfigureLogging pode ser chamado várias vezes.ConfigureLogging may be called multiple times.

    WebHost.CreateDefaultBuilder(args)
        .ConfigureLogging(logging => 
        {
            logging.SetMinimumLevel(LogLevel.Warning);
        })
        ...
    
  • A seguinte chamada para ConfigureKestrel substitui o padrão Limits.MaxRequestBodySize de 30 milhões de bytes, estabelecido quando o Kestrel foi configurado pelo CreateDefaultBuilder:The following call to ConfigureKestrel overrides the default Limits.MaxRequestBodySize of 30,000,000 bytes established when Kestrel was configured by CreateDefaultBuilder:

    WebHost.CreateDefaultBuilder(args)
        .ConfigureKestrel((context, options) =>
        {
            options.Limits.MaxRequestBodySize = 20000000;
        });
        ...
    
  • A seguinte chamada a UseKestrel substitui o padrão Limits.MaxRequestBodySize de 30.000.000 bytes estabelecido quando Kestrel foi configurado por CreateDefaultBuilder:The following call to UseKestrel overrides the default Limits.MaxRequestBodySize of 30,000,000 bytes established when Kestrel was configured by CreateDefaultBuilder:

    WebHost.CreateDefaultBuilder(args)
        .UseKestrel(options =>
        {
            options.Limits.MaxRequestBodySize = 20000000;
        });
        ...
    

A raiz do conteúdo determina onde o host procura por arquivos de conteúdo, como arquivos de exibição do MVC.The content root determines where the host searches for content files, such as MVC view files. Quando o aplicativo é iniciado na pasta raiz do projeto, essa pasta é usada como a raiz do conteúdo.When the app is started from the project's root folder, the project's root folder is used as the content root. Esse é o padrão usado no Visual Studio e nos novos modelos dotnet.This is the default used in Visual Studio and the dotnet new templates.

Para obter mais informações sobre a configuração de aplicativo, veja Configuração no ASP.NET Core.For more information on app configuration, see Configuração no ASP.NET Core.

Observação

Como uma alternativa ao uso do método CreateDefaultBuilder estático, criar um host de WebHostBuilder é uma abordagem compatível com o ASP.NET Core 2. x.As an alternative to using the static CreateDefaultBuilder method, creating a host from WebHostBuilder is a supported approach with ASP.NET Core 2.x. Para obter mais informações, consulte a guia do ASP.NET Core 1.x.For more information, see the ASP.NET Core 1.x tab.

Crie um host usando uma instância de WebHostBuilder.Create a host using an instance of WebHostBuilder. A criação de um host normalmente é feita no ponto de entrada do aplicativo, o método Main.Creating a host is typically performed in the app's entry point, the Main method. Em modelos de projeto, Main está localizado em Program.cs:In the project templates, Main is located in Program.cs:

public class Program
{
    public static void Main(string[] args)
    {
        BuildWebHost(args).Run();
    }

    public static IWebHost BuildWebHost(string[] args) =>
        WebHost.CreateDefaultBuilder(args)
            .UseStartup<Startup>()
            .Build();
}

WebHostBuilder requer um servidor que implementa IServer.WebHostBuilder requires a server that implements IServer. Os servidores internos são Kestrel e HTTP.sys (antes do lançamento do ASP.NET Core 2.0, HTTP.sys era chamado de WebListener).The built-in servers are Kestrel and HTTP.sys (prior to the release of ASP.NET Core 2.0, HTTP.sys was called WebListener). Neste exemplo, o método de extensão UseKestrel especifica o servidor Kestrel.In this example, the UseKestrel extension method specifies the Kestrel server.

A raiz do conteúdo determina onde o host procura por arquivos de conteúdo, como arquivos de exibição do MVC.The content root determines where the host searches for content files, such as MVC view files. A raiz de conteúdo padrão é obtida para UseContentRoot por Directory.GetCurrentDirectory.The default content root is obtained for UseContentRoot by Directory.GetCurrentDirectory. Quando o aplicativo é iniciado na pasta raiz do projeto, essa pasta é usada como a raiz do conteúdo.When the app is started from the project's root folder, the project's root folder is used as the content root. Esse é o padrão usado no Visual Studio e nos novos modelos dotnet.This is the default used in Visual Studio and the dotnet new templates.

Para usar o IIS como um proxy reverso, chame UseIISIntegration como parte da compilação do host.To use IIS as a reverse proxy, call UseIISIntegration as part of building the host. UseIISIntegration não configura um servidor como UseKestrel o faz.UseIISIntegration doesn't configure a server, like UseKestrel does. UseIISIntegration configura o caminho base e a porta que o servidor escuta ao usar o Módulo do ASP.NET Core para criar um proxy reverso entre o Kestrel e o IIS.UseIISIntegration configures the base path and port the server listens on when using the ASP.NET Core Module to create a reverse proxy between Kestrel and IIS. Para usar o IIS com o ASP.NET Core, tanto UseKestrel quanto UseIISIntegration precisam ser especificados.To use IIS with ASP.NET Core, UseKestrel and UseIISIntegration must be specified. UseIISIntegration é ativado somente quando é executado por trás do IIS ou do IIS Express.UseIISIntegration only activates when running behind IIS or IIS Express. Para obter mais informações, consulte Módulo do ASP.NET Core e Referência de configuração do Módulo do ASP.NET Core.For more information, see Módulo do ASP.NET Core and Referência de configuração do Módulo do ASP.NET Core.

Uma implementação mínima que configura um host (e um aplicativo ASP.NET Core) inclui a especificação de um servidor e a configuração do pipeline de solicitações do aplicativo:A minimal implementation that configures a host (and an ASP.NET Core app) includes specifying a server and configuration of the app's request pipeline:

var host = new WebHostBuilder()
    .UseKestrel()
    .Configure(app =>
    {
        app.Run(context => context.Response.WriteAsync("Hello World!"));
    })
    .Build();

host.Run();

Ao configurar um host, os métodos Configure e ConfigureServices podem ser fornecidos.When setting up a host, Configure and ConfigureServices methods can be provided. Se uma classe Startup for especificada, ela deverá definir um método Configure.If a Startup class is specified, it must define a Configure method. Para obter mais informações, consulte Inicialização do aplicativo no ASP.NET Core.For more information, see Inicialização do aplicativo no ASP.NET Core. Diversas chamadas para ConfigureServices são acrescentadas umas às outras.Multiple calls to ConfigureServices append to one another. Diversas chamadas para Configure ou UseStartup no WebHostBuilder substituem configurações anteriores.Multiple calls to Configure or UseStartup on the WebHostBuilder replace previous settings.

Valores de configuração do hostHost configuration values

WebHostBuilder conta com as seguintes abordagens para definir os valores de configuração do host:WebHostBuilder relies on the following approaches to set the host configuration values:

  • Configuração do construtor do host, que inclui variáveis de ambiente com o formato ASPNETCORE_{configurationKey}.Host builder configuration, which includes environment variables with the format ASPNETCORE_{configurationKey}. Por exemplo, ASPNETCORE_ENVIRONMENT.For example, ASPNETCORE_ENVIRONMENT.
  • Extensões como UseContentRoot e UseConfiguration (consulte a seção Configuração de substituição).Extensions such as UseContentRoot and UseConfiguration (see the Override configuration section).
  • UseSetting e a chave associada.UseSetting and the associated key. Ao definir um valor com UseSetting, o valor é definido como uma cadeia de caracteres, independentemente do tipo.When setting a value with UseSetting, the value is set as a string regardless of the type.

O host usa a opção que define um valor por último.The host uses whichever option sets a value last. Para obter mais informações, veja Substituir configuração na próxima seção.For more information, see Override configuration in the next section.

Chave do Aplicativo (Nome)Application Key (Name)

A propriedade IHostingEnvironment.ApplicationName é definida automaticamente quando UseStartup ou Configure é chamado durante a construção do host.The IHostingEnvironment.ApplicationName property is automatically set when UseStartup or Configure is called during host construction. O valor é definido para o nome do assembly que contém o ponto de entrada do aplicativo.The value is set to the name of the assembly containing the app's entry point. Para definir o valor explicitamente, use o WebHostDefaults.ApplicationKey:To set the value explicitly, use the WebHostDefaults.ApplicationKey:

Chave: applicationNameKey: applicationName
Tipo: stringType: string
Padrão: o nome do assembly que contém o ponto de entrada do aplicativo.Default: The name of the assembly containing the app's entry point.
Definido usando: UseSettingSet using: UseSetting
Variável de ambiente: ASPNETCORE_APPLICATIONKEYEnvironment variable: ASPNETCORE_APPLICATIONKEY

WebHost.CreateDefaultBuilder(args)
    .UseSetting(WebHostDefaults.ApplicationKey, "CustomApplicationName")
var host = new WebHostBuilder()
    .UseSetting("applicationName", "CustomApplicationName")

Capturar erros de inicializaçãoCapture Startup Errors

Esta configuração controla a captura de erros de inicialização.This setting controls the capture of startup errors.

Chave: captureStartupErrorsKey: captureStartupErrors
Tipo: bool (true ou 1)Type: bool (true or 1)
Padrão: o padrão é false, a menos que o aplicativo seja executado com o Kestrel por trás do IIS, em que o padrão é true.Default: Defaults to false unless the app runs with Kestrel behind IIS, where the default is true.
Definido usando: CaptureStartupErrorsSet using: CaptureStartupErrors
Variável de ambiente: ASPNETCORE_CAPTURESTARTUPERRORSEnvironment variable: ASPNETCORE_CAPTURESTARTUPERRORS

Quando false, erros durante a inicialização resultam no encerramento do host.When false, errors during startup result in the host exiting. Quando true, o host captura exceções durante a inicialização e tenta iniciar o servidor.When true, the host captures exceptions during startup and attempts to start the server.

WebHost.CreateDefaultBuilder(args)
    .CaptureStartupErrors(true)
var host = new WebHostBuilder()
    .CaptureStartupErrors(true)

Raiz do conteúdoContent Root

Essa configuração determina onde o ASP.NET Core começa a procurar por arquivos de conteúdo, como exibições do MVC.This setting determines where ASP.NET Core begins searching for content files, such as MVC views.

Chave: contentRootKey: contentRoot
Tipo: stringType: string
Padrão: o padrão é a pasta em que o assembly do aplicativo reside.Default: Defaults to the folder where the app assembly resides.
Definido usando: UseContentRootSet using: UseContentRoot
Variável de ambiente: ASPNETCORE_CONTENTROOTEnvironment variable: ASPNETCORE_CONTENTROOT

A raiz do conteúdo também é usada como o caminho base para a Configuração da raiz da Web.The content root is also used as the base path for the Web Root setting. Se o caminho não existir, o host não será iniciado.If the path doesn't exist, the host fails to start.

WebHost.CreateDefaultBuilder(args)
    .UseContentRoot("c:\\<content-root>")
var host = new WebHostBuilder()
    .UseContentRoot("c:\\<content-root>")

Erros detalhadosDetailed Errors

Determina se erros detalhados devem ser capturados.Determines if detailed errors should be captured.

Chave: detailedErrorsKey: detailedErrors
Tipo: bool (true ou 1)Type: bool (true or 1)
Padrão: falsoDefault: false
Definido usando: UseSettingSet using: UseSetting
Variável de ambiente: ASPNETCORE_DETAILEDERRORSEnvironment variable: ASPNETCORE_DETAILEDERRORS

Quando habilitado (ou quando o Ambiente é definido como Development), o aplicativo captura exceções detalhadas.When enabled (or when the Environment is set to Development), the app captures detailed exceptions.

WebHost.CreateDefaultBuilder(args)
    .UseSetting(WebHostDefaults.DetailedErrorsKey, "true")
var host = new WebHostBuilder()
    .UseSetting(WebHostDefaults.DetailedErrorsKey, "true")

AmbienteEnvironment

Define o ambiente do aplicativo.Sets the app's environment.

Chave: ambienteKey: environment
Tipo: stringType: string
Padrão: ProductionDefault: Production
Definido usando: UseEnvironmentSet using: UseEnvironment
Variável de ambiente: ASPNETCORE_ENVIRONMENTEnvironment variable: ASPNETCORE_ENVIRONMENT

O ambiente pode ser definido como qualquer valor.The environment can be set to any value. Os valores definidos pela estrutura incluem Development, Staging e Production.Framework-defined values include Development, Staging, and Production. Os valores não diferenciam maiúsculas de minúsculas.Values aren't case sensitive. Por padrão, o Ambiente é lido da variável de ambiente ASPNETCORE_ENVIRONMENT.By default, the Environment is read from the ASPNETCORE_ENVIRONMENT environment variable. Ao usar o Visual Studio, variáveis de ambiente podem ser definidas no arquivo launchSettings.json.When using Visual Studio, environment variables may be set in the launchSettings.json file. Para obter mais informações, consulte Usar vários ambientes no ASP.NET Core.For more information, see Usar vários ambientes no ASP.NET Core.

WebHost.CreateDefaultBuilder(args)
    .UseEnvironment(EnvironmentName.Development)
var host = new WebHostBuilder()
    .UseEnvironment(EnvironmentName.Development)

Hospedando assemblies de inicializaçãoHosting Startup Assemblies

Define os assemblies de inicialização de hospedagem do aplicativo.Sets the app's hosting startup assemblies.

Chave: hostingStartupAssembliesKey: hostingStartupAssemblies
Tipo: stringType: string
Padrão: cadeia de caracteres vaziaDefault: Empty string
Definido usando: UseSettingSet using: UseSetting
Variável de ambiente: ASPNETCORE_HOSTINGSTARTUPASSEMBLIESEnvironment variable: ASPNETCORE_HOSTINGSTARTUPASSEMBLIES

Uma cadeia de caracteres delimitada por ponto e vírgula de assemblies de inicialização de hospedagem para carregamento na inicialização.A semicolon-delimited string of hosting startup assemblies to load on startup.

Embora o valor padrão da configuração seja uma cadeia de caracteres vazia, os assemblies de inicialização de hospedagem sempre incluem o assembly do aplicativo.Although the configuration value defaults to an empty string, the hosting startup assemblies always include the app's assembly. Quando assemblies de inicialização de hospedagem são fornecidos, eles são adicionados ao assembly do aplicativo para carregamento quando o aplicativo compilar seus serviços comuns durante a inicialização.When hosting startup assemblies are provided, they're added to the app's assembly for loading when the app builds its common services during startup.

WebHost.CreateDefaultBuilder(args)
    .UseSetting(WebHostDefaults.HostingStartupAssembliesKey, "assembly1;assembly2")

Porta HTTPSHTTPS Port

Defina a porta de redirecionamento HTTPS.Set the HTTPS redirect port. Uso em aplicação de HTTPS.Used in enforcing HTTPS.

Chave: https_port Tipo: string Padrão: Um valor padrão não está definido.Key: https_port Type: string Default: A default value isn't set. Definido usando: UseSetting Variável de ambiente: ASPNETCORE_HTTPS_PORTSet using: UseSetting Environment variable: ASPNETCORE_HTTPS_PORT

WebHost.CreateDefaultBuilder(args)
    .UseSetting("https_port", "8080")

Hospedando assemblies de exclusão de inicializaçãoHosting Startup Exclude Assemblies

DESCRIÇÃODESCRIPTION

Chave: hostingStartupExcludeAssembliesKey: hostingStartupExcludeAssemblies
Tipo: stringType: string
Padrão: cadeia de caracteres vaziaDefault: Empty string
Definido usando: UseSettingSet using: UseSetting
Variável de ambiente: ASPNETCORE_HOSTINGSTARTUPEXCLUDEASSEMBLIESEnvironment variable: ASPNETCORE_HOSTINGSTARTUPEXCLUDEASSEMBLIES

Uma cadeia de caracteres delimitada por ponto e vírgula de assemblies de inicialização de hospedagem para exclusão na inicialização.A semicolon-delimited string of hosting startup assemblies to exclude on startup.

WebHost.CreateDefaultBuilder(args)
    .UseSetting(WebHostDefaults.HostingStartupExcludeAssembliesKey, "assembly1;assembly2")

Preferir URLs de hospedagemPrefer Hosting URLs

Indica se o host deve escutar as URLs configuradas com o WebHostBuilder em vez daquelas configuradas com a implementação IServer.Indicates whether the host should listen on the URLs configured with the WebHostBuilder instead of those configured with the IServer implementation.

Chave: preferHostingUrlsKey: preferHostingUrls
Tipo: bool (true ou 1)Type: bool (true or 1)
Padrão: trueDefault: true
Definido usando: PreferHostingUrlsSet using: PreferHostingUrls
Variável de ambiente: ASPNETCORE_PREFERHOSTINGURLSEnvironment variable: ASPNETCORE_PREFERHOSTINGURLS

WebHost.CreateDefaultBuilder(args)
    .PreferHostingUrls(false)

Impedir inicialização de hospedagemPrevent Hosting Startup

Impede o carregamento automático de assemblies de inicialização de hospedagem, incluindo assemblies de inicialização de hospedagem configurados pelo assembly do aplicativo.Prevents the automatic loading of hosting startup assemblies, including hosting startup assemblies configured by the app's assembly. Para obter mais informações, consulte Aprimorar um aplicativo por meio de um assembly externo no ASP.NET Core com IHostingStartup.For more information, see Aprimorar um aplicativo por meio de um assembly externo no ASP.NET Core com IHostingStartup.

Chave: preventHostingStartupKey: preventHostingStartup
Tipo: bool (true ou 1)Type: bool (true or 1)
Padrão: falsoDefault: false
Definido usando: UseSettingSet using: UseSetting
Variável de ambiente: ASPNETCORE_PREVENTHOSTINGSTARTUPEnvironment variable: ASPNETCORE_PREVENTHOSTINGSTARTUP

WebHost.CreateDefaultBuilder(args)
    .UseSetting(WebHostDefaults.PreventHostingStartupKey, "true")

URLs de servidorServer URLs

Indica os endereços IP ou endereços de host com portas e protocolos que o servidor deve escutar para solicitações.Indicates the IP addresses or host addresses with ports and protocols that the server should listen on for requests.

Chave: urlsKey: urls
Tipo: stringType: string
Padrão: http://localhost:5000Default: http://localhost:5000
Definido usando: UseUrlsSet using: UseUrls
Variável de ambiente: ASPNETCORE_URLSEnvironment variable: ASPNETCORE_URLS

Defina como uma lista separada por ponto e vírgula (;) de prefixos de URL aos quais o servidor deve responder.Set to a semicolon-separated (;) list of URL prefixes to which the server should respond. Por exemplo, http://localhost:123.For example, http://localhost:123. Use "*" para indicar que o servidor deve escutar solicitações em qualquer endereço IP ou nome do host usando a porta e o protocolo especificados (por exemplo, http://*:5000).Use "*" to indicate that the server should listen for requests on any IP address or hostname using the specified port and protocol (for example, http://*:5000). O protocolo (http:// ou https://) deve ser incluído com cada URL.The protocol (http:// or https://) must be included with each URL. Os formatos compatíveis variam dependendo dos servidores.Supported formats vary between servers.

WebHost.CreateDefaultBuilder(args)
    .UseUrls("http://*:5000;http://localhost:5001;https://hostname:5002")

O Kestrel tem sua própria API de configuração de ponto de extremidade.Kestrel has its own endpoint configuration API. Para obter mais informações, consulte Implementação do servidor Web Kestrel no ASP.NET Core.For more information, see Implementação do servidor Web Kestrel no ASP.NET Core.

var host = new WebHostBuilder()
    .UseUrls("http://*:5000;http://localhost:5001;https://hostname:5002")

Tempo limite de desligamentoShutdown Timeout

Especifica o tempo de espera para o desligamento do host da Web.Specifies the amount of time to wait for the web host to shut down.

Chave: shutdownTimeoutSecondsKey: shutdownTimeoutSeconds
Tipo: intType: int
Padrão: 5Default: 5
Definido usando: UseShutdownTimeoutSet using: UseShutdownTimeout
Variável de ambiente: ASPNETCORE_SHUTDOWNTIMEOUTSECONDSEnvironment variable: ASPNETCORE_SHUTDOWNTIMEOUTSECONDS

Embora a chave aceite um int com UseSetting (por exemplo, .UseSetting(WebHostDefaults.ShutdownTimeoutKey, "10")), o método de extensão UseShutdownTimeout usa um TimeSpan.Although the key accepts an int with UseSetting (for example, .UseSetting(WebHostDefaults.ShutdownTimeoutKey, "10")), the UseShutdownTimeout extension method takes a TimeSpan.

Durante o período de tempo limite, a hospedagem:During the timeout period, hosting:

Se o período de tempo limite expirar antes que todos os serviços hospedados parem, os serviços ativos restantes serão parados quando o aplicativo for desligado.If the timeout period expires before all of the hosted services stop, any remaining active services are stopped when the app shuts down. Os serviços serão parados mesmo se ainda não tiverem concluído o processamento.The services stop even if they haven't finished processing. Se os serviços exigirem mais tempo para parar, aumente o tempo limite.If services require additional time to stop, increase the timeout.

WebHost.CreateDefaultBuilder(args)
    .UseShutdownTimeout(TimeSpan.FromSeconds(10))

Assembly de inicializaçãoStartup Assembly

Determina o assembly para pesquisar pela classe Startup.Determines the assembly to search for the Startup class.

Chave: startupAssemblyKey: startupAssembly
Tipo: stringType: string
Padrão: o assembly do aplicativoDefault: The app's assembly
Definido usando: UseStartupSet using: UseStartup
Variável de ambiente: ASPNETCORE_STARTUPASSEMBLYEnvironment variable: ASPNETCORE_STARTUPASSEMBLY

O assembly por nome (string) ou por tipo (TStartup) pode ser referenciado.The assembly by name (string) or type (TStartup) can be referenced. Se vários métodos UseStartup forem chamados, o último terá precedência.If multiple UseStartup methods are called, the last one takes precedence.

WebHost.CreateDefaultBuilder(args)
    .UseStartup("StartupAssemblyName")
WebHost.CreateDefaultBuilder(args)
    .UseStartup<TStartup>()
var host = new WebHostBuilder()
    .UseStartup("StartupAssemblyName")
var host = new WebHostBuilder()
    .UseStartup<TStartup>()

Raiz da WebWeb Root

Define o caminho relativo para os ativos estáticos do aplicativo.Sets the relative path to the app's static assets.

Chave: webrootKey: webroot
Tipo: stringType: string
Padrão: se não for especificado, o padrão será "(Raiz do conteúdo)/wwwroot", se o caminho existir.Default: If not specified, the default is "(Content Root)/wwwroot", if the path exists. Se o caminho não existir, um provedor de arquivo não operacional será usado.If the path doesn't exist, then a no-op file provider is used.
Definido usando: UseWebRootSet using: UseWebRoot
Variável de ambiente: ASPNETCORE_WEBROOTEnvironment variable: ASPNETCORE_WEBROOT

WebHost.CreateDefaultBuilder(args)
    .UseWebRoot("public")
var host = new WebHostBuilder()
    .UseWebRoot("public")

Substituir configuraçãoOverride configuration

Use Configuração para configurar o host Web.Use Configuration to configure the web host. No exemplo a seguir, a configuração do host é especificada, opcionalmente, em um arquivo hostsettings.json.In the following example, host configuration is optionally specified in a hostsettings.json file. Qualquer configuração carregada do arquivo hostsettings.json pode ser substituída por argumentos de linha de comando.Any configuration loaded from the hostsettings.json file may be overridden by command-line arguments. A configuração de build (no config) é usada para configurar o host com UseConfiguration.The built configuration (in config) is used to configure the host with UseConfiguration. A configuração IWebHostBuilder é adicionada à configuração do aplicativo, mas o contrário não é verdade—ConfigureAppConfiguration não afeta a configuração IWebHostBuilder.IWebHostBuilder configuration is added to the app's configuration, but the converse isn't true—ConfigureAppConfiguration doesn't affect the IWebHostBuilder configuration.

Substituição da configuração fornecida por UseUrls pela configuração de hostsettings.json primeiro, e pela configuração de argumento da linha de comando depois:Overriding the configuration provided by UseUrls with hostsettings.json config first, command-line argument config second:

public class Program
{
    public static void Main(string[] args)
    {
        CreateWebHostBuilder(args).Build().Run();
    }

    public static IWebHostBuilder CreateWebHostBuilder(string[] args)
    {
        var config = new ConfigurationBuilder()
            .SetBasePath(Directory.GetCurrentDirectory())
            .AddJsonFile("hostsettings.json", optional: true)
            .AddCommandLine(args)
            .Build();

        return WebHost.CreateDefaultBuilder(args)
            .UseUrls("http://*:5000")
            .UseConfiguration(config)
            .Configure(app =>
            {
                app.Run(context => 
                    context.Response.WriteAsync("Hello, World!"));
            })
            .Build();
    }
}

hostsettings.json:hostsettings.json:

{
    urls: "http://*:5005"
}

Substituição da configuração fornecida por UseUrls pela configuração de hostsettings.json primeiro, e pela configuração de argumento da linha de comando depois:Overriding the configuration provided by UseUrls with hostsettings.json config first, command-line argument config second:

public class Program
{
    public static void Main(string[] args)
    {
        var config = new ConfigurationBuilder()
            .SetBasePath(Directory.GetCurrentDirectory())
            .AddJsonFile("hostsettings.json", optional: true)
            .AddCommandLine(args)
            .Build();

        var host = new WebHostBuilder()
            .UseUrls("http://*:5000")
            .UseConfiguration(config)
            .UseKestrel()
            .Configure(app =>
            {
                app.Run(context => 
                    context.Response.WriteAsync("Hello, World!"));
            })
            .Build();

        host.Run();
    }
}

hostsettings.json:hostsettings.json:

{
    urls: "http://*:5005"
}

Observação

Atualmente, o método de extensão UseConfiguration não é capaz de analisar uma seção de configuração retornada por GetSection (por exemplo, .UseConfiguration(Configuration.GetSection("section"))).The UseConfiguration extension method isn't currently capable of parsing a configuration section returned by GetSection (for example, .UseConfiguration(Configuration.GetSection("section")). O método GetSection filtra as chaves de configuração da seção solicitada, mas deixa o nome da seção nas chaves (por exemplo, section:urls, section:environment).The GetSection method filters the configuration keys to the section requested but leaves the section name on the keys (for example, section:urls, section:environment). O método UseConfiguration espera que as chaves correspondam às chaves WebHostBuilder (por exemplo, urls, environment).The UseConfiguration method expects the keys to match the WebHostBuilder keys (for example, urls, environment). A presença do nome da seção nas chaves impede que os valores da seção configurem o host.The presence of the section name on the keys prevents the section's values from configuring the host. Esse problema será corrigido em uma próxima versão.This issue will be addressed in an upcoming release. Para obter mais informações e soluções alternativas, consulte Passar a seção de configuração para WebHostBuilder.UseConfiguration usa chaves completas.For more information and workarounds, see Passing configuration section into WebHostBuilder.UseConfiguration uses full keys.

UseConfiguration somente copia as chaves do IConfiguration fornecido para a configuração do construtor de host.UseConfiguration only copies keys from the provided IConfiguration to the host builder configuration. Portanto, definir reloadOnChange: true para arquivos de configuração JSON, INI e XML não tem nenhum efeito.Therefore, setting reloadOnChange: true for JSON, INI, and XML settings files has no effect.

Para especificar o host executado em uma URL específica, o valor desejado pode ser passado em um prompt de comando ao executar dotnet run.To specify the host run on a particular URL, the desired value can be passed in from a command prompt when executing dotnet run. O argumento de linha de comando substitui o valor urls do arquivo hostsettings.json e o servidor escuta na porta 8080:The command-line argument overrides the urls value from the hostsettings.json file, and the server listens on port 8080:

dotnet run --urls "http://*:8080"

Gerenciar o hostManage the host

ExecutarRun

O método Run inicia o aplicativo Web e bloqueia o thread de chamada até que o host seja desligado:The Run method starts the web app and blocks the calling thread until the host is shut down:

host.Run();

IniciarStart

Execute o host sem bloqueio, chamando seu método Start:Run the host in a non-blocking manner by calling its Start method:

using (host)
{
    host.Start();
    Console.ReadLine();
}

Se uma lista de URLs for passada para o método Start, ele escutará nas URLs especificadas:If a list of URLs is passed to the Start method, it listens on the URLs specified:

var urls = new List<string>()
{
    "http://*:5000",
    "http://localhost:5001"
};

var host = new WebHostBuilder()
    .UseKestrel()
    .UseStartup<Startup>()
    .Start(urls.ToArray());

using (host)
{
    Console.ReadLine();
}

O aplicativo pode inicializar e iniciar um novo host usando os padrões pré-configurados de CreateDefaultBuilder, usando um método estático conveniente.The app can initialize and start a new host using the pre-configured defaults of CreateDefaultBuilder using a static convenience method. Esses métodos iniciam o servidor sem uma saída do console e com WaitForShutdown e aguardam uma quebra (Ctrl-C/SIGINT ou SIGTERM):These methods start the server without console output and with WaitForShutdown wait for a break (Ctrl-C/SIGINT or SIGTERM):

Start(RequestDelegate app)Start(RequestDelegate app)

Inicie com um RequestDelegate:Start with a RequestDelegate:

using (var host = WebHost.Start(app => app.Response.WriteAsync("Hello, World!")))
{
    Console.WriteLine("Use Ctrl-C to shutdown the host...");
    host.WaitForShutdown();
}

Faça uma solicitação no navegador para http://localhost:5000 para receber a resposta "Olá, Mundo!"Make a request in the browser to http://localhost:5000 to receive the response "Hello World!" WaitForShutdown bloqueia até que uma quebra (Ctrl-C/SIGINT ou SIGTERM) seja emitida.WaitForShutdown blocks until a break (Ctrl-C/SIGINT or SIGTERM) is issued. O aplicativo exibe a mensagem Console.WriteLine e aguarda um pressionamento de tecla para ser encerrado.The app displays the Console.WriteLine message and waits for a keypress to exit.

Start(string url, RequestDelegate app)Start(string url, RequestDelegate app)

Inicie com uma URL e RequestDelegate:Start with a URL and RequestDelegate:

using (var host = WebHost.Start("http://localhost:8080", app => app.Response.WriteAsync("Hello, World!")))
{
    Console.WriteLine("Use Ctrl-C to shutdown the host...");
    host.WaitForShutdown();
}

Produz o mesmo resultado que Start(RequestDelegate app), mas o aplicativo responde em http://localhost:8080.Produces the same result as Start(RequestDelegate app), except the app responds on http://localhost:8080.

Start(Action<IRouteBuilder> routeBuilder)Start(Action<IRouteBuilder> routeBuilder)

Use uma instância de IRouteBuilder (Microsoft.AspNetCore.Routing) para usar o middleware de roteamento:Use an instance of IRouteBuilder (Microsoft.AspNetCore.Routing) to use routing middleware:

using (var host = WebHost.Start(router => router
    .MapGet("hello/{name}", (req, res, data) => 
        res.WriteAsync($"Hello, {data.Values["name"]}!"))
    .MapGet("buenosdias/{name}", (req, res, data) => 
        res.WriteAsync($"Buenos dias, {data.Values["name"]}!"))
    .MapGet("throw/{message?}", (req, res, data) => 
        throw new Exception((string)data.Values["message"] ?? "Uh oh!"))
    .MapGet("{greeting}/{name}", (req, res, data) => 
        res.WriteAsync($"{data.Values["greeting"]}, {data.Values["name"]}!"))
    .MapGet("", (req, res, data) => res.WriteAsync("Hello, World!"))))
{
    Console.WriteLine("Use Ctrl-C to shutdown the host...");
    host.WaitForShutdown();
}

Use as seguintes solicitações de navegador com o exemplo:Use the following browser requests with the example:

SolicitaçãoRequest RespostaResponse
http://localhost:5000/hello/Martin Hello, Martin!Hello, Martin!
http://localhost:5000/buenosdias/Catrina Buenos dias, Catrina!Buenos dias, Catrina!
http://localhost:5000/throw/ooops! Gera uma exceção com a cadeia de caracteres "ooops!"Throws an exception with string "ooops!"
http://localhost:5000/throw Gera uma exceção com a cadeia de caracteres "Uh oh!"Throws an exception with string "Uh oh!"
http://localhost:5000/Sante/Kevin Sante, Kevin!Sante, Kevin!
http://localhost:5000 Olá, Mundo!Hello World!

WaitForShutdown bloqueia até que uma quebra (Ctrl-C/SIGINT ou SIGTERM) seja emitida.WaitForShutdown blocks until a break (Ctrl-C/SIGINT or SIGTERM) is issued. O aplicativo exibe a mensagem Console.WriteLine e aguarda um pressionamento de tecla para ser encerrado.The app displays the Console.WriteLine message and waits for a keypress to exit.

Start(string url, Action<IRouteBuilder> routeBuilder)Start(string url, Action<IRouteBuilder> routeBuilder)

Use uma URL e uma instância de IRouteBuilder:Use a URL and an instance of IRouteBuilder:

using (var host = WebHost.Start("http://localhost:8080", router => router
    .MapGet("hello/{name}", (req, res, data) => 
        res.WriteAsync($"Hello, {data.Values["name"]}!"))
    .MapGet("buenosdias/{name}", (req, res, data) => 
        res.WriteAsync($"Buenos dias, {data.Values["name"]}!"))
    .MapGet("throw/{message?}", (req, res, data) => 
        throw new Exception((string)data.Values["message"] ?? "Uh oh!"))
    .MapGet("{greeting}/{name}", (req, res, data) => 
        res.WriteAsync($"{data.Values["greeting"]}, {data.Values["name"]}!"))
    .MapGet("", (req, res, data) => res.WriteAsync("Hello, World!"))))
{
    Console.WriteLine("Use Ctrl-C to shut down the host...");
    host.WaitForShutdown();
}

Produz o mesmo resultado que Start(Action<IRouteBuilder> routeBuilder), mas o aplicativo responde em http://localhost:8080.Produces the same result as Start(Action<IRouteBuilder> routeBuilder), except the app responds at http://localhost:8080.

StartWith(Action<IApplicationBuilder> app)StartWith(Action<IApplicationBuilder> app)

Forneça um delegado para configurar um IApplicationBuilder:Provide a delegate to configure an IApplicationBuilder:

using (var host = WebHost.StartWith(app => 
    app.Use(next => 
    {
        return async context => 
        {
            await context.Response.WriteAsync("Hello World!");
        };
    })))
{
    Console.WriteLine("Use Ctrl-C to shut down the host...");
    host.WaitForShutdown();
}

Faça uma solicitação no navegador para http://localhost:5000 para receber a resposta "Olá, Mundo!"Make a request in the browser to http://localhost:5000 to receive the response "Hello World!" WaitForShutdown bloqueia até que uma quebra (Ctrl-C/SIGINT ou SIGTERM) seja emitida.WaitForShutdown blocks until a break (Ctrl-C/SIGINT or SIGTERM) is issued. O aplicativo exibe a mensagem Console.WriteLine e aguarda um pressionamento de tecla para ser encerrado.The app displays the Console.WriteLine message and waits for a keypress to exit.

StartWith(string url, Action<IApplicationBuilder> app)StartWith(string url, Action<IApplicationBuilder> app)

Forneça um delegado e uma URL para configurar um IApplicationBuilder:Provide a URL and a delegate to configure an IApplicationBuilder:

using (var host = WebHost.StartWith("http://localhost:8080", app => 
    app.Use(next => 
    {
        return async context => 
        {
            await context.Response.WriteAsync("Hello World!");
        };
    })))
{
    Console.WriteLine("Use Ctrl-C to shut down the host...");
    host.WaitForShutdown();
}

Produz o mesmo resultado que StartWith(Action<IApplicationBuilder> app), mas o aplicativo responde em http://localhost:8080.Produces the same result as StartWith(Action<IApplicationBuilder> app), except the app responds on http://localhost:8080.

ExecutarRun

O método Run inicia o aplicativo Web e bloqueia o thread de chamada até que o host seja desligado:The Run method starts the web app and blocks the calling thread until the host is shut down:

host.Run();

IniciarStart

Execute o host sem bloqueio, chamando seu método Start:Run the host in a non-blocking manner by calling its Start method:

using (host)
{
    host.Start();
    Console.ReadLine();
}

Se uma lista de URLs for passada para o método Start, ele escutará nas URLs especificadas:If a list of URLs is passed to the Start method, it listens on the URLs specified:

var urls = new List<string>()
{
    "http://*:5000",
    "http://localhost:5001"
};

var host = new WebHostBuilder()
    .UseKestrel()
    .UseStartup<Startup>()
    .Start(urls.ToArray());

using (host)
{
    Console.ReadLine();
}

Interface IHostingEnvironmentIHostingEnvironment interface

A interface IHostingEnvironment fornece informações sobre o ambiente de hospedagem na Web do aplicativo.The IHostingEnvironment interface provides information about the app's web hosting environment. Use a injeção de construtor para obter o IHostingEnvironment para usar suas propriedades e métodos de extensão:Use constructor injection to obtain the IHostingEnvironment in order to use its properties and extension methods:

public class CustomFileReader
{
    private readonly IHostingEnvironment _env;

    public CustomFileReader(IHostingEnvironment env)
    {
        _env = env;
    }

    public string ReadFile(string filePath)
    {
        var fileProvider = _env.WebRootFileProvider;
        // Process the file here
    }
}

Uma abordagem baseada em convenção pode ser usada para configurar o aplicativo na inicialização com base no ambiente.A convention-based approach can be used to configure the app at startup based on the environment. Como alternativa, injete o IHostingEnvironment no construtor Startup para uso em ConfigureServices:Alternatively, inject the IHostingEnvironment into the Startup constructor for use in ConfigureServices:

public class Startup
{
    public Startup(IHostingEnvironment env)
    {
        HostingEnvironment = env;
    }

    public IHostingEnvironment HostingEnvironment { get; }

    public void ConfigureServices(IServiceCollection services)
    {
        if (HostingEnvironment.IsDevelopment())
        {
            // Development configuration
        }
        else
        {
            // Staging/Production configuration
        }

        var contentRootPath = HostingEnvironment.ContentRootPath;
    }
}

Observação

Além do método de extensão IsDevelopment, IHostingEnvironment oferece os métodos IsStaging, IsProduction e IsEnvironment(string environmentName).In addition to the IsDevelopment extension method, IHostingEnvironment offers IsStaging, IsProduction, and IsEnvironment(string environmentName) methods. Para obter mais informações, consulte Usar vários ambientes no ASP.NET Core.For more information, see Usar vários ambientes no ASP.NET Core.

O serviço IHostingEnvironment também pode ser injetado diretamente no método Configure para configurar o pipeline de processamento:The IHostingEnvironment service can also be injected directly into the Configure method for setting up the processing pipeline:

public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
    if (env.IsDevelopment())
    {
        // In Development, use the developer exception page
        app.UseDeveloperExceptionPage();
    }
    else
    {
        // In Staging/Production, route exceptions to /error
        app.UseExceptionHandler("/error");
    }

    var contentRootPath = env.ContentRootPath;
}

IHostingEnvironment pode ser injetado no método Invoke ao criar um middleware personalizado:IHostingEnvironment can be injected into the Invoke method when creating custom middleware:

public async Task Invoke(HttpContext context, IHostingEnvironment env)
{
    if (env.IsDevelopment())
    {
        // Configure middleware for Development
    }
    else
    {
        // Configure middleware for Staging/Production
    }

    var contentRootPath = env.ContentRootPath;
}

Interface IApplicationLifetimeIApplicationLifetime interface

IApplicationLifetime permite atividades pós-inicialização e desligamento.IApplicationLifetime allows for post-startup and shutdown activities. Três propriedades na interface são tokens de cancelamento usados para registrar métodos Action que definem eventos de inicialização e desligamento.Three properties on the interface are cancellation tokens used to register Action methods that define startup and shutdown events.

Token de cancelamentoCancellation Token Acionado quando…Triggered when…
ApplicationStartedApplicationStarted O host foi iniciado totalmente.The host has fully started.
ApplicationStoppedApplicationStopped O host está concluindo um desligamento normal.The host is completing a graceful shutdown. Todas as solicitações devem ser processadas.All requests should be processed. O desligamento é bloqueado até que esse evento seja concluído.Shutdown blocks until this event completes.
ApplicationStoppingApplicationStopping O host está executando um desligamento normal.The host is performing a graceful shutdown. Solicitações ainda podem estar sendo processadas.Requests may still be processing. O desligamento é bloqueado até que esse evento seja concluído.Shutdown blocks until this event completes.
public class Startup
{
    public void Configure(IApplicationBuilder app, IApplicationLifetime appLifetime)
    {
        appLifetime.ApplicationStarted.Register(OnStarted);
        appLifetime.ApplicationStopping.Register(OnStopping);
        appLifetime.ApplicationStopped.Register(OnStopped);

        Console.CancelKeyPress += (sender, eventArgs) =>
        {
            appLifetime.StopApplication();
            // Don't terminate the process immediately, wait for the Main thread to exit gracefully.
            eventArgs.Cancel = true;
        };
    }

    private void OnStarted()
    {
        // Perform post-startup activities here
    }

    private void OnStopping()
    {
        // Perform on-stopping activities here
    }

    private void OnStopped()
    {
        // Perform post-stopped activities here
    }
}

StopApplication solicita o término do aplicativo.StopApplication requests termination of the app. A classe a seguir usa StopApplication para desligar normalmente um aplicativo quando o método Shutdown da classe é chamado:The following class uses StopApplication to gracefully shut down an app when the class's Shutdown method is called:

public class MyClass
{
    private readonly IApplicationLifetime _appLifetime;

    public MyClass(IApplicationLifetime appLifetime)
    {
        _appLifetime = appLifetime;
    }

    public void Shutdown()
    {
        _appLifetime.StopApplication();
    }
}

Validação de escopoScope validation

CreateDefaultBuilder define ServiceProviderOptions.ValidateScopes como true quando o ambiente do aplicativo é de desenvolvimento.CreateDefaultBuilder sets ServiceProviderOptions.ValidateScopes to true if the app's environment is Development.

Quando ValidateScopes está definido como true, o provedor de serviço padrão executa verificações para saber se:When ValidateScopes is set to true, the default service provider performs checks to verify that:

  • Os serviços com escopo não são resolvidos direta ou indiretamente pelo provedor de serviço raiz.Scoped services aren't directly or indirectly resolved from the root service provider.
  • Os serviços com escopo não são injetados direta ou indiretamente em singletons.Scoped services aren't directly or indirectly injected into singletons.

O provedor de serviços raiz é criado quando BuildServiceProvider é chamado.The root service provider is created when BuildServiceProvider is called. O tempo de vida do provedor de serviço raiz corresponde ao tempo de vida do aplicativo/servidor quando o provedor começa com o aplicativo e é descartado quando o aplicativo é desligado.The root service provider's lifetime corresponds to the app/server's lifetime when the provider starts with the app and is disposed when the app shuts down.

Os serviços com escopo são descartados pelo contêiner que os criou.Scoped services are disposed by the container that created them. Se um serviço com escopo é criado no contêiner raiz, o tempo de vida do serviço é promovido efetivamente para singleton, porque ele só é descartado pelo contêiner raiz quando o aplicativo/servidor é desligado.If a scoped service is created in the root container, the service's lifetime is effectively promoted to singleton because it's only disposed by the root container when app/server is shut down. A validação dos escopos de serviço detecta essas situações quando BuildServiceProvider é chamado.Validating service scopes catches these situations when BuildServiceProvider is called.

Para que os escopos sempre sejam validados, incluindo no ambiente de produção, configure ServiceProviderOptions com UseDefaultServiceProvider no construtor do host:To always validate scopes, including in the Production environment, configure the ServiceProviderOptions with UseDefaultServiceProvider on the host builder:

WebHost.CreateDefaultBuilder(args)
    .UseDefaultServiceProvider((context, options) => {
        options.ValidateScopes = true;
    })

Solução de problemas de System.ArgumentExceptionTroubleshooting System.ArgumentException

O seguinte se aplica somente aos aplicativos do ASP.NET Core 2.0 quando o aplicativo não chama UseStartup ou Configure.The following only applies to ASP.NET Core 2.0 apps when the app doesn't call UseStartup or Configure.

Um host pode ser compilado injetando IStartup diretamente no contêiner de injeção de dependência em vez de chamar UseStartup ou Configure:A host may be built by injecting IStartup directly into the dependency injection container rather than calling UseStartup or Configure:

services.AddSingleton<IStartup, Startup>();

Se o host for compilado dessa maneira, o seguinte erro poderá ocorrer:If the host is built this way, the following error may occur:

Unhandled Exception: System.ArgumentException: A valid non-empty application name must be provided.

Isso ocorre porque o nome do aplicativo (o nome do assembly atual) é necessário para verificar se há HostingStartupAttributes.This occurs because the app name (the name of the current assembly) is required to scan for HostingStartupAttributes. Se o aplicativo injetar manualmente IStartup no contêiner de injeção de dependência, adicione a seguinte chamada para WebHostBuilder com o nome do assembly especificado:If the app manually injects IStartup into the dependency injection container, add the following call to WebHostBuilder with the assembly name specified:

WebHost.CreateDefaultBuilder(args)
    .UseSetting("applicationName", "AssemblyName")

Como alternativa, adicione um Configure fictício ao WebHostBuilder, que define o nome do aplicativo automaticamente:Alternatively, add a dummy Configure to the WebHostBuilder, which sets the app name automatically:

WebHost.CreateDefaultBuilder(args)
    .Configure(_ => { })

Para obter mais informações, consulte Comunicado: Microsoft.Extensions.PlatformAbstractions foi removido (comentário) e o Exemplo de StartupInjection.For more information, see Announcements: Microsoft.Extensions.PlatformAbstractions has been removed (comment) and the StartupInjection sample.

Recursos adicionaisAdditional resources