.NET Generic Host in ASP.NET Core

Dit artikel bevat informatie over het gebruik van de .NET Generic Host in ASP.NET Core.

De ASP.NET Core-sjablonen maken een WebApplicationBuilder en WebApplication, die een gestroomlijnde manier bieden om webtoepassingen te configureren en uit te voeren zonder een Startup-klasse. Zie Migreren van ASP.NET Core 5.0 naar 6.0voor meer informatie over WebApplicationBuilder en WebApplication.

Zie .NET Generic Hostvoor meer informatie over het gebruik van de .NET Generic Host in console-apps.

Hostdefinitie

Een host is een object dat de resources van een app inkapselt, zoals:

• Afhankelijkheidsinjectie (DI)
• Logboekregistratie
• Configuratie
• IHostedService implementaties

Wanneer een host wordt gestart, roept deze IHostedService.StartAsync aan bij elke implementatie van IHostedService geregistreerd in de verzameling gehoste services van de servicecontainer. In een web-app is een van de IHostedService-implementaties een webservice die een HTTP-server-implementatie start.

Als u alle interdependent resources van de app in één object opvoegt, kunt u de controle over het opstarten van apps en het probleemloos afsluiten van de app inschakelen.

Een host instellen

De host wordt doorgaans geconfigureerd, gebouwd en uitgevoerd door code in de Program.cs. Met de volgende code wordt een host gemaakt met een IHostedService-implementatie die is toegevoegd aan de DI-container:

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

Voor een HTTP-workload roept u ConfigureWebHostDefaults aan na CreateDefaultBuilder:

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

Standaardinstellingen voor opbouwer

De methode CreateDefaultBuilder:

• Stelt de root van de inhoud in op het pad dat door GetCurrentDirectorywordt geretourneerd.
• Hostconfiguratie wordt geladen van:
  • Omgevingsvariabelen voorafgegaan door DOTNET_.
  • Opdrachtregelargumenten.
• De app-configuratie wordt geladen van:
  • appsettings.json.
  • appsettings.{Environment}.json.
  • Gebruikersgeheimen wanneer de app draait in de Development-omgeving.
  • Omgevingsvariabelen.
  • Opdrachtregelargumenten.
• Voegt de volgende logboekregistratie providers toe:
  • Console
  • Fouten opsporen
  • EventSource
  • EventLog (alleen bij uitvoering in Windows)
• Schakelt bereikvalidatie in en afhankelijkheidsvalidatie wanneer de omgeving Development is.

De methode ConfigureWebHostDefaults:

• Laadt de hostconfiguratie van omgevingsvariabelen met het voorvoegsel ASPNETCORE_.
• Stelt Kestrel server in als de webserver en configureert deze met behulp van de hostingconfiguratieproviders van de app. Zie voor de standaardopties van de Kestrel-server Opties configureren voor de ASP.NET Core Kestrel webserver.
• Voegt middleware voor hostfiltering toe.
• Voegt doorgestuurde headers middleware toe als ASPNETCORE_FORWARDEDHEADERS_ENABLED gelijk is aan true.
• Hiermee schakelt u IIS-integratie in. Zie Host ASP.NET Core in Windows met IIS-voor de standaardopties van IIS.

De Instellingen voor alle app-typen en Instellingen voor web-apps secties later in dit artikel laten zien hoe u de standaardinstellingen van de bouwer overschrijft.

Door framework geleverde services

De volgende services worden automatisch geregistreerd:

• IHostApplicationLifetime
• IHostLifetime
• IHostEnvironment/IWebHostEnvironment

Zie Afhankelijkheidsinjectie in ASP.NET Corevoor meer informatie over door framework geleverde services.

IHostApplicationLifetime

Injecteer de service IHostApplicationLifetime (voorheen IApplicationLifetime) in elke klasse om taken na het opstarten en zorgvuldige afsluiting af te handelen. Drie eigenschappen op de interface zijn annuleringstokens die worden gebruikt om methoden voor het starten en stoppen van apps te registreren. De interface bevat ook een StopApplication methode, waarmee apps een probleemloos afsluiten kunnen aanvragen.

Bij het uitvoeren van een probleemloos afsluiten, doet de host het volgende:

• Activeert de ApplicationStopping event handlers, waarmee de app in staat wordt gesteld om logica uit te voeren voordat het afsluitproces begint.
• Hiermee stopt u de server, waardoor nieuwe verbindingen worden uitgeschakeld. De server wacht tot aanvragen voor bestaande verbindingen zijn voltooid, zolang als de afsluitingstime-out toestaat. De server verzendt de header voor het sluiten van de verbinding voor verdere aanvragen voor bestaande verbindingen.
• Activeert de ApplicationStopped gebeurtenis-handlers, waardoor de app logica kan uitvoeren nadat de toepassing is afgesloten.

Het volgende voorbeeld is een IHostedService-implementatie waarmee IHostApplicationLifetime gebeurtenishandlers worden geregistreerd.

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

De IHostLifetime implementatie bepaalt wanneer de host wordt gestart en wanneer deze stopt. De laatste geregistreerde implementatie wordt gebruikt.

Microsoft.Extensions.Hosting.Internal.ConsoleLifetime is de standaard-IHostLifetime-implementatie. ConsoleLifetime:

• Luistert naar Ctrl+C/SIGINT (Windows), Ctrl+C (macOS) of SIGTERM en roept StopApplication aan om het afsluitproces te starten.
• Blokkeringen opheffen van extensies zoals RunAsync- en WaitForShutdownAsync-.

IHostEnvironment

Injecteer de IHostEnvironment-service in een klasse om informatie over de volgende instellingen op te halen:

• ApplicationName
• EnvironmentName
• ContentRootPath

Web-apps implementeren de IWebHostEnvironment-interface, die IHostEnvironment over neemt en de WebRootPath-toevoegt.

Hostconfiguratie

Hostconfiguratie wordt gebruikt voor de eigenschappen van de IHostEnvironment-implementatie.

Hostconfiguratie is beschikbaar vanuit HostBuilderContext.Configuration binnen ConfigureAppConfiguration. Na ConfigureAppConfigurationwordt HostBuilderContext.Configuration vervangen door de app-configuratie.

Als u hostconfiguratie wilt toevoegen, roept u ConfigureHostConfiguration aan op IHostBuilder. ConfigureHostConfiguration kan meerdere keren worden aangeroepen met additief resultaat. De host gebruikt de optie die een waarde voor het laatst instelt op een bepaalde sleutel.

De provider van omgevingsvariabelen met voorvoegsel DOTNET_ en opdrachtregelargumenten worden opgenomen door CreateDefaultBuilder. Voor web-apps wordt de omgevingsvariabeleprovider met voorvoegsel ASPNETCORE_ toegevoegd. Het voorvoegsel wordt verwijderd wanneer de omgevingsvariabelen worden gelezen. De waarde van de omgevingsvariabele voor ASPNETCORE_ENVIRONMENT wordt bijvoorbeeld de hostconfiguratiewaarde voor de environment-sleutel.

In het volgende voorbeeld wordt een hostconfiguratie gemaakt:

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

App-configuratie

App-configuratie wordt gemaakt door ConfigureAppConfiguration aan te roepen op IHostBuilder. ConfigureAppConfiguration kan meerdere keren worden aangeroepen met additief resultaat. De app gebruikt de optie waarmee een waarde voor het laatst op een bepaalde sleutel wordt ingesteld.

De configuratie die door ConfigureAppConfiguration is gemaakt, is beschikbaar op HostBuilderContext.Configuration voor volgende bewerkingen en als een service van DI. De hostconfiguratie wordt ook toegevoegd aan de app-configuratie.

Zie Configuratie in ASP.NET Corevoor meer informatie.

Instellingen voor alle app-typen

In deze sectie vindt u een lijst met hostinstellingen die van toepassing zijn op zowel HTTP- als niet-HTTP-workloads. Omgevingsvariabelen die worden gebruikt om deze instellingen te configureren, kunnen standaard een DOTNET_ of ASPNETCORE_ voorvoegsel hebben. Deze worden weergegeven in de volgende lijst met instellingen als tijdelijke aanduiding voor {PREFIX_}. Zie de sectie Instellingen voor standaardbouwer en Configuratie: Omgevingsvariabelenvoor meer informatie.

Applicatienaam

De eigenschap IHostEnvironment.ApplicationName is ingesteld vanuit de hostconfiguratie tijdens het bouwen van de host.

Sleutel: applicationName
Typ: string
Standaard: De naam van de assembly die het toegangspunt van de app bevat.
omgevingsvariabele: {PREFIX_}APPLICATIONNAME

Als u deze waarde wilt instellen, gebruikt u de omgevingsvariabele.

ContentRoot

De eigenschap IHostEnvironment.ContentRootPath bepaalt waar de host begint met het zoeken naar inhoudsbestanden. Als het pad niet bestaat, start de host niet.

