ASP.NET Core'da .NET Genel Ana Bilgisayarı

  • Makale

Bu makale, ASP.NET Core'da .NET Genel Ana Bilgisayarı kullanma hakkında bilgi sağlar.

ASP.NET Core şablonları, web uygulamalarını sınıf olmadan yapılandırmak ve çalıştırmak için kolay bir yol sağlayan ve Startup oluşturur WebApplicationBuilderWebApplication. ve WebApplicationhakkında WebApplicationBuilder daha fazla bilgi için bkz. ASP.NET Core 5.0'dan 6.0'a geçiş.

Konsol uygulamalarında .NET Genel Ana Bilgisayarı kullanma hakkında bilgi için bkz . .NET Genel Ana Bilgisayarı.

Konak tanımı

Konak, bir uygulamanın kaynaklarını kapsülleyen bir nesnedir, örneğin:

  • Bağımlılık ekleme (DI)
  • Günlük Kaydı
  • Yapılandırma
  • IHostedService Uygulama

Bir konak başlatıldığında, hizmet kapsayıcısının barındırılan IHostedService hizmetler koleksiyonunda kayıtlı olan her uygulamasını çağırırIHostedService.StartAsync. Bir web uygulamasında, uygulamalardan IHostedService biri HTTP sunucusu uygulamasını başlatan bir web hizmetidir.

Uygulamanın tüm birbirine bağlı kaynaklarını tek bir nesneye dahil ederek uygulama başlatma ve düzgün kapatma üzerinde denetime olanak tanır.

Konak ayarlama

Konak genellikle içinde kodla Program.csyapılandırılır, oluşturulur ve çalıştırılır. Aşağıdaki kod, DI kapsayıcısına bir uygulama eklenmiş bir IHostedService konak oluşturur:

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

BIR HTTP iş yükü için, öğesinin ardından CreateDefaultBuilderöğesini arayınConfigureWebHostDefaults:

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

Varsayılan oluşturucu ayarları

CreateDefaultBuilder yöntemi:

  • İçerik kökünü tarafından GetCurrentDirectorydöndürülen yola ayarlar.
  • Konak yapılandırmasını şu kaynaktan yükler:
    • ile önekli DOTNET_ortam değişkenleri.
    • Komut satırı bağımsız değişkenleri.
  • Uygulama yapılandırmasını şu kaynaktan yükler:
    • appsettings.json.
    • appsettings.{Environment}.json.
    • Uygulama Development ortamında çalıştığında kullanıcı gizli dizileri.
    • Ortam değişkenleri.
    • Komut satırı bağımsız değişkenleri.
  • Aşağıdaki günlük sağlayıcılarını ekler:
    • Konsol
    • Hata Ayıklama
    • EventSource
    • EventLog (yalnızca Windows üzerinde çalışırken)
  • Ortam Geliştirme olduğunda kapsam doğrulamasını ve bağımlılık doğrulamasını etkinleştirir.

ConfigureWebHostDefaults yöntemi:

  • ön ekli ASPNETCORE_ortam değişkenlerinden konak yapılandırmasını yükler.
  • Sunucuyu web sunucusu olarak ayarlar Kestrel ve uygulamanın barındırma yapılandırma sağlayıcılarını kullanarak yapılandırılır. Sunucunun Kestrel varsayılan seçenekleri için bkz . ASP.NET Core Kestrel web sunucusu için seçenekleri yapılandırma.
  • Konak Filtreleme ara yazılımı ekler.
  • eşitse trueASPNETCORE_FORWARDEDHEADERS_ENABLED İletilen Üst Bilgiler ara yazılımı ekler.
  • IIS tümleştirmesini etkinleştirir. IIS varsayılan seçenekleri için bkz . IIS ile Windows'ta Konak ASP.NET Çekirdeği.

Bu makalenin devamında tüm uygulama türleri için Ayarlar ve web uygulamaları için Ayarlar bölümlerinde varsayılan oluşturucu ayarlarının nasıl geçersiz kılınacakları gösterilmektedir.

Çerçeve tarafından sağlanan hizmetler

Aşağıdaki hizmetler otomatik olarak kaydedilir:

Çerçeve tarafından sağlanan hizmetler hakkında daha fazla bilgi için bkz . ASP.NET Core'da bağımlılık ekleme.

IHostApplicationLifetime

IHostApplicationLifetime Başlatma sonrası ve düzgün kapatma görevlerini işlemek için herhangi bir sınıfa (eski adıylaIApplicationLifetime) hizmet ekleme. Arabirimdeki üç özellik, uygulama başlatma ve uygulama durdurma olay işleyicisi yöntemlerini kaydetmek için kullanılan iptal belirteçleridir. Arabirim ayrıca uygulamaların düzgün bir şekilde kapatma isteğinde bulunmalarını sağlayan bir StopApplication yöntem de içerir.

Düzgün bir kapatma gerçekleştirirken konak:

  • ApplicationStopping Uygulamanın kapatma işlemi başlamadan önce mantık çalıştırmasını sağlayan olay işleyicilerini tetikler.
  • Sunucuyu durdurur ve bu da yeni bağlantıları devre dışı bırakır. Sunucu, kapatma zaman aşımına izin verdiği sürece mevcut bağlantılardaki isteklerin tamamlanmasını bekler. Sunucu, mevcut bağlantılarla ilgili diğer istekler için bağlantı kapatma üst bilgisini gönderir.
  • ApplicationStopped Uygulama kapatıldıktan sonra uygulamanın mantık çalıştırmasını sağlayan olay işleyicilerini tetikler.

Aşağıdaki örnek, olay işleyicilerini IHostApplicationLifetime kaydeden bir IHostedService uygulamadır:

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

Uygulama, IHostLifetime konağın ne zaman başlayacağını ve ne zaman durduğunda denetler. Kaydedilen son uygulama kullanılır.

Microsoft.Extensions.Hosting.Internal.ConsoleLifetime varsayılan IHostLifetime uygulamadır. ConsoleLifetime:

IHostEnvironment

IHostEnvironment Aşağıdaki ayarlar hakkında bilgi almak için hizmeti bir sınıfa ekleyin:

Web uygulamaları, WebRootPath'i devralan IHostEnvironment ve ekleyen arabirimini uygularIWebHostEnvironment.

Konak yapılandırması

Ana bilgisayar yapılandırması, uygulamanın özellikleri IHostEnvironment için kullanılır.

Konak yapılandırması içinden HostBuilderContext.ConfigurationConfigureAppConfigurationkullanılabilir. HostBuilderContext.Configuration'nin ardındanConfigureAppConfiguration, uygulama yapılandırmasıyla değiştirilir.

Konak yapılandırması eklemek için çağrısında ConfigureHostConfiguration bulunur IHostBuilder. ConfigureHostConfiguration eklenebilir sonuçlarla birden çok kez çağrılabilir. Konak, belirli bir anahtarda en son değer ayarlayan seçeneği kullanır.

Ön ek DOTNET_ ve komut satırı bağımsız değişkenlerine sahip ortam değişkeni sağlayıcısı tarafından CreateDefaultBuilderdahil edilir. Web uygulamaları için, ön ekli ASPNETCORE_ ortam değişkeni sağlayıcısı eklenir. Ortam değişkenleri okunduğunda ön ek kaldırılır. Örneğin, için ASPNETCORE_ENVIRONMENT ortam değişkeni değeri anahtarın konak yapılandırma değeri environment olur.

Aşağıdaki örnek konak yapılandırması oluşturur:

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

Uygulama yapılandırması

Uygulama yapılandırması, üzerinde IHostBuilderçağrılarak ConfigureAppConfiguration oluşturulur. ConfigureAppConfiguration eklenebilir sonuçlarla birden çok kez çağrılabilir. Uygulama, belirli bir anahtarda en son değer ayarlayan seçeneği kullanır.

tarafından ConfigureAppConfiguration oluşturulan yapılandırma, sonraki işlemler için ve DI'den bir hizmet olarak kullanılabilir HostBuilderContext.Configuration . Konak yapılandırması, uygulama yapılandırmasına da eklenir.

