Host da Web do ASP.NET Core

Artigo
08/29/2024

Observação

Esta não é a versão mais recente deste artigo. Para informações sobre a versão vigente, confira a Versão do .NET 8 deste artigo.

Aviso

Esta versão do ASP.NET Core não tem mais suporte. Para obter mais informações, confira .NET e a Política de Suporte do .NET Core. Para informações sobre a versão vigente, confira a Versão do .NET 8 deste artigo.

Importante

Essas informações relacionam-se ao produto de pré-lançamento, que poderá ser substancialmente modificado antes do lançamento comercial. A Microsoft não oferece nenhuma garantia, explícita ou implícita, quanto às informações fornecidas aqui.

Para informações sobre a versão vigente, confira a Versão do .NET 8 deste artigo.

Aplicativos ASP.NET Core configuram e inicializam um host. O host é responsável pelo gerenciamento de tempo de vida e pela inicialização do aplicativo. No mínimo, o host configura um servidor e um pipeline de processamento de solicitações. O host também pode configurar registro em log, a injeção de dependência e a configuração.

Este artigo aborda o host da Web, que permanece disponível somente para compatibilidade com versões anteriores. Os modelos do ASP.NET Core criam um WebApplicationBuilder e um WebApplication, que são recomendados para aplicativos Web. Para obter mais informações sobre WebApplicationBuilder e WebApplication, confira Migrar do ASP.NET Core 5.0 para 6.0

Configurar um host

Crie um host usando uma instância do IWebHostBuilder. Normalmente, isso é executado no ponto de entrada do aplicativo, o método Main em Program.cs. Um aplicativo típico chama CreateDefaultBuilder para iniciar a configuração de um 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>();
}

O código que chama CreateDefaultBuilder está em um método chamado CreateWebHostBuilder, que o separa do código em Main, que chama Run no objeto de construtor. Essa separação será necessária se você usar ferramentas do Entity Framework Core. As ferramentas esperam encontrar um método CreateWebHostBuilder que elas possam chamar em tempo de design para configurar o host sem executar o aplicativo. Uma alternativa é implementar IDesignTimeDbContextFactory. Para obter mais informações, confira Criação de DbContext no tempo de design.

CreateDefaultBuilder realiza as seguintes tarefas:

Configura o servidor Kestrel como o servidor Web usando provedores de configuração de hospedagem do aplicativo. Para obter as opções padrão do servidor Kestrel, confira Configurar opções para o servidor Web Kestrel do ASP.NET Core.
Define a raiz do conteúdo como o caminho retornado por Directory.GetCurrentDirectory.
Carrega a configuração do host de:
- Variáveis de ambiente prefixadas com ASPNETCORE_ (por exemplo, ASPNETCORE_ENVIRONMENT).
- Argumentos de linha de comando.
Carrega a configuração do aplicativo na seguinte ordem de:
- appsettings.json.
- appsettings.{Environment}.json.
- Segredos do usuário quando o aplicativo é executado no ambiente Development usando o assembly de entrada.
- Variáveis de ambiente.
- Argumentos de linha de comando.
Configura o registro em log para a saída do console e de depuração. O registro em log inclui regras de filtragem de log especificadas em uma seção de configuração de registro em log de um arquivo appsettings.json ou appsettings.{Environment}.json.
Quando executado com a proteção do IIS com o Módulo do ASP.NET Core, CreateDefaultBuilder habilita a Integração do IIS, que configura a porta e o endereço básico do aplicativo. A Integração do IIS também configura o aplicativo para capturar erros de inicialização. Para obter as opções padrão do IIS, confira Hospedar o ASP.NET Core no Windows com o ISS.
Define ServiceProviderOptions.ValidateScopes para true se o ambiente do aplicativo for Desenvolvimento. Para obter mais informações, confira Validação de escopo.

A configuração definida por CreateDefaultBuilder pode ser substituída e aumentada por ConfigureAppConfiguration, ConfigureLogging e outros métodos e métodos de extensão de IWebHostBuilder. Veja a seguir alguns exemplos:

ConfigureAppConfiguration é usado para especificar IConfiguration adicionais para o aplicativo. A chamada ConfigureAppConfiguration a seguir adiciona um delegado para incluir a configuração do aplicativo no arquivo appsettings.xml. ConfigureAppConfiguration pode ser chamado várias vezes. Observe que essa configuração não se aplica ao host (por exemplo, URLs de servidor ou de ambiente). Consulte a seção Valores de configuração de Host.
```
WebHost.CreateDefaultBuilder(args)
    .ConfigureAppConfiguration((hostingContext, config) =>
    {
        config.AddXmlFile("appsettings.xml", optional: true, reloadOnChange: true);
    })
    ...
```
A chamada ConfigureLogging a seguir adiciona um delegado para configurar o nível mínimo de registro em log (SetMinimumLevel) para LogLevel.Warning. Essa configuração substitui as configurações em appsettings.Development.json (LogLevel.Debug) e appsettings.Production.json (LogLevel.Error) configuradas por CreateDefaultBuilder. ConfigureLogging pode ser chamado várias vezes.
```
WebHost.CreateDefaultBuilder(args)
    .ConfigureLogging(logging => 
    {
        logging.SetMinimumLevel(LogLevel.Warning);
    })
    ...
```
A chamada a seguir para ConfigureKestrel substitui o padrão Limits.MaxRequestBodySize de 30.000.000 bytes estabelecidos quando o Kestrel foi configurado pelo CreateDefaultBuilder:
```
WebHost.CreateDefaultBuilder(args)
    .ConfigureKestrel((context, 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. Quando o aplicativo é iniciado na pasta raiz do projeto, essa pasta é usada como a raiz do conteúdo. Esse é o padrão usado no Visual Studio e nos novos modelos dotnet.

Para obter mais informações sobre a configuração de aplicativos, consulte Configuração no ASP.NET Core.

Observação

Como uma alternativa ao uso do método CreateDefaultBuilder estático, criar um host no WebHostBuilder é uma abordagem compatível com o ASP.NET Core 2.x.

Ao configurar um host, os métodos Configure e ConfigureServices podem ser fornecidos. Se uma classe Startup for especificada, ela deverá definir um método Configure. Saiba mais em Inicialização de aplicativos no ASP.NET Core. Diversas chamadas para ConfigureServices são acrescentadas umas às outras. Diversas chamadas para Configure ou UseStartup no WebHostBuilder substituem configurações anteriores.

Valores de configuração do host

O WebHostBuilder depende das seguintes abordagens para definir os valores de configuração do host:

Configuração do construtor do host, que inclui variáveis de ambiente com o formato ASPNETCORE_{configurationKey}. Por exemplo, ASPNETCORE_ENVIRONMENT.
Extensões como UseContentRoot e UseConfiguration (veja a seção Configuração de substituição).
UseSetting e a chave associada. Ao definir um valor com UseSetting, o valor é definido como uma cadeia de caracteres, independentemente do tipo.

O host usa a opção que define um valor por último. Para obter mais informações, veja Substituir configuração na próxima seção.

Chave do Aplicativo (Nome)

A propriedade IWebHostEnvironment.ApplicationName é definida automaticamente quando UseStartup ou Configure é chamado durante a construção do host. O valor é definido para o nome do assembly que contém o ponto de entrada do aplicativo. Para definir o valor explicitamente, use o WebHostDefaults.ApplicationKey:

Chave: applicationName
Tipo: string
Padrão: o nome do assembly que contém o ponto de entrada do aplicativo.
Definido usando: UseSetting
Variável de ambiente: ASPNETCORE_APPLICATIONNAME

WebHost.CreateDefaultBuilder(args)
    .UseSetting(WebHostDefaults.ApplicationKey, "CustomApplicationName")

Capturar erros de inicialização

Esta configuração controla a captura de erros de inicialização.

Chave: captureStartupErrors
Tipo: bool (true ou 1)
Padrão: o padrão é false, a menos que o aplicativo seja executado com Kestrel por atrás do IIS, em que o padrão é true.
Definido usando: CaptureStartupErrors
Variável de ambiente: ASPNETCORE_CAPTURESTARTUPERRORS

Quando false, erros durante a inicialização resultam no encerramento do host. Quando true, o host captura exceções durante a inicialização e tenta iniciar o servidor.

WebHost.CreateDefaultBuilder(args)
    .CaptureStartupErrors(true)

Raiz do conteúdo

Essa configuração determina onde o ASP.NET Core começa a procurar por arquivos de conteúdo.

Chave: contentRoot
Tipo: string
Padrão: o padrão é a pasta em que o assembly do aplicativo reside.
Definido usando: UseContentRoot
Variável de ambiente: ASPNETCORE_CONTENTROOT

A raiz do conteúdo também é usada como o caminho base para a raiz da Web. Se o caminho raiz do conteúdo não existir, o host não será iniciado.

WebHost.CreateDefaultBuilder(args)
    .UseContentRoot("c:\\<content-root>")

Para obter mais informações, consulte:

Erros detalhados

Determina se erros detalhados devem ser capturados.

Chave: detailedErrors
Tipo: bool (true ou 1)
Padrão: falso
Definido usando: UseSetting
Variável de ambiente: ASPNETCORE_DETAILEDERRORS

Quando habilitado (ou quando o Ambiente é definido como Development), o aplicativo captura exceções detalhadas.

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

Ambiente

Define o ambiente do aplicativo.

Chave: ambiente
Tipo: string
Padrão: Production
Definido usando: UseEnvironment
Variável de ambiente: ASPNETCORE_ENVIRONMENT

O ambiente pode ser definido como qualquer valor. Os valores definidos pela estrutura incluem Development, Staging e Production. Os valores não diferenciam maiúsculas de minúsculas. Por padrão, o Ambiente é lido da variável de ambiente ASPNETCORE_ENVIRONMENT. Ao usar o Visual Studio, as variáveis de ambiente podem ser definidas no arquivo launchSettings.json. Para obter mais informações, confira Usar vários ambientes no ASP.NET Core.

WebHost.CreateDefaultBuilder(args)
    .UseEnvironment(EnvironmentName.Development)

Hospedando assemblies de inicialização

Define os assemblies de inicialização de hospedagem do aplicativo.

Chave: hostingStartupAssemblies
Tipo: string
Padrão: cadeia de caracteres vazia
Definido usando: UseSetting
Variável de ambiente: ASPNETCORE_HOSTINGSTARTUPASSEMBLIES

Uma cadeia de caracteres delimitada por ponto e vírgula de assemblies de inicialização de hospedagem para carregamento na inicialização.

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. 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.

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

Porta HTTPS

Defina a porta HTTPS para a qual redirecionar se você obtiver uma conexão não HTTPS. Uso em aplicação de HTTPS. Essa configuração não faz com que o servidor escute na porta especificada. Ou seja, é possível redirecionar acidentalmente as solicitações para uma porta não utilizada.

Chave: https_port
Tipo: string
Padrão: um valor padrão não está definido.
Definido usando: UseSetting
Variável de ambiente: ASPNETCORE_HTTPS_PORT

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

Portas HTTPS

Defina as portas nas quais escutar as conexões HTTPS.

Chave: https_ports Tipo: cadeia de caracteres
Padrão: um valor padrão não está definido.
Definido usando: UseSetting
Variável de ambiente: ASPNETCORE_HTTPS_PORTS

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

Hospedando assemblies de exclusão de inicialização

Uma cadeia de caracteres delimitada por ponto e vírgula de assemblies de inicialização de hospedagem para exclusão na inicialização.

Chave: hostingStartupExcludeAssemblies
Tipo: string
Padrão: cadeia de caracteres vazia
Definido usando: UseSetting
Variável de ambiente: ASPNETCORE_HOSTINGSTARTUPEXCLUDEASSEMBLIES

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

Preferir URLs de hospedagem

Indica se o host deve escutar as URLs configuradas com o WebHostBuilder em vez daquelas configuradas com a implementação IServer.

Chave: preferHostingUrls
Tipo: bool (true ou 1)
Padrão: falso
Definido usando: PreferHostingUrls
Variável de ambiente: ASPNETCORE_PREFERHOSTINGURLS

WebHost.CreateDefaultBuilder(args)
    .PreferHostingUrls(true)

Impedir inicialização de hospedagem

Impede o carregamento automático de assemblies de inicialização de hospedagem, incluindo assemblies de inicialização de hospedagem configurados pelo assembly do aplicativo. Para obter mais informações, confira Usar assemblies de inicialização de hospedagem no ASP.NET Core.

Chave: preventHostingStartup
Tipo: bool (true ou 1)
Padrão: falso
Definido usando: UseSetting
Variável de ambiente: ASPNETCORE_PREVENTHOSTINGSTARTUP

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

URLs de servidor

Indica os endereços IP ou endereços de host com portas e protocolos que o servidor deve escutar para solicitações.

Chave: urls
Tipo: string
Padrão: http://localhost:5000
Definido usando: UseUrls
Variável de ambiente: ASPNETCORE_URLS

Defina como uma lista separada por ponto e vírgula (;) de prefixos de URL aos quais o servidor deve responder. Por exemplo, 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). O protocolo (http:// ou https://) deve ser incluído com cada URL. Os formatos compatíveis variam dependendo dos servidores.

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. Para obter mais informações, confira Configurar pontos de extremidade para o servidor Web Kestrel do ASP.NET Core.

Tempo limite de desligamento

Especifica o tempo de espera para o desligamento do host da Web.

Chave: shutdownTimeoutSeconds
Tipo: int
Padrão: 5
Definido usando: UseShutdownTimeout
Variável de ambiente: ASPNETCORE_SHUTDOWNTIMEOUTSECONDS

Embora a chave aceite um int com UseSetting (por exemplo, .UseSetting(WebHostDefaults.ShutdownTimeoutKey, "10")), o UseShutdownTimeout método de extensão usa um TimeSpan.

Durante o período de tempo limite, a hospedagem:

Dispara IApplicationLifetime.ApplicationStopping.
Tenta parar os serviços hospedados, registrando em log os erros dos serviços que falham ao parar.

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. Os serviços serão parados mesmo se ainda não tiverem concluído o processamento. Se os serviços exigirem mais tempo para parar, aumente o tempo limite.

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

Assembly de inicialização

Determina o assembly para pesquisar pela classe Startup.

Chave: startupAssembly
Tipo: string
Padrão: o assembly do aplicativo
Definido usando: UseStartup
Variável de ambiente: ASPNETCORE_STARTUPASSEMBLY

O assembly por nome (string) ou por tipo (TStartup) pode ser referenciado. Se vários métodos UseStartup forem chamados, o último terá precedência.

WebHost.CreateDefaultBuilder(args)
    .UseStartup("StartupAssemblyName")

WebHost.CreateDefaultBuilder(args)
    .UseStartup<TStartup>()

Raiz da Web

Define o caminho relativo para os ativos estáticos do aplicativo.

Chave: webroot
Tipo: string
Padrão: o padrão é wwwroot. O caminho para {raiz do conteúdo}/wwwroot deve existir. Se o caminho não existir, um provedor de arquivo não operacional será usado.
Definido usando: UseWebRoot
Variável de ambiente: ASPNETCORE_WEBROOT

WebHost.CreateDefaultBuilder(args)
    .UseWebRoot("public")

Para obter mais informações, consulte:

Substituir configuração

Use Configuração para configurar o host da Web. No exemplo a seguir, a configuração do host é especificada, opcionalmente, em um arquivo hostsettings.json. Qualquer configuração carregada do arquivo hostsettings.json pode ser substituída por argumentos de linha de comando. A configuração interna (no config) é usada para configurar o host com UseConfiguration. A configuração IWebHostBuilder é adicionada à configuração do aplicativo, mas o contrário não é verdade, pois ConfigureAppConfiguration não afeta a configuração do IWebHostBuilder.

Substituição da configuração fornecida por UseUrls pela configuração do hostsettings.json primeiro e pela configuração de argumento da linha de comando em seguida:

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

hostsettings.json:

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

Observação

UseConfiguration somente copia as chaves do IConfiguration fornecido para a configuração do construtor de host. Portanto, definir reloadOnChange: true para arquivos de configuração JSON, INI e XML não tem nenhum efeito.

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. O argumento de linha de comando substitui o valor urls do arquivo hostsettings.json e o servidor escuta na porta 8080:

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

Gerenciar o host

Executar

O método Run inicia o aplicativo Web e bloqueia o thread de chamada até que o host seja desligado:

host.Run();

Iniciar

Execute o host sem bloqueio, chamando seu método Start:

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

Se uma lista de URLs for passada para o método Start, ele escutará nas URLs especificadas:

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. Esses métodos iniciam o servidor sem uma saída do console e com WaitForShutdown e aguardam uma interrupção (Ctrl-C/SIGINT ou SIGTERM):

Start(RequestDelegate app)

Inicie com um 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 os blocos de resposta "Olá, Mundo!" WaitForShutdown até que uma interrupção (Ctrl-C/SIGINT ou SIGTERM) seja emitida. O aplicativo exibe a mensagem Console.WriteLine e aguarda um pressionamento de tecla para ser encerrado.

Start(string url, RequestDelegate app)

Inicie com uma URL e 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.

Start(Action<IRouteBuilder> routeBuilder)

Use uma instância de IRouteBuilder (Microsoft.AspNetCore.Routing) para usar o middleware de roteamento:

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:

Solicitação	Resposta
`http://localhost:5000/hello/Martin`	Hello, Martin!
`http://localhost:5000/buenosdias/Catrina`	Buenos dias, Catrina!
`http://localhost:5000/throw/ooops!`	Gera uma exceção com a cadeia de caracteres "ooops!"
`http://localhost:5000/throw`	Gera uma exceção com a cadeia de caracteres "Uh oh!"
`http://localhost:5000/Sante/Kevin`	Sante, Kevin!
`http://localhost:5000`	Olá, Mundo!