Sleutel: contentRoot
Typ: string
Standaard: de map waarin de app-assembly zich bevindt.
omgevingsvariabele: {PREFIX_}CONTENTROOT

Als u deze waarde wilt instellen, gebruikt u de omgevingsvariabele of roept u UseContentRoot aan op IHostBuilder:

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

Zie voor meer informatie:

• Basisbeginselen: inhoudsmap
• WebRoot

Omgevingsnaam

De eigenschap IHostEnvironment.EnvironmentName kan worden ingesteld op elke waarde. Framework-gedefinieerde waarden omvatten Development, Stagingen Production. Waarden zijn niet hoofdlettergevoelig.

Sleutel: environment
Typ: string
standaard: Production
omgevingsvariabele: {PREFIX_}ENVIRONMENT

Als u deze waarde wilt instellen, gebruikt u de omgevingsvariabele of roept u UseEnvironment aan op IHostBuilder:

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

ShutdownTimeout

HostOptions.ShutdownTimeout stelt de time-out voor StopAsyncin. De standaardwaarde is 30 seconden. Tijdens de time-outperiode doet de host...

• Triggers IHostApplicationLifetime.ApplicationStopping.
• Pogingen om gehoste services te stoppen, logboekregistratiefouten voor services die niet stoppen.

Als de time-outperiode verloopt voordat alle gehoste services stoppen, worden alle resterende actieve services gestopt wanneer de app wordt afgesloten. De services stoppen zelfs als ze de verwerking nog niet hebben voltooid. Als voor services meer tijd nodig is om te stoppen, verhoogt u de time-out.

Sleutel: shutdownTimeoutSeconds
Typ: int
standaard: 30 seconden
omgevingsvariabele: {PREFIX_}SHUTDOWNTIMEOUTSECONDS

Als u deze waarde wilt instellen, gebruikt u de omgevingsvariabele of configureert u HostOptions. In het volgende voorbeeld wordt de time-out ingesteld op 20 seconden:

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

Het opnieuw laden van de app-configuratie bij wijzigingen uitschakelen

Door standaardworden appsettings.json en appsettings.{Environment}.json opnieuw geladen wanneer het bestand wordt gewijzigd. Als u dit gedrag voor opnieuw laden wilt uitschakelen in ASP.NET Core 5.0 of hoger, stelt u de hostBuilder:reloadConfigOnChange sleutel in op false.

Sleutel: hostBuilder:reloadConfigOnChange
Typ: bool (true of false)
standaard: true
opdrachtregelargument: hostBuilder:reloadConfigOnChange
omgevingsvariabele: {PREFIX_}hostBuilder:reloadConfigOnChange

Waarschuwing

Het dubbele punt-scheidingsteken (:) werkt niet met hiërarchische sleutels van omgevingsvariabelen op alle platformen. Zie Omgevingsvariabelenvoor meer informatie.

Instellingen voor web-apps

Sommige hostinstellingen zijn alleen van toepassing op HTTP-workloads. Omgevingsvariabelen die worden gebruikt om deze instellingen te configureren, kunnen standaard een DOTNET_ of ASPNETCORE_ voorvoegsel hebben. Deze worden weergegeven in de volgende lijst met instellingen als tijdelijke aanduiding voor {PREFIX_}.

Extensiemethoden op IWebHostBuilder zijn beschikbaar voor deze instellingen. Codevoorbeelden die laten zien hoe u de extensiemethoden aanroept, gaan ervan uit dat webBuilder een exemplaar van IWebHostBuilderis, zoals in het volgende voorbeeld:

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

OpstartfoutenVastleggen

Wanneer false, leiden fouten tijdens het opstarten ertoe dat de host stopt. Wanneer true, legt de host uitzonderingen vast tijdens het opstarten en probeert de server te starten.

Sleutel: captureStartupErrors
Typ: bool (true/1 of false/0)
standaard: wordt standaard ingesteld op false, tenzij de app wordt uitgevoerd met Kestrel achter IIS, waarbij de standaardwaarde is true.
omgevingsvariabele: {PREFIX_}CAPTURESTARTUPERRORS

Als u deze waarde wilt instellen, gebruikt u configuratie of aanroept u CaptureStartupErrors:

webBuilder.CaptureStartupErrors(true);

GedetailleerdeFouten

Wanneer de app is ingeschakeld of wanneer de omgeving is Development, worden gedetailleerde fouten vastgelegd.

Sleutel: detailedErrors
Typ: bool (true/1 of false/0)
standaard: false
omgevingsvariabele: {PREFIX_}DETAILEDERRORS

