Generisk .NET-värd i ASP.NET Core

Den här artikeln innehåller information om hur du använder .NET Generic Host i ASP.NET Core.

ASP.NET Core-mallarna skapar en WebApplicationBuilder och WebApplication, som ger ett effektivt sätt att konfigurera och köra webbprogram utan en Startup-klass. Mer information om WebApplicationBuilder och WebApplicationfinns i Migrera från ASP.NET Core i .NET 5 till .NET 6.

Information om hur du använder .NET Generic Host i konsolappar finns i .NET Generic Host.

Host definition

En värd är ett objekt som kapslar in en apps resurser, till exempel:

• Beroendeinjektion (DI)
• Logging
• Configuration
• IHostedService implementeringar

När en värd startar anropas IHostedService.StartAsync för varje implementering av IHostedService som registrerats i tjänstbehållarens samling av värdtjänster. I en webbapp är en av de IHostedService implementeringarna en webbtjänst som startar en HTTP-serverimplementering.

Om du inkluderar alla appens beroende resurser i ett objekt kan du styra appstarten och den graciösa avstängningen.

Konfigurera en värd

Värden konfigureras, byggs och körs vanligtvis med kod i Program.cs. Följande kod skapar en värd med en IHostedService implementering som läggs till i DI-containern:

await Host.CreateDefaultBuilder(args)
    .ConfigureServices(services =>
    {
        services.AddHostedService<SampleHostedService>();
    })
    .Build()
    .RunAsync();

För en HTTP-arbetsbelastning anropar du ConfigureWebHostDefaults efter CreateDefaultBuilder:

await Host.CreateDefaultBuilder(args)
    .ConfigureWebHostDefaults(webBuilder =>
    {
        webBuilder.UseStartup<Startup>();
    })
    .Build()
    .RunAsync();

Standardinställningar för builder

Metoden CreateDefaultBuilder:

• Anger innehållsroten till den sökväg som returneras av GetCurrentDirectory.
• Läser in värdkonfiguration från:
  • Miljövariabler med prefixet DOTNET_.
  • Command-line arguments.
• Läser in appkonfiguration från:
  • appsettings.json.
  • appsettings.{Environment}.json.
  • Användarhemligheter när appen körs i den Development miljön.
  • Environment variables.
  • Command-line arguments.
• Lägger till följande loggning leverantörer:
  • Console
  • Debug
  • EventSource
  • EventLog (endast när du kör på Windows)
• Aktiverar omfångsverifiering och beroendeverifiering när miljön är utvecklingsmiljö.

Metoden ConfigureWebHostDefaults:

• Läser in värdkonfiguration från miljövariabler med prefixet ASPNETCORE_.
• Anger Kestrel server som webbserver och konfigurerar den med hjälp av appens värdkonfigurationsproviders. Standardalternativen för Kestrel-servern finns i Konfigurera alternativ för ASP.NET Core Kestrel-webbservern.
• Lägger till mellanprogram för värdfiltrering.
• Lägger till middleware för vidarebefordrade headers om ASPNETCORE_FORWARDEDHEADERS_ENABLED är lika med true.
• Aktiverar IIS-integrering. Standardalternativen för IIS finns i Host ASP.NET Core on Windows with IIS.

I Inställningar för alla apptyper och Inställningar för webbappar avsnitt senare i den här artikeln visas hur du åsidosätter standardinställningarna för builder.

Framework-provided services

Följande tjänster registreras automatiskt:

• IHostApplicationLifetime
• IHostLifetime
• IHostEnvironment/IWebHostEnvironment

Mer information om ramverkstjänster finns i Beroendeinmatning i ASP.NET Core.

IHostApplicationLifetime

Injicera tjänsten IHostApplicationLifetime (tidigare IApplicationLifetime) i varje klass för att hantera uppgifter efter start och graciös avstängning. Tre egenskaper i gränssnittet är annulleringstoken som används för att registrera metoder för att starta och stoppa apphändelser. Gränssnittet innehåller också en StopApplication-metod som gör att appar kan begära en korrekt avstängning.

När du utför en graciös avstängning gör värden följande:

• Utlöser ApplicationStopping händelsehanterare, vilket gör att appen kan köra logik innan avstängningsprocessen börjar.
• Stoppar servern, vilket inaktiverar nya anslutningar. Servern väntar på att begäranden om befintliga anslutningar ska slutföras, så länge tidsgränsen för avstängning tillåter. Servern skickar anslutningsstängningshuvudet för ytterligare begäranden om befintliga anslutningar.
• Utlöser ApplicationStopped händelsehanterare, vilket gör att appen kan köra logik när programmet har stängts av.

Följande exempel är en IHostedService implementering som registrerar IHostApplicationLifetime händelsehanterare:

public class HostApplicationLifetimeEventsHostedService : IHostedService
{
    private readonly IHostApplicationLifetime _hostApplicationLifetime;

    public HostApplicationLifetimeEventsHostedService(
        IHostApplicationLifetime hostApplicationLifetime)
        => _hostApplicationLifetime = hostApplicationLifetime;

    public Task StartAsync(CancellationToken cancellationToken)
    {
        _hostApplicationLifetime.ApplicationStarted.Register(OnStarted);
        _hostApplicationLifetime.ApplicationStopping.Register(OnStopping);
        _hostApplicationLifetime.ApplicationStopped.Register(OnStopped);

        return Task.CompletedTask;
    }

    public Task StopAsync(CancellationToken cancellationToken)
        => Task.CompletedTask;

    private void OnStarted()
    {
        // ...
    }

    private void OnStopping()
    {
        // ...
    }

    private void OnStopped()
    {
        // ...
    }
}

IHostLifetime

Den IHostLifetime-implementeringen styr när hosten startar och när den stoppar. Den senast registrerade implementeringen används.

Microsoft.Extensions.Hosting.Internal.ConsoleLifetime är standardimplementeringen IHostLifetime. ConsoleLifetime:

• Lyssnar efter Ctrl+C/SIGINT (Windows), Ctrl+C (macOS) eller SIGTERM och anropar StopApplication för att starta avstängningsprocessen.
• Avblockera tillägg som RunAsync och WaitForShutdownAsync.

IHostEnvironment

Mata in IHostEnvironment-tjänsten i en klass för att få information om följande inställningar:

• ApplicationName
• EnvironmentName
• ContentRootPath

Webbappar implementerar IWebHostEnvironment-gränssnittet, som ärver IHostEnvironment och lägger till WebRootPath-.

Host configuration

Värdkonfiguration används för egenskaperna hos implementeringen av IHostEnvironment.

Värdkonfigurationen är tillgänglig från HostBuilderContext.Configuration inuti ConfigureAppConfiguration. Efter ConfigureAppConfigurationersätts HostBuilderContext.Configuration med appkonfigurationen.

Om du vill lägga till värdkonfiguration anropar du ConfigureHostConfiguration på IHostBuilder. ConfigureHostConfiguration kan anropas flera gånger med additiva resultat. Värdenheten använder det alternativ som anger ett värde sist på en viss nyckel.

Miljövariabelprovidern med prefixet DOTNET_ och kommandoradsargument ingår i CreateDefaultBuilder. För webbappar läggs miljövariabelprovidern med prefixet ASPNETCORE_ till. Prefixet tas bort när miljövariablerna läses. Miljövariabelvärdet för ASPNETCORE_ENVIRONMENT blir till exempel värdkonfigurationsvärdet för den environment nyckeln.

I följande exempel skapas värdkonfiguration:

Host.CreateDefaultBuilder(args)
    .ConfigureHostConfiguration(hostConfig =>
    {
        hostConfig.SetBasePath(Directory.GetCurrentDirectory());
        hostConfig.AddJsonFile("hostsettings.json", optional: true);
        hostConfig.AddEnvironmentVariables(prefix: "PREFIX_");
        hostConfig.AddCommandLine(args);
    });

App configuration

