ASP.NET Core'da uygulama başlatma

Note

Bu, bu makalenin en son sürümü değildir. Geçerli sürüm için bu makalenin .NET 10 sürümüne bakın.

Warning

ASP.NET Core'un bu sürümü artık desteklenmiyor. Daha fazla bilgi için bkz . .NET ve .NET Core Destek İlkesi. Geçerli sürüm için bu makalenin .NET 10 sürümüne bakın.

Bu makalede, ASP.NET Core uygulamaların nasıl başlatıldığı ve hizmetlerin ve uygulamanın istek işlem hattının nasıl yapılandırıldığı açıklanır.

Blazor Bu makaledeki yönergeleri ekleyen veya yerine geçen başlangıç kılavuzu için bkz. ASP.NET Core Blazor başlatma.

Dosya Program

ASP.NET Core uygulamaları, başlangıcı uygulamanın Program dosyasında (Program.cs) başlatır ve yapılandırır.

Dosyanın ilk bölümü Program , uygulamayı oluşturmaya odaklanır. Bu aşama, uygulama başlatılmadan önce önceden yapılandırılmış varsayılanlarla sınıfın WebApplicationBuilder yeni bir örneğini başlatmak için kullanılırWebApplication.CreateBuilder. ASP.NET Core proje şablonları web uygulaması oluşturucusunu adlı builderbir değişkene atar:

var builder = WebApplication.CreateBuilder(args);

Web uygulaması oluşturucusunun özellikleri şunlardır:

Uygulama, oluşturulmuş WebApplication öğesini döndüren WebApplicationBuilder.Build çağrılarak oluşturulur. ASP.NET Core proje şablonları, yerleşik web uygulamasını adlı appbir değişkene atar:

var app = builder.Build();

Dosyanın bir sonraki bölümü Program , HTTP isteği işleme işlem hattını bir dizi ara yazılım bileşeni olarak oluşturmaya odaklanır. Her ara yazılım bir HttpContext üzerinde işlemler gerçekleştirir ve işlem hattında sonraki ara yazılımı çağırır veya isteği sonlandırır. Kural gereği, ara yazılım bileşenleri "Use." ile başlayan bir uzantı yöntemi çağrılarak işlem hattına eklenir. Daha fazla bilgi için bkz. ara yazılım ASP.NET Core.

Run yöntemi uygulamayı başlatır ve ana bilgisayar kapatılana kadar çağıran iş parçacığını bloke eder:

app.Run();

Run yürütüldüğünde, uygulama etkin, çalışan bir sürece geçer:

  1. Barındırılan hizmetler başlatılır.

    Ana bilgisayar, tüm kayıtlı barındırılan hizmetler (IHostedService örnekleri) üzerinde döngü kurar ve StartAsync yöntemlerini çağırır. Uygulama eşzamanlı barındırılan hizmet başlatmayı kabul etmediği sürece (.NET 8 veya üzeri), barındırılan hizmetler DI kapsayıcı kayıtları sırasına göre sıralı olarak başlar. Daha fazla bilgi için bkz. ASP.NET Core barındırılan hizmetlerle arka plan görevleri.

  2. Ara katman işlem hattı oluşturuldu.

    Çağrıldığında builder.Build bağımlılıklar çözümlenir, ancak gerçek işlem hattı tam olarak ayarlanmadı. app.Run çalıştırıldığında çerçeve, HTTP ara yazılım işlem hattını sonlandırır. Bildirilen ara yazılım yöntemleri ve uç nokta eşlemeleri tek, yüksek performanslı yürütme temsilcisi dizisinde derlenir. Daha fazla bilgi için bkz. ASP.NET Core ara yazılımı.

  3. Web sunucusu (Kestrel varsayılan olarak) başlatılır.

    Konak bağımlılık kapsayıcısının içine bakar, kayıtlı sunucu uygulamasını (genellikle Kestrel) bulur ve başlatma döngüsünü tetikler. Kestrel ardından:

    • Yapılandırma, ortam değişkenleri veya komut satırı bağımsız değişkenlerinden tanımlı barındırma URL'lerini ve bağlantı noktalarını arar.
    • Fiziksel ağ yuvalarını açar ve ayırır.
    • Bağlantı noktalarını bağlar ve gelen trafiği dinlemeye başlar.

    Daha fazla bilgi için bkz. ASP.NET Core'da genel ana bilgisayar .NET, ASP.NET Core'da Web sunucusu uygulamaları ve Kestrel ASP.NET Core'da web sunucusu.

  4. Uygulama başlatıldığında yaşam döngüsü olayları tetiklenir.

    IHostApplicationLifetime hizmeti, ApplicationStarted belirtecini tetikler; bu da belirteç üzerine kaydedilmiş geri çağırmaları çağırır. Belirtecin tetiklenmesini bekleyecek şekilde yapılandırılmış tüm geri çağrı işlevleri, veritabanı başlatıcıları veya diğer özel olay dinleyicileri işlemeye başlamak üzere tetiklenir.

  5. Uygulama çalışırken ana yürütme iş parçacığı bloklanır.

    Run (app.Run()) kapatılana kadar eşzamanlı olarak bekler.

  6. Uygulama istekleri işlemeye hazırdır.

    Bu noktada, komut kabuğu barındırma tanılamalarını günlüğe kaydeder:

    info: Microsoft.Hosting.Lifetime[14]
      Now listening on: https://localhost:7123