Als u deze waarde wilt instellen, gebruikt u configuratie of aanroept u UseSetting:

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

HostingStartupAssemblies

Een door puntkomma's gescheiden tekenreeks voor het hosten van opstartassembly's om te laden bij het opstarten. Hoewel de configuratiewaarde standaard is ingesteld op een lege tekenreeks, bevatten de hosting-opstartassembly's altijd de assembly van de app. Wanneer opstartassembly's worden gehost, worden ze toegevoegd aan de assembly van de app voor het laden wanneer de app zijn algemene services opbouwt tijdens het opstarten.

Sleutel: hostingStartupAssemblies
Typ: string
standaard: lege tekenreeks
omgevingsvariabele: {PREFIX_}HOSTINGSTARTUPASSEMBLIES

Als u deze waarde wilt instellen, gebruikt u configuratie of aanroept u UseSetting:

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

HostingStartupExcludeAssemblies

Een door puntkomma's gescheiden tekenreeks voor het hosten van opstartassembly's die moeten worden uitgesloten bij het opstarten.

Sleutel: hostingStartupExcludeAssemblies
Typ: string
standaard: lege tekenreeks
omgevingsvariabele: {PREFIX_}HOSTINGSTARTUPEXCLUDEASSEMBLIES

Als u deze waarde wilt instellen, gebruikt u configuratie of aanroept u UseSetting:

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

HTTPS-poort

Stel de HTTPS-poort in waarnaar moet worden omgeleid als u een niet-HTTPS-verbinding krijgt. Gebruikt in om HTTPSaf te dwingen. Deze instelling zorgt er niet voor dat de server luistert op de opgegeven poort. Dat wil gezegd, het is mogelijk om aanvragen per ongeluk om te leiden naar een ongebruikte poort.

Sleutel: https_portType: string
Standaard: er is geen standaardwaarde ingesteld.
omgevingsvariabele: {PREFIX_}HTTPS_PORT

Als u deze waarde wilt instellen, gebruikt u configuratie of aanroept u UseSetting:

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

HTTPS_Ports

De poorten waarin geluisterd moet worden naar HTTPS-verbindingen.

Sleutel: https_ports
Typ: string
Standaard: er is geen standaardwaarde ingesteld.
omgevingsvariabele: {PREFIX_}HTTPS_PORTS

Als u deze waarde wilt instellen, gebruikt u configuratie of aanroept u UseSetting:

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

GeefVoorkeurAanHostingUrls

Geeft aan of de host moet luisteren naar de URL's die zijn geconfigureerd met de IWebHostBuilder in plaats van die URL's die zijn geconfigureerd met de IServer-implementatie.

Sleutel: preferHostingUrls
Typ: bool (true/1 of false/0)
standaard: false
omgevingsvariabele: {PREFIX_}PREFERHOSTINGURLS

Als u deze waarde wilt instellen, gebruikt u de omgevingsvariabele of roept u PreferHostingUrlsaan:

webBuilder.PreferHostingUrls(true);

VoorkomHostingOpstart

Voorkomt het automatisch laden van opstartassembly's, waaronder het hosten van opstartassembly's die zijn geconfigureerd door de assembly van de app. Zie Hosting-opstartassembly's gebruiken in ASP.NET Corevoor meer informatie.

Sleutel: preventHostingStartup
Typ: bool (true/1 of false/0)
standaard: false
omgevingsvariabele: {PREFIX_}PREVENTHOSTINGSTARTUP

Als u deze waarde wilt instellen, gebruikt u de omgevingsvariabele of roept u UseSetting aan:

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

StartupAssembly

De assembly om te zoeken naar de Startup-klasse.

Sleutel: startupAssembly
Typ: string
Standaard: de samenstelling van de app
omgevingsvariabele: {PREFIX_}STARTUPASSEMBLY

Als u deze waarde wilt instellen, gebruikt u de omgevingsvariabele of roept u UseStartupaan. UseStartup kan een assemblynaam (string) of een type (TStartup) gebruiken. Als er meerdere UseStartup methoden worden aangeroepen, heeft de laatste prioriteit.

webBuilder.UseStartup("StartupAssemblyName");

webBuilder.UseStartup<Startup>();

StatusberichtenVerbergen

Wanneer deze optie is ingeschakeld, onderdrukt u het hosten van opstartstatusberichten.

Sleutel: suppressStatusMessages
Typ: bool (true/1 of false/0)
standaard: false
omgevingsvariabele: {PREFIX_}SUPPRESSSTATUSMESSAGES

