Host Generik .NET di ASP.NET Core

Note

Ini bukan versi terbaru dari artikel ini. Untuk rilis saat ini, lihat versi .NET 10 dari artikel ini.

Warning

Versi ASP.NET Core ini tidak lagi didukung. Untuk informasi selengkapnya, lihat Kebijakan Dukungan .NET dan .NET Core. Untuk rilis saat ini, lihat versi .NET 10 dari artikel ini.

Templat ASP.NET Core membuat instans WebApplicationBuilder dan WebApplication. Objek ini menyediakan cara yang efisien untuk mengonfigurasi dan menjalankan aplikasi web tanpa Startup kelas. Untuk informasi selengkapnya tentang WebApplicationBuilder dan WebApplication, lihat Migrasi dari ASP.NET Core di .NET 5 ke .NET 6.

Templat ASP.NET Core membuat instans .NET Generic Host (HostBuilder).

Artikel ini menyediakan informasi tentang menggunakan Host Generik .NET di ASP.NET Core. Untuk informasi tentang menggunakan Host Generik .NET di aplikasi konsol, lihat Host Generik .NET.

Memahami peran host

Host adalah objek yang merangkum sumber daya aplikasi, seperti:

  • Injeksi dependensi (DI)
  • Logging
  • Configuration
  • Implementasi IHostedService

Ketika host dimulai, host memanggil metode StartAsync pada setiap instans IHostedService yang terdaftar dalam koleksi layanan yang dihosting di kontainer layanan. Dalam aplikasi web, salah satu implementasinya IHostedService adalah layanan web yang memulai implementasi server HTTP.

Dengan menyertakan semua sumber daya aplikasi yang saling bergantung dalam satu objek, host memungkinkan kontrol pengaktifan aplikasi dan penonaktifan yang anggun.

Menyiapkan host

Host biasanya dikonfigurasi, dibangun, dan dijalankan berdasarkan kode dalam file Program.cs .

Kode berikut membuat host dengan menambahkan implementasi IHostedService ke dalam kontainer DI:

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

Untuk beban kerja HTTP, panggil ConfigureWebHostDefaults metode setelah CreateDefaultBuilder metode :

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

Metode Main melakukan tugas-tugas berikut:

  • Memanggil metode CreateHostBuilder untuk membuat dan mengonfigurasi objek penyusun.
  • Memanggil metode Build dan Run pada objek penyusun.

Templat web ASP.NET Core menghasilkan kode berikut untuk membuat instans Host Generik .NET:

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

Kode berikut membuat Host Generik dengan menggunakan beban kerja non-HTTP. Implementasi IHostedService ditambahkan ke kontainer DI:

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

Untuk beban kerja HTTP, templat ASP.NET Core menghasilkan metode yang sama Main, tetapi metode tersebut memanggil metode CreateHostBuilder yang memanggil metode ConfigureWebHostDefaults.

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

Jika aplikasi menggunakan Entity Framework Core, jangan ubah nama atau tanda tangan CreateHostBuilder metode . Alat Entity Framework Core mengharapkan untuk menemukan CreateHostBuilder metode yang mengonfigurasi host tanpa menjalankan aplikasi. Untuk informasi selengkapnya, lihat Pembuatan DbContext saat desain.

Mengonfigurasi pengaturan penyusun default

Metode CreateDefaultBuilder melakukan tugas-tugas berikut:

  • Mengatur akar konten ke jalur yang dikembalikan oleh GetCurrentDirectory.

  • Memuat konfigurasi host dari sumber berikut:

    • Variabel lingkungan diawali dengan DOTNET_
    • Argumen baris perintah

  • Memuat konfigurasi aplikasi dalam urutan berikut:

    • file appsettings.json
    • appsettings.{Environment}.json
    • Rahasia pengguna (Dimuat saat aplikasi berjalan di Development lingkungan dengan menggunakan rakitan entri.)
    • Variabel lingkungan
    • Argumen baris perintah

  • Menambahkan penyedia pengelogan berikut:

    • Console
    • Debug
    • EventSource
    • EventLog (hanya saat menjalankan di Windows)

  • Mengaktifkan validasi cakupan dan validasi dependensi saat lingkungan adalah Development.

Metode ConfigureWebHostDefaults melakukan tugas-tugas berikut:

Untuk informasi tentang cara mengambil alih pengaturan penyusun default, lihat Mengonfigurasi pengaturan untuk semua jenis aplikasi dan Mengonfigurasi pengaturan untuk aplikasi web nanti di artikel ini.

Layanan yang disediakan oleh kerangka kerja

Host Generik .NET secara otomatis mendaftarkan layanan berikut:

Untuk informasi selengkapnya tentang layanan yang disediakan kerangka kerja, lihat Injeksi dependensi di ASP.NET Core.

IHostApplicationLifetime

Suntikkan layanan IHostApplicationLifetime (sebelumnya IApplicationLifetime) ke dalam kelas apa pun untuk menangani tugas setelah startup dan penutupan yang lancar. Tiga properti pada antarmuka adalah token pembatalan yang digunakan untuk mendaftarkan mulai aplikasi dan metode penanganan aktivitas penghentian aplikasi. Antarmuka juga menyertakan metode StopApplication, yang memungkinkan aplikasi untuk meminta penutupan yang mulus.

Saat melakukan penutupan yang terkendali, host:

  • Memicu pengendali acara ApplicationStopping, yang memungkinkan aplikasi menjalankan logika sebelum proses penghentian dimulai.

  • Menghentikan server, yang menonaktifkan koneksi baru. Server menunggu permintaan pada koneksi yang ada hingga selesai sejauh batas waktu penonaktifan memungkinkan. Server mengirimkan header penutupan koneksi untuk permintaan berikutnya terhadap koneksi yang ada.

  • Memicu penangan kejadian ApplicationStopped, yang memungkinkan aplikasi menjalankan fungsi logika setelah aplikasi telah dimatikan.

Contoh berikut adalah IHostedService implementasi yang mendaftarkan IHostApplicationLifetime penanganan aktivitas:

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

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

Implementasi IHostLifetime mengendalikan saat host mulai dan berhenti. Implementasi terakhir yang terdaftar akan digunakan.

Microsoft.Extensions.Hosting.Internal.ConsoleLifetime adalah implementasi IHostLifetime default.

Metode ConsoleLifetime melakukan tugas-tugas berikut:

  • Mendengarkan Ctrl+C/SIGINT (Windows), Ctrl+C (macOS), atau SIGTERM dan memanggil StopApplication, yang memulai proses penghentian.

  • Buka blokir ekstensi, seperti dengan menjalankan metode RunAsync dan WaitForShutdownAsync .

IHostEnvironment (IWebHostEnvironment)

Injeksikan layanan IHostEnvironment ke dalam kelas untuk mendapatkan informasi tentang pengaturan berikut:

Aplikasi web mengimplementasikan IWebHostEnvironment antarmuka, yang mewarisi IHostEnvironment dan menambahkan WebRootPath.

Menyiapkan konfigurasi host

Konfigurasi host digunakan untuk properti dari implementasi IHostEnvironment.

Konfigurasi host tersedia dari properti Configuration di dalam metode ConfigureAppConfiguration. Setelah ConfigureAppConfiguration, HostBuilderContext.Configuration diganti dengan konfigurasi aplikasi.

Untuk menambahkan konfigurasi host, panggil ConfigureHostConfiguration metode pada IHostBuilder instans. ConfigureHostConfiguration dapat dipanggil beberapa kali dengan hasil tambahan. Host menggunakan opsi apapun yang menetapkan nilai terakhir pada kunci tertentu.