Appkonfigurationen skapas genom att anropa ConfigureAppConfiguration på IHostBuilder. ConfigureAppConfiguration kan anropas flera gånger med additiva resultat. Appen använder det alternativ som anger ett värde sist på en viss nyckel.

Konfigurationen som skapas av ConfigureAppConfiguration är tillgänglig på HostBuilderContext.Configuration för efterföljande åtgärder och som en tjänst från DI. Värdkonfigurationen läggs också till i app-konfigurationen.

Mer information finns i Configuration i ASP.NET Core.

Inställningar för alla apptyper

I det här avsnittet visas värdinställningar som gäller för både HTTP- och icke-HTTP-arbetsbelastningar. Som standard kan miljövariabler som används för att konfigurera dessa inställningar ha ett DOTNET_- eller ASPNETCORE_ prefix, som visas i följande lista med inställningar som platshållare för {PREFIX_}. Mer information finns i avsnittet Standard builder-inställningar och Configuration: Environment variables.

ApplicationName

Egenskapen IHostEnvironment.ApplicationName anges från värdkonfigurationen under värdkonstruktionen.

nyckel: applicationName
typ: string
Standard: Namnet på den sammansättning som innehåller appens startpunkt.
Miljövariabel: {PREFIX_}APPLICATIONNAME

Använd miljövariabeln för att ange det här värdet.

ContentRoot

Egenskapen IHostEnvironment.ContentRootPath bestämmer var värddatorn börjar söka efter innehållsfiler. Om sökvägen inte finns misslyckas hosten med att starta.

nyckel: contentRoot
typ: string
Standard: Mappen där appsammansättningen finns.
Miljövariabel: {PREFIX_}CONTENTROOT

Om du vill ange det här värdet använder du miljövariabeln eller anropar UseContentRoot på IHostBuilder:

Host.CreateDefaultBuilder(args)
    .UseContentRoot("/path/to/content/root")
    // ...

Mer information finns i:

• Grunderna: Innehållsrot
• WebRoot

EnvironmentName

Egenskapen IHostEnvironment.EnvironmentName kan anges till valfritt värde. Ramverksdefinierade värden omfattar Development, Stagingoch Production. Värden är inte skiftlägeskänsliga.

nyckel: environment
typ: string
standard: Production
Miljövariabel: {PREFIX_}ENVIRONMENT

Om du vill ange det här värdet använder du miljövariabeln eller anropar UseEnvironment på IHostBuilder:

Host.CreateDefaultBuilder(args)
    .UseEnvironment("Development")
    // ...

ShutdownTimeout

HostOptions.ShutdownTimeout anger tidsgränsen för StopAsync. Standardvärdet är 30 sekunder. Under time-out-perioden:

• Utlösare IHostApplicationLifetime.ApplicationStopping.
• Försöker stoppa värdbaserade tjänster, loggningsfel för tjänster som inte kan stoppas.

Om tidsgränsen går ut innan alla värdbaserade tjänster stoppas stoppas alla återstående aktiva tjänster när appen stängs av. Tjänsterna stoppas även om de inte har slutfört bearbetningen. Om tjänster kräver mer tid för att stoppa ökar du tidsgränsen.

nyckel: shutdownTimeoutSeconds
typ: int
Standard: 30 sekunder
Miljövariabel: {PREFIX_}SHUTDOWNTIMEOUTSECONDS

Om du vill ange det här värdet använder du miljövariabeln eller konfigurerar HostOptions. I följande exempel anges tidsgränsen till 20 sekunder:

Host.CreateDefaultBuilder(args)
    .ConfigureServices((hostContext, services) =>
    {
        services.Configure<HostOptions>(options =>
        {
            options.ShutdownTimeout = TimeSpan.FromSeconds(20);
        });
    });

Inaktivera omläsning av appkonfiguration vid ändring

Som standard, laddas appsettings.json och appsettings.{Environment}.json om när filen ändras. Om du vill inaktivera det här inläsningsbeteendet i .NET 5 eller senare anger du hostBuilder:reloadConfigOnChange nyckeln till false.

nyckel: hostBuilder:reloadConfigOnChange
typ: bool (true eller false)
standard: true
kommandoradsargument: hostBuilder:reloadConfigOnChange
Miljövariabel: {PREFIX_}hostBuilder:reloadConfigOnChange

Inställningar för webbappar

Vissa värdinställningar gäller endast för HTTP-arbetsbelastningar. Som standard kan miljövariabler som används för att konfigurera dessa inställningar ha ett DOTNET_- eller ASPNETCORE_ prefix, som visas i följande lista med inställningar som platshållare för {PREFIX_}.

Förlängningsmetoder på IWebHostBuilder är tillgängliga för dessa inställningar. Kodexempel som visar hur du anropar tilläggsmetoderna förutsätter webBuilder är en instans av IWebHostBuilder, som i följande exempel:

Host.CreateDefaultBuilder(args)
    .ConfigureWebHostDefaults(webBuilder =>
    {
        // ...
    });

CaptureStartupErrors

När falseinträffar fel vid start resulterar det i att värdenheten avslutas. När truefångar upp undantag under uppstart och försöker starta servern.

nyckel: captureStartupErrors
typ: bool (true/1 eller false/0)
Standard: Standardvärdet är false förutom när appen körs med Kestrel via IIS, där standardvärdet är true.
Miljövariabel: {PREFIX_}CAPTURESTARTUPERRORS

Om du vill ange det här värdet använder du konfiguration eller anropar CaptureStartupErrors:

webBuilder.CaptureStartupErrors(true);

DetailedErrors

När den är aktiverad eller när miljön är Developmentsamlar appen in detaljerade fel.

nyckel: detailedErrors
typ: bool (true/1 eller false/0)
standard: false
Miljövariabel: {PREFIX_}DETAILEDERRORS

Om du vill ange det här värdet använder du konfiguration eller anropar UseSetting:

webBuilder.UseSetting(WebHostDefaults.DetailedErrorsKey, "true");

HostingStartupAssemblies

En semikolonavgränsad sträng som är värd för startsammansättningar för att läsa in vid start. Även om konfigurationsvärdet som standard är en tom sträng inkluderar värdstartssammansättningarna alltid appens sammansättning. När du tillhandahåller värdtjänster för startsammansättningar läggs de till i appens sammansättning för inläsning när appen skapar sina gemensamma tjänster under starten.

nyckel: hostingStartupAssemblies
typ: string
Standard: Tom sträng
Miljövariabel: {PREFIX_}HOSTINGSTARTUPASSEMBLIES

Om du vill ange det här värdet använder du konfiguration eller anropar UseSetting:

webBuilder.UseSetting(
    WebHostDefaults.HostingStartupAssembliesKey, "assembly1;assembly2");

HostingStartupExcludeAssemblies

En semikolonavgränsad sträng med uppstartssammansättningar som ska undantas vid start.

nyckel: hostingStartupExcludeAssemblies
typ: string
Standard: Tom sträng
Miljövariabel: {PREFIX_}HOSTINGSTARTUPEXCLUDEASSEMBLIES

Om du vill ange det här värdet använder du konfiguration eller anropar UseSetting:

webBuilder.UseSetting(
    WebHostDefaults.HostingStartupExcludeAssembliesKey, "assembly1;assembly2");

HTTPS_Port

Ange HTTPS-porten som omdirigering till om du får en icke-HTTPS-anslutning. Används i att upprätthålla HTTPS. Den här inställningen gör inte att servern lyssnar på den angivna porten. Det är alltså möjligt att oavsiktligt omdirigera begäranden till en oanvänd port.

Nyckel: https_portTyp: string
Standard: Ett standardvärde har inte angetts.
Miljövariabel: {PREFIX_}HTTPS_PORT

Om du vill ange det här värdet använder du konfiguration eller anropar UseSetting:

webBuilder.UseSetting("https_port", "8080");

HTTPS_Ports

Portarna som ska lyssnas på för HTTPS-anslutningar.

