Megosztás a következőn keresztül:


.NET Általános Gazdagép az ASP.NET Core-ban

Note

Ez nem a cikk legújabb verziója. Az aktuális kiadásról a cikk .NET 10-es verziójában olvashat.

Warning

A ASP.NET Core ezen verziója már nem támogatott. További információ: .NET és .NET Core támogatási szabályzat. Az aktuális kiadásért lásd ennek a cikknek a .NET 9-es verzióját.

Ez a cikk a .NET Általános gazdagép ASP.NET Core-ban való használatáról nyújt tájékoztatást.

A ASP.NET Core-sablonok létrehoznak egy WebApplicationBuilder és WebApplication, amely leegyszerűsíti a webalkalmazások Startup osztály nélküli konfigurálását és futtatását. További információért a WebApplicationBuilder és WebApplication elemekkel kapcsolatban, tekintse meg a Migrálás ASP.NET Core-ból .NET 5-ről .NET 6-ra című dokumentumot.

A .NET Generic Host konzolalkalmazásokban való használatáról további információt .NET Generic Hosttémakörben olvashat.

Hoszt definíció

A host olyan tárgy, amely egy alkalmazás erőforrásait foglalja magában, például:

  • Függőséginjektálás (DI)
  • Logging
  • Configuration
  • IHostedService implementációk

Amikor egy hoszt elindul, a szolgáltatástárolóban regisztrált üzemeltetett szolgáltatások gyűjteményében lévő minden IHostedService.StartAsync implementáción meghívja a IHostedService-t. Egy webalkalmazás egyik IHostedService implementációja egy webszolgáltatás, amely elindít egy HTTP-kiszolgáló implementációt.

Az alkalmazás minden egymástól függő erőforrásának egy objektumba való belefogalmazásával szabályozható az alkalmazás indítása és a kecses leállítás.

Gazdagép beállítása

A gazdagép általában a Program.cskóddal van konfigurálva, létrehozva és futtatva. Az alábbi kód létrehoz egy gazdagépet, amelyhez egy IHostedService implementáció kerül hozzáadásra a DI konténerbe.

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

HTTP-számítási feladat esetén hívja meg ConfigureWebHostDefaultsCreateDefaultBuilderután:

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

Alapértelmezett szerkesztőbeállítások

A CreateDefaultBuilder módszer:

A ConfigureWebHostDefaults módszer:

A cikk későbbi szakaszaiban a Minden alkalmazástípus beállításai és Webalkalmazások beállításai bemutatják, hogyan bírálhatja felül az alapértelmezett építőbeállításokat.

Keretrendszer által biztosított szolgáltatások

A rendszer automatikusan regisztrálja a következő szolgáltatásokat:

A keretrendszer által biztosított szolgáltatásokról további információt az ASP.NET Core függőséginjektálásában talál.

IHostApplicationLifetime

A IHostApplicationLifetime (korábban IApplicationLifetime) szolgáltatást bármely osztályba injektálhatja az indítás utáni és a kecses leállítási feladatok kezeléséhez. A felületen három tulajdonság van, amelyek lemondási tokeneket használnak az alkalmazásindítási és alkalmazásleállítási eseménykezelő metódusok regisztrálásához. A felület egy StopApplication metódust is tartalmaz, amely lehetővé teszi az alkalmazások számára, hogy zavartalan leállítást kérjenek.

Kifinomult leállítás végrehajtásakor a gazdagép:

  • Aktiválja a ApplicationStopping eseménykezelőket, amelyek lehetővé teszik az alkalmazás számára a logika futtatását a leállítási folyamat megkezdése előtt.
  • Leállítja a kiszolgálót, amely letiltja az új kapcsolatokat. A kiszolgáló megvárja, amíg befejeződnek a meglévő kapcsolatokra vonatkozó kérések, mindaddig, amíg azt a leállítási időtúllépési engedélyezi. A kiszolgáló elküldi a kapcsolat bezárása fejlécet a meglévő kapcsolatokra vonatkozó további kérésekhez.
  • Aktiválja a ApplicationStopped eseménykezelőket, amelyek lehetővé teszik az alkalmazás számára a logika futtatását az alkalmazás leállítása után.

Az alábbi példa egy IHostedService implementáció, amely IHostApplicationLifetime eseménykezelőket regisztrál:

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

A IHostLifetime implementáció vezérli, hogy mikor indul el a host rendszer, és mikor áll le. A rendszer az utolsó regisztrált implementációt használja.

Microsoft.Extensions.Hosting.Internal.ConsoleLifetime az alapértelmezett IHostLifetime implementáció. ConsoleLifetime:

  • Figyeli Ctrl+C/SIGINT (Windows), Ctrl+C (macOS) vagy SIGTERM billentyűkombinációt, és meghívja StopApplication a leállítási folyamat elindításához.
  • Feloldja az olyan bővítmények letiltását, mint például RunAsync és WaitForShutdownAsync.

IHostEnvironment

A IHostEnvironment szolgáltatás beszúrása egy osztályba a következő beállításokkal kapcsolatos információk lekéréséhez:

A webalkalmazások a IWebHostEnvironment felületet implementálják, amely örökli a IHostEnvironment-et, és hozzáadja a WebRootPath-at.

Hoszt konfigurációja

A gazdagépkonfiguráció a IHostEnvironment implementáció tulajdonságaihoz használható.

Gazdakó konfiguráció a HostBuilderContext.Configuration a ConfigureAppConfigurationbelül érhető el. A ConfigureAppConfigurationután a HostBuilderContext.Configuration az alkalmazáskonfigurációra lesz cserélve.

Gazdagépkonfiguráció hozzáadásához hívja a ConfigureHostConfiguration a IHostBuilder-re. ConfigureHostConfiguration az additív eredményekkel többször is meghívható. A gazdagép azt a beállítást alkalmazza, amely legutoljára állított be egy értéket egy adott kulcson.

A DOTNET_ előtaggal és parancssori argumentumokkal rendelkező környezeti változószolgáltatót CreateDefaultBuildertartalmazza. Webalkalmazások esetén a rendszer hozzáadja az ASPNETCORE_ előtaggal rendelkező környezeti változószolgáltatót. A környezeti változók beolvasásakor az előtag el lesz távolítva. Az ASPNETCORE_ENVIRONMENT környezeti változó értéke például a environment kulcs gazdagépkonfigurációs értéke lesz.

Az alábbi példa gazdagépkonfigurációt hoz létre:

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

Alkalmazáskonfiguráció

Az alkalmazáskonfiguráció a(z) ConfigureAppConfiguration hívásával jön létre a IHostBuilder-on. ConfigureAppConfiguration az additív eredményekkel többször is meghívható. Az alkalmazás bármelyik beállítással állít be egy értéket egy adott kulcsra.

A ConfigureAppConfiguration által létrehozott konfiguráció elérhető a HostBuilderContext.Configuration-nél a későbbi műveletekhez és szolgáltatásként a DI által. A hoszt konfigurációja az alkalmazáskonfigurációhoz is hozzáadódik.

További információ: ASP.NET Corekonfigurációja.

Az összes alkalmazástípus beállításai

Ez a szakasz a HTTP- és nem HTTP-számítási feladatokra egyaránt érvényes gazdagépbeállításokat sorolja fel. Alapértelmezés szerint a beállítások konfigurálásához használt környezeti változók DOTNET_ vagy ASPNETCORE_ előtaggal rendelkezhetnek, amelyek a beállítások alábbi listájában {PREFIX_} helyőrzőként jelennek meg. További információ: Alapértelmezett szerkesztő beállításai szakasz és Konfiguráció: Környezeti változók.