CreateDefaultBuilder mencakup penyedia variabel lingkungan dengan awalan DOTNET_ dan argumen baris perintah. Untuk aplikasi web, penyedia variabel lingkungan dengan awalan ASPNETCORE_ ditambahkan. Awalan dihapus saat variabel lingkungan sistem dibaca. Misalnya, nilai variabel lingkungan untuk ASPNETCORE_ENVIRONMENT menjadi nilai konfigurasi host untuk environment kunci.

Contoh berikut membuat konfigurasi host:

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

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

Membuat konfigurasi aplikasi

Konfigurasi aplikasi dibuat dengan memanggil ConfigureAppConfiguration metode pada IHostBuilder instans. ConfigureAppConfiguration dapat dipanggil beberapa kali dengan hasil tambahan. Aplikasi ini menggunakan opsi mana pun yang mengatur nilai terakhir pada kunci tertentu.

Konfigurasi yang dibuat oleh ConfigureAppConfiguration tersedia di Configuration properti untuk operasi berikutnya dan sebagai layanan dari DI. Konfigurasi host juga ditambahkan ke konfigurasi aplikasi.

Untuk informasi lebih lanjut, lihat Konfigurasi di ASP.NET Core.

Mengonfigurasi pengaturan untuk semua jenis aplikasi

Bagian ini mencantumkan pengaturan host yang berlaku untuk beban kerja HTTP dan non-HTTP.

Secara bawaan, variabel lingkungan yang digunakan untuk mengonfigurasi pengaturan ini dapat memiliki prefiks DOTNET_ atau ASPNETCORE_, yang muncul dalam daftar pengaturan berikut sebagai placeholder {PREFIX_}.

Untuk informasi selengkapnya, lihat Mengonfigurasi pengaturan penyusun default dan Konfigurasi: Variabel lingkungan.

Nama aplikasi

Menentukan nama rakitan yang berisi titik masuk untuk aplikasi.

Kunci: applicationName
Jenis: string
Default: Nama assemblasi yang memiliki titik masuk utama aplikasi.
Atur menggunakan: Variabel lingkungan
Variabel lingkungan: {PREFIX_}APPLICATIONNAME

Properti ApplicationName diatur dari konfigurasi host selama pembuatan host.

Akar konten

Menentukan tempat host memulai pencarian file konten.

Kunci: contentRoot
Jenis: string
Default: Folder tempat rakitan aplikasi berada.
Atur menggunakan: Variabel lingkungan atau UseContentRoot pada IHostBuilder
Variabel lingkungan: {PREFIX_}CONTENTROOT

Properti ContentRootPath mengidentifikasi tempat host mulai mencari. Jika jalur tidak ada, host gagal memulai.

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

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

Untuk informasi selengkapnya, lihat:

Nama lingkungan

Memberikan nama untuk lingkungan.

Kunci: environment
Jenis: string
Default: Production
Atur menggunakan: Variabel lingkungan atau panggilan UseEnvironment pada IHostBuilder
Variabel lingkungan: {PREFIX_}ENVIRONMENT

Properti EnvironmentName dapat diatur ke nilai apa pun. Nilai yang ditentukan kerangka kerja meliputi Development, Staging, dan Production. Nilai tidak membedakan huruf besar/kecil.

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

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

Batas waktu penonaktifan

Menentukan jumlah waktu untuk menunggu host dimatikan.

Kunci: shutdownTimeoutSeconds
Jenis: int
Default: 30 detik (Dalam .NET 5.0 dan yang lebih lama, defaultnya adalah 5 detik.)
Atur menggunakan: Variabel lingkungan atau HostOptions
Variabel lingkungan: {PREFIX_}SHUTDOWNTIMEOUTSECONDS

Properti ShutdownTimeout mengatur batas waktu untuk StopAsync. Nilai standarnya adalah 30 detik.

Selama periode batas waktu, host:

  • Pemicu ApplicationStopping.
  • Upaya menghentikan layanan yang dihosting, serta mencatat kesalahan untuk layanan yang gagal dihentikan.

Jika periode batas waktu berakhir sebelum semua layanan yang dihosting berhenti, layanan aktif yang tersisa berhenti saat aplikasi dimatikan. Layanan berhenti meskipun masih diproses. Jika layanan memerlukan lebih banyak waktu untuk berhenti, tingkatkan batas waktu.

Contoh berikut mengatur batas waktu menjadi 20 detik:

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

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

Muat ulang konfigurasi saat berubah

Memuat ulang appsettings.json dan appsettings.{ Environment}.json file ketika file berubah. Perilaku ini secara default, seperti yang dijelaskan dalam Sumber konfigurasi aplikasi default.

Kunci: hostBuilder:reloadConfigOnChange
Jenis: bool (true atau false)
Default: true
Atur menggunakan: Argumen baris perintah hostBuilder:reloadConfigOnChange
Variabel lingkungan: {PREFIX_}hostBuilder:reloadConfigOnChange

Di .NET 5 dan yang lebih baru, Anda dapat menonaktifkan perilaku pemuatan ulang dengan mengatur hostBuilder:reloadConfigOnChange argumen ke false.

Warning

Pemisah titik dua (:) tidak berfungsi dengan kunci hierarki variabel lingkungan di semua platform. Untuk informasi selengkapnya, lihat Variabel lingkungan.

Mengonfigurasi pengaturan untuk aplikasi web

Beberapa pengaturan host hanya berlaku untuk beban kerja HTTP. Secara bawaan, variabel lingkungan yang digunakan untuk mengonfigurasi pengaturan ini dapat memiliki prefiks DOTNET_ atau ASPNETCORE_, yang muncul dalam daftar pengaturan berikut sebagai placeholder {PREFIX_}.

Metode ekstensi pada IWebHostBuilder tersedia untuk pengaturan ini. Sampel kode yang menunjukkan cara memanggil metode ekstensi mengasumsikan webBuilder adalah instans IWebHostBuilder, seperti dalam contoh berikut:

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

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

Menangkap kesalahan startup

Mengontrol pencatatan kesalahan saat memulai.

Kunci: captureStartupErrors
Jenis: bool (true/1 atau false/0)
Default: false. Jika aplikasi berjalan dengan Kestrel di belakang IIS, defaultnya adalah true.
Atur menggunakan: Konfigurasi atau CaptureStartupErrors
Variabel lingkungan: {PREFIX_}CAPTURESTARTUPERRORS

Ketika false, kesalahan selama startup mengakibatkan host keluar. Ketika true, host menangkap pengecualian selama startup dan mencoba memulai server.

webBuilder.CaptureStartupErrors(true);

webBuilder.CaptureStartupErrors(true);

Kesalahan terperinci

Menentukan apakah akan menangkap kesalahan terperinci.

Kunci: detailedErrors
Jenis: bool (true/1 atau false/0)
Default: false
Atur menggunakan: Konfigurasi atau UseSetting
Variabel lingkungan: {PREFIX_}DETAILEDERRORS

Saat diaktifkan, atau saat lingkungan diatur ke Development, aplikasi menangkap kesalahan terperinci.

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

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

Penyelenggaraan pertemuan startup

Menyediakan string rakitan startup hosting yang dibatasi titik koma untuk dimuat saat startup.

Kunci: hostingStartupAssemblies
Jenis: string
Default: String kosong
Atur menggunakan: UseSetting
Variabel lingkungan: {PREFIX_}HOSTINGSTARTUPASSEMBLIES

Meskipun nilai default konfigurasi adalah string kosong, rakitan startup hosting selalu memuat rakitan aplikasi. Saat rakitan startup hosting disediakan, rakitan tersebut ditambahkan ke rakitan aplikasi untuk dimuat saat aplikasi membangun layanan umum selama startup.

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

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

Startup hosting mengecualikan rakitan