nyckel: https_ports
typ: string
Standard: Ett standardvärde har inte angetts.
Miljövariabel: {PREFIX_}HTTPS_PORTS

Om du vill ange det här värdet använder du konfiguration eller anropar UseSetting:

webBuilder.UseSetting("https_ports", "8080");

PreferHostingUrls

Anger om värden ska lyssna på url:erna som konfigurerats med IWebHostBuilder i stället för de URL:er som konfigurerats med IServer implementeringen.

nyckel: preferHostingUrls
typ: bool (true/1 eller false/0)
standard: false
Miljövariabel: {PREFIX_}PREFERHOSTINGURLS

Om du vill ange det här värdet använder du miljövariabeln eller anropar PreferHostingUrls:

webBuilder.PreferHostingUrls(true);

PreventHostingStartup

Förhindrar automatisk läsning av värdstartssamlingar, inklusive sådana som konfigurerats av appens samling. För mer information, se Användning av värdstartssammansättningar i ASP.NET Core.

nyckel: preventHostingStartup
typ: bool (true/1 eller false/0)
standard: false
Miljövariabel: {PREFIX_}PREVENTHOSTINGSTARTUP

Om du vill ange det här värdet använder du miljövariabeln eller anropar UseSetting :

webBuilder.UseSetting(WebHostDefaults.PreventHostingStartupKey, "true");

StartupAssembly

Sammansättningen för att söka efter klassen Startup.

nyckel: startupAssembly
typ: string
Standard: Appens sammansättning
Miljövariabel: {PREFIX_}STARTUPASSEMBLY

Om du vill ange det här värdet använder du miljövariabeln eller anropar UseStartup. UseStartup kan ta ett sammansättningsnamn (string) eller en typ (TStartup). Om flera UseStartup metoder anropas har den sista företräde.

webBuilder.UseStartup("StartupAssemblyName");

webBuilder.UseStartup<Startup>();

SuppressStatusMessages

När det är aktiverat, undertrycker det startstatusmeddelanden.

nyckel: suppressStatusMessages
typ: bool (true/1 eller false/0)
standard: false
Miljövariabel: {PREFIX_}SUPPRESSSTATUSMESSAGES

Om du vill ange det här värdet använder du konfiguration eller anropar UseSetting:

webBuilder.UseSetting(WebHostDefaults.SuppressStatusMessagesKey, "true");

URLs

En semikolonavgränsad lista över IP-adresser eller värdadresser med portar och protokoll som servern ska lyssna på efter begäranden. Till exempel http://localhost:123. Använd "*" för att ange att servern ska lyssna efter begäranden på alla IP-adresser eller värdnamn med den angivna porten och protokollet (till exempel http://*:5000). Protokollet (http:// eller https://) måste ingå i varje URL. Format som stöds varierar mellan servrar.

nyckel: urls
typ: string
Standard: http://localhost:5000 och https://localhost:5001
Miljövariabel: {PREFIX_}URLS

Om du vill ange det här värdet använder du miljövariabeln eller anropar UseUrls:

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

Kestrel har ett eget API för slutpunktskonfiguration. Mer information finns i Konfigurera slutpunkter för ASP.NET Core Kestrel-webbservern.

WebRoot

Egenskapen IWebHostEnvironment.WebRootPath avgör den relativa sökvägen till appens statiska tillgångar. Om sökvägen inte finns används en no-op filprovider.

nyckel: webroot
typ: string
standard: Standardvärdet är wwwroot. Sökvägen till {content root}/wwwroot måste finnas.
Miljövariabel: {PREFIX_}WEBROOT

Om du vill ange det här värdet använder du miljövariabeln eller anropar UseWebRoot på IWebHostBuilder:

webBuilder.UseWebRoot("public");

Mer information finns i:

• grunderna: Webbroten
• ContentRoot

Hantera värdlivslängden

Anropa metoder för den inbyggda IHost-implementeringen för att starta och stoppa appen. Dessa metoder påverkar alla IHostedService implementeringar som är registrerade i tjänstcontainern.

Skillnaden mellan Run* och Start* metoderna är att Run* metoderna väntar tills värden har slutfört innan de returnerar, medan Start* metoderna returnerar omedelbart. De Run* metoderna används vanligtvis i konsolappar, medan de Start* metoderna vanligtvis används i långvariga tjänster.

Run

Run kör appen och blockerar den anropande tråden tills värdssystemet stängs ned.

RunAsync

RunAsync kör appen och returnerar en Task som slutförs när annulleringstoken eller avstängningen utlöses.

RunConsoleAsync

RunConsoleAsync aktiverar konsolstöd, skapar och startar värden och väntar på att Ctrl+C/SIGINT (Windows), Ctrl+C (macOS) eller SIGTERM stängs av.

Start

Start startar värdtjänsten synkront.

StartAsync

StartAsync startar värddatorn och returnerar en Task som slutförs när en avbrytningstoken eller avstängning aktiveras.

WaitForStartAsync anropas i början av StartAsync, vilket väntar tills detta är klart innan programmet fortsätter. Den här metoden kan användas för att fördröja starten tills den signaleras av en extern händelse.

StopAsync

StopAsync försöker stoppa värddatorn inom den angivna tidsgränsen.

WaitForShutdown

WaitForShutdown blockerar den anropande tråden tills avstängningen utlöses av IHostLifetime, till exempel via Ctrl+C/SIGINT (Windows), Ctrl+C (macOS) eller SIGTERM.

WaitForShutdownAsync

WaitForShutdownAsync returnerar en Task som slutförs när avstängningen utlöses via den angivna token och anropar StopAsync.

Mallarna ASP.NET Core skapar en .NET Generic Host (HostBuilder).

Den här artikeln innehåller information om hur du använder .NET Generic Host i ASP.NET Core. Information om hur du använder .NET Generic Host i konsolappar finns i .NET Generic Host.

Host definition

En värd är ett objekt som kapslar in en apps resurser, till exempel:

• Beroendeinjektion (DI)
• Logging
• Configuration
• IHostedService implementeringar

När en värd startar anropas IHostedService.StartAsync för varje implementering av IHostedService som registrerats i tjänstbehållarens samling av värdtjänster. I en webbapp är en av de IHostedService implementeringarna en webbtjänst som startar en HTTP-serverimplementering.

Den främsta orsaken till att inkludera alla appens beroende resurser i ett objekt är livslängdshantering: kontroll över appstart och graciös avstängning.

Konfigurera en värd

Värden konfigureras, skapas och körs vanligtvis av kod i klassen Program. Metoden Main:

• Anropar en CreateHostBuilder metod för att skapa och konfigurera ett builder-objekt.
• Anropar Build- och Run-metoder på builder-objektet.

Webbmallarna ASP.NET Core genererar följande kod för att skapa en värd:

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

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
}

Följande kod skapar en icke-HTTP-arbetsbelastning med en IHostedService implementering som läggs till i DI-containern.

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

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureServices((hostContext, services) =>
            {
               services.AddHostedService<Worker>();
            });
}

För en HTTP-arbetsbelastning är metoden Main samma men CreateHostBuilder anropar ConfigureWebHostDefaults:

public static IHostBuilder CreateHostBuilder(string[] args) =>
    Host.CreateDefaultBuilder(args)
        .ConfigureWebHostDefaults(webBuilder =>
        {
            webBuilder.UseStartup<Startup>();
        });

Om appen använder Entity Framework Core ändrar du inte namnet eller signaturen för metoden CreateHostBuilder. Verktygen Entity Framework Core förväntar sig att hitta en CreateHostBuilder metod som konfigurerar värden utan att köra appen. Mer information finns i Design-time DbContext Creation.

Standardinställningar för builder

Metoden CreateDefaultBuilder:

• Anger innehållsroten till den sökväg som returneras av GetCurrentDirectory.
• Läser in värdkonfiguration från:
  • Miljövariabler med prefixet DOTNET_.
  • Command-line arguments.