ApplicationName

A IHostEnvironment.ApplicationName tulajdonság a gazdagép beállításaiból van megadva a gazdagép létrehozásakor.

kulcs: applicationName
Típus: string
Alapértelmezett: Az alkalmazás belépési pontját tartalmazó szerelvény neve.
környezeti változó: {PREFIX_}APPLICATIONNAME

Az érték beállításához használja a környezeti változót.

ContentRoot

A IHostEnvironment.ContentRootPath tulajdonság határozza meg, hogy a gazdagép hol kezd tartalomfájlokat keresni. Ha az elérési út nem létezik, a szerver nem indul el.

kulcs: contentRoot
Típus: string
Alapértelmezett: Az a mappa, amelyben az alkalmazásszerelvény található.
környezeti változó: {PREFIX_}CONTENTROOT

Az érték beállításához használja a környezeti változót, vagy hívja meg UseContentRootIHostBuilder:

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

További információ:

EnvironmentName

A IHostEnvironment.EnvironmentName tulajdonság bármilyen értékre beállítható. A keretrendszer által definiált értékek közé tartozik a Development, a Stagingés a Production. Az értékek nem érzékenyek a kis- és nagybetűkre.

kulcs: environment
Típus: string
alapértelmezett: Production
környezeti változó: {PREFIX_}ENVIRONMENT

Az érték beállításához használja a környezeti változót, vagy hívja meg UseEnvironmentIHostBuilder:

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

ShutdownTimeout

HostOptions.ShutdownTimeout beállítja a StopAsyncidőtúllépési idejét. Az alapértelmezett érték 30 másodperc. Az időtúllépési időszak alatt a gazdagép:

  • Eseményindítók IHostApplicationLifetime.ApplicationStopping.
  • Megkísérli leállítani az üzemeltetett szolgáltatásokat, és naplózza azokat a hibákat, amelyek a szolgáltatások leállítása során jelentkeznek.

Ha az időtúllépési időszak az összes üzemeltetett szolgáltatás leállása előtt lejár, a fennmaradó aktív szolgáltatások leállnak az alkalmazás leállásakor. A szolgáltatások akkor is leállnak, ha még nem fejezték be a feldolgozást. Ha a szolgáltatások leállítása több időt igényel, növelje az időkorlátot.

kulcs: shutdownTimeoutSeconds
Típus: int
alapértelmezett: 30 másodperc
környezeti változó: {PREFIX_}SHUTDOWNTIMEOUTSECONDS

Az érték beállításához használja a környezeti változót, vagy konfigurálja HostOptions. Az alábbi példa 20 másodpercre állítja be az időtúllépést:

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

Alkalmazáskonfiguráció újrabetöltésének letiltása a módosításhoz

Alapértelmezés szerint ,, appsettings.json és appsettings.{Environment}.json újratöltődnek a fájl módosításakor. Ha le szeretné tiltani ezt az újratöltési viselkedést a .NET 5-ös vagy újabb verziójában, állítsa a kulcsot hostBuilder:reloadConfigOnChange értékre false.

kulcs: hostBuilder:reloadConfigOnChange
Típus: bool (true vagy false)
alapértelmezett: true
parancssori argumentum: hostBuilder:reloadConfigOnChange
környezeti változó: {PREFIX_}hostBuilder:reloadConfigOnChange

Warning

A kettőspont (:) elválasztó nem működik a környezeti változók hierarchikus kulcsaival minden platformon. További információ: Környezeti változók.

Webalkalmazások beállításai

Egyes gazdagépbeállítások csak HTTP terhelésekre vonatkoznak. Alapértelmezés szerint a beállítások konfigurálásához használt környezeti változók DOTNET_ vagy ASPNETCORE_ előtaggal rendelkezhetnek, amelyek a beállítások alábbi listájában {PREFIX_} helyőrzőként jelennek meg.

A IWebHostBuilder bővítménymetelyei ezekhez a beállításokhoz érhetők el. A bővítménymetelyek meghívását bemutató kódminták feltételezik, hogy webBuilderIWebHostBuilderegy példánya, ahogyan az alábbi példában is látható:

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

CaptureStartupErrors

Ha false, az indítás során előforduló hibák a gazdagép kilépését okozzák. Ha true, a gazdagép rögzíti a kivételeket az indításkor, és megpróbálja elindítani a kiszolgálót.

kulcs: captureStartupErrors
Típus: bool (true/1 vagy false/0)
Alapértelmezett: Alapértelmezés szerint false, kivéve, ha az alkalmazás az IIS mögött Kestrel módban fut, ahol az alapértelmezett érték true.
környezeti változó: {PREFIX_}CAPTURESTARTUPERRORS

Az érték beállításához használja a konfigurációt, vagy hívja meg a CaptureStartupErrors:

webBuilder.CaptureStartupErrors(true);

DetailedErrors

Ha engedélyezve van, vagy ha a környezet Development, az alkalmazás részletes hibákat rögzít.

kulcs: detailedErrors
Típus: bool (true/1 vagy false/0)
alapértelmezett: false
környezeti változó: {PREFIX_}DETAILEDERRORS

Az érték beállításához használja a konfigurációt, vagy hívja meg a UseSetting:

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

HostingStartupAssemblies

Az indításkor betöltendő, pontosvesszővel elválasztott összeállítások karakterlánca. Bár a konfigurációs érték alapértelmezett értéke egy üres sztring, az üzemeltetési indítási szerelvények mindig tartalmazzák az alkalmazás szerelvényét. Ha biztosítják az indítási szerelvényeket, azokat az alkalmazás szerelvényéhez adják hozzá, hogy betöltődhessenek, amikor az alkalmazás az indítás során létrehozza a közös szolgáltatásait.

kulcs: hostingStartupAssemblies
Típus: string
Alapértelmezett: Üres karakterlánc
környezeti változó: {PREFIX_}HOSTINGSTARTUPASSEMBLIES

Az érték beállításához használja a konfigurációt, vagy hívja meg a UseSetting:

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

HostingStartupExcludeAssemblies

Indításkor kizárandó, pontosvesszővel elválasztott, hosting indító szerelvények sztringje.

kulcs: hostingStartupExcludeAssemblies
Típus: string
Alapértelmezett: Üres karakterlánc
környezeti változó: {PREFIX_}HOSTINGSTARTUPEXCLUDEASSEMBLIES

Az érték beállításához használja a konfigurációt, vagy hívja meg a UseSetting:

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

HTTPS_Port

Állítsa be a HTTPS-portot, amelyre átirányít, ha nem HTTPS-kapcsolatot észlel. A HTTPS-kényszerítésénél használt. Ez a beállítás nem okozza, hogy a kiszolgáló a megadott porton figyel. Ez azt is lehetővé teszi, hogy véletlenül átirányítsa a kéréseket egy nem használt portra.

kulcs: https_portTípus: string
Alapértelmezett: Nincs beállítva alapértelmezett érték.
környezeti változó: {PREFIX_}HTTPS_PORT

Az érték beállításához használja a konfigurációt, vagy hívja meg a UseSetting:

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

HTTPS_Ports

A HTTPS-kapcsolatok figyeléséhez használt portok.