Daha fazla bilgi için, bkz. ASP.NET Core’da yapılandırma analizi.

Tüm uygulama türleri için Ayarlar

Bu bölümde hem HTTP hem de HTTP olmayan iş yüklerine uygulanan konak ayarları listelenir. Varsayılan olarak, bu ayarları yapılandırmak için kullanılan ortam değişkenleri aşağıdaki ayarlar listesinde yer tutucu olarak görünen veya DOTNET_ASPNETCORE_ ön ekine {PREFIX_} sahip olabilir. Daha fazla bilgi için Varsayılan oluşturucu ayarları bölümüne ve Yapılandırma: Ortam değişkenleri bölümüne bakın.

ApplicationName

IHostEnvironment.ApplicationName Özelliği, konak oluşturma sırasında konak yapılandırmasından ayarlanır.

Anahtar: applicationName
Tür: string
Varsayılan: Uygulamanın giriş noktasını içeren derlemenin adı.
Ortam değişkeni: {PREFIX_}APPLICATIONNAME

Bu değeri ayarlamak için ortam değişkenini kullanın.

ContentRoot

özelliği, IHostEnvironment.ContentRootPath konağın içerik dosyalarını aramaya nereden başladığını belirler. Yol yoksa konak başlatılamaz.

Anahtar: contentRoot
Tür: string
Varsayılan: Uygulama derlemesinin bulunduğu klasör.
Ortam değişkeni: {PREFIX_}CONTENTROOT

Bu değeri ayarlamak için ortam değişkenini kullanın veya üzerinde öğesini çağırın UseContentRootIHostBuilder:

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

Daha fazla bilgi için bkz.

EnvironmentName

IHostEnvironment.EnvironmentName özelliği herhangi bir değere ayarlanabilir. Çerçeve tanımlı değerler , Stagingve Productiondeğerlerini içerirDevelopment. Değerler büyük/küçük harfe duyarlı değildir.

Anahtar: environment
Tür: string
Varsayılan: Production
Ortam değişkeni: {PREFIX_}ENVIRONMENT

Bu değeri ayarlamak için ortam değişkenini kullanın veya üzerinde öğesini çağırın UseEnvironmentIHostBuilder:

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

ShutdownTimeout

HostOptions.ShutdownTimeout için StopAsynczaman aşımını ayarlar. Varsayılan değer beş saniyedir. Zaman aşımı süresi boyunca konak:

Barındırılan hizmetlerin tümü durdurulmadan zaman aşımı süresi dolarsa, uygulama kapatıldığında kalan tüm etkin hizmetler durdurulur. İşlemleri tamamlamamış olsalar bile hizmetler durduruluyor. Hizmetlerin durdurulması için daha fazla zaman gerekiyorsa zaman aşımını artırın.

Anahtar: shutdownTimeoutSeconds
Tür: int
Varsayılan: 30 saniye
Ortam değişkeni: {PREFIX_}SHUTDOWNTIMEOUTSECONDS

Bu değeri ayarlamak için ortam değişkenini kullanın veya yapılandırın HostOptions. Aşağıdaki örnek zaman aşımını 20 saniye olarak ayarlar:

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

Değişiklikte uygulama yapılandırmasını yeniden yüklemeyi devre dışı bırakma

Varsayılan olarak ve appsettings.jsonappsettings.{Environment}.json dosya değiştiğinde yeniden yüklenir. ASP.NET Core 5.0 veya sonraki sürümlerinde bu yeniden yükleme davranışını devre dışı bırakmak için anahtarını olarak falseayarlayınhostBuilder:reloadConfigOnChange.

Anahtar: hostBuilder:reloadConfigOnChange
Tür: bool (true veya false)
Varsayılan: true
Komut satırı bağımsız değişkeni: hostBuilder:reloadConfigOnChange
Ortam değişkeni: {PREFIX_}hostBuilder:reloadConfigOnChange

Uyarı

İki nokta üst üste (:) ayırıcısı tüm platformlarda ortam değişkeni hiyerarşik anahtarlarla çalışmaz. Daha fazla bilgi için bkz . Ortam değişkenleri.

Web uygulamaları için Ayarlar

Bazı konak ayarları yalnızca HTTP iş yükleri için geçerlidir. Varsayılan olarak, bu ayarları yapılandırmak için kullanılan ortam değişkenleri aşağıdaki ayarlar listesinde yer tutucu olarak görünen veya DOTNET_ASPNETCORE_ ön ekine {PREFIX_} sahip olabilir.

Üzerindeki IWebHostBuilder uzantı yöntemleri bu ayarlar için kullanılabilir. Uzantı yöntemlerinin nasıl çağrıldığını gösteren kod örnekleri, aşağıdaki örnekte olduğu gibi öğesinin IWebHostBuilderbir örneği olduğunu varsayarwebBuilder:

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

CaptureStartupErrors

olduğunda false, başlatma sırasındaki hatalar konağın çıkmasıyla sonuçlanır. olduğunda true, konak başlatma sırasında özel durumları yakalar ve sunucuyu başlatmayı dener.

Anahtar: captureStartupErrors
Tür: bool (true/1 veya false/0)
Varsayılan: false Uygulama IIS'nin arkasında çalıştırılmadığı Kestrel sürece varsayılan olarak ayarlanır ve burada varsayılan değeri olur true.
Ortam değişkeni: {PREFIX_}CAPTURESTARTUPERRORS

Bu değeri ayarlamak için yapılandırmayı kullanın veya öğesini çağırin CaptureStartupErrors:

webBuilder.CaptureStartupErrors(true);

DetailedErrors

Etkinleştirildiğinde veya ortam olduğunda Developmentuygulama ayrıntılı hataları yakalar.

Anahtar: detailedErrors
Tür: bool (true/1 veya false/0)
Varsayılan: false
Ortam değişkeni: {PREFIX_}DETAILEDERRORS

Bu değeri ayarlamak için yapılandırmayı kullanın veya öğesini çağırin UseSetting:

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

HostingStartupAssemblies

Başlatma sırasında yüklenecek barındırma başlangıç derlemelerinin noktalı virgülle ayrılmış dizesi. Yapılandırma değeri varsayılan olarak boş bir dize olsa da, barındırma başlangıç derlemeleri her zaman uygulamanın derlemesini içerir. Barındırma başlangıç derlemeleri sağlanırken, uygulama başlatma sırasında ortak hizmetlerini oluştururken yüklenmek üzere uygulamanın derlemesine eklenirler.

Anahtar: hostingStartupAssemblies
Tür: string
Varsayılan: Boş dize
Ortam değişkeni: {PREFIX_}HOSTINGSTARTUPASSEMBLIES

Bu değeri ayarlamak için yapılandırmayı kullanın veya öğesini çağırin UseSetting:

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

HostingStartupExcludeAssemblies

Başlatma sırasında hariç tutulacak, barındırma başlangıç derlemelerinin noktalı virgülle ayrılmış dizesi.

Anahtar: hostingStartupExcludeAssemblies
Tür: string
Varsayılan: Boş dize
Ortam değişkeni: {PREFIX_}HOSTINGSTARTUPEXCLUDEASSEMBLIES

Bu değeri ayarlamak için yapılandırmayı kullanın veya öğesini çağırin UseSetting:

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

HTTPS_Port

HTTPS yeniden yönlendirme bağlantı noktası. HTTPS zorlamada kullanılır.

Anahtar: https_port
Tür: string
Varsayılan: Varsayılan değer ayarlanmadı.
Ortam değişkeni: {PREFIX_}HTTPS_PORT

Bu değeri ayarlamak için yapılandırmayı kullanın veya öğesini çağırin UseSetting:

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

PreferHostingUrls

Konağın uygulamayla yapılandırılan URL'ler yerine ile IWebHostBuilder yapılandırılan URL'leri dinlemesi IServer gerekip gerekmediğini gösterir.

Anahtar: preferHostingUrls
Tür: bool (true/1 veya false/0)
Varsayılan: false
Ortam değişkeni: {PREFIX_}PREFERHOSTINGURLS

Bu değeri ayarlamak için ortam değişkenini kullanın veya öğesini çağırın PreferHostingUrls:

webBuilder.PreferHostingUrls(true);

PreventHostingStartup

Uygulamanın derlemesi tarafından yapılandırılan barındırma başlangıç derlemeleri de dahil olmak üzere barındırma başlangıç derlemelerinin otomatik yüklenmesini engeller. Daha fazla bilgi için, bkz. ASP.NET Core'da barındırma başlangıç derlemelerini kullanma.

Anahtar: preventHostingStartup
Tür: bool (true/1 veya false/0)
Varsayılan: false
Ortam değişkeni: {PREFIX_}PREVENTHOSTINGSTARTUP

Bu değeri ayarlamak için ortam değişkenini kullanın veya öğesini çağırın UseSetting :

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

StartupAssembly

Sınıfını aramak için derleme Startup .

Anahtar: startupAssembly
Tür: string
Varsayılan: Uygulamanın derlemesi
Ortam değişkeni: {PREFIX_}STARTUPASSEMBLY

Bu değeri ayarlamak için ortam değişkenini kullanın veya komutunu çağırın UseStartup. UseStartup bir derleme adı (string) veya tür (TStartup) alabilir. Birden çok UseStartup yöntem çağrılırsa, sonuncusu öncelikli olur.

webBuilder.UseStartup("StartupAssemblyName");

webBuilder.UseStartup<Startup>();

SuppressStatusMessages

Etkinleştirildiğinde, barındırma başlatma durumu iletilerini gizler.

Anahtar: suppressStatusMessages
Tür: bool (true/1 veya false/0)
Varsayılan: false
Ortam değişkeni: {PREFIX_}SUPPRESSSTATUSMESSAGES

Bu değeri ayarlamak için yapılandırmayı kullanın veya öğesini çağırin UseSetting:

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

URL'ler

Sunucunun istekler için dinlemesi gereken bağlantı noktalarına ve protokollere sahip IP adreslerinin veya konak adreslerinin noktalı virgülle ayrılmış listesi. Örneğin, http://localhost:123. Sunucunun belirtilen bağlantı noktasını ve protokolü (örneğin, http://*:5000) kullanarak herhangi bir IP adresi veya ana bilgisayar adı üzerindeki istekleri dinlemesi gerektiğini belirtmek için "*" kullanın. Protokol (http:// veya https://) her URL'ye eklenmelidir. Desteklenen biçimler sunucular arasında farklılık gösterir.

Anahtar: urls
Tür: string
Varsayılan: http://localhost:5000 ve https://localhost:5001
Ortam değişkeni: {PREFIX_}URLS

Bu değeri ayarlamak için ortam değişkenini kullanın veya öğesini çağırın UseUrls:

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

Kestrel kendi uç nokta yapılandırma API'sine sahiptir. Daha fazla bilgi için bkz . ASP.NET Core Kestrel web sunucusu için uç noktaları yapılandırma.

Webroot

IWebHostEnvironment.WebRootPath özelliği, uygulamanın statik varlıklarının göreli yolunu belirler. Yol yoksa, işlem yapılmayan bir dosya sağlayıcısı kullanılır.

Anahtar: webroot
Tür: string
Varsayılan: Varsayılan değerdir wwwroot. {content root}/wwwroot yolunun mevcut olması gerekir.
Ortam değişkeni: {PREFIX_}WEBROOT

Bu değeri ayarlamak için ortam değişkenini kullanın veya üzerinde öğesini çağırın UseWebRootIWebHostBuilder:

webBuilder.UseWebRoot("public");

Daha fazla bilgi için bkz.

Konak ömrünü yönetme

Uygulamayı başlatmak ve durdurmak için yerleşik IHost uygulamada yöntemleri çağırın. Bu yöntemler, hizmet kapsayıcısında kayıtlı olan tüm IHostedService uygulamaları etkiler.

ve Start* yöntemleri arasındaki Run* fark, yöntemlerin Run* döndürmeden önce konağın tamamlanmasını beklemesi, yöntemlerin ise Start* hemen döndürülmesidir. Yöntemler Run* genellikle konsol uygulamalarında kullanılırken Start* , yöntemler genellikle uzun süre çalışan hizmetlerde kullanılır.

Çalıştır

Run uygulamayı çalıştırır ve konak kapatana kadar çağıran iş parçacığını engeller.

RunAsync

RunAsync uygulamayı çalıştırır ve iptal belirteci veya kapatma tetiklendiğinde tamamlanan bir Task döndürür.

RunConsoleAsync

RunConsoleAsynckonsol desteğini etkinleştirir, konağı derler ve başlatır ve Ctrl+C/SIGINT (Windows), ⌘+C (macOS) veya SIGTERM'nin kapatılmasını bekler.

Başlangıç

Start konağı zaman uyumlu olarak başlatır.

StartAsync

StartAsync konağı başlatır ve iptal belirteci veya kapatma tetiklendiğinde tamamlanan bir Task döndürür.

WaitForStartAsync , devam etmeden önce tamamlanana kadar bekleyen öğesinin StartAsyncbaşında çağrılır. Bu yöntem, bir dış olay tarafından sinyal alınana kadar başlatmayı geciktirmek için kullanılabilir.

StopAsync

StopAsync sağlanan zaman aşımı içinde konağı durdurmaya çalışır.

WaitForShutdown

WaitForShutdownCtrl+C/SIGINT (Windows), ⌘C (macOS) veya SIGTERM gibi kapatma IHostLifetime tarafından tetiklenene+ kadar çağıran iş parçacığını engeller.

WaitForShutdownAsync

WaitForShutdownAsyncverilen belirteç aracılığıyla kapatma tetiklendiğinde ve çağrısı StopAsyncyapıldığında tamamlanan bir Task döndürür.

ASP.NET Core şablonları bir .NET Core Genel Ana Bilgisayarı (HostBuilder ) oluşturur.

Bu makale, ASP.NET Core'da .NET Genel Ana Bilgisayarı kullanma hakkında bilgi sağlar. Konsol uygulamalarında .NET Genel Ana Bilgisayarı kullanma hakkında bilgi için bkz . .NET Genel Ana Bilgisayarı.

Konak tanımı

Konak, bir uygulamanın kaynaklarını kapsülleyen bir nesnedir, örneğin:

  • Bağımlılık ekleme (DI)
  • Günlük Kaydı
  • Yapılandırma
  • IHostedService Uygulama

Bir konak başlatıldığında, hizmet kapsayıcısının barındırılan IHostedService hizmetler koleksiyonunda kayıtlı olan her uygulamasını çağırırIHostedService.StartAsync. Bir web uygulamasında, uygulamalardan IHostedService biri HTTP sunucusu uygulamasını başlatan bir web hizmetidir.

Uygulamanın tüm birbirine bağlı kaynaklarını tek bir nesneye eklemenin temel nedeni yaşam süresi yönetimidir: uygulama başlatma ve düzgün kapatma üzerinde denetim.

Konak ayarlama

Konak genellikle sınıfında kodla Program yapılandırılır, oluşturulur ve çalıştırılır. Main yöntemi:

  • CreateHostBuilder Oluşturucu nesnesi oluşturmak ve yapılandırmak için bir yöntem çağırır.
  • Oluşturucu nesnesinde çağrılar Build ve Run yöntemler.

ASP.NET Core web şablonları, konak oluşturmak için aşağıdaki kodu oluşturur:

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

Aşağıdaki kod, DI kapsayıcısına eklenen bir uygulamayla HTTP olmayan bir IHostedService iş yükü oluşturur.

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

BIR HTTP iş yükü için Main yöntemi aynıdır ancak CreateHostBuilder öğesini çağırır ConfigureWebHostDefaults:

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

