Bagikan melalui


ASP.NET Core Web Host

Catatan

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

Peringatan

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 8 dari artikel ini.

Penting

Informasi ini berkaitan dengan produk pra-rilis yang mungkin dimodifikasi secara substansial sebelum dirilis secara komersial. Microsoft tidak memberikan jaminan, tersirat maupun tersurat, sehubungan dengan informasi yang diberikan di sini.

Untuk rilis saat ini, lihat versi .NET 8 dari artikel ini.

Aplikasi ASP.NET Core mengonfigurasi dan meluncurkan host. Host bertanggung jawab atas startup aplikasi dan manajemen seumur hidup. Minimal, host mengonfigurasi server dan alur pemrosesan permintaan. Host juga dapat menyiapkan pengelogan, injeksi dependensi, dan konfigurasi.

Artikel ini membahas Web Host, yang tetap tersedia hanya untuk kompatibilitas mundur. Templat ASP.NET Core membuat WebApplicationBuilder dan WebApplication, yang direkomendasikan untuk aplikasi web. Untuk informasi selengkapnya tentang WebApplicationBuilder dan WebApplication, lihat Migrasi dari ASP.NET Core 5.0 ke 6.0

Menyiapkan host

Buat host menggunakan instans IWebHostBuilder. Ini biasanya dilakukan di titik masuk aplikasi, Main metode di Program.cs. Panggilan CreateDefaultBuilder aplikasi umum untuk mulai menyiapkan host:

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

    public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
        WebHost.CreateDefaultBuilder(args)
            .UseStartup<Startup>();
}

Kode yang memanggil CreateDefaultBuilder berada dalam metode bernama CreateWebHostBuilder, yang memisahkannya dari kode dalam Main panggilan Run tersebut pada objek penyusun. Pemisahan ini diperlukan jika Anda menggunakan alat Entity Framework Core. Alat mengharapkan untuk menemukan CreateWebHostBuilder metode yang dapat mereka panggil pada waktu desain untuk mengonfigurasi host tanpa menjalankan aplikasi. Alternatifnya adalah menerapkan IDesignTimeDbContextFactory. Untuk informasi selengkapnya, lihat Pembuatan DbContext waktu desain.

CreateDefaultBuilder melakukan tugas-tugas berikut:

Konfigurasi yang ditentukan oleh CreateDefaultBuilder dapat ditimpa dan ditambah oleh ConfigureAppConfiguration, ConfigureLogging, dan metode dan metode ekstensi lainnya dari IWebHostBuilder. Beberapa contoh berikut:

  • ConfigureAppConfiguration digunakan untuk menentukan tambahan IConfiguration untuk aplikasi. Panggilan berikut ConfigureAppConfiguration menambahkan delegasi untuk menyertakan konfigurasi aplikasi dalam appsettings.xml file. ConfigureAppConfiguration dapat dipanggil beberapa kali. Perhatikan bahwa konfigurasi ini tidak berlaku untuk host (misalnya, URL atau lingkungan server). Lihat bagian Nilai konfigurasi host.

    WebHost.CreateDefaultBuilder(args)
        .ConfigureAppConfiguration((hostingContext, config) =>
        {
            config.AddXmlFile("appsettings.xml", optional: true, reloadOnChange: true);
        })
        ...
    
  • Panggilan berikut ConfigureLogging menambahkan delegasi untuk mengonfigurasi tingkat pengelogan minimum (SetMinimumLevel) ke LogLevel.Warning. Pengaturan ini mengambil alih pengaturan di (LogLevel.Debug) dan appsettings.Production.json (LogLevel.Error) yang dikonfigurasi appsettings.Development.json oleh CreateDefaultBuilder. ConfigureLogging dapat dipanggil beberapa kali.

    WebHost.CreateDefaultBuilder(args)
        .ConfigureLogging(logging => 
        {
            logging.SetMinimumLevel(LogLevel.Warning);
        })
        ...
    
  • Panggilan berikut untuk ConfigureKestrel mengambil alih Limits.MaxRequestBodySize default sebesar 30.000.000 byte yang dibuat saat Kestrel dikonfigurasi oleh CreateDefaultBuilder:

    WebHost.CreateDefaultBuilder(args)
        .ConfigureKestrel((context, options) =>
        {
            options.Limits.MaxRequestBodySize = 20000000;
        });
    

Akar konten menentukan tempat host mencari file konten, seperti file tampilan MVC. Saat aplikasi dimulai dari folder akar proyek, folder akar proyek digunakan sebagai akar konten. Ini adalah default yang digunakan di Visual Studio dan templat baru dotnet.

Untuk informasi selengkapnya tentang konfigurasi aplikasi, lihat Konfigurasi di ASP.NET Core.

Catatan

Sebagai alternatif untuk menggunakan metode statis CreateDefaultBuilder , membuat host dari WebHostBuilder adalah pendekatan yang didukung dengan ASP.NET Core 2.x.

Saat menyiapkan host, Configure dan ConfigureServices metode dapat disediakan. Startup Jika kelas ditentukan, kelas harus menentukan Configure metode. Untuk informasi selengkapnya, lihat Pengaktifan aplikasi di ASP.NET Core. Beberapa panggilan untuk ConfigureServices ditambahkan satu dengan yang lain. Beberapa panggilan ke Configure atau UseStartup pada WebHostBuilder pengaturan ganti sebelumnya.

Nilai konfigurasi host

WebHostBuilder bergantung pada pendekatan berikut untuk mengatur nilai konfigurasi host:

  • Konfigurasi penyusun host, yang mencakup variabel lingkungan dengan format ASPNETCORE_{configurationKey}. Contohnya,ASPNETCORE_ENVIRONMENT.
  • Ekstensi seperti UseContentRoot dan UseConfiguration (lihat bagian Ambil alih konfigurasi ).
  • UseSetting dan kunci terkait. Saat mengatur nilai dengan UseSetting, nilai diatur sebagai string terlepas dari jenisnya.

Host menggunakan opsi mana pun yang menetapkan nilai yang terakhir. Untuk informasi selengkapnya, lihat Mengambil alih konfigurasi di bagian berikutnya.

Kunci Aplikasi (Nama)

Properti IWebHostEnvironment.ApplicationName secara otomatis diatur ketika UseStartup atau Configure dipanggil selama konstruksi host. Nilai diatur ke nama rakitan yang berisi titik masuk aplikasi. Untuk mengatur nilai secara eksplisit, gunakan WebHostDefaults.ApplicationKey:

Kunci: applicationName
Jenis: string
Default: Nama rakitan yang berisi titik masuk aplikasi.
Atur menggunakan: UseSetting
Variabel lingkungan: ASPNETCORE_APPLICATIONNAME

WebHost.CreateDefaultBuilder(args)
    .UseSetting(WebHostDefaults.ApplicationKey, "CustomApplicationName")

Menangkap Kesalahan Startup

Pengaturan ini mengontrol pengambilan kesalahan startup.

Kunci: captureStartupErrors
Jenis: bool (true atau 1)
Default: Default ke false kecuali aplikasi berjalan dengan Kestrel di belakang IIS, di mana defaultnya adalah true.
Atur menggunakan: CaptureStartupErrors
Variabel lingkungan: ASPNETCORE_CAPTURESTARTUPERRORS

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

WebHost.CreateDefaultBuilder(args)
    .CaptureStartupErrors(true)

Akar konten

Pengaturan ini menentukan di mana ASP.NET Core mulai mencari file konten.

Kunci: contentRoot
Jenis: string
Default: Default ke folder tempat perakitan aplikasi berada.
Atur menggunakan: UseContentRoot
Variabel lingkungan: ASPNETCORE_CONTENTROOT

Akar konten juga digunakan sebagai jalur dasar untuk akar web. Jika jalur akar konten tidak ada, host gagal memulai.

WebHost.CreateDefaultBuilder(args)
    .UseContentRoot("c:\\<content-root>")

Untuk informasi selengkapnya, lihat:

Kesalahan Terperinci

Menentukan apakah kesalahan terperinci harus diambil.

Kunci: detailedErrors
Jenis: bool (true atau 1)
Default: false
Atur menggunakan: UseSetting
Variabel lingkungan: ASPNETCORE_DETAILEDERRORS

Saat diaktifkan (atau saat Lingkungan diatur ke Development), aplikasi menangkap pengecualian terperinci.

WebHost.CreateDefaultBuilder(args)
    .UseSetting(WebHostDefaults.DetailedErrorsKey, "true")

Lingkungan

Mengatur lingkungan aplikasi.

Kunci: lingkungan
Jenis: string
Default: Produksi
Atur menggunakan: UseEnvironment
Variabel lingkungan: ASPNETCORE_ENVIRONMENT

Lingkungan dapat diatur ke nilai apa pun. Nilai yang ditentukan kerangka kerja meliputi Development, Staging, dan Production. Nilai tidak peka huruf besar/kecil. Secara default, Lingkungan dibaca dari ASPNETCORE_ENVIRONMENT variabel lingkungan. Saat menggunakan Visual Studio, variabel lingkungan dapat diatur dalam launchSettings.json file. Untuk informasi lebih lanjut, lihat Menggunakan beberapa lingkungan di ASP.NET Core.

WebHost.CreateDefaultBuilder(args)
    .UseEnvironment(EnvironmentName.Development)

Hosting Startup Assemblies

Mengatur rakitan startup hosting aplikasi.

Kunci: hostingStartupAssemblies
Jenis: string
Default: String kosong
Atur menggunakan: UseSetting
Variabel lingkungan: ASPNETCORE_HOSTINGSTARTUPASSEMBLIES

String rakitan startup hosting yang dibatasi titik koma untuk dimuat saat startup.

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

WebHost.CreateDefaultBuilder(args)
    .UseSetting(WebHostDefaults.HostingStartupAssembliesKey, "assembly1;assembly2")

Port HTTPS

Atur port HTTPS untuk dialihkan jika Anda mendapatkan koneksi non-HTTPS. 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.

Kunci: https_port
Jenis: string
Default: Nilai default tidak diatur.
Atur menggunakan: UseSetting
Variabel lingkungan: ASPNETCORE_HTTPS_PORT

WebHost.CreateDefaultBuilder(args)
    .UseSetting("https_port", "8080")

Port HTTPS

Atur port untuk mendengarkan koneksi HTTPS.

Kunci: Jenis https_ports: string
Default: Nilai default tidak diatur.
Atur menggunakan: UseSetting
Variabel lingkungan: ASPNETCORE_HTTPS_PORTS