WaitForShutdown bloqueia até que uma quebra (Ctrl-C/SIGINT ou SIGTERM) seja emitida. O aplicativo exibe a mensagem Console.WriteLine e aguarda um pressionamento de tecla para ser encerrado.

Start(string url, Action<IRouteBuilder> routeBuilder)

Use uma URL e uma instância de 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.

StartWith(Action<IApplicationBuilder> app)

Forneça um delegado para configurar um 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();
}

StartWith(string url, Action<IApplicationBuilder> app)

Forneça um delegado e uma URL para configurar um 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.

Interface IWebHostEnvironment

A interface IWebHostEnvironment fornece informações sobre o ambiente de hospedagem na Web do aplicativo. Use a injeção de construtor para obter o IWebHostEnvironment para usar suas propriedades e métodos de extensão:

public class CustomFileReader
{
    private readonly IWebHostEnvironment _env;

    public CustomFileReader(IWebHostEnvironment 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. Como alternativa, injete o IWebHostEnvironment no construtor Startup para uso em ConfigureServices:

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

    public IWebHostEnvironment 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, IWebHostEnvironment oferece os métodos IsStaging, IsProduction e IsEnvironment(string environmentName). Para obter mais informações, confira Usar vários ambientes no ASP.NET Core.

O serviço IWebHostEnvironment também pode ser injetado diretamente no método Configure para configurar o pipeline de processamento:

public void Configure(IApplicationBuilder app, IWebHostEnvironment 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;
}

IWebHostEnvironment pode ser injetado no método Invoke ao criar um middleware personalizado:

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

    var contentRootPath = env.ContentRootPath;
}

Interface IHostApplicationLifetime

IHostApplicationLifetime permite atividades pós-inicialização e desligamento. Três propriedades na interface são tokens de cancelamento usados para registrar métodos Action que definem eventos de inicialização e desligamento.

Token de cancelamento	Disparado quando…
`ApplicationStarted`	O host foi iniciado totalmente.
`ApplicationStopped`	O host está concluindo um desligamento normal. Todas as solicitações devem ser processadas. O desligamento é bloqueado até que esse evento seja concluído.
`ApplicationStopping`	O host está executando um desligamento normal. Solicitações ainda podem estar sendo processadas. O desligamento é bloqueado até que esse evento seja concluído.

public class Startup
{
    public void Configure(IApplicationBuilder app, IHostApplicationLifetime 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. A classe a seguir usa StopApplication para desligar normalmente um aplicativo quando o método Shutdown da classe é chamado:

public class MyClass
{
    private readonly IHostApplicationLifetime _appLifetime;

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

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

Validação de escopo

CreateDefaultBuilder define ServiceProviderOptions.ValidateScopes como true se o ambiente do aplicativo for Desenvolvimento.

Quando ValidateScopes está definido como true, o provedor de serviço padrão executa verificações para saber se:

Os serviços com escopo não são resolvidos direta ou indiretamente pelo provedor de serviço raiz.
Os serviços com escopo não são injetados direta ou indiretamente em singletons.

O provedor de serviços raiz é criado quando BuildServiceProvider é chamado. 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.

Os serviços com escopo são descartados pelo contêiner que os criou. 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. A validação dos escopos de serviço detecta essas situações quando BuildServiceProvider é chamado.

Para que os escopos sempre sejam validados, incluindo no ambiente de produção, configure ServiceProviderOptions com UseDefaultServiceProvider no construtor do host:

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

Recursos adicionais

Este artigo aborda o host da Web, que permanece disponível somente para compatibilidade com versões anteriores. Os modelos do ASP.NET Core criam um Host Genérico do .NET, que é recomendado para todos os tipos de aplicativo.

Configurar um host

Crie um host usando uma instância do IWebHostBuilder. Normalmente, isso é feito no ponto de entrada do aplicativo, o método Main.

Em modelos de projeto, Main está localizado em Program.cs. Um aplicativo típico chama CreateDefaultBuilder para iniciar a configuração de um 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 realiza as seguintes tarefas:

Configura o servidor Kestrel como o servidor Web usando provedores de configuração de hospedagem do aplicativo. Para obter as opções padrão do servidor Kestrel, confira Configurar opções para o servidor Web Kestrel do ASP.NET Core.
Define a raiz do conteúdo como o caminho retornado por Directory.GetCurrentDirectory.
Carrega a configuração do host de:
- Variáveis de ambiente prefixadas com ASPNETCORE_ (por exemplo, ASPNETCORE_ENVIRONMENT).
- Argumentos de linha de comando.
Carrega a configuração do aplicativo na seguinte ordem de:
- appsettings.json.
- appsettings.{Environment}.json.
- Segredos do usuário quando o aplicativo é executado no ambiente Development usando o assembly de entrada.
- Variáveis de ambiente.
- Argumentos de linha de comando.
Configura o registro em log para a saída do console e de depuração. O registro em log inclui regras de filtragem de log especificadas em uma seção de configuração de registro em log de um arquivo appsettings.json ou appsettings.{Environment}.json.
Quando executado com a proteção do IIS com o Módulo do ASP.NET Core, CreateDefaultBuilder habilita a Integração do IIS, que configura a porta e o endereço básico do aplicativo. A Integração do IIS também configura o aplicativo para capturar erros de inicialização. Para obter as opções padrão do IIS, confira Hospedar o ASP.NET Core no Windows com o ISS.
Define ServiceProviderOptions.ValidateScopes para true se o ambiente do aplicativo for Desenvolvimento. Para obter mais informações, confira Validação de escopo.

ConfigureAppConfiguration é usado para especificar IConfiguration adicionais para o aplicativo. A chamada ConfigureAppConfiguration a seguir adiciona um delegado para incluir a configuração do aplicativo no arquivo appsettings.xml. ConfigureAppConfiguration pode ser chamado várias vezes. Observe que essa configuração não se aplica ao host (por exemplo, URLs de servidor ou de ambiente). Consulte a seção Valores de configuração de Host.
```
WebHost.CreateDefaultBuilder(args)
    .ConfigureAppConfiguration((hostingContext, config) =>
    {
        config.AddXmlFile("appsettings.xml", optional: true, reloadOnChange: true);
    })
    ...
```
A chamada ConfigureLogging a seguir adiciona um delegado para configurar o nível mínimo de registro em log (SetMinimumLevel) para LogLevel.Warning. Essa configuração substitui as configurações em appsettings.Development.json (LogLevel.Debug) e appsettings.Production.json (LogLevel.Error) configuradas por CreateDefaultBuilder. ConfigureLogging pode ser chamado várias vezes.
```
WebHost.CreateDefaultBuilder(args)
    .ConfigureLogging(logging => 
    {
        logging.SetMinimumLevel(LogLevel.Warning);
    })
    ...
```
A chamada a seguir para ConfigureKestrel substitui o padrão Limits.MaxRequestBodySize de 30.000.000 bytes estabelecidos quando o Kestrel foi configurado pelo CreateDefaultBuilder:
```
WebHost.CreateDefaultBuilder(args)
    .ConfigureKestrel((context, options) =>
    {
        options.Limits.MaxRequestBodySize = 20000000;
    });
```

Para obter mais informações sobre a configuração de aplicativos, consulte Configuração no ASP.NET Core.

Observação

Como uma alternativa ao uso do método CreateDefaultBuilder estático, criar um host no WebHostBuilder é uma abordagem compatível com o ASP.NET Core 2.x.

Valores de configuração do host

O WebHostBuilder depende das seguintes abordagens para definir os valores de configuração do host:

Configuração do construtor do host, que inclui variáveis de ambiente com o formato ASPNETCORE_{configurationKey}. Por exemplo, ASPNETCORE_ENVIRONMENT.
Extensões como UseContentRoot e UseConfiguration (veja a seção Configuração de substituição).
UseSetting e a chave associada. Ao definir um valor com UseSetting, o valor é definido como uma cadeia de caracteres, independentemente do tipo.

O host usa a opção que define um valor por último. Para obter mais informações, veja Substituir configuração na próxima seção.

Chave do Aplicativo (Nome)

WebHost.CreateDefaultBuilder(args)
    .UseSetting(WebHostDefaults.ApplicationKey, "CustomApplicationName")

Capturar erros de inicialização

Esta configuração controla a captura de erros de inicialização.

Quando false, erros durante a inicialização resultam no encerramento do host. Quando true, o host captura exceções durante a inicialização e tenta iniciar o servidor.

WebHost.CreateDefaultBuilder(args)
    .CaptureStartupErrors(true)

Raiz do conteúdo

Essa configuração determina onde o ASP.NET Core começa a procurar por arquivos de conteúdo.

A raiz do conteúdo também é usada como o caminho base para a raiz da Web. Se o caminho raiz do conteúdo não existir, o host não será iniciado.

WebHost.CreateDefaultBuilder(args)
    .UseContentRoot("c:\\<content-root>")

Para obter mais informações, consulte:

Erros detalhados

Determina se erros detalhados devem ser capturados.

Chave: detailedErrors
Tipo: bool (true ou 1)
Padrão: falso
Definido usando: UseSetting
Variável de ambiente: ASPNETCORE_DETAILEDERRORS

Quando habilitado (ou quando o Ambiente é definido como Development), o aplicativo captura exceções detalhadas.

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

Ambiente

Define o ambiente do aplicativo.

Chave: ambiente
Tipo: string
Padrão: Production
Definido usando: UseEnvironment
Variável de ambiente: ASPNETCORE_ENVIRONMENT

WebHost.CreateDefaultBuilder(args)
    .UseEnvironment(EnvironmentName.Development)

Hospedando assemblies de inicialização

Define os assemblies de inicialização de hospedagem do aplicativo.

Chave: hostingStartupAssemblies
Tipo: string
Padrão: cadeia de caracteres vazia
Definido usando: UseSetting
Variável de ambiente: ASPNETCORE_HOSTINGSTARTUPASSEMBLIES

Uma cadeia de caracteres delimitada por ponto e vírgula de assemblies de inicialização de hospedagem para carregamento na inicialização.

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

Porta HTTPS

Defina a porta de redirecionamento HTTPS. Uso em aplicação de HTTPS.

Chave: https_port
Tipo: string
Padrão: um valor padrão não está definido.
Definido usando: UseSetting
Variável de ambiente: ASPNETCORE_HTTPS_PORTS

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

Hospedando assemblies de exclusão de inicialização

Uma cadeia de caracteres delimitada por ponto e vírgula de assemblies de inicialização de hospedagem para exclusão na inicialização.

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

Preferir URLs de hospedagem

Indica se o host deve escutar as URLs configuradas com o WebHostBuilder em vez daquelas configuradas com a implementação IServer.

Chave: preferHostingUrls
Tipo: bool (true ou 1)
Padrão: falso
Definido usando: PreferHostingUrls
Variável de ambiente: ASPNETCORE_PREFERHOSTINGURLS

WebHost.CreateDefaultBuilder(args)
    .PreferHostingUrls(true)

Impedir inicialização de hospedagem

Chave: preventHostingStartup
Tipo: bool (true ou 1)
Padrão: falso
Definido usando: UseSetting
Variável de ambiente: ASPNETCORE_PREVENTHOSTINGSTARTUP

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

URLs de servidor

Indica os endereços IP ou endereços de host com portas e protocolos que o servidor deve escutar para solicitações.

Chave: urls
Tipo: string
Padrão: http://localhost:5000
Definido usando: UseUrls
Variável de ambiente: ASPNETCORE_URLS

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. Para obter mais informações, confira Configurar pontos de extremidade para o servidor Web Kestrel do ASP.NET Core.

Tempo limite de desligamento

Especifica o tempo de espera para o desligamento do host da Web.

Chave: shutdownTimeoutSeconds
Tipo: int
Padrão: 5
Definido usando: UseShutdownTimeout
Variável de ambiente: ASPNETCORE_SHUTDOWNTIMEOUTSECONDS

Embora a chave aceite um int com UseSetting (por exemplo, .UseSetting(WebHostDefaults.ShutdownTimeoutKey, "10")), o UseShutdownTimeout método de extensão usa um TimeSpan.

Durante o período de tempo limite, a hospedagem:

Dispara IApplicationLifetime.ApplicationStopping.
Tenta parar os serviços hospedados, registrando em log os erros dos serviços que falham ao parar.

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

Assembly de inicialização

Determina o assembly para pesquisar pela classe Startup.

Chave: startupAssembly
Tipo: string
Padrão: o assembly do aplicativo
Definido usando: UseStartup
Variável de ambiente: ASPNETCORE_STARTUPASSEMBLY

O assembly por nome (string) ou por tipo (TStartup) pode ser referenciado. Se vários métodos UseStartup forem chamados, o último terá precedência.

WebHost.CreateDefaultBuilder(args)
    .UseStartup("StartupAssemblyName")

WebHost.CreateDefaultBuilder(args)
    .UseStartup<TStartup>()

Raiz da Web

Define o caminho relativo para os ativos estáticos do aplicativo.

WebHost.CreateDefaultBuilder(args)
    .UseWebRoot("public")

Para obter mais informações, consulte:

Substituir configuração

Substituição da configuração fornecida por UseUrls pela configuração do hostsettings.json primeiro e pela configuração de argumento da linha de comando em seguida:

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

hostsettings.json:

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

Observação

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

Gerenciar o host

Executar

O método Run inicia o aplicativo Web e bloqueia o thread de chamada até que o host seja desligado:

host.Run();

Iniciar

Execute o host sem bloqueio, chamando seu método Start:

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

Se uma lista de URLs for passada para o método Start, ele escutará nas URLs especificadas:

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

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

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

Start(RequestDelegate app)

Inicie com um RequestDelegate:

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

Start(string url, RequestDelegate app)

Inicie com uma URL e 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.

Start(Action<IRouteBuilder> routeBuilder)

Use uma instância de IRouteBuilder (Microsoft.AspNetCore.Routing) para usar o middleware de roteamento:

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:

Solicitação	Resposta
`http://localhost:5000/hello/Martin`	Hello, Martin!
`http://localhost:5000/buenosdias/Catrina`	Buenos dias, Catrina!
`http://localhost:5000/throw/ooops!`	Gera uma exceção com a cadeia de caracteres "ooops!"
`http://localhost:5000/throw`	Gera uma exceção com a cadeia de caracteres "Uh oh!"
`http://localhost:5000/Sante/Kevin`	Sante, Kevin!
`http://localhost:5000`	Olá, Mundo!

WaitForShutdown bloqueia até que uma quebra (Ctrl-C/SIGINT ou SIGTERM) seja emitida. O aplicativo exibe a mensagem Console.WriteLine e aguarda um pressionamento de tecla para ser encerrado.

Start(string url, Action<IRouteBuilder> routeBuilder)

Use uma URL e uma instância de 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.

StartWith(Action<IApplicationBuilder> app)

Forneça um delegado para configurar um 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();
}

StartWith(string url, Action<IApplicationBuilder> app)

Forneça um delegado e uma URL para configurar um 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.

Interface IWebHostEnvironment

public class CustomFileReader
{
    private readonly IWebHostEnvironment _env;

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

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

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

    public IWebHostEnvironment HostingEnvironment { get; }

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

        var contentRootPath = HostingEnvironment.ContentRootPath;
    }
}

Observação

O serviço IWebHostEnvironment também pode ser injetado diretamente no método Configure para configurar o pipeline de processamento:

public void Configure(IApplicationBuilder app, IWebHostEnvironment 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;
}

IWebHostEnvironment pode ser injetado no método Invoke ao criar um middleware personalizado:

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