info: Microsoft.Hosting.Lifetime[14]
      Now listening on: http://localhost:5123
info: Microsoft.Hosting.Lifetime[0]
      Application started. Press Ctrl+C to shut down.

Uygulama süresiz olarak bu durumda kalır ve gelen web trafiğini ara yazılım işlem hattından geçirir ve yanıtlar gönderir.

Kapatma sinyali alındığında, örneğin uygulamayı çalıştıran komut kabuğunda Ctrl+c algılandığında veya bir kapsayıcı orkestrasyon aracı SIGTERM sinyali gönderdiğinde, Run engeli kalkar ve aşağıdaki işlemler gerçekleşir:

  1. ApplicationStopping belirteçler tetiklenir ve bu da uygulamanın kapatma işlemi başlamadan önce mantık çalıştırmasına olanak tanır.

  2. Sunucu Kestrel kapatılır 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, var olan bağlantılar üzerinde yapılacak ek istekler için bağlantı kapatma başlığını gönderir.

  3. Ana bilgisayar, kayıtlı barındırılan hizmetleri durdurur. Uygulama, barındırılan hizmetlerin eşzamanlı olarak durdurulmasını tercih etmediği sürece (.NET 8 veya sonrası), barındırılan hizmetler DI kapsayıcısındaki kayıt sıralarının tersine göre sırayla durdurulur. Daha fazla bilgi için bkz. ASP.NET Core barındırılan hizmetlerle arka plan görevleri.

  4. ApplicationStopped olay işleyicileri tetiklenir ve uygulama kapatıldıktan sonra uygulamanın mantık çalıştırmasına olanak tanır.

  5. Konsol yürütmesi, 0 çıkış koduyla sorunsuz bir şekilde sonlanır.

Startup sınıfı hizmetleri ve uygulamanın istek işlem hattını yapılandırmaktadır.

Startup sınıfı

ASP.NET Core uygulamalar, kural tarafından adlandırılan Startup bir başlangıç sınıfı kullanır. Startup sınıfı:

  • İsteğe bağlı olarak uygulamanın hizmetlerini yapılandırmak için bir ConfigureServices yöntemi içerir. Hizmet, uygulama işlevselliği sağlayan yeniden kullanılabilir bir bileşendir. Hizmetler kaydedilir ve uygulama genelinde ConfigureServices veya aracılığıyla tüketilir.
  • Uygulamanın istek işleme işlem hattını oluşturmak için bir Configure yöntem içerir.

ConfigureServices ve Configure uygulama başlatıldığında ASP.NET Core çalışma zamanı tarafından çağrılır:

public class Startup
{
    public void ConfigureServices(IServiceCollection services)
    {
        ...
    }

    public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
    {
        ...
    }
}

Sınıfı Startup , uygulamanın konağı oluşturulduğunda belirtilir. Startup sınıfı genellikle ana bilgisayar oluşturucusunda WebHostBuilderExtensions.UseStartup çağrılarak belirtilir:

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

Sunucu, Startup sınıf oluşturucusunun kullanabileceği hizmetler sağlar. Uygulama ConfigureServices aracılığıyla ek hizmetler ekler. Ana bilgisayar ve uygulama hizmetleri, gerek Configure gerekse uygulama genelinde kullanılabilir.

Yalnızca aşağıdaki hizmet türleri Startup oluşturucuya Genel Ana Bilgisayar (IHostBuilder) kullanılırken eklenebilir.

public class Startup
{
    private readonly IWebHostEnvironment _env;

    public Startup(IConfiguration configuration, IWebHostEnvironment env)
    {
        Configuration = configuration;
        _env = env;
    }

    public IConfiguration Configuration { get; }

    public void ConfigureServices(IServiceCollection services)
    {
        if (_env.IsDevelopment())
        {
        }
        else
        {
        }
    }
}

Çoğu hizmet, Configure yöntemi çağrılana kadar kullanılamaz.

Note

Yukarıdaki örnekteki IWebHostEnvironment özel alan bir alt çizgi (_env ) ile adlandırılmıştır. Özel alan this.env = env kullandığında (this oluşturucuda ve ConfigureServices yönteminde), enjekte edilen env.IsDevelopment() ile (IWebHostEnvironment) aynı adı kullanan bir kodlama kuralını benimsemek de kabul edilebilir.

.NET 8 ve C# 12 öncesi ASP.NET Core proje şablonları birincil oluşturucuları benimsemez, ancak kuruluşunuz .NET 8 veya sonraki bir SDK kullanıyorsa ve uygulama C# 12 veya üstünü hedeflerse (örneğin, <LangVersion>12.0</LangVersion>) önceki kod birincil oluşturucuyu benimsemek için yeniden düzenleyebilir. Daha fazla bilgi için bkz. Sınıflar ve yapılar için birincil oluşturucuları bildirme (C# belgeleri öğreticisi) ve Birincil oluşturucular (C# Kılavuzu).

Birden çok Startup sınıf

Uygulama farklı ortamlar için ayrı Startup sınıflar tanımladığında (örneğin, StartupDevelopment), çalışma zamanında uygun Startup sınıf seçilir. Mevcut çevre ile ad eki eşleşen sınıfa öncelik verilir. Uygulama ortamda Development çalıştırılırsa ve hem sınıf Startup hem de sınıf StartupDevelopment içeriyorsa, StartupDevelopment sınıfı kullanılır. Daha fazla bilgi için bkz . Birden çok ortam kullanma.

ConfigureServices yöntemi

İsteğe bağlı ConfigureServices yöntem:

  • Yöntem Configure çalıştırılmadan önce, uygulamanın hizmetlerini yapılandırmak için ana bilgisayar tarafından çağrılır.
  • Yapılandırma seçeneklerinin kurala göre ayarlandığı yer.

Sunucu, yöntemler çağrılmadan önce Startup bazı hizmetleri yapılandırabilir. Daha fazla bilgi için bkz. ASP.NET Temel bilgilere genel bakış.

Kapsamlı yapılandırma gerektiren özellikler için, Add{Service} üzerinde, örneğin şu IServiceCollection genişletme yöntemleri vardır:

  • AddDbContext
  • AddDefaultIdentity
  • AddEntityFrameworkStores
  • AddRazorPages
public class Startup
{
    public Startup(IConfiguration configuration)
    {
        Configuration = configuration;
    }

    public IConfiguration Configuration { get; }

    public void ConfigureServices(IServiceCollection services)
    {

        services.AddDbContext<ApplicationDbContext>(options =>
            options.UseSqlServer(
                Configuration.GetConnectionString("DefaultConnection")));
        services.AddDefaultIdentity<IdentityUser>(
            options => options.SignIn.RequireConfirmedAccount = true)
            .AddEntityFrameworkStores<ApplicationDbContext>();

        services.AddRazorPages();
    }
}

Hizmet kapsayıcısına hizmet eklemek, bunların uygulama içinde ve Configure yönteminde kullanılabilir olmasını sağlar. Hizmetler, bağımlılık enjeksiyonu veya ApplicationServices aracılığıyla çözülür.

Configure yöntemi

Configure yöntemi, uygulamanın HTTP isteklerine nasıl yanıt vereceğini belirtmek için kullanılır. İstek işlem hattı, ara yazılım bileşenlerinin bir IApplicationBuilder örneğine eklenmesiyle yapılandırılır. IApplicationBuilder Configure metoduna kullanılabilir, ancak hizmet kapsayıcısında kayıtlı değildir. Barındırma bir IApplicationBuilder oluşturur ve bunu doğrudan Configure öğesine geçirir.

ASP.NET Core şablonları işlem hattını aşağıdakiler için destekle yapılandırmaktadır:

Aşağıdaki örnekte tipik Razor bir Pages uygulaması için ara yazılım gösterilmektedir:

public class Startup
{
    public void ConfigureServices(IServiceCollection services)
    {
        services.AddRazorPages();
    }

    public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
    {
        if (env.IsDevelopment())
        {
            app.UseDeveloperExceptionPage();
        }
        else
        {
            app.UseExceptionHandler("/Error");
            app.UseHsts();
        }

        app.UseHttpsRedirection();
        app.UseStaticFiles();
        app.UseRouting();

        app.UseEndpoints(endpoints =>
        {
            endpoints.MapRazorPages();
        });
    }
}

Yukarıdaki örnek Sayfalar içindir; MVC sürümü benzerdir.

Her Use uzantı yöntemi, istek işlem hattına bir veya daha fazla ara yazılım bileşeni ekler. Örneğin, UseStaticFiles statik dosyaları ara yazılımın sunması için yapılandırır.

İstek işlem hattındaki her ara yazılım bileşeni, işlem hattında sonraki bileşeni çağırmak veya uygunsa zinciri kısa devre yapmakla yükümlüdür.

Yöntem imzasında, IWebHostEnvironment gibi ek hizmetler, ILoggerFactory veya ConfigureServices içinde tanımlanan herhangi bir şey belirtilebilir. Bu hizmetler kullanılabilir durumdaysa eklenir.

IApplicationBuilder öğesinin nasıl kullanılacağı ve ara yazılım işleme sırası hakkında daha fazla bilgi için ASP.NET Core ara yazılımı bölümüne bakın.

Startup sınıfı olmadan hizmetleri yapılandırma

Hizmetleri ve istek işleme işlem hattını bir Startup sınıfı kullanmadan yapılandırmak için host builder'ı üzerinde ConfigureServices ve Configure kolaylık yöntemlerini çağırın. Birbirinin sonuna ConfigureServices eklenecek birden çok çağrı. Birden çok Configure yöntem çağrısı varsa, son Configure çağrı kullanılır.

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

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureAppConfiguration((hostingContext, config) =>
            {
            })
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.ConfigureServices(services =>
                {
                    ...
                })
                .Configure(app =>
                {
                    ...
                });
        });
}

Başlangıç filtreleri

Bir uygulama genellikle açık bir ara yazılım yürütme işlem hattı oluştururken, başlangıç filtresi (IStartupFilter) şunlar için kullanışlıdır:

  • Uygulamanın ara yazılımının "Use" yöntemini açıkça çağırmasına gerek kalmadan özel ara yazılımı otomatik olarak yükleyen paylaşılan bir kitaplık/NuGet paketi oluşturma. Örneğin, kitaplığın tüketicisinin uygulamanın istek işleme işlem hattındaki bir görüntü işleme ara yazılımı için app.UseImageProcessingMiddleware çağrısı yapması gerekmez.
  • Bir ara yazılım parçasının, bir geliştiricinin uygulamanın istek işleme işlem hattını nasıl değiştirdiğine bakılmaksızın diğer ara yazılımdan önce veya sonra yürütülmesini garanti eder.

Bir başlangıç filtresi uygulaması, bir Action<IApplicationBuilder> alan ve döndüren bir IStartupFilter.Configure yöntem sağlar. Arabirim IApplicationBuilder , uygulamanın istek işlem hattını yapılandırmak için kullanılır. Daha fazla bilgi için bkz. IApplicationBuilder ile ara yazılım işlem hattı oluşturma.

Her başlangıç filtresi uygulaması, istek işlem hattına bir veya daha fazla ara yazılım ekleyebilir. Filtreler, hizmet kapsayıcısına eklendikleri sırayla çağrılır. Filtreler, denetimi sonraki filtreye geçirmeden önce veya sonra ara yazılım ekleyebilir, böylece işlem hattının başına veya sonuna eklenir.

Aşağıdaki örnek, IStartupFilter ile bir middleware kaydetme işlemini göstermektedir. CustomResponseHeaderFilter başlangıç filtresi, diğer ara yazılımlar yürütülmeden önce uygulamanın tüm yanıtlarına özel bir üst bilgi (X-Custom-Header) eklemek için ara yazılım kullanır.

CustomResponseHeaderFilter.cs:

using System;
using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Hosting;
using Microsoft.AspNetCore.Http;

public class CustomResponseHeaderFilter : IStartupFilter
{
    public Action<IApplicationBuilder> Configure(Action<IApplicationBuilder> next)
    {
        return builder =>
        {
            // 1. Add middleware that runs BEFORE subsequent middlewares
            builder.Use(async (context, nextMiddleware) =>
            {
                context.Response.Headers.Append("X-Custom-Header", "VALUE");
                await nextMiddleware();
            });

            // 2. Call the rest of the application's configuration pipeline
            next(builder);

            // 3. (Optional) Add middleware that runs AFTER the rest of the pipeline
        };
    }
}

Başlangıç filtresi uygulaması dosyaya Program kaydedilir:

builder.Services.AddTransient<IStartupFilter, CustomResponseHeaderFilter>();

Başlangıç filtresi uygulaması Startup.ConfigureServices içinde kaydedilir:

services.AddTransient<IStartupFilter, CustomResponseHeaderFilter>();

Ara yazılım yürütme sırası, başlangıç filtresi kayıtlarının sırasına göre ayarlanır:

  • Birden çok uygulama aynı nesnelerle etkileşimde olabilir. Sıralama önemliyse, hizmet kayıtlarını ara katmanlarının çalışması gereken sırayla eşleşecek şekilde sıralayın.
  • Kitaplıklar, IStartupFilter ile kaydedilen diğer uygulama ara yazılımlarından önce veya sonra çalışan bir veya daha fazla gerçekleştirim içeren ara yazılım ekleyebilir. Kitaplığın başlangıç filtresi tarafından eklenen bir ara yazılımdan önce başlangıç filtresi ara yazılımını çağırmak için:
    • Kitaplık hizmet kapsayıcısına eklenmeden önce başlangıç filtresi hizmet kaydını konumlandırın.
    • Hizmeti daha sonra çağırmak için, kitaplık eklendikten sonra hizmet kaydını konumlandırın.

Note

Configure temsilcisini geçersiz kıldığınızda ASP.NET Core uygulamasını başlangıç filtreleriyle genişletemezsiniz. Daha fazla bilgi için bkz. Configure yönteminin geçersiz kılınması durumunda WebApplicationFactory istemcisi tüm istekler için NotFound döndürür (dotnet/aspnetcore #45372).

Dış derlemeden başlangıçta yapılandırma ekleme

Bir IHostingStartup uygulaması, uygulamanın Startup dosyası veya Program sınıfı dışında bulunan harici bir derlemeden başlangıçta uygulamaya geliştirmeler eklenmesine olanak tanır. Daha fazla bilgi için, bkz. ASP.NET Core'da barındırma başlangıç derlemelerini kullanma.

Sınıfı Startup (ConfigureServices ve Configure yöntemleri)

.NET 6 veya sonraki sürümleri hedefleyen ASP.NET Core uygulamalarında destekleniyor olsa da, Startup sınıfının kullanılması önerilmez. Daha fazla bilgi için bkz. .NET 5'te ASP.NET Core'dan .NET 6'ya geçiş.

Configure ve ConfigureServices yöntemlerini minimal barındırma modeliyle kullanma hakkında bilgi için aşağıdakilere bakın:

Başlangıç performansını ölçme

ASP.NET Core barındırması EventSource sunucunun isteklere yanıt vermeye hazır olduğu noktayı temsil eden ve başlangıç süresini ölçmek için kullanılabilen ServerReady olayını yayınlar. Daha fazla bilgi için bkz . .NET ve ASP.NET Core'da oturum açma.

Ek kaynaklar

  • Son güncelleştirme: