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 5.0 till 6.0.

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

Definition av värd

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

• Beroendeinjektion (DI)
• Skogsavverkning
• Konfiguration
• 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_.
  • Kommandoradsargument.
• Läser in appkonfiguration från:
  • appsettings.json.
  • appsettings.{Environment}.json.
  • Användarhemligheter när appen körs i den Development miljön.
  • Miljövariabler.
  • Kommandoradsargument.
• Lägger till följande loggning leverantörer:
  • Konsol
  • Felsöka
  • 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.

Ramverksbaserade tjänster

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

Värdkonfiguration

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

Appkonfiguration

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

Miljönamn

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")
    // ...

Avstängningstidsgräns

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 ASP.NET Core 5.0 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

Varning

Kolonavgränsaren (:) fungerar inte med hierarkiska nycklar för miljövariabler på alla plattformar. Mer information finns i Miljövariabler.

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 =>
    {
        // ...
    });

FångaStartfel

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);

Detaljerade Fel

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)
förval: 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");

HostingStartupFörsamlingar

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

ExkluderaSamlingarFörHostingStartup

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

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>();

UndertryckStatusMeddelanden

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

URL:er

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.

Springa

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.

Starta

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.

Ytterligare resurser

• Bakgrundsaktiviteter med värdbaserade tjänster i ASP.NET Core
• GitHub-länk till allmän värdkälla

  Anteckning

  Dokumentationslänkar till .NET-referenskällan läser vanligtvis in lagringsplatsens standardgren, vilket representerar den aktuella utvecklingen för nästa version av .NET. Om du vill välja en tagg för en specifik version använder du listrutan Växla grenar eller taggar. Mer information finns i Så här väljer du en versionstagg för ASP.NET Core-källkod (dotnet/AspNetCore.Docs #26205).