• Läser in appkonfiguration från:
  • appsettings.json.
  • appsettings.{Environment}.json.
  • Användarhemligheter när appen körs i den Development miljön.
  • Environment variables.
  • Command-line arguments.
• Lägger till följande loggning leverantörer:
  • Console
  • Debug
  • EventSource
  • EventLog (endast när du kör på Windows)
• Aktiverar omfångsverifiering och beroendeverifiering när miljön är utvecklingsmiljö.

Metoden ConfigureWebHostDefaults:

• Läser in värdkonfiguration från miljövariabler med prefixet ASPNETCORE_.
• Anger Kestrel server som webbserver och konfigurerar den med hjälp av appens värdkonfigurationsproviders. Standardalternativen för Kestrel-servern finns i Konfigurera alternativ för ASP.NET Core Kestrel-webbservern.
• Lägger till mellanprogram för värdfiltrering.
• Lägger till middleware för vidarebefordrade headers om ASPNETCORE_FORWARDEDHEADERS_ENABLED är lika med true.
• Aktiverar IIS-integrering. Standardalternativen för IIS finns i Host ASP.NET Core on Windows with IIS.

I Inställningar för alla apptyper och Inställningar för webbappar avsnitt senare i den här artikeln visas hur du åsidosätter standardinställningarna för builder.

Framework-provided services

Följande tjänster registreras automatiskt:

• IHostApplicationLifetime
• IHostLifetime
• IHostEnvironment/IWebHostEnvironment

Mer information om ramverkstjänster finns i Beroendeinmatning i ASP.NET Core.

IHostApplicationLifetime

Injicera tjänsten IHostApplicationLifetime (tidigare IApplicationLifetime) i varje klass för att hantera uppgifter efter start och graciös avstängning. Tre egenskaper i gränssnittet är annulleringstoken som används för att registrera metoder för att starta och stoppa apphändelser. Gränssnittet innehåller även en StopApplication-metod.

Följande exempel är en IHostedService implementering som registrerar IHostApplicationLifetime händelser:

internal class LifetimeEventsHostedService : IHostedService
{
    private readonly ILogger _logger;
    private readonly IHostApplicationLifetime _appLifetime;

    public LifetimeEventsHostedService(
        ILogger<LifetimeEventsHostedService> logger, 
        IHostApplicationLifetime appLifetime)
    {
        _logger = logger;
        _appLifetime = appLifetime;
    }

    public Task StartAsync(CancellationToken cancellationToken)
    {
        _appLifetime.ApplicationStarted.Register(OnStarted);
        _appLifetime.ApplicationStopping.Register(OnStopping);
        _appLifetime.ApplicationStopped.Register(OnStopped);

        return Task.CompletedTask;
    }

    public Task StopAsync(CancellationToken cancellationToken)
    {
        return Task.CompletedTask;
    }

    private void OnStarted()
    {
        _logger.LogInformation("OnStarted has been called.");

        // Perform post-startup activities here
    }

    private void OnStopping()
    {
        _logger.LogInformation("OnStopping has been called.");

        // Perform on-stopping activities here
    }

    private void OnStopped()
    {
        _logger.LogInformation("OnStopped has been called.");

        // Perform post-stopped activities here
    }
}

IHostLifetime

Den IHostLifetime-implementeringen styr när hosten startar och när den stoppar. Den senast registrerade implementeringen används.

Microsoft.Extensions.Hosting.Internal.ConsoleLifetime är standardimplementeringen IHostLifetime. ConsoleLifetime:

• Lyssnar efter Ctrl+C/SIGINT (Windows), Ctrl+C (macOS) eller SIGTERM och anropar StopApplication för att starta avstängningsprocessen.
• Avblockera tillägg som RunAsync och WaitForShutdownAsync.

IHostEnvironment

Mata in IHostEnvironment-tjänsten i en klass för att få information om följande inställningar:

• ApplicationName
• EnvironmentName
• ContentRootPath

Webbappar implementerar IWebHostEnvironment-gränssnittet, som ärver IHostEnvironment och lägger till WebRootPath-.

Host configuration

Värdkonfiguration används för egenskaperna hos implementeringen av IHostEnvironment.

Värdkonfigurationen är tillgänglig från HostBuilderContext.Configuration inuti ConfigureAppConfiguration. Efter ConfigureAppConfigurationersätts HostBuilderContext.Configuration med appkonfigurationen.

Om du vill lägga till värdkonfiguration anropar du ConfigureHostConfiguration på IHostBuilder. ConfigureHostConfiguration kan anropas flera gånger med additiva resultat. Värdenheten använder det alternativ som anger ett värde sist på en viss nyckel.

Miljövariabelprovidern med prefixet DOTNET_ och kommandoradsargument ingår i CreateDefaultBuilder. För webbappar läggs miljövariabelprovidern med prefixet ASPNETCORE_ till. Prefixet tas bort när miljövariablerna läses. Miljövariabelvärdet för ASPNETCORE_ENVIRONMENT blir till exempel värdkonfigurationsvärdet för den environment nyckeln.

I följande exempel skapas värdkonfiguration:

// using Microsoft.Extensions.Configuration;

Host.CreateDefaultBuilder(args)
    .ConfigureHostConfiguration(configHost =>
    {
        configHost.SetBasePath(Directory.GetCurrentDirectory());
        configHost.AddJsonFile("hostsettings.json", optional: true);
        configHost.AddEnvironmentVariables(prefix: "PREFIX_");
        configHost.AddCommandLine(args);
    });

App configuration

Appkonfigurationen skapas genom att anropa ConfigureAppConfiguration på IHostBuilder. ConfigureAppConfiguration kan anropas flera gånger med additiva resultat. Appen använder det alternativ som anger ett värde sist på en viss nyckel.

Konfigurationen som skapas av ConfigureAppConfiguration är tillgänglig på HostBuilderContext.Configuration för efterföljande åtgärder och som en tjänst från DI. Värdkonfigurationen läggs också till i app-konfigurationen.

Mer information finns i Configuration i ASP.NET Core.

Inställningar för alla apptyper

I det här avsnittet visas värdinställningar som gäller för både HTTP- och icke-HTTP-arbetsbelastningar. Som standard kan miljövariabler som används för att konfigurera dessa inställningar ha ett DOTNET_- eller ASPNETCORE_ prefix, som visas i följande lista med inställningar som platshållare för {PREFIX_}. Mer information finns i avsnittet Standard builder-inställningar och Configuration: Environment variables.

ApplicationName

Egenskapen IHostEnvironment.ApplicationName anges från värdkonfigurationen under värdkonstruktionen.

nyckel: applicationName
typ: string
Standard: Namnet på den sammansättning som innehåller appens startpunkt.
Miljövariabel: {PREFIX_}APPLICATIONNAME

Använd miljövariabeln för att ange det här värdet.

ContentRoot

Egenskapen IHostEnvironment.ContentRootPath bestämmer var värddatorn börjar söka efter innehållsfiler. Om sökvägen inte finns misslyckas hosten med att starta.

nyckel: contentRoot
typ: string
Standard: Mappen där appsammansättningen finns.
Miljövariabel: {PREFIX_}CONTENTROOT

Om du vill ange det här värdet använder du miljövariabeln eller anropar UseContentRoot på IHostBuilder:

Host.CreateDefaultBuilder(args)
    .UseContentRoot("c:\\content-root")
    //...

Mer information finns i:

• Grunderna: Innehållsrot
• WebRoot

EnvironmentName

Egenskapen IHostEnvironment.EnvironmentName kan anges till valfritt värde. Ramverksdefinierade värden omfattar Development, Stagingoch Production. Värden är inte skiftlägeskänsliga.

nyckel: environment
typ: string
standard: Production
Miljövariabel: {PREFIX_}ENVIRONMENT

Om du vill ange det här värdet använder du miljövariabeln eller anropar UseEnvironment på IHostBuilder:

Host.CreateDefaultBuilder(args)
    .UseEnvironment("Development")
    //...

