WebApplication dan WebApplicationBuilder di aplikasi API Minimal

WebApplication

Kode berikut dihasilkan oleh templat ASP.NET Core:

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

app.MapGet("/", () => "Hello World!");

app.Run();

Kode sebelumnya dapat dibuat melalui dotnet new web pada baris perintah atau memilih templat Web Kosong di Visual Studio.

Kode berikut membuat WebApplication (app) tanpa secara eksplisit membuat WebApplicationBuilder:

var app = WebApplication.Create(args);

app.MapGet("/", () => "Hello World!");

app.Run();

WebApplication.Create menginisialisasi instans WebApplication baru kelas dengan default yang telah dikonfigurasi sebelumnya.

Bekerja dengan port

Saat aplikasi web dibuat dengan Visual Studio atau dotnet new, Properties/launchSettings.json file dibuat yang menentukan port yang ditanggapi aplikasi. Di sampel pengaturan port berikut, menjalankan aplikasi dari Visual Studio mengembalikan dialog Unable to connect to web server 'AppName'kesalahan . Visual Studio mengembalikan kesalahan karena mengharapkan port yang ditentukan dalam Properties/launchSettings.json, tetapi aplikasi menggunakan port yang ditentukan oleh app.Run("http://localhost:3000"). Jalankan sampel perubahan port berikut dari baris perintah.

Bagian berikut mengatur port yang direspons aplikasi.

var app = WebApplication.Create(args);

app.MapGet("/", () => "Hello World!");

app.Run("http://localhost:3000");

Dalam kode sebelumnya, aplikasi merespons port 3000.

Beberapa port

Dalam kode berikut, aplikasi merespons port 3000 dan 4000.

var app = WebApplication.Create(args);

app.Urls.Add("http://localhost:3000");
app.Urls.Add("http://localhost:4000");

app.MapGet("/", () => "Hello World");

app.Run();

Mengatur port dari baris perintah

Perintah berikut membuat aplikasi merespons port 7777:

dotnet run --urls="https://localhost:7777"

Kestrel Jika titik akhir juga dikonfigurasi dalam appsettings.json file, appsettings.json URL yang ditentukan file akan digunakan. Untuk informasi selengkapnya, lihat Kestrel konfigurasi titik akhir

Membaca port dari lingkungan

Kode berikut membaca port dari lingkungan:

var app = WebApplication.Create(args);

var port = Environment.GetEnvironmentVariable("PORT") ?? "3000";

app.MapGet("/", () => "Hello World");

app.Run($"http://localhost:{port}");

Cara yang disukai untuk mengatur port dari lingkungan adalah dengan menggunakan ASPNETCORE_URLS variabel lingkungan, yang ditunjukkan di bagian berikut.

Mengatur port melalui variabel lingkungan ASPNETCORE_URLS

Variabel ASPNETCORE_URLS lingkungan tersedia untuk mengatur port:

ASPNETCORE_URLS=http://localhost:3000

ASPNETCORE_URLS mendukung beberapa URL:

ASPNETCORE_URLS=http://localhost:3000;https://localhost:5000

Dengarkan semua antarmuka

Sampel berikut menunjukkan mendengarkan di semua antarmuka

http://*:3000

var app = WebApplication.Create(args);

app.Urls.Add("http://*:3000");

app.MapGet("/", () => "Hello World");

app.Run();

http://+:3000

var app = WebApplication.Create(args);

app.Urls.Add("http://+:3000");

app.MapGet("/", () => "Hello World");

app.Run();

http://0.0.0.0:3000

var app = WebApplication.Create(args);

app.Urls.Add("http://0.0.0.0:3000");

app.MapGet("/", () => "Hello World");

app.Run();

Dengarkan semua antarmuka menggunakan ASPNETCORE_URLS

Sampel sebelumnya dapat menggunakan ASPNETCORE_URLS

ASPNETCORE_URLS=http://*:3000;https://+:5000;http://0.0.0.0:5005

Dengarkan semua antarmuka menggunakan ASPNETCORE_HTTPS_PORTS

Sampel sebelumnya dapat menggunakan ASPNETCORE_HTTPS_PORTS dan ASPNETCORE_HTTP_PORTS.

ASPNETCORE_HTTP_PORTS=3000;5005
ASPNETCORE_HTTPS_PORTS=5000

Untuk informasi selengkapnya, lihat Mengonfigurasi titik akhir untuk server web ASP.NET Core Kestrel

Tentukan HTTPS dengan sertifikat pengembangan

var app = WebApplication.Create(args);

app.Urls.Add("https://localhost:3000");

app.MapGet("/", () => "Hello World");

app.Run();

Untuk informasi selengkapnya tentang sertifikat pengembangan, lihat Mempercayai sertifikat pengembangan ASP.NET Core HTTPS di Windows dan macOS.

Tentukan HTTPS menggunakan sertifikat kustom

Bagian berikut menunjukkan cara menentukan sertifikat kustom menggunakan appsettings.json file dan melalui konfigurasi.