WebHost.CreateDefaultBuilder(args)
    .UseSetting("https_ports", "8080")

Hosting Startup Mengecualikan Rakitan

String rakitan startup hosting yang dibatasi titik koma untuk dikecualikan saat startup.

Kunci: hostingStartupExcludeAssemblies
Jenis: string
Default: String kosong
Atur menggunakan: UseSetting
Variabel lingkungan: ASPNETCORE_HOSTINGSTARTUPEXCLUDEASSEMBLIES

WebHost.CreateDefaultBuilder(args)
    .UseSetting(WebHostDefaults.HostingStartupExcludeAssembliesKey, "assembly1;assembly2")

Lebih suka URL Hosting

Menunjukkan apakah host harus mendengarkan URL yang dikonfigurasi dengan WebHostBuilder alih-alih yang dikonfigurasi dengan IServer implementasi.

Kunci: preferHostingUrls
Jenis: bool (true atau 1)
Default: false
Atur menggunakan: PreferHostingUrls
Variabel lingkungan: ASPNETCORE_PREFERHOSTINGURLS

WebHost.CreateDefaultBuilder(args)
    .PreferHostingUrls(true)

Mencegah Startup 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 atau 1)
Default: false
Atur menggunakan: UseSetting
Variabel lingkungan: ASPNETCORE_PREVENTHOSTINGSTARTUP

WebHost.CreateDefaultBuilder(args)
    .UseSetting(WebHostDefaults.PreventHostingStartupKey, "true")

URL Server

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

Kunci: url
Jenis: string
Default: http://localhost:5000
Atur menggunakan: UseUrls
Variabel lingkungan: ASPNETCORE_URLS

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

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

Kestrel memiliki API konfigurasi titik akhirnya sendiri. Untuk informasi selengkapnya, lihat Mengonfigurasi titik akhir untuk server web ASP.NET CoreKestrel.

Waktu Matikan Habis

Menentukan jumlah waktu untuk menunggu Web Host dimatikan.

Kunci: shutdownTimeoutSeconds
Jenis: int
Default: 5
Atur menggunakan: UseShutdownTimeout
Variabel lingkungan: ASPNETCORE_SHUTDOWNTIMEOUTSECONDS

Meskipun kunci menerima int dengan UseSetting (misalnya, .UseSetting(WebHostDefaults.ShutdownTimeoutKey, "10")), UseShutdownTimeout metode ekstensi mengambil TimeSpan.

Selama periode waktu habis, hosting:

Jika periode batas waktu berakhir sebelum semua layanan yang dihosting berhenti, layanan aktif yang tersisa akan dihentikan saat aplikasi dimatikan. Layanan berhenti meskipun belum selesai diproses. Jika layanan memerlukan waktu tambahan untuk berhenti, tingkatkan batas waktu.

WebHost.CreateDefaultBuilder(args)
    .UseShutdownTimeout(TimeSpan.FromSeconds(10))

Rakitan Startup

Menentukan assembly untuk Startup mencari kelas.

Kunci: startupAssembly
Jenis: string
Default: Rakitan aplikasi
Atur menggunakan: UseStartup
Variabel lingkungan: ASPNETCORE_STARTUPASSEMBLY

Rakitan berdasarkan nama (string) atau jenis (TStartup) dapat dirujuk. Jika beberapa UseStartup metode dipanggil, metode terakhir lebih diutamakan.

WebHost.CreateDefaultBuilder(args)
    .UseStartup("StartupAssemblyName")
WebHost.CreateDefaultBuilder(args)
    .UseStartup<TStartup>()

Akar web

Mengatur jalur relatif ke aset statis aplikasi.

Kunci: webroot
Jenis: string
Default: Defaultnya adalah wwwroot. Jalur ke {content root}/wwwroot harus ada. Jika jalur tidak ada, penyedia file tanpa operasi akan digunakan.
Atur menggunakan: UseWebRoot
Variabel lingkungan: ASPNETCORE_WEBROOT

WebHost.CreateDefaultBuilder(args)
    .UseWebRoot("public")

Untuk informasi selengkapnya, lihat:

Mengesampingkan konfigurasi

Gunakan Konfigurasi untuk mengonfigurasi Web Host. Dalam contoh berikut, konfigurasi host secara opsional ditentukan dalam hostsettings.json file. Konfigurasi apa pun yang hostsettings.json dimuat dari file dapat ditimpa oleh argumen baris perintah. Konfigurasi bawaan (dalam config) digunakan untuk mengonfigurasi host dengan UseConfiguration. IWebHostBuilder konfigurasi ditambahkan ke konfigurasi aplikasi, tetapi sebaliknya tidak benar—ConfigureAppConfiguration tidak memengaruhi IWebHostBuilder konfigurasi.

Mengambil alih konfigurasi yang disediakan oleh UseUrls hostsettings.json konfigurasi terlebih dahulu, konfigurasi argumen baris perintah kedua:

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

    public static IWebHostBuilder CreateWebHostBuilder(string[] args)
    {
        var config = new ConfigurationBuilder()
            .SetBasePath(Directory.GetCurrentDirectory())
            .AddJsonFile("hostsettings.json", optional: true)
            .AddCommandLine(args)
            .Build();

        return WebHost.CreateDefaultBuilder(args)
            .UseUrls("http://*:5000")
            .UseConfiguration(config)
            .Configure(app =>
            {
                app.Run(context => 
                    context.Response.WriteAsync("Hello, World!"));
            });
    }
}

hostsettings.json:

{
    urls: "http://*:5005"
}

Catatan

UseConfiguration hanya menyalin kunci dari yang disediakan IConfiguration ke konfigurasi pembangun host. Oleh karena itu, pengaturan reloadOnChange: true untuk file pengaturan JSON, INI, dan XML tidak berpengaruh.

Untuk menentukan host yang dijalankan pada URL tertentu, nilai yang diinginkan dapat diteruskan dari prompt perintah saat menjalankan dotnet run. Argumen baris perintah mengambil urls alih nilai dari hostsettings.json file, dan server mendengarkan port 8080:

dotnet run --urls "http://*:8080"

Mengelola host

jalankan

Metode Run memulai aplikasi web dan memblokir utas panggilan hingga host dimatikan:

host.Run();

Mulai

Jalankan host dengan cara yang tidak memblokir dengan memanggil metodenya Start :

using (host)
{
    host.Start();
    Console.ReadLine();
}

Jika daftar URL diteruskan ke Start metode , URL akan didengarkan pada URL yang ditentukan:

var urls = new List<string>()
{
    "http://*:5000",
    "http://localhost:5001"
};

var host = new WebHostBuilder()
    .UseKestrel()
    .UseStartup<Startup>()
    .Start(urls.ToArray());

using (host)
{
    Console.ReadLine();
}

Aplikasi ini dapat menginisialisasi dan memulai host baru menggunakan default yang telah dikonfigurasi sebelumnya menggunakan CreateDefaultBuilder metode kenyamanan statis. Metode ini memulai server tanpa output konsol dan dengan WaitForShutdown menunggu jeda (Ctrl-C/SIGINT atau SIGTERM):

Start(RequestDelegate app)

Mulailah dengan RequestDelegate:

using (var host = WebHost.Start(app => app.Response.WriteAsync("Hello, World!")))
{
    Console.WriteLine("Use Ctrl-C to shutdown the host...");
    host.WaitForShutdown();
}

Buat permintaan di browser untuk http://localhost:5000 menerima respons "Halo Dunia!" WaitForShutdown blok hingga jeda (Ctrl-C/SIGINT atau SIGTERM) dikeluarkan. Aplikasi menampilkan Console.WriteLine pesan dan menunggu keypress keluar.

Mulai(url string, aplikasi RequestDelegate)

Mulai dengan URL dan RequestDelegate:

using (var host = WebHost.Start("http://localhost:8080", app => app.Response.WriteAsync("Hello, World!")))
{
    Console.WriteLine("Use Ctrl-C to shutdown the host...");
    host.WaitForShutdown();
}

Menghasilkan hasil yang sama dengan Start(RequestDelegate app), kecuali aplikasi merespons di http://localhost:8080.

Start(Action<IRouteBuilder> routeBuilder)

Gunakan instans IRouteBuilder (Microsoft.AspNetCore.Routing) untuk menggunakan middleware perutean:

using (var host = WebHost.Start(router => router
    .MapGet("hello/{name}", (req, res, data) => 
        res.WriteAsync($"Hello, {data.Values["name"]}!"))
    .MapGet("buenosdias/{name}", (req, res, data) => 
        res.WriteAsync($"Buenos dias, {data.Values["name"]}!"))
    .MapGet("throw/{message?}", (req, res, data) => 
        throw new Exception((string)data.Values["message"] ?? "Uh oh!"))
    .MapGet("{greeting}/{name}", (req, res, data) => 
        res.WriteAsync($"{data.Values["greeting"]}, {data.Values["name"]}!"))
    .MapGet("", (req, res, data) => res.WriteAsync("Hello, World!"))))
{
    Console.WriteLine("Use Ctrl-C to shutdown the host...");
    host.WaitForShutdown();
}

Gunakan permintaan browser berikut dengan contoh:

Permintaan Respons
http://localhost:5000/hello/Martin Halo, Martin!
http://localhost:5000/buenosdias/Catrina Buenos dias, Catrina!
http://localhost:5000/throw/ooops! Melempar pengecualian dengan string "ooops!"
http://localhost:5000/throw Melempar pengecualian dengan string "Uh oh!"
http://localhost:5000/Sante/Kevin Sante, Kevin!
http://localhost:5000 Halo Dunia!

WaitForShutdown memblokir hingga jeda (Ctrl-C/SIGINT atau SIGTERM) dikeluarkan. Aplikasi menampilkan Console.WriteLine pesan dan menunggu keypress keluar.

Start(string url, Action<IRouteBuilder> routeBuilder)

Gunakan URL dan instans IRouteBuilder:

using (var host = WebHost.Start("http://localhost:8080", router => router
    .MapGet("hello/{name}", (req, res, data) => 
        res.WriteAsync($"Hello, {data.Values["name"]}!"))
    .MapGet("buenosdias/{name}", (req, res, data) => 
        res.WriteAsync($"Buenos dias, {data.Values["name"]}!"))
    .MapGet("throw/{message?}", (req, res, data) => 
        throw new Exception((string)data.Values["message"] ?? "Uh oh!"))
    .MapGet("{greeting}/{name}", (req, res, data) => 
        res.WriteAsync($"{data.Values["greeting"]}, {data.Values["name"]}!"))
    .MapGet("", (req, res, data) => res.WriteAsync("Hello, World!"))))
{
    Console.WriteLine("Use Ctrl-C to shut down the host...");
    host.WaitForShutdown();
}