kulcs: https_ports
Típus: string
Alapértelmezett: Nincs beállítva alapértelmezett érték.
környezeti változó: {PREFIX_}HTTPS_PORTS

Az érték beállításához használja a konfigurációt, vagy hívja meg a UseSetting:

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

PreferHostingUrls

Azt jelzi, hogy figyelnie kell-e a gazdagépnek a IWebHostBuilder-val konfigurált URL-címekre a IServer megvalósítással konfigurált URL-címek helyett.

kulcs: preferHostingUrls
Típus: bool (true/1 vagy false/0)
alapértelmezett: false
környezeti változó: {PREFIX_}PREFERHOSTINGURLS

Az érték beállításához használja a környezeti változót, vagy hívja meg a PreferHostingUrls:

webBuilder.PreferHostingUrls(true);

PreventHostingStartup

Megakadályozza a hosztindító szerelvények automatikus betöltését, beleértve az alkalmazás szerelvénye által konfigurált hosztindító szerelvényeket is. További információért lásd: Indítási összetevők üzemeltetése az ASP.NET Core-ban.

kulcs: preventHostingStartup
Típus: bool (true/1 vagy false/0)
alapértelmezett: false
környezeti változó: {PREFIX_}PREVENTHOSTINGSTARTUP

Az érték beállításához használja a környezeti változót, vagy hívja meg a UseSetting:

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

StartupAssembly

A Startup osztály keresésére szolgáló összeállítás.

kulcs: startupAssembly
Típus: string
Alapértelmezett: Az alkalmazás összeállítása
környezeti változó: {PREFIX_}STARTUPASSEMBLY

Az érték beállításához használja a környezeti változót, vagy hívja meg UseStartup. UseStartup szerelvénynevet (string) vagy típust (TStartup) vehet fel. Ha több UseStartup metódust hív meg, az utolsó élvez elsőbbséget.

webBuilder.UseStartup("StartupAssemblyName");
webBuilder.UseStartup<Startup>();

SuppressStatusMessages

Ha engedélyezve van, elnyomja a hosztolási indítási állapotüzeneteket.

kulcs: suppressStatusMessages
Típus: bool (true/1 vagy false/0)
alapértelmezett: false
környezeti változó: {PREFIX_}SUPPRESSSTATUSMESSAGES

Az érték beállításához használja a konfigurációt, vagy hívja meg a UseSetting:

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

URLs

Pontosvesszővel tagolt IP-címek vagy gazdagépcímek listája, amelyekhez tartozó portokkal és protokollokkal a kiszolgálónak figyelnie kell a kéréseket. Például http://localhost:123. A "*" használatával jelezheti, hogy a kiszolgálónak a megadott port és protokoll (például http://*:5000) használatával kell figyelnie a kéréseket bármely IP-címen vagy gazdagépnéven. A protokollt (http:// vagy https://) minden URL-címhez hozzá kell adni. A támogatott formátumok kiszolgálók között eltérőek lehetnek.

kulcs: urls
Típus: string
Alapértelmezett: http://localhost:5000 és https://localhost:5001
környezeti változó: {PREFIX_}URLS

Az érték beállításához használja a környezeti változót, vagy hívja meg a UseUrls:

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

Kestrel saját végpontkonfigurációs API-val rendelkezik. További információ: Az ASP.NET Core Kestrel webkiszolgáló végpontjainak konfigurálása.

WebRoot

Az IWebHostEnvironment.WebRootPath tulajdonság határozza meg az alkalmazás statikus eszközeinek relatív elérési útját. Ha az elérési út nem létezik, a rendszer egy no-op fájlszolgáltatót használ.

kulcs: webroot
Típus: string
Alapértelmezett: Az alapértelmezett wwwroot. A elérési útnak {content root}/wwwroot léteznie kell.
környezeti változó: {PREFIX_}WEBROOT

Az érték beállításához használja a környezeti változót, vagy hívja meg UseWebRootIWebHostBuilder:

webBuilder.UseWebRoot("public");

További információ:

A gazdagép élettartamának kezelése

Az alkalmazás elindításához és leállításához hívja meg a beépített IHost implementáció metódusait. Ezek a módszerek a szolgáltatástárolóban regisztrált összes IHostedService implementációra hatással vannak.

A Run* és Start* metódusok között az a különbség, hogy a Run* metódusok megvárják, amíg a gazdagép befejezi a műveleteit a visszatérés előtt, míg a Start* metódusok azonnal visszatérnek. A Run* metódusokat általában konzolalkalmazásokban használják, míg a Start* metódusokat általában hosszú ideig futó szolgáltatásokban használják.

Run

Run futtatja az alkalmazást, és letiltja a hívó szálat, amíg a gazdagép le nem áll.

RunAsync

RunAsync futtatja az alkalmazást, és visszaad egy Task-et, amely befejeződik a lemondási token vagy a leállítás aktiválásakor.

RunConsoleAsync

RunConsoleAsync lehetővé teszi a konzol támogatását, létrehozza és elindítja a gazdagépet, és megvárja, amíg a Ctrl+C/SIGINT (Windows), Ctrl+C (macOS) vagy a SIGTERM leáll.

Start

Start szinkron módon indítja el a "hostot".

StartAsync

StartAsync elindítja a gazdagépet, és visszaad egy Task-et, amely akkor fejeződik be, amikor a lemondási token vagy a leállítás aktiválódik.

WaitForStartAsync a StartAsyncelején hívásra kerül, és StartAsyncmegvárja a befejezést, mielőtt folytatná. Ezzel a módszerrel késleltetheti az indítást, amíg egy külső esemény nem jelzi.

StopAsync

StopAsync megkísérli leállítani a gazdagépet a megadott időkorláton belül.

WaitForShutdown

WaitForShutdown blokkolja a hívószálat, amíg az IHostLifetime által meg nem történik a leállítás, például a Ctrl+C/SIGINT (Windows), Ctrl+C (macOS) vagy SIGTERM billentyűkombinációval.

WaitForShutdownAsync

WaitForShutdownAsync egy Task ad vissza, amely akkor fejeződik be, amikor a leállítás a megadott jogkivonaton keresztül aktiválódik, és meghívja StopAsync.

A ASP.NET Core-sablonok létrehoznak egy .NET Általános gazdagépet (HostBuilder).

Ez a cikk a .NET Generic Host ASP.NET Core-ban való használatáról nyújt tájékoztatást. A .NET Generic Host konzolalkalmazásokban való használatáról további információt a .NET Generic Host című témakörben talál.

Hoszt definíció

A host olyan tárgy, amely egy alkalmazás erőforrásait foglalja magában, például:

  • Függőséginjektálás (DI)
  • Logging
  • Configuration
  • IHostedService implementációk

Amikor egy hoszt elindul, a szolgáltatástárolóban regisztrált üzemeltetett szolgáltatások gyűjteményében lévő minden IHostedService.StartAsync implementáción meghívja a IHostedService-t. Egy webalkalmazás egyik IHostedService implementációja egy webszolgáltatás, amely elindít egy HTTP-kiszolgáló implementációt.

Az alkalmazás összes egymástól függő erőforrásának egy objektumba való belefogalmazásának fő oka az élettartam-kezelés: az alkalmazásindítás és a kecses leállítás vezérlése.

Gazdagép beállítása

A gazdagépet jellemzően a Program osztályban lévő kód konfigurálja, készíti el és futtatja. A Main módszer:

  • Meghív egy CreateHostBuilder metódust egy szerkesztőobjektum létrehozásához és konfigurálásához.
  • Meghívja Build és Run metódusokat a szerkesztőobjektumon.

Az ASP.NET Core-websablonok a következő kódot generálják egy gazdagép létrehozásához:

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

Az alábbi kód létrehoz egy nem HTTP-alapú számítási feladatot a DI-tárolóhoz hozzáadott IHostedService-implementációval.

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

HTTP-számítási feladatok esetén a Main metódus ugyanaz, de CreateHostBuilder hívások ConfigureWebHostDefaults:

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

Ha az alkalmazás Entity Framework Core-t használ, ne módosítsa a CreateHostBuilder metódus nevét vagy aláírását. Az Entity Framework Core-eszközök elvárhatóan megkeresnek egy CreateHostBuilder metódust, amely az alkalmazás futtatása nélkül konfigurálja a kiszolgálót. További információért lásd: Tervezési időben létrehozott DbContext.

Alapértelmezett szerkesztőbeállítások

A CreateDefaultBuilder módszer:

A ConfigureWebHostDefaults módszer:

A cikk későbbi szakaszaiban a Minden alkalmazástípus beállításai és Webalkalmazások beállításai bemutatják, hogyan bírálhatja felül az alapértelmezett építőbeállításokat.

Keretrendszer által biztosított szolgáltatások

A rendszer automatikusan regisztrálja a következő szolgáltatásokat:

A keretrendszer által biztosított szolgáltatásokról további információt az ASP.NET Core függőséginjektálásában talál.

IHostApplicationLifetime

A IHostApplicationLifetime (korábban IApplicationLifetime) szolgáltatást bármely osztályba injektálhatja az indítás utáni és a kecses leállítási feladatok kezeléséhez. A felületen három tulajdonság van, amelyek lemondási tokeneket használnak az alkalmazásindítási és alkalmazásleállítási eseménykezelő metódusok regisztrálásához. Az interfész egy StopApplication metódust is tartalmaz.

Az alábbi példa egy IHostedService implementáció, amely IHostApplicationLifetime eseményeket regisztrál:

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

A IHostLifetime implementáció vezérli, hogy mikor indul el a host rendszer, és mikor áll le. A rendszer az utolsó regisztrált implementációt használja.

Microsoft.Extensions.Hosting.Internal.ConsoleLifetime az alapértelmezett IHostLifetime implementáció. ConsoleLifetime:

  • Figyeli Ctrl+C/SIGINT (Windows), Ctrl+C (macOS) vagy SIGTERM billentyűkombinációt, és meghívja StopApplication a leállítási folyamat elindításához.
  • Feloldja az olyan bővítmények letiltását, mint például RunAsync és WaitForShutdownAsync.

IHostEnvironment

A IHostEnvironment szolgáltatás beszúrása egy osztályba a következő beállításokkal kapcsolatos információk lekéréséhez:

A webalkalmazások a IWebHostEnvironment felületet implementálják, amely örökli a IHostEnvironment-et, és hozzáadja a WebRootPath-at.

Hoszt konfigurációja

A gazdagépkonfiguráció a IHostEnvironment implementáció tulajdonságaihoz használható.

Gazdakó konfiguráció a HostBuilderContext.Configuration a ConfigureAppConfigurationbelül érhető el. A ConfigureAppConfigurationután a HostBuilderContext.Configuration az alkalmazáskonfigurációra lesz cserélve.

Gazdagépkonfiguráció hozzáadásához hívja a ConfigureHostConfiguration a IHostBuilder-re. ConfigureHostConfiguration az additív eredményekkel többször is meghívható. A gazdagép azt a beállítást alkalmazza, amely legutoljára állított be egy értéket egy adott kulcson.

A DOTNET_ előtaggal és parancssori argumentumokkal rendelkező környezeti változószolgáltatót CreateDefaultBuildertartalmazza. Webalkalmazások esetén a rendszer hozzáadja az ASPNETCORE_ előtaggal rendelkező környezeti változószolgáltatót. A környezeti változók beolvasásakor az előtag el lesz távolítva. Az ASPNETCORE_ENVIRONMENT környezeti változó értéke például a environment kulcs gazdagépkonfigurációs értéke lesz.

Az alábbi példa gazdagépkonfigurációt hoz létre:

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

Alkalmazáskonfiguráció

Az alkalmazáskonfiguráció a(z) ConfigureAppConfiguration hívásával jön létre a IHostBuilder-on. ConfigureAppConfiguration az additív eredményekkel többször is meghívható. Az alkalmazás bármelyik beállítással állít be egy értéket egy adott kulcsra.

A ConfigureAppConfiguration által létrehozott konfiguráció elérhető a HostBuilderContext.Configuration-nél a későbbi műveletekhez és szolgáltatásként a DI által. A hoszt konfigurációja az alkalmazáskonfigurációhoz is hozzáadódik.

További információ: ASP.NET Corekonfigurációja.

Az összes alkalmazástípus beállításai

Ez a szakasz a HTTP- és nem HTTP-számítási feladatokra egyaránt érvényes gazdagépbeállításokat sorolja fel. Alapértelmezés szerint a beállítások konfigurálásához használt környezeti változók DOTNET_ vagy ASPNETCORE_ előtaggal rendelkezhetnek, amelyek a beállítások alábbi listájában {PREFIX_} helyőrzőként jelennek meg. További információ: Alapértelmezett szerkesztő beállításai szakasz és Konfiguráció: Környezeti változók.

ApplicationName

A IHostEnvironment.ApplicationName tulajdonság a gazdagép beállításaiból van megadva a gazdagép létrehozásakor.

kulcs: applicationName
Típus: string
Alapértelmezett: Az alkalmazás belépési pontját tartalmazó szerelvény neve.
környezeti változó: {PREFIX_}APPLICATIONNAME

Az érték beállításához használja a környezeti változót.

ContentRoot

A IHostEnvironment.ContentRootPath tulajdonság határozza meg, hogy a gazdagép hol kezd tartalomfájlokat keresni. Ha az elérési út nem létezik, a szerver nem indul el.

kulcs: contentRoot
Típus: string
Alapértelmezett: Az a mappa, amelyben az alkalmazásszerelvény található.
környezeti változó: {PREFIX_}CONTENTROOT

Az érték beállításához használja a környezeti változót, vagy hívja meg UseContentRootIHostBuilder:

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

További információ:

EnvironmentName

A IHostEnvironment.EnvironmentName tulajdonság bármilyen értékre beállítható. A keretrendszer által definiált értékek közé tartozik a Development, a Stagingés a Production. Az értékek nem érzékenyek a kis- és nagybetűkre.

kulcs: environment
Típus: string
alapértelmezett: Production
környezeti változó: {PREFIX_}ENVIRONMENT

Az érték beállításához használja a környezeti változót, vagy hívja meg UseEnvironmentIHostBuilder:

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

ShutdownTimeout

HostOptions.ShutdownTimeout beállítja a StopAsyncidőtúllépési idejét. Az alapértelmezett érték öt másodperc. Az időtúllépési időszak alatt a gazdagép:

  • Eseményindítók IHostApplicationLifetime.ApplicationStopping.
  • Megkísérli leállítani az üzemeltetett szolgáltatásokat, és naplózza azokat a hibákat, amelyek a szolgáltatások leállítása során jelentkeznek.