    var contentRootPath = env.ContentRootPath;
}

Interface IHostApplicationLifetime

Token de cancelamento	Disparado quando…
`ApplicationStarted`	O host foi iniciado totalmente.
`ApplicationStopped`	O host está concluindo um desligamento normal. Todas as solicitações devem ser processadas. O desligamento é bloqueado até que esse evento seja concluído.
`ApplicationStopping`	O host está executando um desligamento normal. Solicitações ainda podem estar sendo processadas. O desligamento é bloqueado até que esse evento seja concluído.

public class Startup
{
    public void Configure(IApplicationBuilder app, IHostApplicationLifetime 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. A classe a seguir usa StopApplication para desligar normalmente um aplicativo quando o método Shutdown da classe é chamado:

public class MyClass
{
    private readonly IHostApplicationLifetime _appLifetime;

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

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

Validação de escopo

CreateDefaultBuilder define ServiceProviderOptions.ValidateScopes como true se o ambiente do aplicativo for Desenvolvimento.

Quando ValidateScopes está definido como true, o provedor de serviço padrão executa verificações para saber se:

Os serviços com escopo não são resolvidos direta ou indiretamente pelo provedor de serviço raiz.
Os serviços com escopo não são injetados direta ou indiretamente em singletons.

Para que os escopos sempre sejam validados, incluindo no ambiente de produção, configure ServiceProviderOptions com UseDefaultServiceProvider no construtor do host:

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

Recursos adicionais

Configurar um host

Crie um host usando uma instância do IWebHostBuilder. Normalmente, isso é feito no ponto de entrada do aplicativo, o método Main.

Em modelos de projeto, Main está localizado em Program.cs. Um aplicativo típico chama CreateDefaultBuilder para iniciar a configuração de um 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 realiza as seguintes tarefas:

Configura o servidor Kestrel como o servidor Web usando provedores de configuração de hospedagem do aplicativo. Para obter as opções padrão do servidor Kestrel, confira servidor web Kestrel no ASP.NET Core.
Define a raiz do conteúdo como o caminho retornado por Directory.GetCurrentDirectory.
Carrega a configuração do host de:
- Variáveis de ambiente prefixadas com ASPNETCORE_ (por exemplo, ASPNETCORE_ENVIRONMENT).
- Argumentos de linha de comando.
Carrega a configuração do aplicativo na seguinte ordem de:
- appsettings.json.
- appsettings.{Environment}.json.
- Segredos do usuário quando o aplicativo é executado no ambiente Development usando o assembly de entrada.
- Variáveis de ambiente.
- Argumentos de linha de comando.
Configura o registro em log para a saída do console e de depuração. O registro em log inclui regras de filtragem de log especificadas em uma seção de configuração de registro em log de um arquivo appsettings.json ou appsettings.{Environment}.json.
Quando executado com a proteção do IIS com o Módulo do ASP.NET Core, CreateDefaultBuilder habilita a Integração do IIS, que configura a porta e o endereço básico do aplicativo. A Integração do IIS também configura o aplicativo para capturar erros de inicialização. Para obter as opções padrão do IIS, confira Hospedar o ASP.NET Core no Windows com o ISS.
Define ServiceProviderOptions.ValidateScopes para true se o ambiente do aplicativo for Desenvolvimento. Para obter mais informações, confira Validação de escopo.

ConfigureAppConfiguration é usado para especificar IConfiguration adicionais para o aplicativo. A chamada ConfigureAppConfiguration a seguir adiciona um delegado para incluir a configuração do aplicativo no arquivo appsettings.xml. ConfigureAppConfiguration pode ser chamado várias vezes. Observe que essa configuração não se aplica ao host (por exemplo, URLs de servidor ou de ambiente). Consulte a seção Valores de configuração de Host.
```
WebHost.CreateDefaultBuilder(args)
    .ConfigureAppConfiguration((hostingContext, config) =>
    {
        config.AddXmlFile("appsettings.xml", optional: true, reloadOnChange: true);
    })
    ...
```
A chamada ConfigureLogging a seguir adiciona um delegado para configurar o nível mínimo de registro em log (SetMinimumLevel) para LogLevel.Warning. Essa configuração substitui as configurações em appsettings.Development.json (LogLevel.Debug) e appsettings.Production.json (LogLevel.Error) configuradas por CreateDefaultBuilder. ConfigureLogging pode ser chamado várias vezes.
```
WebHost.CreateDefaultBuilder(args)
    .ConfigureLogging(logging => 
    {
        logging.SetMinimumLevel(LogLevel.Warning);
    })
    ...
```
A chamada a seguir para ConfigureKestrel substitui o padrão Limits.MaxRequestBodySize de 30.000.000 bytes estabelecidos quando o Kestrel foi configurado pelo CreateDefaultBuilder:
```
WebHost.CreateDefaultBuilder(args)
    .ConfigureKestrel((context, options) =>
    {
        options.Limits.MaxRequestBodySize = 20000000;
    });
```

Para obter mais informações sobre a configuração de aplicativos, consulte Configuração no ASP.NET Core.

Observação

Como uma alternativa ao uso do método CreateDefaultBuilder estático, criar um host no WebHostBuilder é uma abordagem compatível com o ASP.NET Core 2.x.

Valores de configuração do host

O WebHostBuilder depende das seguintes abordagens para definir os valores de configuração do host:

Configuração do construtor do host, que inclui variáveis de ambiente com o formato ASPNETCORE_{configurationKey}. Por exemplo, ASPNETCORE_ENVIRONMENT.
Extensões como UseContentRoot e UseConfiguration (veja a seção Configuração de substituição).
UseSetting e a chave associada. Ao definir um valor com UseSetting, o valor é definido como uma cadeia de caracteres, independentemente do tipo.

O host usa a opção que define um valor por último. Para obter mais informações, veja Substituir configuração na próxima seção.

Chave do Aplicativo (Nome)

WebHost.CreateDefaultBuilder(args)
    .UseSetting(WebHostDefaults.ApplicationKey, "CustomApplicationName")

Capturar erros de inicialização

Esta configuração controla a captura de erros de inicialização.

Quando false, erros durante a inicialização resultam no encerramento do host. Quando true, o host captura exceções durante a inicialização e tenta iniciar o servidor.

WebHost.CreateDefaultBuilder(args)
    .CaptureStartupErrors(true)

Raiz do conteúdo

Essa configuração determina onde o ASP.NET Core começa a procurar por arquivos de conteúdo.

A raiz do conteúdo também é usada como o caminho base para a raiz da Web. Se o caminho raiz do conteúdo não existir, o host não será iniciado.

WebHost.CreateDefaultBuilder(args)
    .UseContentRoot("c:\\<content-root>")

Para obter mais informações, consulte:

Erros detalhados

Determina se erros detalhados devem ser capturados.

Chave: detailedErrors
Tipo: bool (true ou 1)
Padrão: falso
Definido usando: UseSetting
Variável de ambiente: ASPNETCORE_DETAILEDERRORS

Quando habilitado (ou quando o Ambiente é definido como Development), o aplicativo captura exceções detalhadas.

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

Ambiente

Define o ambiente do aplicativo.

Chave: ambiente
Tipo: string
Padrão: Production
Definido usando: UseEnvironment
Variável de ambiente: ASPNETCORE_ENVIRONMENT

WebHost.CreateDefaultBuilder(args)
    .UseEnvironment(EnvironmentName.Development)

Hospedando assemblies de inicialização

Define os assemblies de inicialização de hospedagem do aplicativo.

Chave: hostingStartupAssemblies
Tipo: string
Padrão: cadeia de caracteres vazia
Definido usando: UseSetting
Variável de ambiente: ASPNETCORE_HOSTINGSTARTUPASSEMBLIES

Uma cadeia de caracteres delimitada por ponto e vírgula de assemblies de inicialização de hospedagem para carregamento na inicialização.

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

Porta HTTPS

Defina a porta de redirecionamento HTTPS. Uso em aplicação de HTTPS.

Chave: https_port
Tipo: string
Padrão: um valor padrão não está definido.
Definido usando: UseSetting
Variável de ambiente: ASPNETCORE_HTTPS_PORTS

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

Hospedando assemblies de exclusão de inicialização

Uma cadeia de caracteres delimitada por ponto e vírgula de assemblies de inicialização de hospedagem para exclusão na inicialização.

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

Preferir URLs de hospedagem

Indica se o host deve escutar as URLs configuradas com o WebHostBuilder em vez daquelas configuradas com a implementação IServer.

Chave: preferHostingUrls
Tipo: bool (true ou 1)
Padrão: falso
Definido usando: PreferHostingUrls
Variável de ambiente: ASPNETCORE_PREFERHOSTINGURLS

WebHost.CreateDefaultBuilder(args)
    .PreferHostingUrls(true)

Impedir inicialização de hospedagem

Chave: preventHostingStartup
Tipo: bool (true ou 1)
Padrão: falso
Definido usando: UseSetting
Variável de ambiente: ASPNETCORE_PREVENTHOSTINGSTARTUP

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

URLs de servidor

Indica os endereços IP ou endereços de host com portas e protocolos que o servidor deve escutar para solicitações.

Chave: urls
Tipo: string
Padrão: http://localhost:5000
Definido usando: UseUrls
Variável de ambiente: ASPNETCORE_URLS

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. Para obter mais informações, confira servidor web Kestrel no ASP.NET Core.

Tempo limite de desligamento

Especifica o tempo de espera para o desligamento do host da Web.

Chave: shutdownTimeoutSeconds
Tipo: int
Padrão: 5
Definido usando: UseShutdownTimeout
Variável de ambiente: ASPNETCORE_SHUTDOWNTIMEOUTSECONDS

Embora a chave aceite um int com UseSetting (por exemplo, .UseSetting(WebHostDefaults.ShutdownTimeoutKey, "10")), o UseShutdownTimeout método de extensão usa um TimeSpan.

Durante o período de tempo limite, a hospedagem:

Dispara IApplicationLifetime.ApplicationStopping.
Tenta parar os serviços hospedados, registrando em log os erros dos serviços que falham ao parar.

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

Assembly de inicialização

Determina o assembly para pesquisar pela classe Startup.

Chave: startupAssembly
Tipo: string
Padrão: o assembly do aplicativo
Definido usando: UseStartup
Variável de ambiente: ASPNETCORE_STARTUPASSEMBLY

O assembly por nome (string) ou por tipo (TStartup) pode ser referenciado. Se vários métodos UseStartup forem chamados, o último terá precedência.

WebHost.CreateDefaultBuilder(args)
    .UseStartup("StartupAssemblyName")

WebHost.CreateDefaultBuilder(args)
    .UseStartup<TStartup>()

Raiz da Web

Define o caminho relativo para os ativos estáticos do aplicativo.

WebHost.CreateDefaultBuilder(args)
    .UseWebRoot("public")

Para obter mais informações, consulte:

Substituir configuração

Substituição da configuração fornecida por UseUrls pela configuração do hostsettings.json primeiro e pela configuração de argumento da linha de comando em seguida:

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

hostsettings.json:

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

Observação

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

Gerenciar o host

Executar

O método Run inicia o aplicativo Web e bloqueia o thread de chamada até que o host seja desligado:

host.Run();

Iniciar

Execute o host sem bloqueio, chamando seu método Start:

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

Se uma lista de URLs for passada para o método Start, ele escutará nas URLs especificadas:

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

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

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

Start(RequestDelegate app)

Inicie com um RequestDelegate:

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

Start(string url, RequestDelegate app)

Inicie com uma URL e 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.

Start(Action<IRouteBuilder> routeBuilder)

Use uma instância de IRouteBuilder (Microsoft.AspNetCore.Routing) para usar o middleware de roteamento:

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:

Solicitação	Resposta
`http://localhost:5000/hello/Martin`	Hello, Martin!
`http://localhost:5000/buenosdias/Catrina`	Buenos dias, Catrina!
`http://localhost:5000/throw/ooops!`	Gera uma exceção com a cadeia de caracteres "ooops!"
`http://localhost:5000/throw`	Gera uma exceção com a cadeia de caracteres "Uh oh!"
`http://localhost:5000/Sante/Kevin`	Sante, Kevin!
`http://localhost:5000`	Olá, Mundo!

WaitForShutdown bloqueia até que uma quebra (Ctrl-C/SIGINT ou SIGTERM) seja emitida. O aplicativo exibe a mensagem Console.WriteLine e aguarda um pressionamento de tecla para ser encerrado.

Start(string url, Action<IRouteBuilder> routeBuilder)

Use uma URL e uma instância de 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.

StartWith(Action<IApplicationBuilder> app)

Forneça um delegado para configurar um 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();
}

StartWith(string url, Action<IApplicationBuilder> app)

Forneça um delegado e uma URL para configurar um 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.

Interface IWebHostEnvironment

public class CustomFileReader
{
    private readonly IWebHostEnvironment _env;

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

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

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

    public IWebHostEnvironment HostingEnvironment { get; }

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

        var contentRootPath = HostingEnvironment.ContentRootPath;
    }
}

Observação

O serviço IWebHostEnvironment também pode ser injetado diretamente no método Configure para configurar o pipeline de processamento:

public void Configure(IApplicationBuilder app, IWebHostEnvironment 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;
}

IWebHostEnvironment pode ser injetado no método Invoke ao criar um middleware personalizado:

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