Menghasilkan hasil yang sama dengan Start(Action<IRouteBuilder routeBuilder> ), kecuali aplikasi merespons di http://localhost:8080.

StartWith(Aplikasi Action<IApplicationBuilder> )

Berikan delegasi untuk mengonfigurasi IApplicationBuilder:

using (var host = WebHost.StartWith(app => 
    app.Use(next => 
    {
        return async context => 
        {
            await context.Response.WriteAsync("Hello World!");
        };
    })))
{
    Console.WriteLine("Use Ctrl-C to shut down the host...");
    host.WaitForShutdown();
}

Buat permintaan di browser untuk http://localhost:5000 menerima respons "Halo Dunia!" WaitForShutdown blok hingga jeda (Ctrl-C/SIGINT atau SIGTERM) dikeluarkan. Aplikasi menampilkan Console.WriteLine pesan dan menunggu keypress keluar.

StartWith(url string, Aplikasi Action<IApplicationBuilder> )

Berikan URL dan delegasi untuk mengonfigurasi IApplicationBuilder:

using (var host = WebHost.StartWith("http://localhost:8080", app => 
    app.Use(next => 
    {
        return async context => 
        {
            await context.Response.WriteAsync("Hello World!");
        };
    })))
{
    Console.WriteLine("Use Ctrl-C to shut down the host...");
    host.WaitForShutdown();
}

Menghasilkan hasil yang sama dengan StartWith(Aplikasi Action<IApplicationBuilder> ), kecuali aplikasi merespons di http://localhost:8080.

Antarmuka IWebHostEnvironment

Antarmuka menyediakan IWebHostEnvironment informasi tentang lingkungan hosting web aplikasi. Gunakan injeksi konstruktor untuk mendapatkan IWebHostEnvironment untuk menggunakan properti dan metode ekstensinya:

public class CustomFileReader
{
    private readonly IWebHostEnvironment _env;

    public CustomFileReader(IWebHostEnvironment env)
    {
        _env = env;
    }

    public string ReadFile(string filePath)
    {
        var fileProvider = _env.WebRootFileProvider;
        // Process the file here
    }
}

Pendekatan berbasis konvensi dapat digunakan untuk mengonfigurasi aplikasi saat startup berdasarkan lingkungan. Atau, masukkan ke IWebHostEnvironment Startup dalam konstruktor untuk digunakan dalam ConfigureServices:

public class Startup
{
    public Startup(IWebHostEnvironment env)
    {
        HostingEnvironment = env;
    }

    public IWebHostEnvironment HostingEnvironment { get; }

    public void ConfigureServices(IServiceCollection services)
    {
        if (HostingEnvironment.IsDevelopment())
        {
            // Development configuration
        }
        else
        {
            // Staging/Production configuration
        }

        var contentRootPath = HostingEnvironment.ContentRootPath;
    }
}

Catatan

Selain IsDevelopment metode ekstensi, IWebHostEnvironment menawarkan IsStaging, IsProduction, dan IsEnvironment(string environmentName) metode. Untuk informasi lebih lanjut, lihat Menggunakan beberapa lingkungan di ASP.NET Core.

Layanan ini IWebHostEnvironment juga dapat disuntikkan langsung ke Configure metode untuk menyiapkan alur pemrosesan:

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    if (env.IsDevelopment())
    {
        // In Development, use the Developer Exception Page
        app.UseDeveloperExceptionPage();
    }
    else
    {
        // In Staging/Production, route exceptions to /error
        app.UseExceptionHandler("/error");
    }

    var contentRootPath = env.ContentRootPath;
}

IWebHostEnvironmentdapat disuntikkan ke Invoke dalam metode saat membuat middleware kustom:

public async Task Invoke(HttpContext context, IWebHostEnvironment env)
{
    if (env.IsDevelopment())
    {
        // Configure middleware for Development
    }
    else
    {
        // Configure middleware for Staging/Production
    }

    var contentRootPath = env.ContentRootPath;
}

Antarmuka IHostApplicationLifetime

IHostApplicationLifetime memungkinkan aktivitas pasca-startup dan shutdown. Tiga properti pada antarmuka adalah token pembatalan yang digunakan untuk mendaftarkan Action metode yang menentukan peristiwa startup dan shutdown.

Token Pembatalan Dipicu ketika...
ApplicationStarted Host telah sepenuhnya dimulai.
ApplicationStopped Host menyelesaikan pematian yang anggun. Semua permintaan harus diproses. Matikan blok hingga kejadian ini selesai.
ApplicationStopping Host melakukan pematian yang anggun. Permintaan mungkin masih diproses. Matikan blok hingga kejadian ini selesai.
public class Startup
{
    public void Configure(IApplicationBuilder app, IHostApplicationLifetime appLifetime)
    {
        appLifetime.ApplicationStarted.Register(OnStarted);
        appLifetime.ApplicationStopping.Register(OnStopping);
        appLifetime.ApplicationStopped.Register(OnStopped);

        Console.CancelKeyPress += (sender, eventArgs) =>
        {
            appLifetime.StopApplication();
            // Don't terminate the process immediately, wait for the Main thread to exit gracefully.
            eventArgs.Cancel = true;
        };
    }

    private void OnStarted()
    {
        // Perform post-startup activities here
    }

    private void OnStopping()
    {
        // Perform on-stopping activities here
    }

    private void OnStopped()
    {
        // Perform post-stopped activities here
    }
}

StopApplication meminta penghentian aplikasi. Kelas berikut menggunakan StopApplication untuk mematikan aplikasi dengan anggun saat metode kelas Shutdown dipanggil:

public class MyClass
{
    private readonly IHostApplicationLifetime _appLifetime;

    public MyClass(IHostApplicationLifetime appLifetime)
    {
        _appLifetime = appLifetime;
    }

    public void Shutdown()
    {
        _appLifetime.StopApplication();
    }
}

Validasi cakupan

CreateDefaultBuilderServiceProviderOptions.ValidateScopes diatur ke true jika lingkungan aplikasi adalah Pengembangan.

Ketika ValidateScopes diatur ke true, penyedia layanan default melakukan pemeriksaan untuk memverifikasi bahwa:

  • Layanan terlingkup tidak diselesaikan secara langsung atau tidak langsung dari penyedia layanan akar.
  • Layanan terlingkup tidak secara langsung atau tidak langsung disuntikkan ke dalam singleton.

Penyedia layanan akar dibuat ketika BuildServiceProvider dipanggil. Masa pakai penyedia layanan akar sesuai dengan masa pakai aplikasi/server saat penyedia mulai dengan aplikasi dan dibuang saat aplikasi dimatikan.

Layanan tercakup dibuang oleh kontainer yang membuatnya. Jika layanan tercakup dibuat dalam kontainer akar, masa pakai layanan secara efektif dipromosikan ke singleton karena hanya dibuang oleh kontainer akar saat aplikasi/server dimatikan. Memvalidasi cakupan layanan menangkap situasi ini ketika BuildServiceProvider dipanggil.

Untuk selalu memvalidasi cakupan, termasuk di lingkungan Produksi, konfigurasikan ServiceProviderOptions dengan UseDefaultServiceProvider pada penyusun host:

WebHost.CreateDefaultBuilder(args)
    .UseDefaultServiceProvider((context, options) => {
        options.ValidateScopes = true;
    })

Sumber Daya Tambahan:

Aplikasi ASP.NET Core mengonfigurasi dan meluncurkan host. Host bertanggung jawab atas startup aplikasi dan manajemen seumur hidup. Minimal, host mengonfigurasi server dan alur pemrosesan permintaan. Host juga dapat menyiapkan pengelogan, injeksi dependensi, dan konfigurasi.

Artikel ini membahas Web Host, yang tetap tersedia hanya untuk kompatibilitas mundur. Templat ASP.NET Core membuat Host Generik .NET, yang direkomendasikan untuk semua jenis aplikasi.

Menyiapkan host

Buat host menggunakan instans IWebHostBuilder. Ini biasanya dilakukan di titik masuk aplikasi, Main metode .

Dalam templat proyek, Main terletak di Program.cs. Panggilan CreateDefaultBuilder aplikasi umum untuk mulai menyiapkan host:

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

    public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
        WebHost.CreateDefaultBuilder(args)
            .UseStartup<Startup>();
}

Kode yang memanggil CreateDefaultBuilder berada dalam metode bernama CreateWebHostBuilder, yang memisahkannya dari kode dalam Main panggilan Run tersebut pada objek penyusun. Pemisahan ini diperlukan jika Anda menggunakan alat Entity Framework Core. Alat mengharapkan untuk menemukan CreateWebHostBuilder metode yang dapat mereka panggil pada waktu desain untuk mengonfigurasi host tanpa menjalankan aplikasi. Alternatifnya adalah menerapkan IDesignTimeDbContextFactory. Untuk informasi selengkapnya, lihat Pembuatan DbContext waktu desain.

CreateDefaultBuilder melakukan tugas-tugas berikut:

Konfigurasi yang ditentukan oleh CreateDefaultBuilder dapat ditimpa dan ditambah oleh ConfigureAppConfiguration, ConfigureLogging, dan metode dan metode ekstensi lainnya dari IWebHostBuilder. Beberapa contoh berikut:

  • ConfigureAppConfiguration digunakan untuk menentukan tambahan IConfiguration untuk aplikasi. Panggilan berikut ConfigureAppConfiguration menambahkan delegasi untuk menyertakan konfigurasi aplikasi dalam appsettings.xml file. ConfigureAppConfiguration dapat dipanggil beberapa kali. Perhatikan bahwa konfigurasi ini tidak berlaku untuk host (misalnya, URL atau lingkungan server). Lihat bagian Nilai konfigurasi host.

    WebHost.CreateDefaultBuilder(args)
        .ConfigureAppConfiguration((hostingContext, config) =>
        {
            config.AddXmlFile("appsettings.xml", optional: true, reloadOnChange: true);
        })
        ...
    
  • Panggilan berikut ConfigureLogging menambahkan delegasi untuk mengonfigurasi tingkat pengelogan minimum (SetMinimumLevel) ke LogLevel.Warning. Pengaturan ini mengambil alih pengaturan di (LogLevel.Debug) dan appsettings.Production.json (LogLevel.Error) yang dikonfigurasi appsettings.Development.json oleh CreateDefaultBuilder. ConfigureLogging dapat dipanggil beberapa kali.

    WebHost.CreateDefaultBuilder(args)
        .ConfigureLogging(logging => 
        {
            logging.SetMinimumLevel(LogLevel.Warning);
        })
        ...
    
  • Panggilan berikut untuk ConfigureKestrel mengambil alih Limits.MaxRequestBodySize default sebesar 30.000.000 byte yang dibuat saat Kestrel dikonfigurasi oleh CreateDefaultBuilder:

    WebHost.CreateDefaultBuilder(args)
        .ConfigureKestrel((context, options) =>
        {
            options.Limits.MaxRequestBodySize = 20000000;
        });
    