Ha az időtúllépési időszak az összes üzemeltetett szolgáltatás leállása előtt lejár, a fennmaradó aktív szolgáltatások leállnak az alkalmazás leállásakor. A szolgáltatások akkor is leállnak, ha még nem fejezték be a feldolgozást. Ha a szolgáltatások leállítása több időt igényel, növelje az időkorlátot.

kulcs: shutdownTimeoutSeconds
Típus: int
Alapértelmezett: 5 másodperc
környezeti változó: {PREFIX_}SHUTDOWNTIMEOUTSECONDS

Az érték beállításához használja a környezeti változót, vagy konfigurálja HostOptions. Az alábbi példa 20 másodpercre állítja be az időtúllépést:

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

Alkalmazáskonfiguráció újrabetöltésének letiltása a módosításhoz

Alapértelmezés szerint ,, appsettings.json és appsettings.{Environment}.json újratöltődnek a fájl módosításakor. Ha le szeretné tiltani ezt az újratöltési viselkedést a .NET 5-ös vagy újabb verziójában, állítsa a kulcsot hostBuilder:reloadConfigOnChange értékre false.

kulcs: hostBuilder:reloadConfigOnChange
Típus: bool (true vagy false)
alapértelmezett: true
parancssori argumentum: hostBuilder:reloadConfigOnChange
környezeti változó: {PREFIX_}hostBuilder:reloadConfigOnChange

Warning

A kettőspont (:) elválasztó nem működik a környezeti változók hierarchikus kulcsaival minden platformon. További információ: Környezeti változók.

Webalkalmazások beállításai

Egyes gazdagépbeállítások csak HTTP terhelésekre vonatkoznak. Alapértelmezés szerint a beállítások konfigurálásához használt környezeti változók DOTNET_ vagy ASPNETCORE_ előtaggal rendelkezhetnek, amelyek a beállítások alábbi listájában {PREFIX_} helyőrzőként jelennek meg.

A IWebHostBuilder bővítménymetelyei ezekhez a beállításokhoz érhetők el. A bővítménymetelyek meghívását bemutató kódminták feltételezik, hogy webBuilderIWebHostBuilderegy példánya, ahogyan az alábbi példában is látható:

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

CaptureStartupErrors

Ha false, az indítás során előforduló hibák a gazdagép kilépését okozzák. Ha true, a gazdagép rögzíti a kivételeket az indításkor, és megpróbálja elindítani a kiszolgálót.

kulcs: captureStartupErrors
Típus: bool (true/1 vagy false/0)
Alapértelmezett: Alapértelmezés szerint false, kivéve, ha az alkalmazás az IIS mögött Kestrel módban fut, ahol az alapértelmezett érték true.
környezeti változó: {PREFIX_}CAPTURESTARTUPERRORS

Az érték beállításához használja a konfigurációt, vagy hívja meg a CaptureStartupErrors:

webBuilder.CaptureStartupErrors(true);

DetailedErrors

Ha engedélyezve van, vagy ha a környezet Development, az alkalmazás részletes hibákat rögzít.

kulcs: detailedErrors
Típus: bool (true/1 vagy false/0)
alapértelmezett: false
környezeti változó: {PREFIX_}DETAILEDERRORS

Az érték beállításához használja a konfigurációt, vagy hívja meg a UseSetting:

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

HostingStartupAssemblies

Az indításkor betöltendő, pontosvesszővel elválasztott összeállítások karakterlánca. Bár a konfigurációs érték alapértelmezett értéke egy üres sztring, az üzemeltetési indítási szerelvények mindig tartalmazzák az alkalmazás szerelvényét. Ha biztosítják az indítási szerelvényeket, azokat az alkalmazás szerelvényéhez adják hozzá, hogy betöltődhessenek, amikor az alkalmazás az indítás során létrehozza a közös szolgáltatásait.

kulcs: hostingStartupAssemblies
Típus: string
Alapértelmezett: Üres karakterlánc
környezeti változó: {PREFIX_}HOSTINGSTARTUPASSEMBLIES

Az érték beállításához használja a konfigurációt, vagy hívja meg a UseSetting:

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

HostingStartupExcludeAssemblies

Indításkor kizárandó, pontosvesszővel elválasztott, hosting indító szerelvények sztringje.

kulcs: hostingStartupExcludeAssemblies
Típus: string
Alapértelmezett: Üres karakterlánc
környezeti változó: {PREFIX_}HOSTINGSTARTUPEXCLUDEASSEMBLIES

Az érték beállításához használja a konfigurációt, vagy hívja meg a UseSetting:

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

HTTPS_Port

A HTTPS-átirányítási port. A HTTPS-kényszerítésénél használt.

kulcs: https_port
Típus: string
Alapértelmezett: Nincs beállítva alapértelmezett érték.
környezeti változó: {PREFIX_}HTTPS_PORT

Az érték beállításához használja a konfigurációt, vagy hívja meg a UseSetting:

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

PreferHostingUrls

Azt jelzi, hogy figyelnie kell-e a gazdagépnek a IWebHostBuilder-val konfigurált URL-címekre a IServer megvalósítással konfigurált URL-címek helyett.

kulcs: preferHostingUrls
Típus: bool (true/1 vagy false/0)
alapértelmezett: false
környezeti változó: {PREFIX_}PREFERHOSTINGURLS

Az érték beállításához használja a környezeti változót, vagy hívja meg a PreferHostingUrls:

webBuilder.PreferHostingUrls(true);

PreventHostingStartup

Megakadályozza a hosztindító szerelvények automatikus betöltését, beleértve az alkalmazás szerelvénye által konfigurált hosztindító szerelvényeket is. További információért lásd: Indítási összetevők üzemeltetése az ASP.NET Core-ban.

kulcs: preventHostingStartup
Típus: bool (true/1 vagy false/0)
alapértelmezett: false
környezeti változó: {PREFIX_}PREVENTHOSTINGSTARTUP

Az érték beállításához használja a környezeti változót, vagy hívja meg a UseSetting:

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

StartupAssembly

A Startup osztály keresésére szolgáló összeállítás.

kulcs: startupAssembly
Típus: string
Alapértelmezett: Az alkalmazás összeállítása
környezeti változó: {PREFIX_}STARTUPASSEMBLY

Az érték beállításához használja a környezeti változót, vagy hívja meg UseStartup. UseStartup szerelvénynevet (string) vagy típust (TStartup) vehet fel. Ha több UseStartup metódust hív meg, az utolsó élvez elsőbbséget.

webBuilder.UseStartup("StartupAssemblyName");
webBuilder.UseStartup<Startup>();

SuppressStatusMessages

Ha engedélyezve van, elnyomja a hosztolási indítási állapotüzeneteket.

kulcs: suppressStatusMessages
Típus: bool (true/1 vagy false/0)
alapértelmezett: false
környezeti változó: {PREFIX_}SUPPRESSSTATUSMESSAGES

Az érték beállításához használja a konfigurációt, vagy hívja meg a UseSetting:

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

URLs

Pontosvesszővel tagolt IP-címek vagy gazdagépcímek listája, amelyekhez tartozó portokkal és protokollokkal a kiszolgálónak figyelnie kell a kéréseket. Például http://localhost:123. A "*" használatával jelezheti, hogy a kiszolgálónak a megadott port és protokoll (például http://*:5000) használatával kell figyelnie a kéréseket bármely IP-címen vagy gazdagépnéven. A protokollt (http:// vagy https://) minden URL-címhez hozzá kell adni. A támogatott formátumok kiszolgálók között eltérőek lehetnek.