Menyediakan string rakitan startup hosting yang dibatasi titik koma untuk dikecualikan pada startup.

Kunci: hostingStartupExcludeAssemblies
Jenis: string
Default: String kosong
Atur menggunakan: Konfigurasi atau UseSetting
Variabel lingkungan: {PREFIX_}HOSTINGSTARTUPEXCLUDEASSEMBLIES

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

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

Port HTTPS

Mengatur port HTTPS untuk pengalihan jika Anda mendapatkan koneksi non-HTTPS.

Kunci: https_port
Jenis: string
Default: Tidak ada default.
Atur menggunakan: Konfigurasi atau UseSetting
Variabel lingkungan: {PREFIX_}HTTPS_PORT

Pengaturan ini digunakan dalam memberlakukan HTTPS. Pengaturan ini tidak menyebabkan server mendengarkan port yang ditentukan. Artinya, dimungkinkan untuk mengalihkan permintaan secara tidak sengaja ke port yang tidak digunakan.

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

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

Port HTTPS

Menentukan port yang mungkin untuk didengarkan untuk koneksi HTTPS.

Kunci: https_ports
Jenis: string
Default: Tidak ada default.
Atur menggunakan: Konfigurasi atau UseSetting
Variabel lingkungan: {PREFIX_}HTTPS_PORTS

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

Lebih memilih URL untuk hosting

Menunjukkan apakah host harus mendengarkan URL yang dikonfigurasi dengan IWebHostBuilder daripada URL yang dikonfigurasi dengan implementasi IServer.

Kunci: preferHostingUrls
Jenis: bool (true/1 atau false/0)
Default: false
Atur menggunakan: Variabel lingkungan atau PreferHostingUrls
Variabel lingkungan: {PREFIX_}PREFERHOSTINGURLS

webBuilder.PreferHostingUrls(true);

webBuilder.PreferHostingUrls(true);

Mencegah pemulaian hosting

Mencegah pemuatan otomatis rakitan startup hosting, termasuk rakitan startup hosting yang dikonfigurasi oleh rakitan aplikasi. Untuk informasi selengkapnya, lihat Menggunakan rakitan startup hosting di ASP.NET Core.

Kunci: preventHostingStartup
Jenis: bool (true/1 atau false/0)
Default: false
Atur menggunakan: Variabel lingkungan atau UseSetting
Variabel lingkungan: {PREFIX_}PREVENTHOSTINGSTARTUP

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

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

Perakitan startup

Menentukan perakitan untuk mencari kelas Startup.

Kunci: startupAssembly
Jenis: string
Default: Rakitan aplikasi.
Atur menggunakan: Variabel lingkungan atau UseStartup
Variabel lingkungan: {PREFIX_}STARTUPASSEMBLY

Anda dapat mereferensikan rakitan berdasarkan nama (string) atau jenis (TStartup). Jika beberapa UseStartup metode dipanggil, panggilan terakhir lebih diutamakan.

webBuilder.UseStartup("StartupAssemblyName");

webBuilder.UseStartup<Startup>();

webBuilder.UseStartup("StartupAssemblyName");

webBuilder.UseStartup<Startup>();

Sembunyikan pesan status

Menunjukkan apakah akan menyembunyikan pesan status startup hosting.

Kunci: suppressStatusMessages
Jenis: bool (true/1 atau false/0)
Default: false
Atur menggunakan: Konfigurasi atau UseSetting
Variabel lingkungan: {PREFIX_}SUPPRESSSTATUSMESSAGES

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

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

URL Server

Menunjukkan alamat IP atau alamat host dengan port dan protokol yang harus didengarkan server untuk permintaan.

Kunci: urls
Jenis: string
Default: http://localhost:5000 dan https://localhost:5001
Atur menggunakan: Variabel lingkungan atau UseUrls
Variabel lingkungan: {PREFIX_}URLS