ShutdownTimeout

HostOptions.ShutdownTimeout anger tidsgränsen för StopAsync. Standardvärdet är fem sekunder. Under time-out-perioden:

• Utlösare IHostApplicationLifetime.ApplicationStopping.
• Försöker stoppa värdbaserade tjänster, loggningsfel för tjänster som inte kan stoppas.

Om tidsgränsen går ut innan alla värdbaserade tjänster stoppas stoppas alla återstående aktiva tjänster när appen stängs av. Tjänsterna stoppas även om de inte har slutfört bearbetningen. Om tjänster kräver mer tid för att stoppa ökar du tidsgränsen.

nyckel: shutdownTimeoutSeconds
typ: int
Standard: 5 sekunder
Miljövariabel: {PREFIX_}SHUTDOWNTIMEOUTSECONDS

Om du vill ange det här värdet använder du miljövariabeln eller konfigurerar HostOptions. I följande exempel anges tidsgränsen till 20 sekunder:

Host.CreateDefaultBuilder(args)
    .ConfigureServices((hostContext, services) =>
    {
        services.Configure<HostOptions>(option =>
        {
            option.ShutdownTimeout = System.TimeSpan.FromSeconds(20);
        });
    });

Inaktivera omläsning av appkonfiguration vid ändring

Som standard, laddas appsettings.json och appsettings.{Environment}.json om när filen ändras. Om du vill inaktivera det här inläsningsbeteendet i .NET 5 eller senare anger du hostBuilder:reloadConfigOnChange nyckeln till false.

nyckel: hostBuilder:reloadConfigOnChange
typ: bool (true eller false)
standard: true
kommandoradsargument: hostBuilder:reloadConfigOnChange
Miljövariabel: {PREFIX_}hostBuilder:reloadConfigOnChange

Inställningar för webbappar

Vissa värdinställningar gäller endast för HTTP-arbetsbelastningar. Som standard kan miljövariabler som används för att konfigurera dessa inställningar ha ett DOTNET_- eller ASPNETCORE_ prefix, som visas i följande lista med inställningar som platshållare för {PREFIX_}.

Förlängningsmetoder på IWebHostBuilder är tillgängliga för dessa inställningar. Kodexempel som visar hur du anropar tilläggsmetoderna förutsätter webBuilder är en instans av IWebHostBuilder, som i följande exempel:

public static IHostBuilder CreateHostBuilder(string[] args) =>
    Host.CreateDefaultBuilder(args)
        .ConfigureWebHostDefaults(webBuilder =>
        {
            webBuilder.CaptureStartupErrors(true);
            webBuilder.UseStartup<Startup>();
        });

CaptureStartupErrors

När falseinträffar fel vid start resulterar det i att värdenheten avslutas. När truefångar upp undantag under uppstart och försöker starta servern.

nyckel: captureStartupErrors
typ: bool (true/1 eller false/0)
Standard: Standardvärdet är false förutom när appen körs med Kestrel via IIS, där standardvärdet är true.
Miljövariabel: {PREFIX_}CAPTURESTARTUPERRORS

Om du vill ange det här värdet använder du konfiguration eller anropar CaptureStartupErrors:

webBuilder.CaptureStartupErrors(true);

DetailedErrors

När den är aktiverad eller när miljön är Developmentsamlar appen in detaljerade fel.

nyckel: detailedErrors
typ: bool (true/1 eller false/0)
standard: false
Miljövariabel: {PREFIX_}DETAILEDERRORS

Om du vill ange det här värdet använder du konfiguration eller anropar UseSetting:

webBuilder.UseSetting(WebHostDefaults.DetailedErrorsKey, "true");

HostingStartupAssemblies

En semikolonavgränsad sträng som är värd för startsammansättningar för att läsa in vid start. Även om konfigurationsvärdet som standard är en tom sträng inkluderar värdstartssammansättningarna alltid appens sammansättning. När du tillhandahåller värdtjänster för startsammansättningar läggs de till i appens sammansättning för inläsning när appen skapar sina gemensamma tjänster under starten.

nyckel: hostingStartupAssemblies
typ: string
Standard: Tom sträng
Miljövariabel: {PREFIX_}HOSTINGSTARTUPASSEMBLIES

Om du vill ange det här värdet använder du konfiguration eller anropar UseSetting:

webBuilder.UseSetting(WebHostDefaults.HostingStartupAssembliesKey, "assembly1;assembly2");

HostingStartupExcludeAssemblies

En semikolonavgränsad sträng med uppstartssammansättningar som ska undantas vid start.

nyckel: hostingStartupExcludeAssemblies
typ: string
Standard: Tom sträng
Miljövariabel: {PREFIX_}HOSTINGSTARTUPEXCLUDEASSEMBLIES

Om du vill ange det här värdet använder du konfiguration eller anropar UseSetting:

webBuilder.UseSetting(WebHostDefaults.HostingStartupExcludeAssembliesKey, "assembly1;assembly2");

HTTPS_Port

HTTPS-omdirigeringsporten. Används i att upprätthålla HTTPS.

nyckel: https_port
typ: string
Standard: Ett standardvärde har inte angetts.
Miljövariabel: {PREFIX_}HTTPS_PORT

Om du vill ange det här värdet använder du konfiguration eller anropar UseSetting:

webBuilder.UseSetting("https_port", "8080");

PreferHostingUrls

Anger om värden ska lyssna på url:erna som konfigurerats med IWebHostBuilder i stället för de URL:er som konfigurerats med IServer implementeringen.

nyckel: preferHostingUrls
typ: bool (true/1 eller false/0)
standard: false
Miljövariabel: {PREFIX_}PREFERHOSTINGURLS

Om du vill ange det här värdet använder du miljövariabeln eller anropar PreferHostingUrls:

webBuilder.PreferHostingUrls(true);

PreventHostingStartup

Förhindrar automatisk läsning av värdstartssamlingar, inklusive sådana som konfigurerats av appens samling. För mer information, se Användning av värdstartssammansättningar i ASP.NET Core.

nyckel: preventHostingStartup
typ: bool (true/1 eller false/0)
standard: false
Miljövariabel: {PREFIX_}PREVENTHOSTINGSTARTUP

Om du vill ange det här värdet använder du miljövariabeln eller anropar UseSetting :

webBuilder.UseSetting(WebHostDefaults.PreventHostingStartupKey, "true");

StartupAssembly

Sammansättningen för att söka efter klassen Startup.

nyckel: startupAssembly
typ: string
Standard: Appens sammansättning
Miljövariabel: {PREFIX_}STARTUPASSEMBLY

Om du vill ange det här värdet använder du miljövariabeln eller anropar UseStartup. UseStartup kan ta ett sammansättningsnamn (string) eller en typ (TStartup). Om flera UseStartup metoder anropas har den sista företräde.

webBuilder.UseStartup("StartupAssemblyName");

webBuilder.UseStartup<Startup>();

SuppressStatusMessages

När det är aktiverat, undertrycker det startstatusmeddelanden.

nyckel: suppressStatusMessages
typ: bool (true/1 eller false/0)
standard: false
Miljövariabel: {PREFIX_}SUPPRESSSTATUSMESSAGES

Om du vill ange det här värdet använder du konfiguration eller anropar UseSetting:

webBuilder.UseSetting(WebHostDefaults.SuppressStatusMessagesKey, "true");

URLs

En semikolonavgränsad lista över IP-adresser eller värdadresser med portar och protokoll som servern ska lyssna på efter begäranden. Till exempel http://localhost:123. Använd "*" för att ange att servern ska lyssna efter begäranden på alla IP-adresser eller värdnamn med den angivna porten och protokollet (till exempel http://*:5000). Protokollet (http:// eller https://) måste ingå i varje URL. Format som stöds varierar mellan servrar.

nyckel: urls
typ: string
Standard: http://localhost:5000 och https://localhost:5001
Miljövariabel: {PREFIX_}URLS