kulcs: urls
Típus: string
Alapértelmezett: http://localhost:5000 és https://localhost:5001
környezeti változó: {PREFIX_}URLS

Az érték beállításához használja a környezeti változót, vagy hívja meg a UseUrls:

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

Kestrel saját végpontkonfigurációs API-val rendelkezik. További információ: Az ASP.NET Core Kestrel webkiszolgáló végpontjainak konfigurálása.

WebRoot

Az IWebHostEnvironment.WebRootPath tulajdonság határozza meg az alkalmazás statikus eszközeinek relatív elérési útját. Ha az elérési út nem létezik, a rendszer egy no-op fájlszolgáltatót használ.

kulcs: webroot
Típus: string
Alapértelmezett: Az alapértelmezett wwwroot. A elérési útnak {content root}/wwwroot léteznie kell.
környezeti változó: {PREFIX_}WEBROOT

Az érték beállításához használja a környezeti változót, vagy hívja meg UseWebRootIWebHostBuilder:

webBuilder.UseWebRoot("public");

További információ:

A gazdagép élettartamának kezelése

Az alkalmazás elindításához és leállításához hívja meg a beépített IHost implementáció metódusait. Ezek a módszerek a szolgáltatástárolóban regisztrált összes IHostedService implementációra hatással vannak.

A Run* és Start* metódusok között az a különbség, hogy a Run* metódusok megvárják, amíg a gazdagép befejezi a műveleteit a visszatérés előtt, míg a Start* metódusok azonnal visszatérnek. A Run* metódusokat általában konzolalkalmazásokban használják, míg a Start* metódusokat általában hosszú ideig futó szolgáltatásokban használják.

Run

Run futtatja az alkalmazást, és letiltja a hívó szálat, amíg a gazdagép le nem áll.

RunAsync

RunAsync futtatja az alkalmazást, és visszaad egy Task-et, amely befejeződik a lemondási token vagy a leállítás aktiválásakor.

RunConsoleAsync

RunConsoleAsync lehetővé teszi a konzol támogatását, létrehozza és elindítja a gazdagépet, és megvárja, amíg a Ctrl+C/SIGINT (Windows), Ctrl+C (macOS) vagy a SIGTERM leáll.

Start

Start szinkron módon indítja el a "hostot".

StartAsync

StartAsync elindítja a gazdagépet, és visszaad egy Task-et, amely akkor fejeződik be, amikor a lemondási token vagy a leállítás aktiválódik.

WaitForStartAsync a StartAsyncelején hívásra kerül, és StartAsyncmegvárja a befejezést, mielőtt folytatná. Ezzel a módszerrel késleltetheti az indítást, amíg egy külső esemény nem jelzi.

StopAsync

StopAsync megkísérli leállítani a gazdagépet a megadott időkorláton belül.

WaitForShutdown

WaitForShutdown blokkolja a hívószálat, amíg az IHostLifetime által meg nem történik a leállítás, például a Ctrl+C/SIGINT (Windows), Ctrl+C (macOS) vagy SIGTERM billentyűkombinációval.

WaitForShutdownAsync

WaitForShutdownAsync egy Task ad vissza, amely akkor fejeződik be, amikor a leállítás a megadott jogkivonaton keresztül aktiválódik, és meghívja StopAsync.

Külső vezérlő

A gazdagép élettartamának közvetlen vezérlése külsőleg hívható metódusokkal érhető el:

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

A ASP.NET Core-sablonok létrehoznak egy .NET Általános gazdagépet (HostBuilder).

Ez a cikk a .NET Generic Host ASP.NET Core-ban való használatáról nyújt tájékoztatást. A .NET Generic Host konzolalkalmazásokban való használatáról további információt a .NET Generic Host című témakörben talál.

Hoszt definíció

A host olyan tárgy, amely egy alkalmazás erőforrásait foglalja magában, például:

  • Függőséginjektálás (DI)
  • Logging
  • Configuration
  • IHostedService implementációk

Amikor egy hoszt elindul, a szolgáltatástárolóban regisztrált üzemeltetett szolgáltatások gyűjteményében lévő minden IHostedService.StartAsync implementáción meghívja a IHostedService-t. Egy webalkalmazás egyik IHostedService implementációja egy webszolgáltatás, amely elindít egy HTTP-kiszolgáló implementációt.

Az alkalmazás összes egymástól függő erőforrásának egy objektumba való belefogalmazásának fő oka az élettartam-kezelés: az alkalmazásindítás és a kecses leállítás vezérlése.

Gazdagép beállítása

A gazdagépet jellemzően a Program osztályban lévő kód konfigurálja, készíti el és futtatja. A Main módszer:

  • Meghív egy CreateHostBuilder metódust egy szerkesztőobjektum létrehozásához és konfigurálásához.
  • Meghívja Build és Run metódusokat a szerkesztőobjektumon.

Az ASP.NET Core websablonok a következő kódot hozzák létre egy generikus gazdagép létrehozásához.

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

Az alábbi kód létrehoz egy általános gazdagépet nem HTTP-alapú számítási feladat használatával. A IHostedService implementáció hozzáadódik a DI-tárolóhoz:

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

HTTP-számítási feladatok esetén a Main metódus ugyanaz, de CreateHostBuilder hívások ConfigureWebHostDefaults:

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

Az előző kódot a ASP.NET Core-sablonok generálják.

Ha az alkalmazás Entity Framework Core-t használ, ne módosítsa a CreateHostBuilder metódus nevét vagy aláírását. Az Entity Framework Core-eszközök elvárhatóan megkeresnek egy CreateHostBuilder metódust, amely az alkalmazás futtatása nélkül konfigurálja a kiszolgálót. További információért lásd: Tervezési időben létrehozott DbContext.

Alapértelmezett szerkesztőbeállítások

A CreateDefaultBuilder módszer:

A ConfigureWebHostDefaults módszer:

A cikk későbbi szakaszaiban a Minden alkalmazástípus beállításai és Webalkalmazások beállításai bemutatják, hogyan bírálhatja felül az alapértelmezett építőbeállításokat.

Keretrendszer által biztosított szolgáltatások

A rendszer automatikusan regisztrálja a következő szolgáltatásokat:

A keretrendszer által biztosított szolgáltatásokról további információt az ASP.NET Core függőséginjektálásában talál.

IHostApplicationLifetime

A IHostApplicationLifetime (korábban IApplicationLifetime) szolgáltatást bármely osztályba injektálhatja az indítás utáni és a kecses leállítási feladatok kezeléséhez. A felületen három tulajdonság van, amelyek lemondási tokeneket használnak az alkalmazásindítási és alkalmazásleállítási eseménykezelő metódusok regisztrálásához. Az interfész egy StopApplication metódust is tartalmaz.

Az alábbi példa egy IHostedService implementáció, amely IHostApplicationLifetime eseményeket regisztrál:

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

A IHostLifetime implementáció vezérli, hogy mikor indul el a host rendszer, és mikor áll le. A rendszer az utolsó regisztrált implementációt használja.

Microsoft.Extensions.Hosting.Internal.ConsoleLifetime az alapértelmezett IHostLifetime implementáció. ConsoleLifetime:

  • Figyeli Ctrl+C/SIGINT (Windows), Ctrl+C (macOS) vagy SIGTERM billentyűkombinációt, és meghívja StopApplication a leállítási folyamat elindításához.
  • Feloldja az olyan bővítmények letiltását, mint például RunAsync és WaitForShutdownAsync.

IHostEnvironment

A IHostEnvironment szolgáltatás beszúrása egy osztályba a következő beállításokkal kapcsolatos információk lekéréséhez:

A webalkalmazások a IWebHostEnvironment felületet implementálják, amely örökli a IHostEnvironment-et, és hozzáadja a WebRootPath-at.

Hoszt konfigurációja

A gazdagépkonfiguráció a IHostEnvironment implementáció tulajdonságaihoz használható.

Gazdakó konfiguráció a HostBuilderContext.Configuration a ConfigureAppConfigurationbelül érhető el. A ConfigureAppConfigurationután a HostBuilderContext.Configuration az alkalmazáskonfigurációra lesz cserélve.

Gazdagépkonfiguráció hozzáadásához hívja a ConfigureHostConfiguration a IHostBuilder-re. ConfigureHostConfiguration az additív eredményekkel többször is meghívható. A gazdagép azt a beállítást alkalmazza, amely legutoljára állított be egy értéket egy adott kulcson.

A DOTNET_ előtaggal és parancssori argumentumokkal rendelkező környezeti változószolgáltatót CreateDefaultBuildertartalmazza. Webalkalmazások esetén a rendszer hozzáadja az ASPNETCORE_ előtaggal rendelkező környezeti változószolgáltatót. A környezeti változók beolvasásakor az előtag el lesz távolítva. Az ASPNETCORE_ENVIRONMENT környezeti változó értéke például a environment kulcs gazdagépkonfigurációs értéke lesz.

Az alábbi példa gazdagépkonfigurációt hoz létre:

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

Alkalmazáskonfiguráció

Az alkalmazáskonfiguráció a(z) ConfigureAppConfiguration hívásával jön létre a IHostBuilder-on. ConfigureAppConfiguration az additív eredményekkel többször is meghívható. Az alkalmazás bármelyik beállítással állít be egy értéket egy adott kulcsra.

A ConfigureAppConfiguration által létrehozott konfiguráció elérhető a HostBuilderContext.Configuration-nél a későbbi műveletekhez és szolgáltatásként a DI által. A hoszt konfigurációja az alkalmazáskonfigurációhoz is hozzáadódik.

További információ: ASP.NET Corekonfigurációja.

Az összes alkalmazástípus beállításai

Ez a szakasz a HTTP- és nem HTTP-számítási feladatokra egyaránt érvényes gazdagépbeállításokat sorolja fel. Alapértelmezés szerint a beállítások konfigurálásához használt környezeti változók DOTNET_ vagy ASPNETCORE_ előtaggal rendelkezhetnek, amelyek a {PREFIX_} helyőrző következő konfigurációjában jelennek meg.

ApplicationName

A IHostEnvironment.ApplicationName tulajdonság a gazdagép beállításaiból van megadva a gazdagép létrehozásakor.

kulcs: applicationName
Típus: string
Alapértelmezett: Az alkalmazás belépési pontját tartalmazó szerelvény neve.
környezeti változó: {PREFIX_}APPLICATIONNAME

Az érték beállításához használja a környezeti változót.

ContentRoot

A IHostEnvironment.ContentRootPath tulajdonság határozza meg, hogy a gazdagép hol kezd tartalomfájlokat keresni. Ha az elérési út nem létezik, a szerver nem indul el.

kulcs: contentRoot
Típus: string
Alapértelmezett: Az a mappa, amelyben az alkalmazásszerelvény található.
környezeti változó: {PREFIX_}CONTENTROOT

Az érték beállításához használja a környezeti változót, vagy hívja meg UseContentRootIHostBuilder:

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

További információ:

EnvironmentName

A IHostEnvironment.EnvironmentName tulajdonság bármilyen értékre beállítható. A keretrendszer által definiált értékek közé tartozik a Development, a Stagingés a Production. Az értékek nem érzékenyek a kis- és nagybetűkre.

kulcs: environment
Típus: string
alapértelmezett: Production
környezeti változó: {PREFIX_}ENVIRONMENT

Az érték beállításához használja a környezeti változót, vagy hívja meg UseEnvironmentIHostBuilder:

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

ShutdownTimeout

HostOptions.ShutdownTimeout beállítja a StopAsyncidőtúllépési idejét. Az alapértelmezett érték öt másodperc. Az időtúllépési időszak alatt a gazdagép:

  • Eseményindítók IHostApplicationLifetime.ApplicationStopping.
  • Megkísérli leállítani az üzemeltetett szolgáltatásokat, és naplózza azokat a hibákat, amelyek a szolgáltatások leállítása során jelentkeznek.

Ha az időtúllépési időszak az összes üzemeltetett szolgáltatás leállása előtt lejár, a fennmaradó aktív szolgáltatások leállnak az alkalmazás leállásakor. A szolgáltatások akkor is leállnak, ha még nem fejezték be a feldolgozást. Ha a szolgáltatások leállítása több időt igényel, növelje az időkorlátot.

kulcs: shutdownTimeoutSeconds
Típus: int
Alapértelmezett: 5 másodperc
környezeti változó: {PREFIX_}SHUTDOWNTIMEOUTSECONDS

Az érték beállításához használja a környezeti változót, vagy konfigurálja HostOptions. Az alábbi példa 20 másodpercre állítja be az időtúllépést:

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

Webalkalmazások beállításai

Egyes gazdagépbeállítások csak HTTP terhelésekre vonatkoznak. A beállítások konfigurálásához használt környezeti változók alapértelmezés szerint DOTNET_ vagy ASPNETCORE_ előtaggal rendelkezhetnek.

A IWebHostBuilder bővítménymetelyei ezekhez a beállításokhoz érhetők el. A bővítménymetelyek meghívását bemutató kódminták feltételezik, hogy webBuilderIWebHostBuilderegy példánya, ahogyan az alábbi példában is látható:

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

CaptureStartupErrors

Ha false, az indítás során előforduló hibák a gazdagép kilépését okozzák. Ha true, a gazdagép rögzíti a kivételeket az indításkor, és megpróbálja elindítani a kiszolgálót.

kulcs: captureStartupErrors
Típus: bool (true/1 vagy false/0)
Alapértelmezett: Alapértelmezés szerint false, kivéve, ha az alkalmazás az IIS mögött Kestrel módban fut, ahol az alapértelmezett érték true.
környezeti változó: {PREFIX_}CAPTURESTARTUPERRORS

Az érték beállításához használja a konfigurációt, vagy hívja meg a CaptureStartupErrors:

webBuilder.CaptureStartupErrors(true);

DetailedErrors

Ha engedélyezve van, vagy ha a környezet Development, az alkalmazás részletes hibákat rögzít.

kulcs: detailedErrors
Típus: bool (true/1 vagy false/0)
alapértelmezett: false
környezeti változó: {PREFIX_}DETAILEDERRORS

Az érték beállításához használja a konfigurációt, vagy hívja meg a UseSetting:

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

HostingStartupAssemblies