Akar konten menentukan tempat host mencari file konten, seperti file tampilan MVC. Saat aplikasi dimulai dari folder akar proyek, folder akar proyek digunakan sebagai akar konten. Ini adalah default yang digunakan di Visual Studio dan templat baru dotnet.

Untuk informasi selengkapnya tentang konfigurasi aplikasi, lihat Konfigurasi di ASP.NET Core.

Catatan

Sebagai alternatif untuk menggunakan metode statis CreateDefaultBuilder , membuat host dari WebHostBuilder adalah pendekatan yang didukung dengan ASP.NET Core 2.x.

Saat menyiapkan host, Configure dan ConfigureServices metode dapat disediakan. Startup Jika kelas ditentukan, kelas harus menentukan Configure metode. Untuk informasi selengkapnya, lihat Pengaktifan aplikasi di ASP.NET Core. Beberapa panggilan untuk ConfigureServices ditambahkan satu dengan yang lain. Beberapa panggilan ke Configure atau UseStartup pada WebHostBuilder pengaturan ganti sebelumnya.

Nilai konfigurasi host

WebHostBuilder bergantung pada pendekatan berikut untuk mengatur nilai konfigurasi host:

  • Konfigurasi penyusun host, yang mencakup variabel lingkungan dengan format ASPNETCORE_{configurationKey}. Contohnya,ASPNETCORE_ENVIRONMENT.
  • Ekstensi seperti UseContentRoot dan UseConfiguration (lihat bagian Ambil alih konfigurasi ).
  • UseSetting dan kunci terkait. Saat mengatur nilai dengan UseSetting, nilai diatur sebagai string terlepas dari jenisnya.

Host menggunakan opsi mana pun yang menetapkan nilai yang terakhir. Untuk informasi selengkapnya, lihat Mengambil alih konfigurasi di bagian berikutnya.

Kunci Aplikasi (Nama)

Properti IWebHostEnvironment.ApplicationName secara otomatis diatur ketika UseStartup atau Configure dipanggil selama konstruksi host. Nilai diatur ke nama rakitan yang berisi titik masuk aplikasi. Untuk mengatur nilai secara eksplisit, gunakan WebHostDefaults.ApplicationKey:

Kunci: applicationName
Jenis: string
Default: Nama rakitan yang berisi titik masuk aplikasi.
Atur menggunakan: UseSetting
Variabel lingkungan: ASPNETCORE_APPLICATIONNAME

WebHost.CreateDefaultBuilder(args)
    .UseSetting(WebHostDefaults.ApplicationKey, "CustomApplicationName")

Menangkap Kesalahan Startup

Pengaturan ini mengontrol pengambilan kesalahan startup.

Kunci: captureStartupErrors
Jenis: bool (true atau 1)
Default: Default ke false kecuali aplikasi berjalan dengan Kestrel di belakang IIS, di mana defaultnya adalah true.
Atur menggunakan: CaptureStartupErrors
Variabel lingkungan: ASPNETCORE_CAPTURESTARTUPERRORS

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

WebHost.CreateDefaultBuilder(args)
    .CaptureStartupErrors(true)

Akar konten

Pengaturan ini menentukan di mana ASP.NET Core mulai mencari file konten.

Kunci: contentRoot
Jenis: string
Default: Default ke folder tempat perakitan aplikasi berada.
Atur menggunakan: UseContentRoot
Variabel lingkungan: ASPNETCORE_CONTENTROOT

Akar konten juga digunakan sebagai jalur dasar untuk akar web. Jika jalur akar konten tidak ada, host gagal memulai.

WebHost.CreateDefaultBuilder(args)
    .UseContentRoot("c:\\<content-root>")

Untuk informasi selengkapnya, lihat:

Kesalahan Terperinci

Menentukan apakah kesalahan terperinci harus diambil.

Kunci: detailedErrors
Jenis: bool (true atau 1)
Default: false
Atur menggunakan: UseSetting
Variabel lingkungan: ASPNETCORE_DETAILEDERRORS

Saat diaktifkan (atau saat Lingkungan diatur ke Development), aplikasi menangkap pengecualian terperinci.

WebHost.CreateDefaultBuilder(args)
    .UseSetting(WebHostDefaults.DetailedErrorsKey, "true")

Lingkungan

Mengatur lingkungan aplikasi.

Kunci: lingkungan
Jenis: string
Default: Produksi
Atur menggunakan: UseEnvironment
Variabel lingkungan: ASPNETCORE_ENVIRONMENT

Lingkungan dapat diatur ke nilai apa pun. Nilai yang ditentukan kerangka kerja meliputi Development, Staging, dan Production. Nilai tidak peka huruf besar/kecil. Secara default, Lingkungan dibaca dari ASPNETCORE_ENVIRONMENT variabel lingkungan. Saat menggunakan Visual Studio, variabel lingkungan dapat diatur dalam launchSettings.json file. Untuk informasi lebih lanjut, lihat Menggunakan beberapa lingkungan di ASP.NET Core.

WebHost.CreateDefaultBuilder(args)
    .UseEnvironment(EnvironmentName.Development)

Hosting Startup Assemblies

Mengatur rakitan startup hosting aplikasi.

Kunci: hostingStartupAssemblies
Jenis: string
Default: String kosong
Atur menggunakan: UseSetting
Variabel lingkungan: ASPNETCORE_HOSTINGSTARTUPASSEMBLIES

String rakitan startup hosting yang dibatasi titik koma untuk dimuat saat startup.

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

WebHost.CreateDefaultBuilder(args)
    .UseSetting(WebHostDefaults.HostingStartupAssembliesKey, "assembly1;assembly2")

Port HTTPS

Atur port pengalihan HTTPS. Digunakan dalam memberlakukan HTTPS.

Kunci: https_port
Jenis: string
Default: Nilai default tidak diatur.
Atur menggunakan: UseSetting
Variabel lingkungan: ASPNETCORE_HTTPS_PORTS

WebHost.CreateDefaultBuilder(args)
    .UseSetting("https_port", "8080")

Hosting Startup Mengecualikan Rakitan

String rakitan startup hosting yang dibatasi titik koma untuk dikecualikan saat startup.

Kunci: hostingStartupExcludeAssemblies
Jenis: string
Default: String kosong
Atur menggunakan: UseSetting
Variabel lingkungan: ASPNETCORE_HOSTINGSTARTUPEXCLUDEASSEMBLIES

WebHost.CreateDefaultBuilder(args)
    .UseSetting(WebHostDefaults.HostingStartupExcludeAssembliesKey, "assembly1;assembly2")

Lebih suka URL Hosting

Menunjukkan apakah host harus mendengarkan URL yang dikonfigurasi dengan WebHostBuilder alih-alih yang dikonfigurasi dengan IServer implementasi.

Kunci: preferHostingUrls
Jenis: bool (true atau 1)
Default: false
Atur menggunakan: PreferHostingUrls
Variabel lingkungan: ASPNETCORE_PREFERHOSTINGURLS

WebHost.CreateDefaultBuilder(args)
    .PreferHostingUrls(true)

Mencegah Startup 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 atau 1)
Default: false
Atur menggunakan: UseSetting
Variabel lingkungan: ASPNETCORE_PREVENTHOSTINGSTARTUP

WebHost.CreateDefaultBuilder(args)
    .UseSetting(WebHostDefaults.PreventHostingStartupKey, "true")

URL Server

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

Kunci: url
Jenis: string
Default: http://localhost:5000
Atur menggunakan: UseUrls
Variabel lingkungan: ASPNETCORE_URLS

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

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

Kestrel memiliki API konfigurasi titik akhirnya sendiri. Untuk informasi selengkapnya, lihat Mengonfigurasi titik akhir untuk server web ASP.NET CoreKestrel.

Waktu Matikan Habis

Menentukan jumlah waktu untuk menunggu Web Host dimatikan.

Kunci: shutdownTimeoutSeconds
Jenis: int
Default: 5
Atur menggunakan: UseShutdownTimeout
Variabel lingkungan: ASPNETCORE_SHUTDOWNTIMEOUTSECONDS

Meskipun kunci menerima int dengan UseSetting (misalnya, .UseSetting(WebHostDefaults.ShutdownTimeoutKey, "10")), UseShutdownTimeout metode ekstensi mengambil TimeSpan.

Selama periode waktu habis, hosting:

Jika periode batas waktu berakhir sebelum semua layanan yang dihosting berhenti, layanan aktif yang tersisa akan dihentikan saat aplikasi dimatikan. Layanan berhenti meskipun belum selesai diproses. Jika layanan memerlukan waktu tambahan untuk berhenti, tingkatkan batas waktu.

WebHost.CreateDefaultBuilder(args)
    .UseShutdownTimeout(TimeSpan.FromSeconds(10))

Rakitan Startup

Menentukan assembly untuk Startup mencari kelas.

Kunci: startupAssembly
Jenis: string
Default: Rakitan aplikasi
Atur menggunakan: UseStartup
Variabel lingkungan: ASPNETCORE_STARTUPASSEMBLY

Rakitan berdasarkan nama (string) atau jenis (TStartup) dapat dirujuk. Jika beberapa UseStartup metode dipanggil, metode terakhir lebih diutamakan.

WebHost.CreateDefaultBuilder(args)
    .UseStartup("StartupAssemblyName")
WebHost.CreateDefaultBuilder(args)
    .UseStartup<TStartup>()

Akar web

Mengatur jalur relatif ke aset statis aplikasi.

Kunci: webroot
Jenis: string
Default: Defaultnya adalah wwwroot. Jalur ke {content root}/wwwroot harus ada. Jika jalur tidak ada, penyedia file tanpa operasi akan digunakan.
Atur menggunakan: UseWebRoot
Variabel lingkungan: ASPNETCORE_WEBROOT