Om du vill ange det här värdet använder du miljövariabeln eller anropar UseUrls:

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

Kestrel har ett eget API för slutpunktskonfiguration. Mer information finns i Konfigurera slutpunkter för ASP.NET Core Kestrel-webbservern.

WebRoot

Egenskapen IWebHostEnvironment.WebRootPath avgör den relativa sökvägen till appens statiska tillgångar. Om sökvägen inte finns används en no-op filprovider.

nyckel: webroot
typ: string
standard: Standardvärdet är wwwroot. Sökvägen till {content root}/wwwroot måste finnas.
Miljövariabel: {PREFIX_}WEBROOT

Om du vill ange det här värdet använder du miljövariabeln eller anropar UseWebRoot på IWebHostBuilder:

webBuilder.UseWebRoot("public");

Mer information finns i:

• grunderna: Webbroten
• ContentRoot

Hantera värdlivslängden

Anropa metoder för den inbyggda IHost-implementeringen för att starta och stoppa appen. Dessa metoder påverkar alla IHostedService implementeringar som är registrerade i tjänstcontainern.

Skillnaden mellan Run* och Start* metoderna är att Run* metoderna väntar tills värden har slutfört innan de returnerar, medan Start* metoderna returnerar omedelbart. De Run* metoderna används vanligtvis i konsolappar, medan de Start* metoderna vanligtvis används i långvariga tjänster.

Run

Run kör appen och blockerar den anropande tråden tills värdssystemet stängs ned.

RunAsync

RunAsync kör appen och returnerar en Task som slutförs när annulleringstoken eller avstängningen utlöses.

RunConsoleAsync

RunConsoleAsync aktiverar konsolstöd, skapar och startar värden och väntar på att Ctrl+C/SIGINT (Windows), Ctrl+C (macOS) eller SIGTERM stängs av.

Start

Start startar värdtjänsten synkront.

StartAsync

StartAsync startar värddatorn och returnerar en Task som slutförs när en avbrytningstoken eller avstängning aktiveras.

WaitForStartAsync anropas i början av StartAsync, vilket väntar tills detta är klart innan programmet fortsätter. Den här metoden kan användas för att fördröja starten tills den signaleras av en extern händelse.

StopAsync

StopAsync försöker stoppa värddatorn inom den angivna tidsgränsen.

WaitForShutdown

WaitForShutdown blockerar den anropande tråden tills avstängningen utlöses av IHostLifetime, till exempel via Ctrl+C/SIGINT (Windows), Ctrl+C (macOS) eller SIGTERM.

WaitForShutdownAsync

WaitForShutdownAsync returnerar en Task som slutförs när avstängningen utlöses via den angivna token och anropar StopAsync.

External control

Direkt kontroll över värdlivslängden kan uppnås med metoder som kan anropas externt:

public class Program
{
    private IHost _host;

    public Program()
    {
        _host = new HostBuilder()
            .Build();
    }

    public async Task StartAsync()
    {
        _host.StartAsync();
    }

    public async Task StopAsync()
    {
        using (_host)
        {
            await _host.StopAsync(TimeSpan.FromSeconds(5));
        }
    }
}

Mallarna ASP.NET Core skapar en .NET Generic Host (HostBuilder).

Den här artikeln innehåller information om hur du använder .NET Generic Host i ASP.NET Core. Information om hur du använder .NET Generic Host i konsolappar finns i .NET Generic Host.

Host definition

En värd är ett objekt som kapslar in en apps resurser, till exempel:

• Beroendeinjektion (DI)
• Logging
• Configuration
• IHostedService implementeringar

När en värd startar anropas IHostedService.StartAsync för varje implementering av IHostedService som registrerats i tjänstbehållarens samling av värdtjänster. I en webbapp är en av de IHostedService implementeringarna en webbtjänst som startar en HTTP-serverimplementering.

Den främsta orsaken till att inkludera alla appens beroende resurser i ett objekt är livslängdshantering: kontroll över appstart och graciös avstängning.

Konfigurera en värd

Värden konfigureras, skapas och körs vanligtvis av kod i klassen Program. Metoden Main:

• Anropar en CreateHostBuilder metod för att skapa och konfigurera ett builder-objekt.
• Anropar Build- och Run-metoder på builder-objektet.

Webbmallarna ASP.NET Core genererar följande kod för att skapa en allmän värd:

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

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
}

Följande kod skapar en allmän värd med hjälp av en icke-HTTP-arbetsbelastning. Implementeringen IHostedService läggs till i DI-containern:

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

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureServices((hostContext, services) =>
            {
               services.AddHostedService<Worker>();
            });
}

För en HTTP-arbetsbelastning är metoden Main samma men CreateHostBuilder anropar ConfigureWebHostDefaults:

public static IHostBuilder CreateHostBuilder(string[] args) =>
    Host.CreateDefaultBuilder(args)
        .ConfigureWebHostDefaults(webBuilder =>
        {
            webBuilder.UseStartup<Startup>();
        });

Föregående kod genereras av ASP.NET Core-mallar.

Om appen använder Entity Framework Core ändrar du inte namnet eller signaturen för metoden CreateHostBuilder. Verktygen Entity Framework Core förväntar sig att hitta en CreateHostBuilder metod som konfigurerar värden utan att köra appen. Mer information finns i Design-time DbContext Creation.

Standardinställningar för builder

Metoden CreateDefaultBuilder:

• Anger innehållsroten till den sökväg som returneras av GetCurrentDirectory.
• Läser in värdkonfiguration från:
  • Miljövariabler med prefixet DOTNET_.
  • Command-line arguments.
• Läser in appkonfiguration från:
  • appsettings.json.
  • appsettings.{Environment}.json.
  • Användarhemligheter när appen körs i den Development miljön.
  • Environment variables.
  • Command-line arguments.
• Lägger till följande loggning leverantörer:
  • Console
  • Debug
  • EventSource
  • EventLog (endast när du kör på Windows)
• Aktiverar omfångsverifiering och beroendeverifiering när miljön är utvecklingsmiljö.

Metoden ConfigureWebHostDefaults:

• Läser in värdkonfiguration från miljövariabler med prefixet ASPNETCORE_.
• Anger Kestrel server som webbserver och konfigurerar den med hjälp av appens värdkonfigurationsproviders. Standardalternativen för Kestrel-servern finns i Kestrel webbserver i ASP.NET Core.
• Lägger till mellanprogram för värdfiltrering.
• Lägger till middleware för vidarebefordrade headers om ASPNETCORE_FORWARDEDHEADERS_ENABLED är lika med true.
• Aktiverar IIS-integrering. Standardalternativen för IIS finns i Host ASP.NET Core on Windows with IIS.

I Inställningar för alla apptyper och Inställningar för webbappar avsnitt senare i den här artikeln visas hur du åsidosätter standardinställningarna för builder.

Framework-provided services

Följande tjänster registreras automatiskt:

• IHostApplicationLifetime
• IHostLifetime
• IHostEnvironment/IWebHostEnvironment

Mer information om ramverkstjänster finns i Beroendeinmatning i ASP.NET Core.

IHostApplicationLifetime

Injicera tjänsten IHostApplicationLifetime (tidigare IApplicationLifetime) i varje klass för att hantera uppgifter efter start och graciös avstängning. Tre egenskaper i gränssnittet är annulleringstoken som används för att registrera metoder för att starta och stoppa apphändelser. Gränssnittet innehåller även en StopApplication-metod.

Följande exempel är en IHostedService implementering som registrerar IHostApplicationLifetime händelser:

internal class LifetimeEventsHostedService : IHostedService
{
    private readonly ILogger _logger;
    private readonly IHostApplicationLifetime _appLifetime;

    public LifetimeEventsHostedService(
        ILogger<LifetimeEventsHostedService> logger, 
        IHostApplicationLifetime appLifetime)
    {
        _logger = logger;
        _appLifetime = appLifetime;
    }