Tentukan sertifikat kustom dengan appsettings.json

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning"
    }
  },
  "AllowedHosts": "*",
  "Kestrel": {
    "Certificates": {
      "Default": {
        "Path": "cert.pem",
        "KeyPath": "key.pem"
      }
    }
  }
}

Tentukan sertifikat kustom melalui konfigurasi

var builder = WebApplication.CreateBuilder(args);

// Configure the cert and the key
builder.Configuration["Kestrel:Certificates:Default:Path"] = "cert.pem";
builder.Configuration["Kestrel:Certificates:Default:KeyPath"] = "key.pem";

var app = builder.Build();

app.Urls.Add("https://localhost:3000");

app.MapGet("/", () => "Hello World");

app.Run();

Menggunakan API sertifikat

using System.Security.Cryptography.X509Certificates;

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel(options =>
{
    options.ConfigureHttpsDefaults(httpsOptions =>
    {
        var certPath = Path.Combine(builder.Environment.ContentRootPath, "cert.pem");
        var keyPath = Path.Combine(builder.Environment.ContentRootPath, "key.pem");

        httpsOptions.ServerCertificate = X509Certificate2.CreateFromPemFile(certPath, 
                                         keyPath);
    });
});

var app = builder.Build();

app.Urls.Add("https://localhost:3000");

app.MapGet("/", () => "Hello World");

app.Run();

Membaca lingkungan

var app = WebApplication.Create(args);

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/oops");
}

app.MapGet("/", () => "Hello World");
app.MapGet("/oops", () => "Oops! An error happened.");

app.Run();

Untuk informasi selengkapnya menggunakan lingkungan, lihat Menggunakan beberapa lingkungan di ASP.NET Core

Konfigurasi

Kode berikut membaca dari sistem konfigurasi:

var app = WebApplication.Create(args);

var message = app.Configuration["HelloKey"] ?? "Config failed!";

app.MapGet("/", () => message);

app.Run();

Untuk informasi selengkapnya, lihat Konfigurasi di ASP.NET Core

Pencatatan

Kode berikut menulis pesan ke startup aplikasi masuk:

var app = WebApplication.Create(args);

app.Logger.LogInformation("The app started");

app.MapGet("/", () => "Hello World");

app.Run();

Untuk informasi selengkapnya, lihat Pengelogan di .NET Core dan ASP.NET Core

Mengakses kontainer Injeksi Dependensi (DI)

Kode berikut menunjukkan cara mendapatkan layanan dari kontainer DI selama pengaktifan aplikasi:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers();
builder.Services.AddScoped<SampleService>();

var app = builder.Build();

app.MapControllers();

using (var scope = app.Services.CreateScope())
{
    var sampleService = scope.ServiceProvider.GetRequiredService<SampleService>();
    sampleService.DoSomething();
}

app.Run();

Kode berikut menunjukkan cara mengakses kunci dari kontainer DI menggunakan [FromKeyedServices] atribut :

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddKeyedSingleton<ICache, BigCache>("big");
builder.Services.AddKeyedSingleton<ICache, SmallCache>("small");

var app = builder.Build();

app.MapGet("/big", ([FromKeyedServices("big")] ICache bigCache) => bigCache.Get("date"));

app.MapGet("/small", ([FromKeyedServices("small")] ICache smallCache) => smallCache.Get("date"));

app.Run();

public interface ICache
{
    object Get(string key);
}
public class BigCache : ICache
{
    public object Get(string key) => $"Resolving {key} from big cache.";
}

public class SmallCache : ICache
{
    public object Get(string key) => $"Resolving {key} from small cache.";
}

Untuk informasi selengkapnya tentang DI, lihat Injeksi dependensi di ASP.NET Core.

WebApplicationBuilder

Bagian ini berisi kode sampel menggunakan WebApplicationBuilder.

Mengubah akar konten, nama aplikasi, dan lingkungan

Kode berikut mengatur akar konten, nama aplikasi, dan lingkungan:

var builder = WebApplication.CreateBuilder(new WebApplicationOptions
{
    Args = args,
    ApplicationName = typeof(Program).Assembly.FullName,
    ContentRootPath = Directory.GetCurrentDirectory(),
    EnvironmentName = Environments.Staging,
    WebRootPath = "customwwwroot"
});

Console.WriteLine($"Application Name: {builder.Environment.ApplicationName}");
Console.WriteLine($"Environment Name: {builder.Environment.EnvironmentName}");
Console.WriteLine($"ContentRoot Path: {builder.Environment.ContentRootPath}");
Console.WriteLine($"WebRootPath: {builder.Environment.WebRootPath}");

var app = builder.Build();

WebApplication.CreateBuilder menginisialisasi instans baru kelas WebApplicationBuilder dengan default yang telah dikonfigurasi sebelumnya.

Untuk informasi selengkapnya, lihat gambaran umum dasar-dasar ASP.NET Core

Mengubah akar konten, nama aplikasi, dan lingkungan dengan menggunakan variabel lingkungan atau baris perintah

Tabel berikut ini memperlihatkan variabel lingkungan dan argumen baris perintah yang digunakan untuk mengubah akar konten, nama aplikasi, dan lingkungan:

fitur	Variabel lingkungan	Argumen baris perintah
Nama aplikasi	ASPNETCORE_APPLICATIONNAME	--applicationName
Nama lingkungan	ASPNETCORE_ENVIRONMENT	--Lingkungan
Akar konten	ASPNETCORE_CONTENTROOT	--contentRoot

Menambahkan penyedia konfigurasi

Contoh berikut menambahkan penyedia konfigurasi INI:

var builder = WebApplication.CreateBuilder(args);

builder.Configuration.AddIniFile("appsettings.ini");

var app = builder.Build();

Untuk informasi terperinci, lihat Penyedia konfigurasi file di Konfigurasi di ASP.NET Core.

Membaca konfigurasi

Secara default WebApplicationBuilder , konfigurasi baca dari beberapa sumber, termasuk:

• appSettings.json dan appSettings.{environment}.json
• Variabel lingkungan
• Baris perintah

Untuk daftar lengkap sumber konfigurasi yang dibaca, lihat Konfigurasi default di Konfigurasi di ASP.NET Core.

Kode berikut membaca HelloKey dari konfigurasi dan menampilkan nilai di / titik akhir. Jika nilai konfigurasi null, "Halo" ditetapkan ke message:

var builder = WebApplication.CreateBuilder(args);

var message = builder.Configuration["HelloKey"] ?? "Hello";

var app = builder.Build();

app.MapGet("/", () => message);

app.Run();

Membaca lingkungan

var builder = WebApplication.CreateBuilder(args);

if (builder.Environment.IsDevelopment())
{
    Console.WriteLine($"Running in development.");
}

var app = builder.Build();

app.MapGet("/", () => "Hello World!");

app.Run();

Menambahkan penyedia pengelogan

var builder = WebApplication.CreateBuilder(args);

// Configure JSON logging to the console.
builder.Logging.AddJsonConsole();

var app = builder.Build();

app.MapGet("/", () => "Hello JSON console!");

app.Run();

Menambahkan layanan

var builder = WebApplication.CreateBuilder(args);

// Add the memory cache services.
builder.Services.AddMemoryCache();

// Add a custom scoped service.
builder.Services.AddScoped<ITodoRepository, TodoRepository>();
var app = builder.Build();

Menyesuaikan IHostBuilder

Metode ekstensi yang ada di IHostBuilder dapat diakses menggunakan properti Host:

var builder = WebApplication.CreateBuilder(args);

// Wait 30 seconds for graceful shutdown.
builder.Host.ConfigureHostOptions(o => o.ShutdownTimeout = TimeSpan.FromSeconds(30));

var app = builder.Build();

app.MapGet("/", () => "Hello World!");

app.Run();

Menyesuaikan IWebHostBuilder

Metode ekstensi pada IWebHostBuilder dapat diakses menggunakan properti WebApplicationBuilder.WebHost .

var builder = WebApplication.CreateBuilder(args);

// Change the HTTP server implemenation to be HTTP.sys based
builder.WebHost.UseHttpSys();

var app = builder.Build();

app.MapGet("/", () => "Hello HTTP.sys");

app.Run();

Mengubah akar web

Secara default, akar web relatif terhadap akar konten di wwwroot folder. Akar web adalah tempat middleware file statis mencari file statis. Akar web dapat diubah dengan WebHostOptions, baris perintah, atau dengan UseWebRoot metode :

var builder = WebApplication.CreateBuilder(new WebApplicationOptions
{
    Args = args,
    // Look for static files in webroot
    WebRootPath = "webroot"
});

var app = builder.Build();

app.Run();

Kontainer injeksi dependensi kustom (DI)

Contoh berikut menggunakan Autofac:

var builder = WebApplication.CreateBuilder(args);

builder.Host.UseServiceProviderFactory(new AutofacServiceProviderFactory());

// Register services directly with Autofac here. Don't
// call builder.Populate(), that happens in AutofacServiceProviderFactory.
builder.Host.ConfigureContainer<ContainerBuilder>(builder => builder.RegisterModule(new MyApplicationModule()));

var app = builder.Build();

Tambahkan Middleware

Middleware ASP.NET Core yang ada dapat dikonfigurasi pada WebApplication:

var app = WebApplication.Create(args);

// Setup the file server to serve static files.
app.UseFileServer();

app.MapGet("/", () => "Hello World!");

app.Run();

Untuk informasi selengkapnya, lihat ASP.NET Core Middleware

Halaman pengecualian pengembang

WebApplication.CreateBuilder menginisialisasi instans WebApplicationBuilder baru kelas dengan default yang telah dikonfigurasi sebelumnya. Halaman pengecualian pengembang diaktifkan dalam default yang telah dikonfigurasi sebelumnya. Saat kode berikut dijalankan di lingkungan pengembangan, navigasi untuk / merender halaman ramah yang menunjukkan pengecualian.

var builder = WebApplication.CreateBuilder(args);

var app = builder.Build();

app.MapGet("/", () =>
{
    throw new InvalidOperationException("Oops, the '/' route has thrown an exception.");
});

app.Run();