    var contentRootPath = env.ContentRootPath;
}

Interface IHostApplicationLifetime

Token de cancelamento	Disparado quando…
`ApplicationStarted`	O host foi iniciado totalmente.
`ApplicationStopped`	O host está concluindo um desligamento normal. Todas as solicitações devem ser processadas. O desligamento é bloqueado até que esse evento seja concluído.
`ApplicationStopping`	O host está executando um desligamento normal. Solicitações ainda podem estar sendo processadas. O desligamento é bloqueado até que esse evento seja concluído.

public class Startup
{
    public void Configure(IApplicationBuilder app, IHostApplicationLifetime 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. A classe a seguir usa StopApplication para desligar normalmente um aplicativo quando o método Shutdown da classe é chamado:

public class MyClass
{
    private readonly IHostApplicationLifetime _appLifetime;

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

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

Validação de escopo

CreateDefaultBuilder define ServiceProviderOptions.ValidateScopes como true se o ambiente do aplicativo for Desenvolvimento.

Quando ValidateScopes está definido como true, o provedor de serviço padrão executa verificações para saber se:

Os serviços com escopo não são resolvidos direta ou indiretamente pelo provedor de serviço raiz.
Os serviços com escopo não são injetados direta ou indiretamente em singletons.

Para que os escopos sempre sejam validados, incluindo no ambiente de produção, configure ServiceProviderOptions com UseDefaultServiceProvider no construtor do host:

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

Compartilhar via

Host da Web do ASP.NET Core

Configurar um host

Valores de configuração do host

Chave do Aplicativo (Nome)

Capturar erros de inicialização

Raiz do conteúdo

Erros detalhados

Ambiente

Hospedando assemblies de inicialização

Porta HTTPS

Portas HTTPS

Hospedando assemblies de exclusão de inicialização

Preferir URLs de hospedagem

Impedir inicialização de hospedagem

URLs de servidor

Tempo limite de desligamento

Assembly de inicialização

Raiz da Web

Substituir configuração

Gerenciar o host

Interface IWebHostEnvironment

Interface IHostApplicationLifetime

Validação de escopo

Recursos adicionais

Configurar um host

Valores de configuração do host

Chave do Aplicativo (Nome)

Capturar erros de inicialização

Raiz do conteúdo

Erros detalhados

Ambiente

Hospedando assemblies de inicialização

Porta HTTPS

Hospedando assemblies de exclusão de inicialização

Preferir URLs de hospedagem

Impedir inicialização de hospedagem

URLs de servidor

Tempo limite de desligamento

Assembly de inicialização

Raiz da Web

Substituir configuração

Gerenciar o host

Interface IWebHostEnvironment

Interface IHostApplicationLifetime

Validação de escopo

Recursos adicionais

Configurar um host

Valores de configuração do host

Chave do Aplicativo (Nome)

Capturar erros de inicialização

Raiz do conteúdo

Erros detalhados

Ambiente

Hospedando assemblies de inicialização

Porta HTTPS

Hospedando assemblies de exclusão de inicialização

Preferir URLs de hospedagem

Impedir inicialização de hospedagem

URLs de servidor

Tempo limite de desligamento

Assembly de inicialização

Raiz da Web

Substituir configuração

Gerenciar o host

Interface IWebHostEnvironment

Interface IHostApplicationLifetime

Validação de escopo

Recursos adicionais

Recursos adicionais