Az indításkor betöltendő, pontosvesszővel elválasztott összeállítások karakterlánca. Bár a konfigurációs érték alapértelmezett értéke egy üres sztring, az üzemeltetési indítási szerelvények mindig tartalmazzák az alkalmazás szerelvényét. Ha biztosítják az indítási szerelvényeket, azokat az alkalmazás szerelvényéhez adják hozzá, hogy betöltődhessenek, amikor az alkalmazás az indítás során létrehozza a közös szolgáltatásait.

kulcs: hostingStartupAssemblies
Típus: string
Alapértelmezett: Üres karakterlánc
környezeti változó: {PREFIX_}HOSTINGSTARTUPASSEMBLIES

Az érték beállításához használja a konfigurációt, vagy hívja meg a UseSetting:

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

HostingStartupExcludeAssemblies

Indításkor kizárandó, pontosvesszővel elválasztott, hosting indító szerelvények sztringje.

kulcs: hostingStartupExcludeAssemblies
Típus: string
Alapértelmezett: Üres karakterlánc
környezeti változó: {PREFIX_}HOSTINGSTARTUPEXCLUDEASSEMBLIES

Az érték beállításához használja a konfigurációt, vagy hívja meg a UseSetting:

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

HTTPS_Port

A HTTPS-átirányítási port. A HTTPS-kényszerítésénél használt.

kulcs: https_port
Típus: string
Alapértelmezett: Nincs beállítva alapértelmezett érték.
környezeti változó: {PREFIX_}HTTPS_PORT

Az érték beállításához használja a konfigurációt, vagy hívja meg a UseSetting:

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

PreferHostingUrls

Azt jelzi, hogy figyelnie kell-e a gazdagépnek a IWebHostBuilder-val konfigurált URL-címekre a IServer megvalósítással konfigurált URL-címek helyett.

kulcs: preferHostingUrls
Típus: bool (true/1 vagy false/0)
alapértelmezett: false
környezeti változó: {PREFIX_}PREFERHOSTINGURLS

Az érték beállításához használja a környezeti változót, vagy hívja meg a PreferHostingUrls:

webBuilder.PreferHostingUrls(true);

PreventHostingStartup

Megakadályozza a hosztindító szerelvények automatikus betöltését, beleértve az alkalmazás szerelvénye által konfigurált hosztindító szerelvényeket is. További információért lásd: Indítási összetevők üzemeltetése az ASP.NET Core-ban.

kulcs: preventHostingStartup
Típus: bool (true/1 vagy false/0)
alapértelmezett: false
környezeti változó: {PREFIX_}PREVENTHOSTINGSTARTUP

Az érték beállításához használja a környezeti változót, vagy hívja meg a UseSetting:

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

StartupAssembly

A Startup osztály keresésére szolgáló összeállítás.

kulcs: startupAssembly
Típus: string
Alapértelmezett: Az alkalmazás összeállítása
környezeti változó: {PREFIX_}STARTUPASSEMBLY

Az érték beállításához használja a környezeti változót, vagy hívja meg UseStartup. UseStartup szerelvénynevet (string) vagy típust (TStartup) vehet fel. Ha több UseStartup metódust hív meg, az utolsó élvez elsőbbséget.

webBuilder.UseStartup("StartupAssemblyName");
webBuilder.UseStartup<Startup>();

SuppressStatusMessages

Ha engedélyezve van, elnyomja a hosztolási indítási állapotüzeneteket.

kulcs: suppressStatusMessages
Típus: bool (true/1 vagy false/0)
alapértelmezett: false
környezeti változó: {PREFIX_}SUPPRESSSTATUSMESSAGES

Az érték beállításához használja a konfigurációt, vagy hívja meg a UseSetting:

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

URLs

Pontosvesszővel tagolt IP-címek vagy gazdagépcímek listája, amelyekhez tartozó portokkal és protokollokkal a kiszolgálónak figyelnie kell a kéréseket. Például http://localhost:123. A "*" használatával jelezheti, hogy a kiszolgálónak a megadott port és protokoll (például http://*:5000) használatával kell figyelnie a kéréseket bármely IP-címen vagy gazdagépnéven. A protokollt (http:// vagy https://) minden URL-címhez hozzá kell adni. A támogatott formátumok kiszolgálók között eltérőek lehetnek.

kulcs: urls
Típus: string
Alapértelmezett: http://localhost:5000 és https://localhost:5001
környezeti változó: {PREFIX_}URLS

Az érték beállításához használja a környezeti változót, vagy hívja meg a UseUrls:

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

Kestrel saját végpontkonfigurációs API-val rendelkezik. További információ: az Kestrel webkiszolgáló az ASP.NET Core-ben.

WebRoot

Az IWebHostEnvironment.WebRootPath tulajdonság határozza meg az alkalmazás statikus eszközeinek relatív elérési útját. Ha az elérési út nem létezik, a rendszer egy no-op fájlszolgáltatót használ.

kulcs: webroot
Típus: string
Alapértelmezett: Az alapértelmezett wwwroot. A elérési útnak {content root}/wwwroot léteznie kell.
környezeti változó: {PREFIX_}WEBROOT

Az érték beállításához használja a környezeti változót, vagy hívja meg UseWebRootIWebHostBuilder:

webBuilder.UseWebRoot("public");

További információ:

A gazdagép élettartamának kezelése

Az alkalmazás elindításához és leállításához hívja meg a beépített IHost implementáció metódusait. Ezek a módszerek a szolgáltatástárolóban regisztrált összes IHostedService implementációra hatással vannak.

A Run* és Start* metódusok között az a különbség, hogy a Run* metódusok megvárják, amíg a gazdagép befejezi a műveleteit a visszatérés előtt, míg a Start* metódusok azonnal visszatérnek. A Run* metódusokat általában konzolalkalmazásokban használják, míg a Start* metódusokat általában hosszú ideig futó szolgáltatásokban használják.

Run

Run futtatja az alkalmazást, és letiltja a hívó szálat, amíg a gazdagép le nem áll.

RunAsync

RunAsync futtatja az alkalmazást, és visszaad egy Task-et, amely befejeződik a lemondási token vagy a leállítás aktiválásakor.

RunConsoleAsync

RunConsoleAsync lehetővé teszi a konzol támogatását, létrehozza és elindítja a gazdagépet, és megvárja, amíg a Ctrl+C/SIGINT (Windows), Ctrl+C (macOS) vagy a SIGTERM leáll.

Start

Start szinkron módon indítja el a "hostot".

StartAsync

StartAsync elindítja a gazdagépet, és visszaad egy Task-et, amely akkor fejeződik be, amikor a lemondási token vagy a leállítás aktiválódik.

WaitForStartAsync a StartAsyncelején hívásra kerül, és StartAsyncmegvárja a befejezést, mielőtt folytatná. Ezzel a módszerrel késleltetheti az indítást, amíg egy külső esemény nem jelzi.

StopAsync

StopAsync megkísérli leállítani a gazdagépet a megadott időkorláton belül.

WaitForShutdown

WaitForShutdown blokkolja a hívószálat, amíg az IHostLifetime által meg nem történik a leállítás, például a Ctrl+C/SIGINT (Windows), Ctrl+C (macOS) vagy SIGTERM billentyűkombinációval.

WaitForShutdownAsync

WaitForShutdownAsync egy Task ad vissza, amely akkor fejeződik be, amikor a leállítás a megadott jogkivonaton keresztül aktiválódik, és meghívja StopAsync.

Külső vezérlő

A gazdagép élettartamának közvetlen vezérlése külsőleg hívható metódusokkal érhető el:

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

További erőforrások