WebHost.CreateDefaultBuilder(args)
    .UseWebRoot("public")

Untuk informasi selengkapnya, lihat:

Mengesampingkan konfigurasi

Gunakan Konfigurasi untuk mengonfigurasi Web Host. Dalam contoh berikut, konfigurasi host secara opsional ditentukan dalam hostsettings.json file. Konfigurasi apa pun yang hostsettings.json dimuat dari file dapat ditimpa oleh argumen baris perintah. Konfigurasi bawaan (dalam config) digunakan untuk mengonfigurasi host dengan UseConfiguration. IWebHostBuilder konfigurasi ditambahkan ke konfigurasi aplikasi, tetapi sebaliknya tidak benar—ConfigureAppConfiguration tidak memengaruhi IWebHostBuilder konfigurasi.

Mengambil alih konfigurasi yang disediakan oleh UseUrls hostsettings.json konfigurasi terlebih dahulu, konfigurasi argumen baris perintah kedua:

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

    public static IWebHostBuilder CreateWebHostBuilder(string[] args)
    {
        var config = new ConfigurationBuilder()
            .SetBasePath(Directory.GetCurrentDirectory())
            .AddJsonFile("hostsettings.json", optional: true)
            .AddCommandLine(args)
            .Build();

        return WebHost.CreateDefaultBuilder(args)
            .UseUrls("http://*:5000")
            .UseConfiguration(config)
            .Configure(app =>
            {
                app.Run(context => 
                    context.Response.WriteAsync("Hello, World!"));
            });
    }
}

hostsettings.json:

{
    urls: "http://*:5005"
}

Catatan

UseConfiguration hanya menyalin kunci dari yang disediakan IConfiguration ke konfigurasi pembangun host. Oleh karena itu, pengaturan reloadOnChange: true untuk file pengaturan JSON, INI, dan XML tidak berpengaruh.

Untuk menentukan host yang dijalankan pada URL tertentu, nilai yang diinginkan dapat diteruskan dari prompt perintah saat menjalankan dotnet run. Argumen baris perintah mengambil urls alih nilai dari hostsettings.json file, dan server mendengarkan port 8080:

dotnet run --urls "http://*:8080"

Mengelola host

jalankan

Metode Run memulai aplikasi web dan memblokir utas panggilan hingga host dimatikan:

host.Run();

Mulai

Jalankan host dengan cara yang tidak memblokir dengan memanggil metodenya Start :

using (host)
{
    host.Start();
    Console.ReadLine();
}

Jika daftar URL diteruskan ke Start metode , URL akan didengarkan pada URL yang ditentukan:

var urls = new List<string>()
{
    "http://*:5000",
    "http://localhost:5001"
};

var host = new WebHostBuilder()
    .UseKestrel()
    .UseStartup<Startup>()
    .Start(urls.ToArray());

using (host)
{
    Console.ReadLine();
}

Aplikasi ini dapat menginisialisasi dan memulai host baru menggunakan default yang telah dikonfigurasi sebelumnya menggunakan CreateDefaultBuilder metode kenyamanan statis. Metode ini memulai server tanpa output konsol dan dengan WaitForShutdown menunggu jeda (Ctrl-C/SIGINT atau SIGTERM):

Start(RequestDelegate app)

Mulailah dengan RequestDelegate:

using (var host = WebHost.Start(app => app.Response.WriteAsync("Hello, World!")))
{
    Console.WriteLine("Use Ctrl-C to shutdown the host...");
    host.WaitForShutdown();
}

Buat permintaan di browser untuk http://localhost:5000 menerima respons "Halo Dunia!" WaitForShutdown blok hingga jeda (Ctrl-C/SIGINT atau SIGTERM) dikeluarkan. Aplikasi menampilkan Console.WriteLine pesan dan menunggu keypress keluar.

Mulai(url string, aplikasi RequestDelegate)

Mulai dengan URL dan RequestDelegate:

using (var host = WebHost.Start("http://localhost:8080", app => app.Response.WriteAsync("Hello, World!")))
{
    Console.WriteLine("Use Ctrl-C to shutdown the host...");
    host.WaitForShutdown();
}

Menghasilkan hasil yang sama dengan Start(RequestDelegate app), kecuali aplikasi merespons di http://localhost:8080.

Start(Action<IRouteBuilder> routeBuilder)

Gunakan instans IRouteBuilder (Microsoft.AspNetCore.Routing) untuk menggunakan middleware perutean:

using (var host = WebHost.Start(router => router
    .MapGet("hello/{name}", (req, res, data) => 
        res.WriteAsync($"Hello, {data.Values["name"]}!"))
    .MapGet("buenosdias/{name}", (req, res, data) => 
        res.WriteAsync($"Buenos dias, {data.Values["name"]}!"))
    .MapGet("throw/{message?}", (req, res, data) => 
        throw new Exception((string)data.Values["message"] ?? "Uh oh!"))
    .MapGet("{greeting}/{name}", (req, res, data) => 
        res.WriteAsync($"{data.Values["greeting"]}, {data.Values["name"]}!"))
    .MapGet("", (req, res, data) => res.WriteAsync("Hello, World!"))))
{
    Console.WriteLine("Use Ctrl-C to shutdown the host...");
    host.WaitForShutdown();
}

Gunakan permintaan browser berikut dengan contoh:

Permintaan Respons
http://localhost:5000/hello/Martin Halo, Martin!
http://localhost:5000/buenosdias/Catrina Buenos dias, Catrina!
http://localhost:5000/throw/ooops! Melempar pengecualian dengan string "ooops!"
http://localhost:5000/throw Melempar pengecualian dengan string "Uh oh!"
http://localhost:5000/Sante/Kevin Sante, Kevin!
http://localhost:5000 Halo Dunia!

WaitForShutdown memblokir hingga jeda (Ctrl-C/SIGINT atau SIGTERM) dikeluarkan. Aplikasi menampilkan Console.WriteLine pesan dan menunggu keypress keluar.

Start(string url, Action<IRouteBuilder> routeBuilder)

Gunakan URL dan instans IRouteBuilder:

using (var host = WebHost.Start("http://localhost:8080", router => router
    .MapGet("hello/{name}", (req, res, data) => 
        res.WriteAsync($"Hello, {data.Values["name"]}!"))
    .MapGet("buenosdias/{name}", (req, res, data) => 
        res.WriteAsync($"Buenos dias, {data.Values["name"]}!"))
    .MapGet("throw/{message?}", (req, res, data) => 
        throw new Exception((string)data.Values["message"] ?? "Uh oh!"))
    .MapGet("{greeting}/{name}", (req, res, data) => 
        res.WriteAsync($"{data.Values["greeting"]}, {data.Values["name"]}!"))
    .MapGet("", (req, res, data) => res.WriteAsync("Hello, World!"))))
{
    Console.WriteLine("Use Ctrl-C to shut down the host...");
    host.WaitForShutdown();
}

Menghasilkan hasil yang sama dengan Start(Action<IRouteBuilder routeBuilder> ), kecuali aplikasi merespons di http://localhost:8080.

StartWith(Aplikasi Action<IApplicationBuilder> )

Berikan delegasi untuk mengonfigurasi IApplicationBuilder:

using (var host = WebHost.StartWith(app => 
    app.Use(next => 
    {
        return async context => 
        {
            await context.Response.WriteAsync("Hello World!");
        };
    })))
{
    Console.WriteLine("Use Ctrl-C to shut down the host...");
    host.WaitForShutdown();
}

Buat permintaan di browser untuk http://localhost:5000 menerima respons "Halo Dunia!" WaitForShutdown blok hingga jeda (Ctrl-C/SIGINT atau SIGTERM) dikeluarkan. Aplikasi menampilkan Console.WriteLine pesan dan menunggu keypress keluar.

StartWith(url string, Aplikasi Action<IApplicationBuilder> )

Berikan URL dan delegasi untuk mengonfigurasi IApplicationBuilder:

using (var host = WebHost.StartWith("http://localhost:8080", app => 
    app.Use(next => 
    {
        return async context => 
        {
            await context.Response.WriteAsync("Hello World!");
        };
    })))
{
    Console.WriteLine("Use Ctrl-C to shut down the host...");
    host.WaitForShutdown();
}

Menghasilkan hasil yang sama dengan StartWith(Aplikasi Action<IApplicationBuilder> ), kecuali aplikasi merespons di http://localhost:8080.

Antarmuka IWebHostEnvironment

Antarmuka menyediakan IWebHostEnvironment informasi tentang lingkungan hosting web aplikasi. Gunakan injeksi konstruktor untuk mendapatkan IWebHostEnvironment untuk menggunakan properti dan metode ekstensinya:

public class CustomFileReader
{
    private readonly IWebHostEnvironment _env;

    public CustomFileReader(IWebHostEnvironment env)
    {
        _env = env;
    }

    public string ReadFile(string filePath)
    {
        var fileProvider = _env.WebRootFileProvider;
        // Process the file here
    }
}

Pendekatan berbasis konvensi dapat digunakan untuk mengonfigurasi aplikasi saat startup berdasarkan lingkungan. Atau, masukkan ke IWebHostEnvironment Startup dalam konstruktor untuk digunakan dalam ConfigureServices:

public class Startup
{
    public Startup(IWebHostEnvironment env)
    {
        HostingEnvironment = env;
    }

    public IWebHostEnvironment HostingEnvironment { get; }

    public void ConfigureServices(IServiceCollection services)
    {
        if (HostingEnvironment.IsDevelopment())
        {
            // Development configuration
        }
        else
        {
            // Staging/Production configuration
        }

        var contentRootPath = HostingEnvironment.ContentRootPath;
    }
}

Catatan

Selain IsDevelopment metode ekstensi, IWebHostEnvironment menawarkan IsStaging, IsProduction, dan IsEnvironment(string environmentName) metode. Untuk informasi lebih lanjut, lihat Menggunakan beberapa lingkungan di ASP.NET Core.

Layanan ini IWebHostEnvironment juga dapat disuntikkan langsung ke Configure metode untuk menyiapkan alur pemrosesan:

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    if (env.IsDevelopment())
    {
        // In Development, use the Developer Exception Page
        app.UseDeveloperExceptionPage();
    }
    else
    {
        // In Staging/Production, route exceptions to /error
        app.UseExceptionHandler("/error");
    }

    var contentRootPath = env.ContentRootPath;
}