Uygulama Entity Framework Core kullanıyorsa yöntemin adını veya imzasını değiştirmeyin CreateHostBuilder . Entity Framework Core araçları, uygulamayı çalıştırmadan konağı yapılandıran bir CreateHostBuilder yöntem bulmayı bekler. Daha fazla bilgi için bkz . Tasarım zamanı DbContext Oluşturma.

Varsayılan oluşturucu ayarları

CreateDefaultBuilder yöntemi:

  • İçerik kökünü tarafından GetCurrentDirectorydöndürülen yola ayarlar.
  • Konak yapılandırmasını şu kaynaktan yükler:
    • ile önekli DOTNET_ortam değişkenleri.
    • Komut satırı bağımsız değişkenleri.
  • Uygulama yapılandırmasını şu kaynaktan yükler:
    • appsettings.json.
    • appsettings.{Environment}.json.
    • Uygulama Development ortamında çalıştığında kullanıcı gizli dizileri.
    • Ortam değişkenleri.
    • Komut satırı bağımsız değişkenleri.
  • Aşağıdaki günlük sağlayıcılarını ekler:
    • Konsol
    • Hata Ayıklama
    • EventSource
    • EventLog (yalnızca Windows üzerinde çalışırken)
  • Ortam Geliştirme olduğunda kapsam doğrulamasını ve bağımlılık doğrulamasını etkinleştirir.

ConfigureWebHostDefaults yöntemi:

  • ön ekli ASPNETCORE_ortam değişkenlerinden konak yapılandırmasını yükler.
  • Sunucuyu web sunucusu olarak ayarlar Kestrel ve uygulamanın barındırma yapılandırma sağlayıcılarını kullanarak yapılandırılır. Sunucunun Kestrel varsayılan seçenekleri için bkz . ASP.NET Core Kestrel web sunucusu için seçenekleri yapılandırma.
  • Konak Filtreleme ara yazılımı ekler.
  • eşitse trueASPNETCORE_FORWARDEDHEADERS_ENABLED İletilen Üst Bilgiler ara yazılımı ekler.
  • IIS tümleştirmesini etkinleştirir. IIS varsayılan seçenekleri için bkz . IIS ile Windows'ta Konak ASP.NET Çekirdeği.

Bu makalenin devamında tüm uygulama türleri için Ayarlar ve web uygulamaları için Ayarlar bölümlerinde varsayılan oluşturucu ayarlarının nasıl geçersiz kılınacakları gösterilmektedir.

Çerçeve tarafından sağlanan hizmetler

Aşağıdaki hizmetler otomatik olarak kaydedilir:

Çerçeve tarafından sağlanan hizmetler hakkında daha fazla bilgi için bkz . ASP.NET Core'da bağımlılık ekleme.

IHostApplicationLifetime

IHostApplicationLifetime Başlatma sonrası ve düzgün kapatma görevlerini işlemek için herhangi bir sınıfa (eski adıylaIApplicationLifetime) hizmet ekleme. Arabirimdeki üç özellik, uygulama başlatma ve uygulama durdurma olay işleyicisi yöntemlerini kaydetmek için kullanılan iptal belirteçleridir. Arabirim bir yöntem de içerir StopApplication .

Aşağıdaki örnek, olayları kaydeden IHostApplicationLifetime bir IHostedService uygulamadır:

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

Uygulama, IHostLifetime konağın ne zaman başlayacağını ve ne zaman durduğunda denetler. Kaydedilen son uygulama kullanılır.

Microsoft.Extensions.Hosting.Internal.ConsoleLifetime varsayılan IHostLifetime uygulamadır. ConsoleLifetime:

IHostEnvironment

IHostEnvironment Aşağıdaki ayarlar hakkında bilgi almak için hizmeti bir sınıfa ekleyin:

Web uygulamaları, WebRootPath'i devralan IHostEnvironment ve ekleyen arabirimini uygularIWebHostEnvironment.

Konak yapılandırması

Ana bilgisayar yapılandırması, uygulamanın özellikleri IHostEnvironment için kullanılır.

Konak yapılandırması içinden HostBuilderContext.ConfigurationConfigureAppConfigurationkullanılabilir. HostBuilderContext.Configuration'nin ardındanConfigureAppConfiguration, uygulama yapılandırmasıyla değiştirilir.

Konak yapılandırması eklemek için çağrısında ConfigureHostConfiguration bulunur IHostBuilder. ConfigureHostConfiguration eklenebilir sonuçlarla birden çok kez çağrılabilir. Konak, belirli bir anahtarda en son değer ayarlayan seçeneği kullanır.

Ön ek DOTNET_ ve komut satırı bağımsız değişkenlerine sahip ortam değişkeni sağlayıcısı tarafından CreateDefaultBuilderdahil edilir. Web uygulamaları için, ön ekli ASPNETCORE_ ortam değişkeni sağlayıcısı eklenir. Ortam değişkenleri okunduğunda ön ek kaldırılır. Örneğin, için ASPNETCORE_ENVIRONMENT ortam değişkeni değeri anahtarın konak yapılandırma değeri environment olur.

Aşağıdaki örnek konak yapılandırması oluşturur:

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

Uygulama yapılandırması

Uygulama yapılandırması, üzerinde IHostBuilderçağrılarak ConfigureAppConfiguration oluşturulur. ConfigureAppConfiguration eklenebilir sonuçlarla birden çok kez çağrılabilir. Uygulama, belirli bir anahtarda en son değer ayarlayan seçeneği kullanır.

tarafından ConfigureAppConfiguration oluşturulan yapılandırma, sonraki işlemler için ve DI'den bir hizmet olarak kullanılabilir HostBuilderContext.Configuration . Konak yapılandırması, uygulama yapılandırmasına da eklenir.

Daha fazla bilgi için, bkz. ASP.NET Core’da yapılandırma analizi.

Tüm uygulama türleri için Ayarlar

Bu bölümde hem HTTP hem de HTTP olmayan iş yüklerine uygulanan konak ayarları listelenir. Varsayılan olarak, bu ayarları yapılandırmak için kullanılan ortam değişkenleri aşağıdaki ayarlar listesinde yer tutucu olarak görünen veya DOTNET_ASPNETCORE_ ön ekine {PREFIX_} sahip olabilir. Daha fazla bilgi için Varsayılan oluşturucu ayarları bölümüne ve Yapılandırma: Ortam değişkenleri bölümüne bakın.

ApplicationName

IHostEnvironment.ApplicationName Özelliği, konak oluşturma sırasında konak yapılandırmasından ayarlanır.

Anahtar: applicationName
Tür: string
Varsayılan: Uygulamanın giriş noktasını içeren derlemenin adı.
Ortam değişkeni: {PREFIX_}APPLICATIONNAME

Bu değeri ayarlamak için ortam değişkenini kullanın.

ContentRoot

özelliği, IHostEnvironment.ContentRootPath konağın içerik dosyalarını aramaya nereden başladığını belirler. Yol yoksa konak başlatılamaz.

Anahtar: contentRoot
Tür: string
Varsayılan: Uygulama derlemesinin bulunduğu klasör.
Ortam değişkeni: {PREFIX_}CONTENTROOT

Bu değeri ayarlamak için ortam değişkenini kullanın veya üzerinde öğesini çağırın UseContentRootIHostBuilder:

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

Daha fazla bilgi için bkz.

EnvironmentName

IHostEnvironment.EnvironmentName özelliği herhangi bir değere ayarlanabilir. Çerçeve tanımlı değerler , Stagingve Productiondeğerlerini içerirDevelopment. Değerler büyük/küçük harfe duyarlı değildir.

Anahtar: environment
Tür: string
Varsayılan: Production
Ortam değişkeni: {PREFIX_}ENVIRONMENT

Bu değeri ayarlamak için ortam değişkenini kullanın veya üzerinde öğesini çağırın UseEnvironmentIHostBuilder:

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

ShutdownTimeout

HostOptions.ShutdownTimeout için StopAsynczaman aşımını ayarlar. Varsayılan değer beş saniyedir. Zaman aşımı süresi boyunca konak:

Barındırılan hizmetlerin tümü durdurulmadan zaman aşımı süresi dolarsa, uygulama kapatıldığında kalan tüm etkin hizmetler durdurulur. İşlemleri tamamlamamış olsalar bile hizmetler durduruluyor. Hizmetlerin durdurulması için daha fazla zaman gerekiyorsa zaman aşımını artırın.

Anahtar: shutdownTimeoutSeconds
Tür: int
Varsayılan: 5 saniye
Ortam değişkeni: {PREFIX_}SHUTDOWNTIMEOUTSECONDS

Bu değeri ayarlamak için ortam değişkenini kullanın veya yapılandırın HostOptions. Aşağıdaki örnek zaman aşımını 20 saniye olarak ayarlar:

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

Değişiklikte uygulama yapılandırmasını yeniden yüklemeyi devre dışı bırakma

Varsayılan olarak ve appsettings.jsonappsettings.{Environment}.json dosya değiştiğinde yeniden yüklenir. ASP.NET Core 5.0 veya sonraki sürümlerinde bu yeniden yükleme davranışını devre dışı bırakmak için anahtarını olarak falseayarlayınhostBuilder:reloadConfigOnChange.

Anahtar: hostBuilder:reloadConfigOnChange
Tür: bool (true veya false)
Varsayılan: true
Komut satırı bağımsız değişkeni: hostBuilder:reloadConfigOnChange
Ortam değişkeni: {PREFIX_}hostBuilder:reloadConfigOnChange

Uyarı

İki nokta üst üste (:) ayırıcısı tüm platformlarda ortam değişkeni hiyerarşik anahtarlarla çalışmaz. Daha fazla bilgi için bkz . Ortam değişkenleri.

Web uygulamaları için Ayarlar

Bazı konak ayarları yalnızca HTTP iş yükleri için geçerlidir. Varsayılan olarak, bu ayarları yapılandırmak için kullanılan ortam değişkenleri aşağıdaki ayarlar listesinde yer tutucu olarak görünen veya DOTNET_ASPNETCORE_ ön ekine {PREFIX_} sahip olabilir.

Üzerindeki IWebHostBuilder uzantı yöntemleri bu ayarlar için kullanılabilir. Uzantı yöntemlerinin nasıl çağrıldığını gösteren kod örnekleri, aşağıdaki örnekte olduğu gibi öğesinin IWebHostBuilderbir örneği olduğunu varsayarwebBuilder:

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

CaptureStartupErrors

olduğunda false, başlatma sırasındaki hatalar konağın çıkmasıyla sonuçlanır. olduğunda true, konak başlatma sırasında özel durumları yakalar ve sunucuyu başlatmayı dener.

Anahtar: captureStartupErrors
Tür: bool (true/1 veya false/0)
Varsayılan: false Uygulama IIS'nin arkasında çalıştırılmadığı Kestrel sürece varsayılan olarak ayarlanır ve burada varsayılan değeri olur true.
Ortam değişkeni: {PREFIX_}CAPTURESTARTUPERRORS

Bu değeri ayarlamak için yapılandırmayı kullanın veya öğesini çağırin CaptureStartupErrors:

webBuilder.CaptureStartupErrors(true);

DetailedErrors

Etkinleştirildiğinde veya ortam olduğunda Developmentuygulama ayrıntılı hataları yakalar.

Anahtar: detailedErrors
Tür: bool (true/1 veya false/0)
Varsayılan: false
Ortam değişkeni: {PREFIX_}DETAILEDERRORS

Bu değeri ayarlamak için yapılandırmayı kullanın veya öğesini çağırin UseSetting:

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

HostingStartupAssemblies

Başlatma sırasında yüklenecek barındırma başlangıç derlemelerinin noktalı virgülle ayrılmış dizesi. Yapılandırma değeri varsayılan olarak boş bir dize olsa da, barındırma başlangıç derlemeleri her zaman uygulamanın derlemesini içerir. Barındırma başlangıç derlemeleri sağlanırken, uygulama başlatma sırasında ortak hizmetlerini oluştururken yüklenmek üzere uygulamanın derlemesine eklenirler.

Anahtar: hostingStartupAssemblies
Tür: string
Varsayılan: Boş dize
Ortam değişkeni: {PREFIX_}HOSTINGSTARTUPASSEMBLIES

Bu değeri ayarlamak için yapılandırmayı kullanın veya öğesini çağırin UseSetting:

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

HostingStartupExcludeAssemblies

Başlatma sırasında hariç tutulacak, barındırma başlangıç derlemelerinin noktalı virgülle ayrılmış dizesi.

Anahtar: hostingStartupExcludeAssemblies
Tür: string
Varsayılan: Boş dize
Ortam değişkeni: {PREFIX_}HOSTINGSTARTUPEXCLUDEASSEMBLIES

Bu değeri ayarlamak için yapılandırmayı kullanın veya öğesini çağırin UseSetting:

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

HTTPS_Port

HTTPS yeniden yönlendirme bağlantı noktası. HTTPS zorlamada kullanılır.

Anahtar: https_port
Tür: string
Varsayılan: Varsayılan değer ayarlanmadı.
Ortam değişkeni: {PREFIX_}HTTPS_PORT

Bu değeri ayarlamak için yapılandırmayı kullanın veya öğesini çağırin UseSetting:

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

PreferHostingUrls

Konağın uygulamayla yapılandırılan URL'ler yerine ile IWebHostBuilder yapılandırılan URL'leri dinlemesi IServer gerekip gerekmediğini gösterir.

Anahtar: preferHostingUrls
Tür: bool (true/1 veya false/0)
Varsayılan: false
Ortam değişkeni: {PREFIX_}PREFERHOSTINGURLS

Bu değeri ayarlamak için ortam değişkenini kullanın veya öğesini çağırın PreferHostingUrls:

webBuilder.PreferHostingUrls(true);

PreventHostingStartup

Uygulamanın derlemesi tarafından yapılandırılan barındırma başlangıç derlemeleri de dahil olmak üzere barındırma başlangıç derlemelerinin otomatik yüklenmesini engeller. Daha fazla bilgi için, bkz. ASP.NET Core'da barındırma başlangıç derlemelerini kullanma.

Anahtar: preventHostingStartup
Tür: bool (true/1 veya false/0)
Varsayılan: false
Ortam değişkeni: {PREFIX_}PREVENTHOSTINGSTARTUP

Bu değeri ayarlamak için ortam değişkenini kullanın veya öğesini çağırın UseSetting :

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

StartupAssembly

Sınıfını aramak için derleme Startup .

Anahtar: startupAssembly
Tür: string
Varsayılan: Uygulamanın derlemesi
Ortam değişkeni: {PREFIX_}STARTUPASSEMBLY

Bu değeri ayarlamak için ortam değişkenini kullanın veya komutunu çağırın UseStartup. UseStartup bir derleme adı (string) veya tür (TStartup) alabilir. Birden çok UseStartup yöntem çağrılırsa, sonuncusu öncelikli olur.

webBuilder.UseStartup("StartupAssemblyName");

webBuilder.UseStartup<Startup>();

SuppressStatusMessages

Etkinleştirildiğinde, barındırma başlatma durumu iletilerini gizler.

Anahtar: suppressStatusMessages
Tür: bool (true/1 veya false/0)
Varsayılan: false
Ortam değişkeni: {PREFIX_}SUPPRESSSTATUSMESSAGES

Bu değeri ayarlamak için yapılandırmayı kullanın veya öğesini çağırin UseSetting:

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

URL'ler

Sunucunun istekler için dinlemesi gereken bağlantı noktalarına ve protokollere sahip IP adreslerinin veya konak adreslerinin noktalı virgülle ayrılmış listesi. Örneğin, http://localhost:123. Sunucunun belirtilen bağlantı noktasını ve protokolü (örneğin, http://*:5000) kullanarak herhangi bir IP adresi veya ana bilgisayar adı üzerindeki istekleri dinlemesi gerektiğini belirtmek için "*" kullanın. Protokol (http:// veya https://) her URL'ye eklenmelidir. Desteklenen biçimler sunucular arasında farklılık gösterir.

Anahtar: urls
Tür: string
Varsayılan: http://localhost:5000 ve https://localhost:5001
Ortam değişkeni: {PREFIX_}URLS

Bu değeri ayarlamak için ortam değişkenini kullanın veya öğesini çağırın UseUrls:

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

Kestrel kendi uç nokta yapılandırma API'sine sahiptir. Daha fazla bilgi için bkz . ASP.NET Core Kestrel web sunucusu için uç noktaları yapılandırma.

Webroot

IWebHostEnvironment.WebRootPath özelliği, uygulamanın statik varlıklarının göreli yolunu belirler. Yol yoksa, işlem yapılmayan bir dosya sağlayıcısı kullanılır.

Anahtar: webroot
Tür: string
Varsayılan: Varsayılan değerdir wwwroot. {content root}/wwwroot yolunun mevcut olması gerekir.
Ortam değişkeni: {PREFIX_}WEBROOT

Bu değeri ayarlamak için ortam değişkenini kullanın veya üzerinde öğesini çağırın UseWebRootIWebHostBuilder:

webBuilder.UseWebRoot("public");

Daha fazla bilgi için bkz.

Konak ömrünü yönetme

Uygulamayı başlatmak ve durdurmak için yerleşik IHost uygulamada yöntemleri çağırın. Bu yöntemler, hizmet kapsayıcısında kayıtlı olan tüm IHostedService uygulamaları etkiler.

ve Start* yöntemleri arasındaki Run* fark, yöntemlerin Run* döndürmeden önce konağın tamamlanmasını beklemesi, yöntemlerin ise Start* hemen döndürülmesidir. Yöntemler Run* genellikle konsol uygulamalarında kullanılırken Start* , yöntemler genellikle uzun süre çalışan hizmetlerde kullanılır.

Çalıştır

Run uygulamayı çalıştırır ve konak kapatana kadar çağıran iş parçacığını engeller.

RunAsync

RunAsync uygulamayı çalıştırır ve iptal belirteci veya kapatma tetiklendiğinde tamamlanan bir Task döndürür.

RunConsoleAsync

RunConsoleAsynckonsol desteğini etkinleştirir, konağı derler ve başlatır ve Ctrl+C/SIGINT (Windows), ⌘+C (macOS) veya SIGTERM'nin kapatılmasını bekler.

Başlangıç

Start konağı zaman uyumlu olarak başlatır.

StartAsync

StartAsync konağı başlatır ve iptal belirteci veya kapatma tetiklendiğinde tamamlanan bir Task döndürür.

WaitForStartAsync , devam etmeden önce tamamlanana kadar bekleyen öğesinin StartAsyncbaşında çağrılır. Bu yöntem, bir dış olay tarafından sinyal alınana kadar başlatmayı geciktirmek için kullanılabilir.

StopAsync

StopAsync sağlanan zaman aşımı içinde konağı durdurmaya çalışır.

WaitForShutdown

WaitForShutdownCtrl+C/SIGINT (Windows), ⌘C (macOS) veya SIGTERM gibi kapatma IHostLifetime tarafından tetiklenene+ kadar çağıran iş parçacığını engeller.

WaitForShutdownAsync

WaitForShutdownAsyncverilen belirteç aracılığıyla kapatma tetiklendiğinde ve çağrısı StopAsyncyapıldığında tamamlanan bir Task döndürür.

Dış denetim

Konak ömrünün doğrudan denetimi, dışarıdan çağrılabilen yöntemler kullanılarak elde edilebilir:

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

ASP.NET Core şablonları bir .NET Core Genel Ana Bilgisayarı (HostBuilder ) oluşturur.

Bu makale, ASP.NET Core'da .NET Genel Ana Bilgisayarı kullanma hakkında bilgi sağlar. Konsol uygulamalarında .NET Genel Ana Bilgisayarı kullanma hakkında bilgi için bkz . .NET Genel Ana Bilgisayarı.

Konak tanımı

Konak, bir uygulamanın kaynaklarını kapsülleyen bir nesnedir, örneğin:

  • Bağımlılık ekleme (DI)
  • Günlük Kaydı
  • Yapılandırma
  • IHostedService Uygulama

Bir konak başlatıldığında, hizmet kapsayıcısının barındırılan IHostedService hizmetler koleksiyonunda kayıtlı olan her uygulamasını çağırırIHostedService.StartAsync. Bir web uygulamasında, uygulamalardan IHostedService biri HTTP sunucusu uygulamasını başlatan bir web hizmetidir.

Uygulamanın tüm birbirine bağlı kaynaklarını tek bir nesneye eklemenin temel nedeni yaşam süresi yönetimidir: uygulama başlatma ve düzgün kapatma üzerinde denetim.

Konak ayarlama

Konak genellikle sınıfında kodla Program yapılandırılır, oluşturulur ve çalıştırılır. Main yöntemi:

  • CreateHostBuilder Oluşturucu nesnesi oluşturmak ve yapılandırmak için bir yöntem çağırır.
  • Oluşturucu nesnesinde çağrılar Build ve Run yöntemler.

ASP.NET Core web şablonları, Genel Konak oluşturmak için aşağıdaki kodu oluşturur:

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

Aşağıdaki kod, HTTP olmayan iş yükü kullanarak genel bir Konak oluşturur. Uygulama IHostedService DI kapsayıcısına eklenir:

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

BIR HTTP iş yükü için Main yöntemi aynıdır ancak CreateHostBuilder öğesini çağırır ConfigureWebHostDefaults:

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

Yukarıdaki kod, ASP.NET Core şablonları tarafından oluşturulur.

Uygulama Entity Framework Core kullanıyorsa yöntemin adını veya imzasını değiştirmeyin CreateHostBuilder . Entity Framework Core araçları, uygulamayı çalıştırmadan konağı yapılandıran bir CreateHostBuilder yöntem bulmayı bekler. Daha fazla bilgi için bkz . Tasarım zamanı DbContext Oluşturma.

Varsayılan oluşturucu ayarları

CreateDefaultBuilder yöntemi:

  • İçerik kökünü tarafından GetCurrentDirectorydöndürülen yola ayarlar.
  • Konak yapılandırmasını şu kaynaktan yükler:
    • ile önekli DOTNET_ortam değişkenleri.
    • Komut satırı bağımsız değişkenleri.
  • Uygulama yapılandırmasını şu kaynaktan yükler:
    • appsettings.json.
    • appsettings.{Environment}.json.
    • Uygulama Development ortamında çalıştığında kullanıcı gizli dizileri.
    • Ortam değişkenleri.
    • Komut satırı bağımsız değişkenleri.
  • Aşağıdaki günlük sağlayıcılarını ekler:
    • Konsol
    • Hata Ayıklama
    • EventSource
    • EventLog (yalnızca Windows üzerinde çalışırken)
  • Ortam Geliştirme olduğunda kapsam doğrulamasını ve bağımlılık doğrulamasını etkinleştirir.

ConfigureWebHostDefaults yöntemi:

  • ön ekli ASPNETCORE_ortam değişkenlerinden konak yapılandırmasını yükler.
  • Sunucuyu web sunucusu olarak ayarlar Kestrel ve uygulamanın barındırma yapılandırma sağlayıcılarını kullanarak yapılandırılır. Sunucunun Kestrel varsayılan seçenekleri için bkz Kestrel . ASP.NET Core'da web sunucusu.
  • Konak Filtreleme ara yazılımı ekler.
  • eşitse trueASPNETCORE_FORWARDEDHEADERS_ENABLED İletilen Üst Bilgiler ara yazılımı ekler.
  • IIS tümleştirmesini etkinleştirir. IIS varsayılan seçenekleri için bkz . IIS ile Windows'ta Konak ASP.NET Çekirdeği.

Bu makalenin devamında tüm uygulama türleri için Ayarlar ve web uygulamaları için Ayarlar bölümlerinde varsayılan oluşturucu ayarlarının nasıl geçersiz kılınacakları gösterilmektedir.

Çerçeve tarafından sağlanan hizmetler

Aşağıdaki hizmetler otomatik olarak kaydedilir:

Çerçeve tarafından sağlanan hizmetler hakkında daha fazla bilgi için bkz . ASP.NET Core'da bağımlılık ekleme.

IHostApplicationLifetime

IHostApplicationLifetime Başlatma sonrası ve düzgün kapatma görevlerini işlemek için herhangi bir sınıfa (eski adıylaIApplicationLifetime) hizmet ekleme. Arabirimdeki üç özellik, uygulama başlatma ve uygulama durdurma olay işleyicisi yöntemlerini kaydetmek için kullanılan iptal belirteçleridir. Arabirim bir yöntem de içerir StopApplication .

Aşağıdaki örnek, olayları kaydeden IHostApplicationLifetime bir IHostedService uygulamadır:

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

Uygulama, IHostLifetime konağın ne zaman başlayacağını ve ne zaman durduğunda denetler. Kaydedilen son uygulama kullanılır.

Microsoft.Extensions.Hosting.Internal.ConsoleLifetime varsayılan IHostLifetime uygulamadır. ConsoleLifetime:

IHostEnvironment

IHostEnvironment Aşağıdaki ayarlar hakkında bilgi almak için hizmeti bir sınıfa ekleyin:

Web uygulamaları, WebRootPath'i devralan IHostEnvironment ve ekleyen arabirimini uygularIWebHostEnvironment.

Konak yapılandırması

Ana bilgisayar yapılandırması, uygulamanın özellikleri IHostEnvironment için kullanılır.

Konak yapılandırması içinden HostBuilderContext.ConfigurationConfigureAppConfigurationkullanılabilir. HostBuilderContext.Configuration'nin ardındanConfigureAppConfiguration, uygulama yapılandırmasıyla değiştirilir.

Konak yapılandırması eklemek için çağrısında ConfigureHostConfiguration bulunur IHostBuilder. ConfigureHostConfiguration eklenebilir sonuçlarla birden çok kez çağrılabilir. Konak, belirli bir anahtarda en son değer ayarlayan seçeneği kullanır.

Ön ek DOTNET_ ve komut satırı bağımsız değişkenlerine sahip ortam değişkeni sağlayıcısı tarafından CreateDefaultBuilderdahil edilir. Web uygulamaları için, ön ekli ASPNETCORE_ ortam değişkeni sağlayıcısı eklenir. Ortam değişkenleri okunduğunda ön ek kaldırılır. Örneğin, için ASPNETCORE_ENVIRONMENT ortam değişkeni değeri anahtarın konak yapılandırma değeri environment olur.

Aşağıdaki örnek konak yapılandırması oluşturur:

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

Uygulama yapılandırması

Uygulama yapılandırması, üzerinde IHostBuilderçağrılarak ConfigureAppConfiguration oluşturulur. ConfigureAppConfiguration eklenebilir sonuçlarla birden çok kez çağrılabilir. Uygulama, belirli bir anahtarda en son değer ayarlayan seçeneği kullanır.

tarafından ConfigureAppConfiguration oluşturulan yapılandırma, sonraki işlemler için ve DI'den bir hizmet olarak kullanılabilir HostBuilderContext.Configuration . Konak yapılandırması, uygulama yapılandırmasına da eklenir.

Daha fazla bilgi için, bkz. ASP.NET Core’da yapılandırma analizi.

Tüm uygulama türleri için Ayarlar

Bu bölümde hem HTTP hem de HTTP olmayan iş yüklerine uygulanan konak ayarları listelenir. Varsayılan olarak, bu ayarları yapılandırmak için kullanılan ortam değişkenleri, yer tutucu için aşağıdaki yapılandırmada görünen veya DOTNET_ASPNETCORE_ ön ekine {PREFIX_} sahip olabilir.

ApplicationName

IHostEnvironment.ApplicationName Özelliği, konak oluşturma sırasında konak yapılandırmasından ayarlanır.

Anahtar: applicationName
Tür: string
Varsayılan: Uygulamanın giriş noktasını içeren derlemenin adı.
Ortam değişkeni: {PREFIX_}APPLICATIONNAME

Bu değeri ayarlamak için ortam değişkenini kullanın.

ContentRoot

özelliği, IHostEnvironment.ContentRootPath konağın içerik dosyalarını aramaya nereden başladığını belirler. Yol yoksa konak başlatılamaz.

Anahtar: contentRoot
Tür: string
Varsayılan: Uygulama derlemesinin bulunduğu klasör.
Ortam değişkeni: {PREFIX_}CONTENTROOT

Bu değeri ayarlamak için ortam değişkenini kullanın veya üzerinde öğesini çağırın UseContentRootIHostBuilder:

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

Daha fazla bilgi için bkz.

EnvironmentName

IHostEnvironment.EnvironmentName özelliği herhangi bir değere ayarlanabilir. Çerçeve tanımlı değerler , Stagingve Productiondeğerlerini içerirDevelopment. Değerler büyük/küçük harfe duyarlı değildir.

Anahtar: environment
Tür: string
Varsayılan: Production
Ortam değişkeni: {PREFIX_}ENVIRONMENT

Bu değeri ayarlamak için ortam değişkenini kullanın veya üzerinde öğesini çağırın UseEnvironmentIHostBuilder:

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

ShutdownTimeout

HostOptions.ShutdownTimeout için StopAsynczaman aşımını ayarlar. Varsayılan değer beş saniyedir. Zaman aşımı süresi boyunca konak:

Barındırılan hizmetlerin tümü durdurulmadan zaman aşımı süresi dolarsa, uygulama kapatıldığında kalan tüm etkin hizmetler durdurulur. İşlemleri tamamlamamış olsalar bile hizmetler durduruluyor. Hizmetlerin durdurulması için daha fazla zaman gerekiyorsa zaman aşımını artırın.

Anahtar: shutdownTimeoutSeconds
Tür: int
Varsayılan: 5 saniye
Ortam değişkeni: {PREFIX_}SHUTDOWNTIMEOUTSECONDS

Bu değeri ayarlamak için ortam değişkenini kullanın veya yapılandırın HostOptions. Aşağıdaki örnek zaman aşımını 20 saniye olarak ayarlar:

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

Web uygulamaları için Ayarlar

Bazı konak ayarları yalnızca HTTP iş yükleri için geçerlidir. Varsayılan olarak, bu ayarları yapılandırmak için kullanılan ortam değişkenlerinin bir DOTNET_ veya ASPNETCORE_ ön eki olabilir.

Üzerindeki IWebHostBuilder uzantı yöntemleri bu ayarlar için kullanılabilir. Uzantı yöntemlerinin nasıl çağrıldığını gösteren kod örnekleri, aşağıdaki örnekte olduğu gibi öğesinin IWebHostBuilderbir örneği olduğunu varsayarwebBuilder:

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

CaptureStartupErrors

olduğunda false, başlatma sırasındaki hatalar konağın çıkmasıyla sonuçlanır. olduğunda true, konak başlatma sırasında özel durumları yakalar ve sunucuyu başlatmayı dener.

Anahtar: captureStartupErrors
Tür: bool (true/1 veya false/0)
Varsayılan: false Uygulama IIS'nin arkasında çalıştırılmadığı Kestrel sürece varsayılan olarak ayarlanır ve burada varsayılan değeri olur true.
Ortam değişkeni: {PREFIX_}CAPTURESTARTUPERRORS

Bu değeri ayarlamak için yapılandırmayı kullanın veya öğesini çağırin CaptureStartupErrors:

webBuilder.CaptureStartupErrors(true);

DetailedErrors

Etkinleştirildiğinde veya ortam olduğunda Developmentuygulama ayrıntılı hataları yakalar.

Anahtar: detailedErrors
Tür: bool (true/1 veya false/0)
Varsayılan: false
Ortam değişkeni: {PREFIX_}DETAILEDERRORS

Bu değeri ayarlamak için yapılandırmayı kullanın veya öğesini çağırin UseSetting:

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

HostingStartupAssemblies

Başlatma sırasında yüklenecek barındırma başlangıç derlemelerinin noktalı virgülle ayrılmış dizesi. Yapılandırma değeri varsayılan olarak boş bir dize olsa da, barındırma başlangıç derlemeleri her zaman uygulamanın derlemesini içerir. Barındırma başlangıç derlemeleri sağlanırken, uygulama başlatma sırasında ortak hizmetlerini oluştururken yüklenmek üzere uygulamanın derlemesine eklenirler.

Anahtar: hostingStartupAssemblies
Tür: string
Varsayılan: Boş dize
Ortam değişkeni: {PREFIX_}HOSTINGSTARTUPASSEMBLIES

Bu değeri ayarlamak için yapılandırmayı kullanın veya öğesini çağırin UseSetting:

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

HostingStartupExcludeAssemblies

Başlatma sırasında hariç tutulacak, barındırma başlangıç derlemelerinin noktalı virgülle ayrılmış dizesi.

Anahtar: hostingStartupExcludeAssemblies
Tür: string
Varsayılan: Boş dize
Ortam değişkeni: {PREFIX_}HOSTINGSTARTUPEXCLUDEASSEMBLIES

Bu değeri ayarlamak için yapılandırmayı kullanın veya öğesini çağırin UseSetting:

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

HTTPS_Port

HTTPS yeniden yönlendirme bağlantı noktası. HTTPS zorlamada kullanılır.

Anahtar: https_port
Tür: string
Varsayılan: Varsayılan değer ayarlanmadı.
Ortam değişkeni: {PREFIX_}HTTPS_PORT

Bu değeri ayarlamak için yapılandırmayı kullanın veya öğesini çağırin UseSetting:

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

PreferHostingUrls

Konağın uygulamayla yapılandırılan URL'ler yerine ile IWebHostBuilder yapılandırılan URL'leri dinlemesi IServer gerekip gerekmediğini gösterir.

Anahtar: preferHostingUrls
Tür: bool (true/1 veya false/0)
Varsayılan: false
Ortam değişkeni: {PREFIX_}PREFERHOSTINGURLS

Bu değeri ayarlamak için ortam değişkenini kullanın veya öğesini çağırın PreferHostingUrls:

webBuilder.PreferHostingUrls(true);

PreventHostingStartup

Uygulamanın derlemesi tarafından yapılandırılan barındırma başlangıç derlemeleri de dahil olmak üzere barındırma başlangıç derlemelerinin otomatik yüklenmesini engeller. Daha fazla bilgi için, bkz. ASP.NET Core'da barındırma başlangıç derlemelerini kullanma.

Anahtar: preventHostingStartup
Tür: bool (true/1 veya false/0)
Varsayılan: false
Ortam değişkeni: {PREFIX_}PREVENTHOSTINGSTARTUP

Bu değeri ayarlamak için ortam değişkenini kullanın veya öğesini çağırın UseSetting :

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

StartupAssembly

Sınıfını aramak için derleme Startup .

Anahtar: startupAssembly
Tür: string
Varsayılan: Uygulamanın derlemesi
Ortam değişkeni: {PREFIX_}STARTUPASSEMBLY

Bu değeri ayarlamak için ortam değişkenini kullanın veya komutunu çağırın UseStartup. UseStartup bir derleme adı (string) veya tür (TStartup) alabilir. Birden çok UseStartup yöntem çağrılırsa, sonuncusu öncelikli olur.

webBuilder.UseStartup("StartupAssemblyName");

webBuilder.UseStartup<Startup>();

SuppressStatusMessages

Etkinleştirildiğinde, barındırma başlatma durumu iletilerini gizler.

Anahtar: suppressStatusMessages
Tür: bool (true/1 veya false/0)
Varsayılan: false
Ortam değişkeni: {PREFIX_}SUPPRESSSTATUSMESSAGES

Bu değeri ayarlamak için yapılandırmayı kullanın veya öğesini çağırin UseSetting:

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

URL'ler

Sunucunun istekler için dinlemesi gereken bağlantı noktalarına ve protokollere sahip IP adreslerinin veya konak adreslerinin noktalı virgülle ayrılmış listesi. Örneğin, http://localhost:123. Sunucunun belirtilen bağlantı noktasını ve protokolü (örneğin, http://*:5000) kullanarak herhangi bir IP adresi veya ana bilgisayar adı üzerindeki istekleri dinlemesi gerektiğini belirtmek için "*" kullanın. Protokol (http:// veya https://) her URL'ye eklenmelidir. Desteklenen biçimler sunucular arasında farklılık gösterir.

Anahtar: urls
Tür: string
Varsayılan: http://localhost:5000 ve https://localhost:5001
Ortam değişkeni: {PREFIX_}URLS

Bu değeri ayarlamak için ortam değişkenini kullanın veya öğesini çağırın UseUrls:

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

Kestrel kendi uç nokta yapılandırma API'sine sahiptir. Daha fazla bilgi için bkz Kestrel . ASP.NET Core'da web sunucusu.

Webroot

IWebHostEnvironment.WebRootPath özelliği, uygulamanın statik varlıklarının göreli yolunu belirler. Yol yoksa, işlem yapılmayan bir dosya sağlayıcısı kullanılır.

Anahtar: webroot
Tür: string
Varsayılan: Varsayılan değerdir wwwroot. {content root}/wwwroot yolunun mevcut olması gerekir.
Ortam değişkeni: {PREFIX_}WEBROOT

Bu değeri ayarlamak için ortam değişkenini kullanın veya üzerinde öğesini çağırın UseWebRootIWebHostBuilder:

webBuilder.UseWebRoot("public");

Daha fazla bilgi için bkz.

Konak ömrünü yönetme

Uygulamayı başlatmak ve durdurmak için yerleşik IHost uygulamada yöntemleri çağırın. Bu yöntemler, hizmet kapsayıcısında kayıtlı olan tüm IHostedService uygulamaları etkiler.

ve Start* yöntemleri arasındaki Run* fark, yöntemlerin Run* döndürmeden önce konağın tamamlanmasını beklemesi, yöntemlerin ise Start* hemen döndürülmesidir. Yöntemler Run* genellikle konsol uygulamalarında kullanılırken Start* , yöntemler genellikle uzun süre çalışan hizmetlerde kullanılır.

Çalıştır

Run uygulamayı çalıştırır ve konak kapatana kadar çağıran iş parçacığını engeller.

RunAsync

RunAsync uygulamayı çalıştırır ve iptal belirteci veya kapatma tetiklendiğinde tamamlanan bir Task döndürür.

RunConsoleAsync

RunConsoleAsynckonsol desteğini etkinleştirir, konağı derler ve başlatır ve Ctrl+C/SIGINT (Windows), ⌘+C (macOS) veya SIGTERM'nin kapatılmasını bekler.

Başlangıç

Start konağı zaman uyumlu olarak başlatır.

StartAsync

StartAsync konağı başlatır ve iptal belirteci veya kapatma tetiklendiğinde tamamlanan bir Task döndürür.

WaitForStartAsync , devam etmeden önce tamamlanana kadar bekleyen öğesinin StartAsyncbaşında çağrılır. Bu yöntem, bir dış olay tarafından sinyal alınana kadar başlatmayı geciktirmek için kullanılabilir.

StopAsync

StopAsync sağlanan zaman aşımı içinde konağı durdurmaya çalışır.

WaitForShutdown

WaitForShutdownCtrl+C/SIGINT (Windows), ⌘C (macOS) veya SIGTERM gibi kapatma IHostLifetime tarafından tetiklenene+ kadar çağıran iş parçacığını engeller.

WaitForShutdownAsync

WaitForShutdownAsyncverilen belirteç aracılığıyla kapatma tetiklendiğinde ve çağrısı StopAsyncyapıldığında tamamlanan bir Task döndürür.

Dış denetim

Konak ömrünün doğrudan denetimi, dışarıdan çağrılabilen yöntemler kullanılarak elde edilebilir:

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

Ek kaynaklar