Atur ke sebuah daftar awalan URL yang dipisahkan dengan ; titik koma yang akan direspons oleh server. Contohnya,http://localhost:123. Gunakan wildcard tanda bintang * untuk menunjukkan bahwa server harus mendengarkan permintaan pada alamat IP atau nama host mana pun dengan port dan protokol yang ditentukan (misalnya, http://*:5000). Protokol (http:// atau https://) harus disertakan dengan setiap URL. Format yang didukung bervariasi di antara server.

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

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

Kestrel memiliki API konfigurasi endpoint-nya sendiri. Untuk informasi selengkapnya, lihat Mengonfigurasi titik akhir untuk Kestrel server web.

Akar web

Mengatur jalur relatif ke aset statis aplikasi.

Kunci: webroot
Jenis: string
Default: wwwroot
Atur menggunakan: Variabel lingkungan atau UseWebRoot pada IWebHostBuilder
Variabel lingkungan: {PREFIX_}WEBROOT

Properti WebRootPath menentukan jalur relatif ke aset statis aplikasi.

Jalur ke {content root}/wwwroot harus ada. Jika jalur tidak ada, penyedia file no-op akan digunakan.

webBuilder.UseWebRoot("public");

webBuilder.UseWebRoot("public");

Untuk informasi selengkapnya, lihat:

Mengelola masa pakai host

Untuk memulai dan menghentikan aplikasi, panggil metode pada IHost implementasi. Metode ini memengaruhi semua IHostedService implementasi yang terdaftar dalam kontainer layanan.

Perbedaan antara Run* metode dan Start* adalah bahwa Run* metode menunggu host selesai sebelum kembali, sedangkan Start* metode segera kembali. Metode Run* ini biasanya digunakan dalam aplikasi konsol, sedangkan Start* metode biasanya digunakan dalam layanan yang berjalan lama.

Run

Metode Run menjalankan aplikasi dan memblokir utas pemanggil hingga host dimatikan.

RunAsync

Metode RunAsync menjalankan aplikasi dan mengembalikan objek Task yang selesai ketika dipicu oleh token pembatalan atau penonaktifan.

RunConsoleAsync

Metode RunConsoleAsync ini memungkinkan dukungan konsol, membangun dan memulai host, serta menunggu Ctrl+C/SIGINT (Windows), Ctrl+C (macOS), atau SIGTERM untuk mematikan.

Start

Metode ini Start meluncurkan host secara sinkron.

StartAsync

Metode StartAsync memulai host dan mengembalikan objek Task yang akan selesai ketika token pembatalan atau pemadaman dipicu.

Metode WaitForStartAsync ini dipanggil pada awal StartAsync, yang menunggu hingga selesai sebelum melanjutkan. Metode ini dapat digunakan untuk menunda startup hingga disinyalir oleh peristiwa eksternal.

StopAsync

Metode ini StopAsync mencoba menghentikan host dalam batas waktu yang disediakan.

WaitForShutdown

Metode WaitForShutdown ini memblokir utas panggilan sampai implementasi IHostLifetime memicu penghentian melalui Ctrl+C/SIGINT (Windows), Ctrl+C (macOS), atau SIGTERM.

WaitForShutdownAsync

WaitForShutdownAsyncMetode mengembalikan objek Task yang selesai ketika pengakhiran dipicu melalui token yang diberikan, lalu memanggil metode StopAsync.

Mengontrol masa pakai host

Anda dapat menjalankan kontrol langsung masa pakai host dengan memanggil metode berikut secara eksternal:

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

Konten terkait

Note

Tautan dokumentasi ke sumber referensi .NET biasanya memuat cabang default repositori, yang mewakili pengembangan saat ini untuk rilis .NET berikutnya. Untuk memilih tag rilis tertentu, gunakan daftar dropdown Beralih cabang atau tag. Untuk informasi lebih lanjut, lihat Cara memilih tag versi kode sumber ASP.NET Core (dotnet/AspNetCore.Docs #26205).

  • Last updated on