Als u deze waarde wilt instellen, gebruikt u configuratie of aanroept u UseSetting:

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

URL's

Een door puntkomma's gescheiden lijst met IP-adressen of hostadressen met poorten en protocollen waarop de server moet luisteren naar aanvragen. Bijvoorbeeld http://localhost:123. Gebruik *om aan te geven dat de server moet luisteren naar aanvragen op een IP-adres of hostnaam met behulp van de opgegeven poort en het opgegeven protocol (bijvoorbeeld http://*:5000). Het protocol (http:// of https://) moet worden opgenomen in elke URL. Ondersteunde indelingen verschillen per server.

Sleutel: urls
Typ: string
standaard: http://localhost:5000 en https://localhost:5001
omgevingsvariabele: {PREFIX_}URLS

Als u deze waarde wilt instellen, gebruikt u de omgevingsvariabele of roept u UseUrlsaan:

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

Kestrel heeft een eigen eindpuntconfiguratie-API. Zie Eindpunten configureren voor de ASP.NET Core Kestrel webservervoor meer informatie.

WebRoot

De eigenschap IWebHostEnvironment.WebRootPath bepaalt het relatieve pad naar de statische assets van de app. Als het pad niet bestaat, wordt er een no-op bestandsprovider gebruikt.

Sleutel: webroot
Typ: string
standaard: de standaardwaarde is wwwroot. Het pad naar {content root}/wwwroot- moet bestaan.
omgevingsvariabele: {PREFIX_}WEBROOT

Als u deze waarde wilt instellen, gebruikt u de omgevingsvariabele of roept u UseWebRoot aan op IWebHostBuilder:

webBuilder.UseWebRoot("public");

Zie voor meer informatie:

• Basisprincipes: webrootmap
• ContentRoot

De levensduur van de host beheren

Roep methoden aan voor de ingebouwde IHost-implementatie om de app te starten en te stoppen. Deze methoden zijn van invloed op alle IHostedService implementaties die zijn geregistreerd in de servicecontainer.

Het verschil tussen Run* en Start* methoden is dat Run* methoden wachten tot de host zijn taak heeft voltooid voordat ze terugkeren, terwijl Start* methoden direct terugkeren. De Run* methoden worden doorgaans gebruikt in console-apps, terwijl de Start* methoden doorgaans worden gebruikt in langlopende services.

Rennen

Run de applicatie uitvoert en de aanroepende thread blokkeert totdat de host wordt afgesloten.

RunAsync

RunAsync voert de app uit en retourneert een Task die voltooit wanneer het annuleringstoken of afsluitsignaal wordt geactiveerd.

RunConsoleAsync

RunConsoleAsync activeert consoleondersteuning, bouwt en start de host, en wacht totdat Ctrl+C/SIGINT (Windows), Ctrl+C (macOS) of SIGTERM wordt gebruikt om af te sluiten.

Beginnen

Start start de host synchroon.

StartAsync

StartAsync start de host en retourneert een Task die is voltooid wanneer het annuleringstoken of afsluiten wordt geactiveerd.

WaitForStartAsync wordt aan het begin van StartAsyncaangeroepen, dat wacht totdat dit voltooid is voordat het verdergaat. Deze methode kan worden gebruikt om het opstarten uit te stellen totdat deze wordt gesignaleerd door een externe gebeurtenis.

StopAsync

StopAsync probeert de host binnen de opgegeven time-out te stoppen.

WachtOpAfsluiten

WaitForShutdown blokkeert de aanroepende thread totdat het afsluiten wordt geactiveerd door de IHostLifetime, zoals via Ctrl+C/SIGINT (Windows), Ctrl+C (macOS) of SIGTERM.

WaitForShutdownAsync

WaitForShutdownAsync retourneert een Task die is voltooid wanneer het afsluiten wordt geactiveerd via het opgegeven token en roept StopAsyncaan.

Aanvullende informatiebronnen

• Achtergrondtaken met gehoste services in ASP.NET Core
• GitHub-koppeling naar algemene hostbron

  Notitie

  Documentatiekoppelingen naar .NET-referentiebron laden meestal de standaardbranch van de opslagplaats, die de huidige ontwikkeling vertegenwoordigt voor de volgende release van .NET. Als u een tag voor een specifieke release wilt selecteren, gebruikt u de Switch-vertakkingen of tags vervolgkeuzelijst. Zie Een versietag selecteren van ASP.NET Core-broncode (dotnet/AspNetCore.Docs #26205)voor meer informatie.