IWebHostEnvironmentdapat disuntikkan ke Invoke dalam metode saat membuat middleware kustom:

public async Task Invoke(HttpContext context, IWebHostEnvironment env)
{
    if (env.IsDevelopment())
    {
        // Configure middleware for Development
    }
    else
    {
        // Configure middleware for Staging/Production
    }

    var contentRootPath = env.ContentRootPath;
}

Antarmuka IHostApplicationLifetime

IHostApplicationLifetime memungkinkan aktivitas pasca-startup dan shutdown. Tiga properti pada antarmuka adalah token pembatalan yang digunakan untuk mendaftarkan Action metode yang menentukan peristiwa startup dan shutdown.

Token Pembatalan Dipicu ketika...
ApplicationStarted Host telah sepenuhnya dimulai.
ApplicationStopped Host menyelesaikan pematian yang anggun. Semua permintaan harus diproses. Matikan blok hingga kejadian ini selesai.
ApplicationStopping Host melakukan pematian yang anggun. Permintaan mungkin masih diproses. Matikan blok hingga kejadian ini selesai.
public class Startup
{
    public void Configure(IApplicationBuilder app, IHostApplicationLifetime appLifetime)
    {
        appLifetime.ApplicationStarted.Register(OnStarted);
        appLifetime.ApplicationStopping.Register(OnStopping);
        appLifetime.ApplicationStopped.Register(OnStopped);

        Console.CancelKeyPress += (sender, eventArgs) =>
        {
            appLifetime.StopApplication();
            // Don't terminate the process immediately, wait for the Main thread to exit gracefully.
            eventArgs.Cancel = true;
        };
    }

    private void OnStarted()
    {
        // Perform post-startup activities here
    }

    private void OnStopping()
    {
        // Perform on-stopping activities here
    }

    private void OnStopped()
    {
        // Perform post-stopped activities here
    }
}

StopApplication meminta penghentian aplikasi. Kelas berikut menggunakan StopApplication untuk mematikan aplikasi dengan anggun saat metode kelas Shutdown dipanggil:

public class MyClass
{
    private readonly IHostApplicationLifetime _appLifetime;

    public MyClass(IHostApplicationLifetime appLifetime)
    {
        _appLifetime = appLifetime;
    }

    public void Shutdown()
    {
        _appLifetime.StopApplication();
    }
}

Validasi cakupan

CreateDefaultBuilderServiceProviderOptions.ValidateScopes diatur ke true jika lingkungan aplikasi adalah Pengembangan.

Ketika ValidateScopes diatur ke true, penyedia layanan default melakukan pemeriksaan untuk memverifikasi bahwa:

  • Layanan terlingkup tidak diselesaikan secara langsung atau tidak langsung dari penyedia layanan akar.
  • Layanan terlingkup tidak secara langsung atau tidak langsung disuntikkan ke dalam singleton.

Penyedia layanan akar dibuat ketika BuildServiceProvider dipanggil. Masa pakai penyedia layanan akar sesuai dengan masa pakai aplikasi/server saat penyedia mulai dengan aplikasi dan dibuang saat aplikasi dimatikan.

Layanan tercakup dibuang oleh kontainer yang membuatnya. Jika layanan tercakup dibuat dalam kontainer akar, masa pakai layanan secara efektif dipromosikan ke singleton karena hanya dibuang oleh kontainer akar saat aplikasi/server dimatikan. Memvalidasi cakupan layanan menangkap situasi ini ketika BuildServiceProvider dipanggil.

Untuk selalu memvalidasi cakupan, termasuk di lingkungan Produksi, konfigurasikan ServiceProviderOptions dengan UseDefaultServiceProvider pada penyusun host:

WebHost.CreateDefaultBuilder(args)
    .UseDefaultServiceProvider((context, options) => {
        options.ValidateScopes = true;
    })

Sumber Daya Tambahan:

Aplikasi ASP.NET Core mengonfigurasi dan meluncurkan host. Host bertanggung jawab atas startup aplikasi dan manajemen seumur hidup. Minimal, host mengonfigurasi server dan alur pemrosesan permintaan. Host juga dapat menyiapkan pengelogan, injeksi dependensi, dan konfigurasi.

Artikel ini membahas Web Host, yang tetap tersedia hanya untuk kompatibilitas mundur. Templat ASP.NET Core membuat Host Generik .NET, yang direkomendasikan untuk semua jenis aplikasi.

Menyiapkan host

Buat host menggunakan instans IWebHostBuilder. Ini biasanya dilakukan di titik masuk aplikasi, Main metode .

Dalam templat proyek, Main terletak di Program.cs. Panggilan CreateDefaultBuilder aplikasi umum untuk mulai menyiapkan host:

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

    public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
        WebHost.CreateDefaultBuilder(args)
            .UseStartup<Startup>();
}

Kode yang memanggil CreateDefaultBuilder berada dalam metode bernama CreateWebHostBuilder, yang memisahkannya dari kode dalam Main panggilan Run tersebut pada objek penyusun. Pemisahan ini diperlukan jika Anda menggunakan alat Entity Framework Core. Alat mengharapkan untuk menemukan CreateWebHostBuilder metode yang dapat mereka panggil pada waktu desain untuk mengonfigurasi host tanpa menjalankan aplikasi. Alternatifnya adalah menerapkan IDesignTimeDbContextFactory. Untuk informasi selengkapnya, lihat Pembuatan DbContext waktu desain.

CreateDefaultBuilder melakukan tugas-tugas berikut:

Konfigurasi yang ditentukan oleh CreateDefaultBuilder dapat ditimpa dan ditambah oleh ConfigureAppConfiguration, ConfigureLogging, dan metode dan metode ekstensi lainnya dari IWebHostBuilder. Beberapa contoh berikut:

  • ConfigureAppConfiguration digunakan untuk menentukan tambahan IConfiguration untuk aplikasi. Panggilan berikut ConfigureAppConfiguration menambahkan delegasi untuk menyertakan konfigurasi aplikasi dalam appsettings.xml file. ConfigureAppConfiguration dapat dipanggil beberapa kali. Perhatikan bahwa konfigurasi ini tidak berlaku untuk host (misalnya, URL atau lingkungan server). Lihat bagian Nilai konfigurasi host.

    WebHost.CreateDefaultBuilder(args)
        .ConfigureAppConfiguration((hostingContext, config) =>
        {
            config.AddXmlFile("appsettings.xml", optional: true, reloadOnChange: true);
        })
        ...
    
  • Panggilan berikut ConfigureLogging menambahkan delegasi untuk mengonfigurasi tingkat pengelogan minimum (SetMinimumLevel) ke LogLevel.Warning. Pengaturan ini mengambil alih pengaturan di (LogLevel.Debug) dan appsettings.Production.json (LogLevel.Error) yang dikonfigurasi appsettings.Development.json oleh CreateDefaultBuilder. ConfigureLogging dapat dipanggil beberapa kali.

    WebHost.CreateDefaultBuilder(args)
        .ConfigureLogging(logging => 
        {
            logging.SetMinimumLevel(LogLevel.Warning);
        })
        ...
    
  • Panggilan berikut untuk ConfigureKestrel mengambil alih Limits.MaxRequestBodySize default sebesar 30.000.000 byte yang dibuat saat Kestrel dikonfigurasi oleh CreateDefaultBuilder:

    WebHost.CreateDefaultBuilder(args)
        .ConfigureKestrel((context, options) =>
        {
            options.Limits.MaxRequestBodySize = 20000000;
        });
    

Akar konten menentukan tempat host mencari file konten, seperti file tampilan MVC. Saat aplikasi dimulai dari folder akar proyek, folder akar proyek digunakan sebagai akar konten. Ini adalah default yang digunakan di Visual Studio dan templat baru dotnet.

Untuk informasi selengkapnya tentang konfigurasi aplikasi, lihat Konfigurasi di ASP.NET Core.

Catatan

Sebagai alternatif untuk menggunakan metode statis CreateDefaultBuilder , membuat host dari WebHostBuilder adalah pendekatan yang didukung dengan ASP.NET Core 2.x.

Saat menyiapkan host, Configure dan ConfigureServices metode dapat disediakan. Startup Jika kelas ditentukan, kelas harus menentukan Configure metode. Untuk informasi selengkapnya, lihat Pengaktifan aplikasi di ASP.NET Core. Beberapa panggilan untuk ConfigureServices ditambahkan satu dengan yang lain. Beberapa panggilan ke Configure atau UseStartup pada WebHostBuilder pengaturan ganti sebelumnya.

Nilai konfigurasi host

WebHostBuilder bergantung pada pendekatan berikut untuk mengatur nilai konfigurasi host:

  • Konfigurasi penyusun host, yang mencakup variabel lingkungan dengan format ASPNETCORE_{configurationKey}. Contohnya,ASPNETCORE_ENVIRONMENT.
  • Ekstensi seperti UseContentRoot dan UseConfiguration (lihat bagian Ambil alih konfigurasi ).
  • UseSetting dan kunci terkait. Saat mengatur nilai dengan UseSetting, nilai diatur sebagai string terlepas dari jenisnya.

Host menggunakan opsi mana pun yang menetapkan nilai yang terakhir. Untuk informasi selengkapnya, lihat Mengambil alih konfigurasi di bagian berikutnya.

Kunci Aplikasi (Nama)

Properti IWebHostEnvironment.ApplicationName secara otomatis diatur ketika UseStartup atau Configure dipanggil selama konstruksi host. Nilai diatur ke nama rakitan yang berisi titik masuk aplikasi. Untuk mengatur nilai secara eksplisit, gunakan WebHostDefaults.ApplicationKey:

Kunci: applicationName
Jenis: string
Default: Nama rakitan yang berisi titik masuk aplikasi.
Atur menggunakan: UseSetting
Variabel lingkungan: ASPNETCORE_APPLICATIONNAME

WebHost.CreateDefaultBuilder(args)
    .UseSetting(WebHostDefaults.ApplicationKey, "CustomApplicationName")

Menangkap Kesalahan Startup

Pengaturan ini mengontrol pengambilan kesalahan startup.

Kunci: captureStartupErrors
Jenis: bool (true atau 1)
Default: Default ke false kecuali aplikasi berjalan dengan Kestrel di belakang IIS, di mana defaultnya adalah true.
Atur menggunakan: CaptureStartupErrors
Variabel lingkungan: ASPNETCORE_CAPTURESTARTUPERRORS

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

WebHost.CreateDefaultBuilder(args)
    .CaptureStartupErrors(true)

Akar konten

Pengaturan ini menentukan di mana ASP.NET Core mulai mencari file konten.

Kunci: contentRoot
Jenis: string
Default: Default ke folder tempat perakitan aplikasi berada.
Atur menggunakan: UseContentRoot
Variabel lingkungan: ASPNETCORE_CONTENTROOT

Akar konten juga digunakan sebagai jalur dasar untuk akar web. Jika jalur akar konten tidak ada, host gagal memulai.

WebHost.CreateDefaultBuilder(args)
    .UseContentRoot("c:\\<content-root>")

Untuk informasi selengkapnya, lihat:

Kesalahan Terperinci

Menentukan apakah kesalahan terperinci harus diambil.

Kunci: detailedErrors
Jenis: bool (true atau 1)
Default: false
Atur menggunakan: UseSetting
Variabel lingkungan: ASPNETCORE_DETAILEDERRORS

Saat diaktifkan (atau saat Lingkungan diatur ke Development), aplikasi menangkap pengecualian terperinci.

WebHost.CreateDefaultBuilder(args)
    .UseSetting(WebHostDefaults.DetailedErrorsKey, "true")

Lingkungan

Mengatur lingkungan aplikasi.

Kunci: lingkungan
Jenis: string
Default: Produksi
Atur menggunakan: UseEnvironment
Variabel lingkungan: ASPNETCORE_ENVIRONMENT

Lingkungan dapat diatur ke nilai apa pun. Nilai yang ditentukan kerangka kerja meliputi Development, Staging, dan Production. Nilai tidak peka huruf besar/kecil. Secara default, Lingkungan dibaca dari ASPNETCORE_ENVIRONMENT variabel lingkungan. Saat menggunakan Visual Studio, variabel lingkungan dapat diatur dalam launchSettings.json file. Untuk informasi lebih lanjut, lihat Menggunakan beberapa lingkungan di ASP.NET Core.

WebHost.CreateDefaultBuilder(args)
    .UseEnvironment(EnvironmentName.Development)

Hosting Startup Assemblies

Mengatur rakitan startup hosting aplikasi.

Kunci: hostingStartupAssemblies
Jenis: string
Default: String kosong
Atur menggunakan: UseSetting
Variabel lingkungan: ASPNETCORE_HOSTINGSTARTUPASSEMBLIES

String rakitan startup hosting yang dibatasi titik koma untuk dimuat saat startup.

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

WebHost.CreateDefaultBuilder(args)
    .UseSetting(WebHostDefaults.HostingStartupAssembliesKey, "assembly1;assembly2")

Port HTTPS

Atur port pengalihan HTTPS. Digunakan dalam memberlakukan HTTPS.

Kunci: https_port
Jenis: string
Default: Nilai default tidak diatur.
Atur menggunakan: UseSetting
Variabel lingkungan: ASPNETCORE_HTTPS_PORTS

WebHost.CreateDefaultBuilder(args)
    .UseSetting("https_port", "8080")

Hosting Startup Mengecualikan Rakitan

String rakitan startup hosting yang dibatasi titik koma untuk dikecualikan saat startup.

Kunci: hostingStartupExcludeAssemblies
Jenis: string
Default: String kosong
Atur menggunakan: UseSetting
Variabel lingkungan: ASPNETCORE_HOSTINGSTARTUPEXCLUDEASSEMBLIES

WebHost.CreateDefaultBuilder(args)
    .UseSetting(WebHostDefaults.HostingStartupExcludeAssembliesKey, "assembly1;assembly2")

Lebih suka URL Hosting

Menunjukkan apakah host harus mendengarkan URL yang dikonfigurasi dengan WebHostBuilder alih-alih yang dikonfigurasi dengan IServer implementasi.

Kunci: preferHostingUrls
Jenis: bool (true atau 1)
Default: false
Atur menggunakan: PreferHostingUrls
Variabel lingkungan: ASPNETCORE_PREFERHOSTINGURLS

WebHost.CreateDefaultBuilder(args)
    .PreferHostingUrls(true)

Mencegah Startup 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 atau 1)
Default: false
Atur menggunakan: UseSetting
Variabel lingkungan: ASPNETCORE_PREVENTHOSTINGSTARTUP

WebHost.CreateDefaultBuilder(args)
    .UseSetting(WebHostDefaults.PreventHostingStartupKey, "true")

URL Server

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

Kunci: url
Jenis: string
Default: http://localhost:5000
Atur menggunakan: UseUrls
Variabel lingkungan: ASPNETCORE_URLS

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

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

Kestrel memiliki API konfigurasi titik akhirnya sendiri. Untuk informasi selengkapnya, lihat Kestrel server web di ASP.NET Core.

Waktu Matikan Habis

Menentukan jumlah waktu untuk menunggu Web Host dimatikan.

Kunci: shutdownTimeoutSeconds
Jenis: int
Default: 5
Atur menggunakan: UseShutdownTimeout
Variabel lingkungan: ASPNETCORE_SHUTDOWNTIMEOUTSECONDS

Meskipun kunci menerima int dengan UseSetting (misalnya, .UseSetting(WebHostDefaults.ShutdownTimeoutKey, "10")), UseShutdownTimeout metode ekstensi mengambil TimeSpan.

Selama periode waktu habis, hosting:

Jika periode batas waktu berakhir sebelum semua layanan yang dihosting berhenti, layanan aktif yang tersisa akan dihentikan saat aplikasi dimatikan. Layanan berhenti meskipun belum selesai diproses. Jika layanan memerlukan waktu tambahan untuk berhenti, tingkatkan batas waktu.

WebHost.CreateDefaultBuilder(args)
    .UseShutdownTimeout(TimeSpan.FromSeconds(10))

Rakitan Startup

Menentukan assembly untuk Startup mencari kelas.

Kunci: startupAssembly
Jenis: string
Default: Rakitan aplikasi
Atur menggunakan: UseStartup
Variabel lingkungan: ASPNETCORE_STARTUPASSEMBLY

Rakitan berdasarkan nama (string) atau jenis (TStartup) dapat dirujuk. Jika beberapa UseStartup metode dipanggil, metode terakhir lebih diutamakan.

WebHost.CreateDefaultBuilder(args)
    .UseStartup("StartupAssemblyName")
WebHost.CreateDefaultBuilder(args)
    .UseStartup<TStartup>()

Akar web

Mengatur jalur relatif ke aset statis aplikasi.

Kunci: webroot
Jenis: string
Default: Defaultnya adalah wwwroot. Jalur ke {content root}/wwwroot harus ada. Jika jalur tidak ada, penyedia file tanpa operasi akan digunakan.
Atur menggunakan: UseWebRoot
Variabel lingkungan: ASPNETCORE_WEBROOT

WebHost.CreateDefaultBuilder(args)
    .UseWebRoot("public")

Untuk informasi selengkapnya, lihat:

Mengesampingkan konfigurasi

Gunakan Konfigurasi untuk mengonfigurasi Web Host. Dalam contoh berikut, konfigurasi host secara opsional ditentukan dalam hostsettings.json file. Konfigurasi apa pun yang hostsettings.json dimuat dari file dapat ditimpa oleh argumen baris perintah. Konfigurasi bawaan (dalam config) digunakan untuk mengonfigurasi host dengan UseConfiguration. IWebHostBuilder konfigurasi ditambahkan ke konfigurasi aplikasi, tetapi sebaliknya tidak benar—ConfigureAppConfiguration tidak memengaruhi IWebHostBuilder konfigurasi.

Mengambil alih konfigurasi yang disediakan oleh UseUrls hostsettings.json konfigurasi terlebih dahulu, konfigurasi argumen baris perintah kedua:

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

    public static IWebHostBuilder CreateWebHostBuilder(string[] args)
    {
        var config = new ConfigurationBuilder()
            .SetBasePath(Directory.GetCurrentDirectory())
            .AddJsonFile("hostsettings.json", optional: true)
            .AddCommandLine(args)
            .Build();

        return WebHost.CreateDefaultBuilder(args)
            .UseUrls("http://*:5000")
            .UseConfiguration(config)
            .Configure(app =>
            {
                app.Run(context => 
                    context.Response.WriteAsync("Hello, World!"));
            });
    }
}

hostsettings.json:

{
    urls: "http://*:5005"
}

Catatan

UseConfiguration hanya menyalin kunci dari yang disediakan IConfiguration ke konfigurasi pembangun host. Oleh karena itu, pengaturan reloadOnChange: true untuk file pengaturan JSON, INI, dan XML tidak berpengaruh.

Untuk menentukan host yang dijalankan pada URL tertentu, nilai yang diinginkan dapat diteruskan dari prompt perintah saat menjalankan dotnet run. Argumen baris perintah mengambil urls alih nilai dari hostsettings.json file, dan server mendengarkan port 8080:

dotnet run --urls "http://*:8080"

Mengelola host

jalankan

Metode Run memulai aplikasi web dan memblokir utas panggilan hingga host dimatikan:

host.Run();

Mulai

Jalankan host dengan cara yang tidak memblokir dengan memanggil metodenya Start :

using (host)
{
    host.Start();
    Console.ReadLine();
}

Jika daftar URL diteruskan ke Start metode , URL akan didengarkan pada URL yang ditentukan:

var urls = new List<string>()
{
    "http://*:5000",
    "http://localhost:5001"
};

var host = new WebHostBuilder()
    .UseKestrel()
    .UseStartup<Startup>()
    .Start(urls.ToArray());

using (host)
{
    Console.ReadLine();
}

Aplikasi ini dapat menginisialisasi dan memulai host baru menggunakan default yang telah dikonfigurasi sebelumnya menggunakan CreateDefaultBuilder metode kenyamanan statis. Metode ini memulai server tanpa output konsol dan dengan WaitForShutdown menunggu jeda (Ctrl-C/SIGINT atau SIGTERM):

Start(RequestDelegate app)

Mulailah dengan RequestDelegate:

using (var host = WebHost.Start(app => app.Response.WriteAsync("Hello, World!")))
{
    Console.WriteLine("Use Ctrl-C to shutdown the host...");
    host.WaitForShutdown();
}

Buat permintaan di browser untuk http://localhost:5000 menerima respons "Halo Dunia!" WaitForShutdown blok hingga jeda (Ctrl-C/SIGINT atau SIGTERM) dikeluarkan. Aplikasi menampilkan Console.WriteLine pesan dan menunggu keypress keluar.