    public Task StartAsync(CancellationToken cancellationToken)
    {
        _appLifetime.ApplicationStarted.Register(OnStarted);
        _appLifetime.ApplicationStopping.Register(OnStopping);
        _appLifetime.ApplicationStopped.Register(OnStopped);

        return Task.CompletedTask;
    }

    public Task StopAsync(CancellationToken cancellationToken)
    {
        return Task.CompletedTask;
    }

    private void OnStarted()
    {
        _logger.LogInformation("OnStarted has been called.");

        // Perform post-startup activities here
    }

    private void OnStopping()
    {
        _logger.LogInformation("OnStopping has been called.");

        // Perform on-stopping activities here
    }

    private void OnStopped()
    {
        _logger.LogInformation("OnStopped has been called.");

        // Perform post-stopped activities here
    }
}

IHostLifetime

Den IHostLifetime-implementeringen styr när hosten startar och när den stoppar. Den senast registrerade implementeringen används.

Microsoft.Extensions.Hosting.Internal.ConsoleLifetime är standardimplementeringen IHostLifetime. ConsoleLifetime:

• Lyssnar efter Ctrl+C/SIGINT (Windows), Ctrl+C (macOS) eller SIGTERM och anropar StopApplication för att starta avstängningsprocessen.
• Avblockera tillägg som RunAsync och WaitForShutdownAsync.

IHostEnvironment

Mata in IHostEnvironment-tjänsten i en klass för att få information om följande inställningar:

• ApplicationName
• EnvironmentName
• ContentRootPath

Webbappar implementerar IWebHostEnvironment-gränssnittet, som ärver IHostEnvironment och lägger till WebRootPath-.

Host configuration

Värdkonfiguration används för egenskaperna hos implementeringen av IHostEnvironment.

Värdkonfigurationen är tillgänglig från HostBuilderContext.Configuration inuti ConfigureAppConfiguration. Efter ConfigureAppConfigurationersätts HostBuilderContext.Configuration med appkonfigurationen.

Om du vill lägga till värdkonfiguration anropar du ConfigureHostConfiguration på IHostBuilder. ConfigureHostConfiguration kan anropas flera gånger med additiva resultat. Värdenheten använder det alternativ som anger ett värde sist på en viss nyckel.

Miljövariabelprovidern med prefixet DOTNET_ och kommandoradsargument ingår i CreateDefaultBuilder. För webbappar läggs miljövariabelprovidern med prefixet ASPNETCORE_ till. Prefixet tas bort när miljövariablerna läses. Miljövariabelvärdet för ASPNETCORE_ENVIRONMENT blir till exempel värdkonfigurationsvärdet för den environment nyckeln.

I följande exempel skapas värdkonfiguration:

// using Microsoft.Extensions.Configuration;

Host.CreateDefaultBuilder(args)
    .ConfigureHostConfiguration(configHost =>
    {
        configHost.SetBasePath(Directory.GetCurrentDirectory());
        configHost.AddJsonFile("hostsettings.json", optional: true);
        configHost.AddEnvironmentVariables(prefix: "PREFIX_");
        configHost.AddCommandLine(args);
    });

App configuration

Appkonfigurationen skapas genom att anropa ConfigureAppConfiguration på IHostBuilder. ConfigureAppConfiguration kan anropas flera gånger med additiva resultat. Appen använder det alternativ som anger ett värde sist på en viss nyckel.

Konfigurationen som skapas av ConfigureAppConfiguration är tillgänglig på HostBuilderContext.Configuration för efterföljande åtgärder och som en tjänst från DI. Värdkonfigurationen läggs också till i app-konfigurationen.

Mer information finns i Configuration i ASP.NET Core.

Inställningar för alla apptyper

I det här avsnittet visas värdinställningar som gäller för både HTTP- och icke-HTTP-arbetsbelastningar. Som standard kan miljövariabler som används för att konfigurera dessa inställningar ha ett DOTNET_- eller ASPNETCORE_ prefix, som visas i följande konfiguration för platshållaren för {PREFIX_}.

ApplicationName

Egenskapen IHostEnvironment.ApplicationName anges från värdkonfigurationen under värdkonstruktionen.

nyckel: applicationName
typ: string
Standard: Namnet på den sammansättning som innehåller appens startpunkt.
Miljövariabel: {PREFIX_}APPLICATIONNAME

Använd miljövariabeln för att ange det här värdet.

ContentRoot

Egenskapen IHostEnvironment.ContentRootPath bestämmer var värddatorn börjar söka efter innehållsfiler. Om sökvägen inte finns misslyckas hosten med att starta.

nyckel: contentRoot
typ: string
Standard: Mappen där appsammansättningen finns.
Miljövariabel: {PREFIX_}CONTENTROOT

Om du vill ange det här värdet använder du miljövariabeln eller anropar UseContentRoot på IHostBuilder:

Host.CreateDefaultBuilder(args)
    .UseContentRoot("c:\\content-root")
    //...

Mer information finns i:

• Grunderna: Innehållsrot
• WebRoot

EnvironmentName

Egenskapen IHostEnvironment.EnvironmentName kan anges till valfritt värde. Ramverksdefinierade värden omfattar Development, Stagingoch Production. Värden är inte skiftlägeskänsliga.

nyckel: environment
typ: string
standard: Production
Miljövariabel: {PREFIX_}ENVIRONMENT

Om du vill ange det här värdet använder du miljövariabeln eller anropar UseEnvironment på IHostBuilder:

Host.CreateDefaultBuilder(args)
    .UseEnvironment("Development")
    //...

ShutdownTimeout

HostOptions.ShutdownTimeout anger tidsgränsen för StopAsync. Standardvärdet är fem sekunder. Under time-out-perioden:

• Utlösare IHostApplicationLifetime.ApplicationStopping.
• Försöker stoppa värdbaserade tjänster, loggningsfel för tjänster som inte kan stoppas.

Om tidsgränsen går ut innan alla värdbaserade tjänster stoppas stoppas alla återstående aktiva tjänster när appen stängs av. Tjänsterna stoppas även om de inte har slutfört bearbetningen. Om tjänster kräver mer tid för att stoppa ökar du tidsgränsen.

nyckel: shutdownTimeoutSeconds
typ: int
Standard: 5 sekunder
Miljövariabel: {PREFIX_}SHUTDOWNTIMEOUTSECONDS

Om du vill ange det här värdet använder du miljövariabeln eller konfigurerar HostOptions. I följande exempel anges tidsgränsen till 20 sekunder:

Host.CreateDefaultBuilder(args)
    .ConfigureServices((hostContext, services) =>
    {
        services.Configure<HostOptions>(option =>
        {
            option.ShutdownTimeout = System.TimeSpan.FromSeconds(20);
        });
    });

Inställningar för webbappar

Vissa värdinställningar gäller endast för HTTP-arbetsbelastningar. Som standard kan miljövariabler som används för att konfigurera dessa inställningar ha ett DOTNET_ eller ASPNETCORE_ prefix.

Förlängningsmetoder på IWebHostBuilder är tillgängliga för dessa inställningar. Kodexempel som visar hur du anropar tilläggsmetoderna förutsätter webBuilder är en instans av IWebHostBuilder, som i följande exempel:

public static IHostBuilder CreateHostBuilder(string[] args) =>
    Host.CreateDefaultBuilder(args)
        .ConfigureWebHostDefaults(webBuilder =>
        {
            webBuilder.CaptureStartupErrors(true);
            webBuilder.UseStartup<Startup>();
        });

CaptureStartupErrors

När falseinträffar fel vid start resulterar det i att värdenheten avslutas. När truefångar upp undantag under uppstart och försöker starta servern.

nyckel: captureStartupErrors
typ: bool (true/1 eller false/0)
Standard: Standardvärdet är false förutom när appen körs med Kestrel via IIS, där standardvärdet är true.
Miljövariabel: {PREFIX_}CAPTURESTARTUPERRORS

Om du vill ange det här värdet använder du konfiguration eller anropar CaptureStartupErrors:

webBuilder.CaptureStartupErrors(true);

DetailedErrors

När den är aktiverad eller när miljön är Developmentsamlar appen in detaljerade fel.

nyckel: detailedErrors
typ: bool (true/1 eller false/0)
standard: false
Miljövariabel: {PREFIX_}DETAILEDERRORS

Om du vill ange det här värdet använder du konfiguration eller anropar UseSetting:

webBuilder.UseSetting(WebHostDefaults.DetailedErrorsKey, "true");

HostingStartupAssemblies

En semikolonavgränsad sträng som är värd för startsammansättningar för att läsa in vid start. Även om konfigurationsvärdet som standard är en tom sträng inkluderar värdstartssammansättningarna alltid appens sammansättning. När du tillhandahåller värdtjänster för startsammansättningar läggs de till i appens sammansättning för inläsning när appen skapar sina gemensamma tjänster under starten.

nyckel: hostingStartupAssemblies
typ: string
Standard: Tom sträng
Miljövariabel: {PREFIX_}HOSTINGSTARTUPASSEMBLIES

Om du vill ange det här värdet använder du konfiguration eller anropar UseSetting:

webBuilder.UseSetting(WebHostDefaults.HostingStartupAssembliesKey, "assembly1;assembly2");

HostingStartupExcludeAssemblies

En semikolonavgränsad sträng med uppstartssammansättningar som ska undantas vid start.

nyckel: hostingStartupExcludeAssemblies
typ: string
Standard: Tom sträng
Miljövariabel: {PREFIX_}HOSTINGSTARTUPEXCLUDEASSEMBLIES

Om du vill ange det här värdet använder du konfiguration eller anropar UseSetting:

webBuilder.UseSetting(WebHostDefaults.HostingStartupExcludeAssembliesKey, "assembly1;assembly2");

HTTPS_Port

HTTPS-omdirigeringsporten. Används i att upprätthålla HTTPS.

nyckel: https_port
typ: string
Standard: Ett standardvärde har inte angetts.
Miljövariabel: {PREFIX_}HTTPS_PORT

Om du vill ange det här värdet använder du konfiguration eller anropar UseSetting:

webBuilder.UseSetting("https_port", "8080");

PreferHostingUrls

Anger om värden ska lyssna på url:erna som konfigurerats med IWebHostBuilder i stället för de URL:er som konfigurerats med IServer implementeringen.

nyckel: preferHostingUrls
typ: bool (true/1 eller false/0)
standard: false
Miljövariabel: {PREFIX_}PREFERHOSTINGURLS

Om du vill ange det här värdet använder du miljövariabeln eller anropar PreferHostingUrls:

webBuilder.PreferHostingUrls(true);

PreventHostingStartup

Förhindrar automatisk läsning av värdstartssamlingar, inklusive sådana som konfigurerats av appens samling. För mer information, se Användning av värdstartssammansättningar i ASP.NET Core.

nyckel: preventHostingStartup
typ: bool (true/1 eller false/0)
standard: false
Miljövariabel: {PREFIX_}PREVENTHOSTINGSTARTUP

Om du vill ange det här värdet använder du miljövariabeln eller anropar UseSetting :

webBuilder.UseSetting(WebHostDefaults.PreventHostingStartupKey, "true");

StartupAssembly

Sammansättningen för att söka efter klassen Startup.

nyckel: startupAssembly
typ: string
Standard: Appens sammansättning
Miljövariabel: {PREFIX_}STARTUPASSEMBLY

Om du vill ange det här värdet använder du miljövariabeln eller anropar UseStartup. UseStartup kan ta ett sammansättningsnamn (string) eller en typ (TStartup). Om flera UseStartup metoder anropas har den sista företräde.

webBuilder.UseStartup("StartupAssemblyName");

webBuilder.UseStartup<Startup>();

SuppressStatusMessages

När det är aktiverat, undertrycker det startstatusmeddelanden.

nyckel: suppressStatusMessages
typ: bool (true/1 eller false/0)
standard: false
Miljövariabel: {PREFIX_}SUPPRESSSTATUSMESSAGES

Om du vill ange det här värdet använder du konfiguration eller anropar UseSetting:

webBuilder.UseSetting(WebHostDefaults.SuppressStatusMessagesKey, "true");

URLs

En semikolonavgränsad lista över IP-adresser eller värdadresser med portar och protokoll som servern ska lyssna på efter begäranden. Till exempel http://localhost:123. Använd "*" för att ange att servern ska lyssna efter begäranden på alla IP-adresser eller värdnamn med den angivna porten och protokollet (till exempel http://*:5000). Protokollet (http:// eller https://) måste ingå i varje URL. Format som stöds varierar mellan servrar.

nyckel: urls
typ: string
Standard: http://localhost:5000 och https://localhost:5001
Miljövariabel: {PREFIX_}URLS

Om du vill ange det här värdet använder du miljövariabeln eller anropar UseUrls:

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

Kestrel har ett eget API för slutpunktskonfiguration. Mer information finns i Kestrel webbserver i ASP.NET Core.

WebRoot

Egenskapen IWebHostEnvironment.WebRootPath avgör den relativa sökvägen till appens statiska tillgångar. Om sökvägen inte finns används en no-op filprovider.

nyckel: webroot
typ: string
standard: Standardvärdet är wwwroot. Sökvägen till {content root}/wwwroot måste finnas.
Miljövariabel: {PREFIX_}WEBROOT

Om du vill ange det här värdet använder du miljövariabeln eller anropar UseWebRoot på IWebHostBuilder:

webBuilder.UseWebRoot("public");

Mer information finns i:

• grunderna: Webbroten
• ContentRoot

Hantera värdlivslängden

Anropa metoder för den inbyggda IHost-implementeringen för att starta och stoppa appen. Dessa metoder påverkar alla IHostedService implementeringar som är registrerade i tjänstcontainern.

Skillnaden mellan Run* och Start* metoderna är att Run* metoderna väntar tills värden har slutfört innan de returnerar, medan Start* metoderna returnerar omedelbart. De Run* metoderna används vanligtvis i konsolappar, medan de Start* metoderna vanligtvis används i långvariga tjänster.

Run

Run kör appen och blockerar den anropande tråden tills värdssystemet stängs ned.

RunAsync

RunAsync kör appen och returnerar en Task som slutförs när annulleringstoken eller avstängningen utlöses.

RunConsoleAsync

RunConsoleAsync aktiverar konsolstöd, skapar och startar värden och väntar på att Ctrl+C/SIGINT (Windows), Ctrl+C (macOS) eller SIGTERM stängs av.

Start

Start startar värdtjänsten synkront.

StartAsync

StartAsync startar värddatorn och returnerar en Task som slutförs när en avbrytningstoken eller avstängning aktiveras.

WaitForStartAsync anropas i början av StartAsync, vilket väntar tills detta är klart innan programmet fortsätter. Den här metoden kan användas för att fördröja starten tills den signaleras av en extern händelse.

StopAsync

StopAsync försöker stoppa värddatorn inom den angivna tidsgränsen.

WaitForShutdown

WaitForShutdown blockerar den anropande tråden tills avstängningen utlöses av IHostLifetime, till exempel via Ctrl+C/SIGINT (Windows), Ctrl+C (macOS) eller SIGTERM.

WaitForShutdownAsync

WaitForShutdownAsync returnerar en Task som slutförs när avstängningen utlöses via den angivna token och anropar StopAsync.

External control

Direkt kontroll över värdlivslängden kan uppnås med metoder som kan anropas externt:

public class Program
{
    private IHost _host;

    public Program()
    {
        _host = new HostBuilder()
            .Build();
    }

    public async Task StartAsync()
    {
        _host.StartAsync();
    }

    public async Task StopAsync()
    {
        using (_host)
        {
            await _host.StopAsync(TimeSpan.FromSeconds(5));
        }
    }
}