Host da Web do ASP.NET Core

  • Artigo
  • 50 minutos para o fim da leitura

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 de ASP.NET Core criam um WebApplicationBuilder e WebApplication, que é recomendado para aplicativos Web. Para obter mais informações sobre WebApplicationBuilder e WebApplication, consulte Migrar de 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 Main método 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:

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

  • ConfigureAppConfiguration é usado para especificar adicionais IConfiguration para o aplicativo. A chamada a seguir ConfigureAppConfiguration adiciona um delegado para incluir a configuração do aplicativo no appsettings.xml arquivo. 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 a seguir ConfigureLogging adiciona um delegado para configurar o nível mínimo de log (SetMinimumLevel) para LogLevel.Warning. Essa configuração substitui as configurações em appsettings.Development.json (LogLevel.Debug) e appsettings.Production.json (LogLevel.Error) definidas 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 Kestrel foi configurado por 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 alternativa ao uso do método estáticoCreateDefaultBuilder, criar um host do WebHostBuilder é uma abordagem com suporte com ASP.NET Core 2.x.

Ao configurar um host, Configure os métodos 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

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 (consulte a seção Substituir configuraçã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 IWebHostEnvironment.ApplicationName propriedade é definida automaticamente quando UseStartup ou Configure é chamada 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: cadeia de caracteres
Padrão: o nome do assembly que contém o ponto de entrada do aplicativo.
Defina 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 é a false menos que o aplicativo seja executado com Kestrel o IIS por trás, onde o padrão é true.
Defina 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 ASP.NET Core começa a pesquisar arquivos de conteúdo.

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

A raiz de 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 falhará ao iniciar.

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: false
Defina 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: cadeia de caracteres
Padrão: Production
Defina 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 launchSettings.json arquivo. 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: cadeia de caracteres
Padrão: cadeia de caracteres vazia
Defina 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 de redirecionamento HTTPS. Uso em aplicação de HTTPS.

Chave: https_port
Tipo: cadeia de caracteres
Padrão: um valor padrão não é definido.
Defina usando: UseSetting
Variável de ambiente: ASPNETCORE_HTTPS_PORT

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.

Chave: hostingStartupExcludeAssemblies
Tipo: cadeia de caracteres
Padrão: cadeia de caracteres vazia
Defina 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: true
Defina usando: PreferHostingUrls
Variável de ambiente: ASPNETCORE_PREFERHOSTINGURLS

WebHost.CreateDefaultBuilder(args)
    .PreferHostingUrls(false)

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: false
Defina 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: cadeia de caracteres
Padrão: http://localhost:5000
Defina 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")

Kestrel tem sua própria API de configuração de ponto de extremidade. Para obter mais informações, consulte Configurar pontos de extremidade para o servidor Web ASP.NET CoreKestrel.

Tempo limite de desligamento

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

Chave: shutdownTimeoutSeconds
Tipo: int
Padrão: 5
Defina 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:

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: cadeia de caracteres
Padrão: o assembly do aplicativo
Defina 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: cadeia de caracteres
Padrão: o padrão é wwwroot. O caminho para {raiz de conteúdo}/wwwroot deve existir. Se o caminho não existir, um provedor de arquivo não operacional será usado.
Defina 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 é opcionalmente especificada em um hostsettings.json arquivo. Qualquer configuração carregada do hostsettings.json arquivo pode ser substituída por argumentos de linha de comando. A configuração interna (no config) é usada para configurar o host com UseConfiguration. IWebHostBuilder A configuração é adicionada à configuração do aplicativo, mas o inverso não é verdadeiro,ConfigureAppConfiguration não afeta a IWebHostBuilder configuração.

Substituindo a configuração fornecida por UseUrls com hostsettings.json configuração primeiro, configuração de argumento de linha de comando segundo:

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, a configuração reloadOnChange: true para JSarquivos de configurações ON, INI e XML não tem 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 urls valor do hostsettings.json arquivo 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 saída do console e com WaitForShutdown a espera de 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 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();
}

Faça uma solicitação no navegador para http://localhost:5000 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.

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 IWebHostEnvironment interface fornece informações sobre o ambiente de hospedagem da 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 sempre validar escopos, inclusive no ambiente de produção, configure o ServiceProviderOptions com UseDefaultServiceProvider no construtor de host:

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

Recursos adicionais

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

Nos modelos de projeto, Main está localizado em Program.cs. Um aplicativo típico chama CreateDefaultBuilder para começar a configurar 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:

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

  • ConfigureAppConfiguration é usado para especificar adicionais IConfiguration para o aplicativo. A chamada a seguir ConfigureAppConfiguration adiciona um delegado para incluir a configuração do aplicativo no appsettings.xml arquivo . 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 a seguir ConfigureLogging adiciona um delegado para configurar o nível mínimo de log (SetMinimumLevel) para LogLevel.Warning. Essa configuração substitui as configurações em appsettings.Development.json (LogLevel.Debug) e appsettings.Production.json (LogLevel.Error) definidas 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 Kestrel foi configurado por 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 alternativa ao uso do método estáticoCreateDefaultBuilder, criar um host do WebHostBuilder é uma abordagem com suporte com ASP.NET Core 2.x.

Ao configurar um host, Configure os métodos 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

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 (consulte a seção Substituir configuraçã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 IWebHostEnvironment.ApplicationName propriedade é definida automaticamente quando UseStartup ou Configure é chamada 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: cadeia de caracteres
Padrão: o nome do assembly que contém o ponto de entrada do aplicativo.
Defina 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 trás do IIS, em que o padrão é true.
Defina 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 ASP.NET Core começa a pesquisar arquivos de conteúdo.

Chave: contentRoot
Tipo: cadeia de caracteres
Padrão: o padrão é a pasta em que o assembly do aplicativo reside.
Defina 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: false
Defina 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: cadeia de caracteres
Padrão: Production
Defina 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 launchSettings.json arquivo. 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: cadeia de caracteres
Padrão: cadeia de caracteres vazia
Defina 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 de redirecionamento HTTPS. Uso em aplicação de HTTPS.

Chave: https_port
Tipo: cadeia de caracteres
Padrão: um valor padrão não é definido.
Defina usando: UseSetting
Variável de ambiente: ASPNETCORE_HTTPS_PORT

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.

Chave: hostingStartupExcludeAssemblies
Tipo: cadeia de caracteres
Padrão: cadeia de caracteres vazia
Defina 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: true
Defina usando: PreferHostingUrls
Variável de ambiente: ASPNETCORE_PREFERHOSTINGURLS

WebHost.CreateDefaultBuilder(args)
    .PreferHostingUrls(false)

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: false
Defina 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: cadeia de caracteres
Padrão: http://localhost:5000
Defina 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")

Kestrel tem sua própria API de configuração de ponto de extremidade. Para obter mais informações, consulte Configurar pontos de extremidade para o servidor Web ASP.NET CoreKestrel.

Tempo limite de desligamento

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

Chave: shutdownTimeoutSeconds
Tipo: int
Padrão: 5
Defina 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:

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: cadeia de caracteres
Padrão: o assembly do aplicativo
Defina 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: cadeia de caracteres
Padrão: o padrão é wwwroot. O caminho para {raiz de conteúdo}/wwwroot deve existir. Se o caminho não existir, um provedor de arquivo não operacional será usado.
Defina 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 é opcionalmente especificada em um hostsettings.json arquivo. Qualquer configuração carregada do hostsettings.json arquivo pode ser substituída por argumentos de linha de comando. A configuração interna (no config) é usada para configurar o host com UseConfiguration. IWebHostBuilder A configuração é adicionada à configuração do aplicativo, mas o inverso não é verdadeiro,ConfigureAppConfiguration não afeta a IWebHostBuilder configuração.

Substituindo a configuração fornecida por UseUrls com hostsettings.json configuração primeiro, configuração de argumento de linha de comando segundo:

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, a configuração reloadOnChange: true para JSarquivos de configurações ON, INI e XML não tem 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 urls valor do hostsettings.json arquivo 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 saída do console e com WaitForShutdown a espera de 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 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();
}

Faça uma solicitação no navegador para http://localhost:5000 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.

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 IWebHostEnvironment interface fornece informações sobre o ambiente de hospedagem da 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 sempre validar escopos, inclusive no ambiente de produção, configure o ServiceProviderOptions com UseDefaultServiceProvider no construtor de host:

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

Recursos adicionais

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

Nos modelos de projeto, Main está localizado em Program.cs. Um aplicativo típico chama CreateDefaultBuilder para começar a configurar 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:

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

  • ConfigureAppConfiguration é usado para especificar adicionais IConfiguration para o aplicativo. A chamada a seguir ConfigureAppConfiguration adiciona um delegado para incluir a configuração do aplicativo no appsettings.xml arquivo . 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 a seguir ConfigureLogging adiciona um delegado para configurar o nível mínimo de log (SetMinimumLevel) para LogLevel.Warning. Essa configuração substitui as configurações em appsettings.Development.json (LogLevel.Debug) e appsettings.Production.json (LogLevel.Error) definidas 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 Kestrel foi configurado por 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 alternativa ao uso do método estáticoCreateDefaultBuilder, criar um host do WebHostBuilder é uma abordagem com suporte com ASP.NET Core 2.x.

Ao configurar um host, Configure os métodos 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

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 (consulte a seção Substituir configuraçã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 IWebHostEnvironment.ApplicationName propriedade é definida automaticamente quando UseStartup ou Configure é chamada 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: cadeia de caracteres
Padrão: o nome do assembly que contém o ponto de entrada do aplicativo.
Defina 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 trás do IIS, em que o padrão é true.
Defina 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 ASP.NET Core começa a pesquisar arquivos de conteúdo.

Chave: contentRoot
Tipo: cadeia de caracteres
Padrão: o padrão é a pasta em que o assembly do aplicativo reside.
Defina 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: false
Defina 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: cadeia de caracteres
Padrão: Production
Defina 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 launchSettings.json arquivo . 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: cadeia de caracteres
Padrão: cadeia de caracteres vazia
Defina 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 de redirecionamento HTTPS. Uso em aplicação de HTTPS.

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

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.

Chave: hostingStartupExcludeAssemblies
Tipo: cadeia de caracteres
Padrão: cadeia de caracteres vazia
Defina 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: true
Defina usando: PreferHostingUrls
Variável de ambiente: ASPNETCORE_PREFERHOSTINGURLS

WebHost.CreateDefaultBuilder(args)
    .PreferHostingUrls(false)

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: false
Defina 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: cadeia de caracteres
Padrão: http://localhost:5000
Defina 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")

Kestrel tem sua própria API de configuração de ponto de extremidade. Para obter mais informações, consulte Kestrel Implementação do servidor Web em 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
Defina 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:

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: cadeia de caracteres
Padrão: o assembly do aplicativo
Defina 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: cadeia de caracteres
Padrão: o padrão é wwwroot. O caminho para {content root}/wwwroot deve existir. Se o caminho não existir, um provedor de arquivo não operacional será usado.
Defina 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 é opcionalmente especificada em um hostsettings.json arquivo. Qualquer configuração carregada do hostsettings.json arquivo pode ser substituída por argumentos de linha de comando. A configuração interna (no config) é usada para configurar o host com UseConfiguration. IWebHostBuilder A configuração é adicionada à configuração do aplicativo, mas o inverso não é verdadeiro,ConfigureAppConfiguration não afeta a IWebHostBuilder configuração.

Substituindo a configuração fornecida por UseUrls com hostsettings.json configuração primeiro, configuração de argumento de linha de comando segundo:

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, a configuração reloadOnChange: true para JSarquivos de configurações ON, INI e XML não tem 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 urls valor do hostsettings.json arquivo 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 saída do console e com WaitForShutdown a espera de 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 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();
}

Faça uma solicitação no navegador para http://localhost:5000 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.

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 IWebHostEnvironment interface fornece informações sobre o ambiente de hospedagem da 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 sempre validar escopos, inclusive no ambiente de produção, configure o ServiceProviderOptions com UseDefaultServiceProvider no construtor de host:

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

Recursos adicionais