Mulai(url string, aplikasi RequestDelegate)

Mulai dengan URL dan RequestDelegate:

using (var host = WebHost.Start("http://localhost:8080", app => app.Response.WriteAsync("Hello, World!")))
{
    Console.WriteLine("Use Ctrl-C to shutdown the host...");
    host.WaitForShutdown();
}

Menghasilkan hasil yang sama dengan Start(RequestDelegate app), kecuali aplikasi merespons di http://localhost:8080.

Start(Action<IRouteBuilder> routeBuilder)

Gunakan instans IRouteBuilder (Microsoft.AspNetCore.Routing) untuk menggunakan middleware perutean:

using (var host = WebHost.Start(router => router
    .MapGet("hello/{name}", (req, res, data) => 
        res.WriteAsync($"Hello, {data.Values["name"]}!"))
    .MapGet("buenosdias/{name}", (req, res, data) => 
        res.WriteAsync($"Buenos dias, {data.Values["name"]}!"))
    .MapGet("throw/{message?}", (req, res, data) => 
        throw new Exception((string)data.Values["message"] ?? "Uh oh!"))
    .MapGet("{greeting}/{name}", (req, res, data) => 
        res.WriteAsync($"{data.Values["greeting"]}, {data.Values["name"]}!"))
    .MapGet("", (req, res, data) => res.WriteAsync("Hello, World!"))))
{
    Console.WriteLine("Use Ctrl-C to shutdown the host...");
    host.WaitForShutdown();
}

Gunakan permintaan browser berikut dengan contoh:

Permintaan Respons
http://localhost:5000/hello/Martin Halo, Martin!
http://localhost:5000/buenosdias/Catrina Buenos dias, Catrina!
http://localhost:5000/throw/ooops! Melempar pengecualian dengan string "ooops!"
http://localhost:5000/throw Melempar pengecualian dengan string "Uh oh!"
http://localhost:5000/Sante/Kevin Sante, Kevin!
http://localhost:5000 Halo Dunia!

WaitForShutdown memblokir hingga jeda (Ctrl-C/SIGINT atau SIGTERM) dikeluarkan. Aplikasi menampilkan Console.WriteLine pesan dan menunggu keypress keluar.

Start(string url, Action<IRouteBuilder> routeBuilder)

Gunakan URL dan instans IRouteBuilder:

using (var host = WebHost.Start("http://localhost:8080", router => router
    .MapGet("hello/{name}", (req, res, data) => 
        res.WriteAsync($"Hello, {data.Values["name"]}!"))
    .MapGet("buenosdias/{name}", (req, res, data) => 
        res.WriteAsync($"Buenos dias, {data.Values["name"]}!"))
    .MapGet("throw/{message?}", (req, res, data) => 
        throw new Exception((string)data.Values["message"] ?? "Uh oh!"))
    .MapGet("{greeting}/{name}", (req, res, data) => 
        res.WriteAsync($"{data.Values["greeting"]}, {data.Values["name"]}!"))
    .MapGet("", (req, res, data) => res.WriteAsync("Hello, World!"))))
{
    Console.WriteLine("Use Ctrl-C to shut down the host...");
    host.WaitForShutdown();
}

Menghasilkan hasil yang sama dengan Start(Action<IRouteBuilder routeBuilder> ), kecuali aplikasi merespons di http://localhost:8080.

StartWith(Aplikasi Action<IApplicationBuilder> )

Berikan delegasi untuk mengonfigurasi IApplicationBuilder:

using (var host = WebHost.StartWith(app => 
    app.Use(next => 
    {
        return async context => 
        {
            await context.Response.WriteAsync("Hello World!");
        };
    })))
{
    Console.WriteLine("Use Ctrl-C to shut down the host...");
    host.WaitForShutdown();
}

Buat permintaan di browser untuk http://localhost:5000 menerima respons "Halo Dunia!" WaitForShutdown blok hingga jeda (Ctrl-C/SIGINT atau SIGTERM) dikeluarkan. Aplikasi menampilkan Console.WriteLine pesan dan menunggu keypress keluar.

StartWith(url string, Aplikasi Action<IApplicationBuilder> )

Berikan URL dan delegasi untuk mengonfigurasi IApplicationBuilder:

using (var host = WebHost.StartWith("http://localhost:8080", app => 
    app.Use(next => 
    {
        return async context => 
        {
            await context.Response.WriteAsync("Hello World!");
        };
    })))
{
    Console.WriteLine("Use Ctrl-C to shut down the host...");
    host.WaitForShutdown();
}

Menghasilkan hasil yang sama dengan StartWith(Aplikasi Action<IApplicationBuilder> ), kecuali aplikasi merespons di http://localhost:8080.

Antarmuka IWebHostEnvironment

Antarmuka menyediakan IWebHostEnvironment informasi tentang lingkungan hosting web aplikasi. Gunakan injeksi konstruktor untuk mendapatkan IWebHostEnvironment untuk menggunakan properti dan metode ekstensinya:

public class CustomFileReader
{
    private readonly IWebHostEnvironment _env;

    public CustomFileReader(IWebHostEnvironment env)
    {
        _env = env;
    }

    public string ReadFile(string filePath)
    {
        var fileProvider = _env.WebRootFileProvider;
        // Process the file here
    }
}

Pendekatan berbasis konvensi dapat digunakan untuk mengonfigurasi aplikasi saat startup berdasarkan lingkungan. Atau, masukkan ke IWebHostEnvironment Startup dalam konstruktor untuk digunakan dalam ConfigureServices:

public class Startup
{
    public Startup(IWebHostEnvironment env)
    {
        HostingEnvironment = env;
    }

    public IWebHostEnvironment HostingEnvironment { get; }

    public void ConfigureServices(IServiceCollection services)
    {
        if (HostingEnvironment.IsDevelopment())
        {
            // Development configuration
        }
        else
        {
            // Staging/Production configuration
        }

        var contentRootPath = HostingEnvironment.ContentRootPath;
    }
}

Catatan

Selain IsDevelopment metode ekstensi, IWebHostEnvironment menawarkan IsStaging, IsProduction, dan IsEnvironment(string environmentName) metode. Untuk informasi lebih lanjut, lihat Menggunakan beberapa lingkungan di ASP.NET Core.

Layanan ini IWebHostEnvironment juga dapat disuntikkan langsung ke Configure metode untuk menyiapkan alur pemrosesan:

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    if (env.IsDevelopment())
    {
        // In Development, use the Developer Exception Page
        app.UseDeveloperExceptionPage();
    }
    else
    {
        // In Staging/Production, route exceptions to /error
        app.UseExceptionHandler("/error");
    }

    var contentRootPath = env.ContentRootPath;
}

IWebHostEnvironmentdapat disuntikkan ke Invoke dalam metode saat membuat middleware kustom:

public async Task Invoke(HttpContext context, IWebHostEnvironment env)
{
    if (env.IsDevelopment())
    {
        // Configure middleware for Development
    }
    else
    {
        // Configure middleware for Staging/Production
    }

    var contentRootPath = env.ContentRootPath;
}

Antarmuka IHostApplicationLifetime

IHostApplicationLifetime memungkinkan aktivitas pasca-startup dan shutdown. Tiga properti pada antarmuka adalah token pembatalan yang digunakan untuk mendaftarkan Action metode yang menentukan peristiwa startup dan shutdown.

Token Pembatalan Dipicu ketika...
ApplicationStarted Host telah sepenuhnya dimulai.
ApplicationStopped Host menyelesaikan pematian yang anggun. Semua permintaan harus diproses. Matikan blok hingga kejadian ini selesai.
ApplicationStopping Host melakukan pematian yang anggun. Permintaan mungkin masih diproses. Matikan blok hingga kejadian ini selesai.
public class Startup
{
    public void Configure(IApplicationBuilder app, IHostApplicationLifetime appLifetime)
    {
        appLifetime.ApplicationStarted.Register(OnStarted);
        appLifetime.ApplicationStopping.Register(OnStopping);
        appLifetime.ApplicationStopped.Register(OnStopped);

        Console.CancelKeyPress += (sender, eventArgs) =>
        {
            appLifetime.StopApplication();
            // Don't terminate the process immediately, wait for the Main thread to exit gracefully.
            eventArgs.Cancel = true;
        };
    }

    private void OnStarted()
    {
        // Perform post-startup activities here
    }

    private void OnStopping()
    {
        // Perform on-stopping activities here
    }

    private void OnStopped()
    {
        // Perform post-stopped activities here
    }
}

StopApplication meminta penghentian aplikasi. Kelas berikut menggunakan StopApplication untuk mematikan aplikasi dengan anggun saat metode kelas Shutdown dipanggil:

public class MyClass
{
    private readonly IHostApplicationLifetime _appLifetime;

    public MyClass(IHostApplicationLifetime appLifetime)
    {
        _appLifetime = appLifetime;
    }

    public void Shutdown()
    {
        _appLifetime.StopApplication();
    }
}

Validasi cakupan

CreateDefaultBuilderServiceProviderOptions.ValidateScopes diatur ke true jika lingkungan aplikasi adalah Pengembangan.

Ketika ValidateScopes diatur ke true, penyedia layanan default melakukan pemeriksaan untuk memverifikasi bahwa:

  • Layanan terlingkup tidak diselesaikan secara langsung atau tidak langsung dari penyedia layanan akar.
  • Layanan terlingkup tidak secara langsung atau tidak langsung disuntikkan ke dalam singleton.

Penyedia layanan akar dibuat ketika BuildServiceProvider dipanggil. Masa pakai penyedia layanan akar sesuai dengan masa pakai aplikasi/server saat penyedia mulai dengan aplikasi dan dibuang saat aplikasi dimatikan.

Layanan tercakup dibuang oleh kontainer yang membuatnya. Jika layanan tercakup dibuat dalam kontainer akar, masa pakai layanan secara efektif dipromosikan ke singleton karena hanya dibuang oleh kontainer akar saat aplikasi/server dimatikan. Memvalidasi cakupan layanan menangkap situasi ini ketika BuildServiceProvider dipanggil.

Untuk selalu memvalidasi cakupan, termasuk di lingkungan Produksi, konfigurasikan ServiceProviderOptions dengan UseDefaultServiceProvider pada penyusun host:

WebHost.CreateDefaultBuilder(args)
    .UseDefaultServiceProvider((context, options) => {
        options.ValidateScopes = true;
    })

Sumber Daya Tambahan: