Ringkasan dasar-dasar ASP.NET Core
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.
Artikel ini memberikan ringkasan tentang dasar-dasar untuk membangun aplikasi ASP.NET Core, termasuk injeksi dependensi (DI), konfigurasi, middleware, dan banyak lagi.
Program.cs
Aplikasi ASP.NET Core yang dibuat dengan template web berisi kode pengaktifan aplikasi dalam file Program.cs
. File Program.cs
adalah tempat:
- Layanan yang diperlukan oleh aplikasi dikonfigurasi.
- Alur penanganan permintaan aplikasi didefinisikan sebagai serangkaian komponen middleware.
Kode startup aplikasi berikut mendukung:
var builder = WebApplication.CreateBuilder(args);
// Add services to the container.
builder.Services.AddRazorPages();
builder.Services.AddControllersWithViews();
var app = builder.Build();
// Configure the HTTP request pipeline.
if (!app.Environment.IsDevelopment())
{
app.UseExceptionHandler("/Error");
app.UseHsts();
}
app.UseHttpsRedirection();
app.UseStaticFiles();
app.UseAuthorization();
app.MapGet("/hi", () => "Hello!");
app.MapDefaultControllerRoute();
app.MapRazorPages();
app.Run();
Injeksi dependensi (layanan)
ASP.NET Core menyertakan injeksi dependensi (DI) yang membuat layanan yang dikonfigurasi tersedia di seluruh aplikasi. Layanan ditambahkan ke kontainer DI dengan WebApplicationBuilder.Services, builder.Services
dalam kode sebelumnya. Saat WebApplicationBuilder dibuat, banyak layanan yang disediakan kerangka kerja ditambahkan. builder
merupakan WebApplicationBuilder
dalam kode berikut:
var builder = WebApplication.CreateBuilder(args);
// Add services to the container.
builder.Services.AddRazorPages();
builder.Services.AddControllersWithViews();
var app = builder.Build();
Dalam kode yang disorot sebelumnya, builder
memiliki konfigurasi, pengelogan, dan banyak layanan lain yang ditambahkan ke kontainer DI.
Kode berikut menambahkan Halaman Razor, pengontrol MVC dengan tampilan, dan DbContext kustom ke kontainer DI:
using Microsoft.EntityFrameworkCore;
using RazorPagesMovie.Data;
var builder = WebApplication.CreateBuilder(args);
// Add services to the container.
builder.Services.AddRazorPages();
builder.Services.AddControllersWithViews();
builder.Services.AddDbContext<RazorPagesMovieContext>(options =>
options.UseSqlServer(builder.Configuration.GetConnectionString("RPMovieContext")));
var app = builder.Build();
Layanan biasanya diselesaikan dari DI menggunakan injeksi konstruktor. Kerangka kerja DI menyediakan instans layanan ini saat runtime.
Kode berikut menggunakan injeksi konstruktor untuk menyelesaikan konteks database dan pencatat dari DI:
public class IndexModel : PageModel
{
private readonly RazorPagesMovieContext _context;
private readonly ILogger<IndexModel> _logger;
public IndexModel(RazorPagesMovieContext context, ILogger<IndexModel> logger)
{
_context = context;
_logger = logger;
}
public IList<Movie> Movie { get;set; }
public async Task OnGetAsync()
{
_logger.LogInformation("IndexModel OnGetAsync.");
Movie = await _context.Movie.ToListAsync();
}
}
Middleware
Alur penanganan permintaan terdiri dari serangkaian komponen middleware. Setiap komponen melakukan operasi pada HttpContext
dan memanggil middleware berikutnya dalam alur atau menghentikan permintaan.
Berdasarkan konvensi, komponen middleware ditambahkan ke alur dengan menerapkan metode ekstensi Use{Feature}
. Middleware yang ditambahkan ke aplikasi disorot dalam kode berikut:
var builder = WebApplication.CreateBuilder(args);
// Add services to the container.
builder.Services.AddRazorPages();
builder.Services.AddControllersWithViews();
var app = builder.Build();
// Configure the HTTP request pipeline.
if (!app.Environment.IsDevelopment())
{
app.UseExceptionHandler("/Error");
app.UseHsts();
}
app.UseHttpsRedirection();
app.UseStaticFiles();
app.UseAuthorization();
app.MapGet("/hi", () => "Hello!");
app.MapDefaultControllerRoute();
app.MapRazorPages();
app.Run();
Untuk informasi lebih lanjut, lihat Middleware ASP.NET Core.
Host
Saat memulai, aplikasi ASP.NET Core membuat host. Host merangkum semua sumber daya aplikasi, seperti:
- Penerapan server HTTP
- Komponen middleware
- Pencatatan
- Layanan injeksi dependensi (DI)
- Konfigurasi
Ada tiga host berbeda yang mampu menjalankan aplikasi ASP.NET Core:
- ASP.NET Core WebApplication, juga dikenal sebagai Host Minimal
- Host Generik .NET dikombinasikan dengan ASP.NET Core ConfigureWebHostDefaults
- ASP.NET Core WebHost
ASP.NET Core WebApplication dan WebApplicationBuilder jenis direkomendasikan dan digunakan di semua templat ASP.NET Core. WebApplication
bersifat mirip dengan Host Generik .NET dan mengekspos banyak antarmuka yang sama tetapi membutuhkan lebih sedikit panggilan balik untuk dikonfigurasi. ASP.NET Core WebHost hanya tersedia untuk kompatibilitas mundur.
Contoh berikut membuat instans :WebApplication
var builder = WebApplication.CreateBuilder(args);
// Add services to the container.
builder.Services.AddRazorPages();
builder.Services.AddControllersWithViews();
var app = builder.Build();
Metode WebApplicationBuilder.Build mengonfigurasi host dengan serangkaian opsi default, seperti:
- Gunakan Kestrel sebagai server web dan aktifkan integrasi IIS.
- Muat konfigurasi dari
appsettings.json
, variabel lingkungan, argumen baris perintah, dan sumber konfigurasi lainnya. - Kirim output pengelogan ke konsol dan penyedia debug.
Skenario non-web
Generic Host memungkinkan jenis aplikasi lain menggunakan ekstensi kerangka kerja lintas sektoral, seperti pengelogan, injeksi dependensi (DI), konfigurasi, dan manajemen masa pakai aplikasi. Untuk informasi lebih lanjut, lihat .NET Generic Host di ASP.NET Core dan Tugas latar belakang dengan layanan yang dihosting di ASP.NET Core.
Server
Aplikasi ASP.NET Core menggunakan penerapan server HTTP untuk mendengarkan permintaan HTTP. Server memunculkan permintaan ke aplikasi sebagai kumpulan fitur permintaan yang terdiri dari HttpContext
.
ASP.NET Core menyediakan penerapan server berikut:
- Kestrel adalah server web lintas platform. Kestrel sering dijalankan dalam konfigurasi proksi terbalik menggunakan IIS. Di ASP.NET Core 2.0 atau yang lebih baru, Kestrel dapat dijalankan sebagai server tepi yang mengarah ke publik yang terhubung langsung ke Internet.
- Server HTTP IIS adalah server untuk Windows yang menggunakan IIS. Dengan server ini, aplikasi ASP.NET Core dan IIS berjalan dalam proses yang sama.
- HTTP.sys adalah server untuk Windows yang tidak digunakan dengan IIS.
Untuk informasi lebih lanjut, lihat Penerapan server web di ASP.NET Core.
Konfigurasi
ASP.NET Core menyediakan kerangka kerja konfigurasi yang mendapatkan pengaturan sebagai pasangan nama-nilai dari set penyedia konfigurasi yang diurutkan. Penyedia konfigurasi bawaan tersedia untuk berbagai sumber, seperti file .json
, file .xml
, variabel lingkungan, dan argumen baris perintah. Tulis penyedia konfigurasi kustom untuk mendukung sumber lain.
Secara default, aplikasi ASP.NET Core dikonfigurasi untuk membaca dari appsettings.json
, variabel lingkungan, baris perintah, dan banyak lagi. Saat konfigurasi aplikasi dimuat, nilai dari variabel lingkungan menggantikan nilai dari appsettings.json
.
Untuk mengelola data konfigurasi rahasia seperti kata sandi, .NET Core menyediakan Pengelola Rahasia. Untuk rahasia produksi, kami menyarankan Azure Key Vault.
Untuk informasi lebih lanjut, lihat Konfigurasi di ASP.NET Core.
Lingkungan
Lingkungan eksekusi, seperti Development
, Staging
, dan Production
, tersedia di ASP.NET Core. Tentukan lingkungan tempat aplikasi berjalan dengan mengatur variabel lingkungan ASPNETCORE_ENVIRONMENT
. ASP.NET Core membaca variabel lingkungan tersebut saat memulai aplikasi dan menyimpan nilainya dalam penerapan IWebHostEnvironment
. Penerapan ini tersedia di mana saja di aplikasi melalui injeksi dependensi (DI).
Contoh berikut mengonfigurasi penangan pengecualian dan middleware HTTP Strict Transport Security Protocol (HSTS) saat tidak berjalan di lingkungan Development
:
var builder = WebApplication.CreateBuilder(args);
// Add services to the container.
builder.Services.AddRazorPages();
builder.Services.AddControllersWithViews();
var app = builder.Build();
// Configure the HTTP request pipeline.
if (!app.Environment.IsDevelopment())
{
app.UseExceptionHandler("/Error");
app.UseHsts();
}
app.UseHttpsRedirection();
app.UseStaticFiles();
app.UseAuthorization();
app.MapGet("/hi", () => "Hello!");
app.MapDefaultControllerRoute();
app.MapRazorPages();
app.Run();
Untuk informasi lebih lanjut, lihat Menggunakan beberapa lingkungan di ASP.NET Core.
Pencatatan
ASP.NET Core mendukung API pengelogan yang bekerja dengan berbagai penyedia pengelogan bawaan dan pihak ketiga. Penyedia yang tersedia meliputi:
- Konsol
- Debug
- Pelacakan Peristiwa di Windows
- Log Peristiwa Windows
- TraceSource
- Azure App Service
- Azure Application Insights
Untuk membuat log, selesaikan layanan ILogger<TCategoryName> dari injeksi dependensi (DI) dan panggil metode pengelogan seperti LogInformation. Contohnya:
public class IndexModel : PageModel
{
private readonly RazorPagesMovieContext _context;
private readonly ILogger<IndexModel> _logger;
public IndexModel(RazorPagesMovieContext context, ILogger<IndexModel> logger)
{
_context = context;
_logger = logger;
}
public IList<Movie> Movie { get;set; }
public async Task OnGetAsync()
{
_logger.LogInformation("IndexModel OnGetAsync.");
Movie = await _context.Movie.ToListAsync();
}
}
Untuk informasi selengkapnya, lihat Pengelogan .NET Core dan ASP.NET Core.
Perutean
Rute adalah pola URL yang dipetakan ke penangan. Penangan biasanya adalah halaman Razor, metode tindakan dalam pengontrol MVC, atau middleware. Perutean ASP.NET core memberi Anda kontrol atas URL yang digunakan oleh aplikasi Anda.
Kode berikut, yang dibuat oleh template aplikasi web ASP.NET Core, memanggil UseRouting:
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddRazorPages();
var app = builder.Build();
// Configure the HTTP request pipeline.
if (!app.Environment.IsDevelopment())
{
app.UseExceptionHandler("/Error");
app.UseHsts();
}
app.UseHttpsRedirection();
app.UseStaticFiles();
app.UseRouting();
app.UseAuthorization();
app.MapRazorPages();
app.Run();
Untuk informasi lebih lanjut, lihat Perutean di ASP.NET Core.
Penanganan kesalahan
ASP.NET Core memiliki fitur bawaan untuk menangani kesalahan, seperti:
- Halaman pengecualian pengembang
- Halaman kesalahan kustom
- Halaman kode status statis
- Penanganan pengecualian startup
Untuk informasi lebih lanjut, lihat Menangani kesalahan di ASP.NET Core.
Membuat permintaan HTTP
Penerapan IHttpClientFactory
tersedia untuk membuat instans HttpClient
. Pabrik:
- Menyediakan lokasi pusat untuk penamaan dan konfigurasi instans
HttpClient
logis. Misalnya, daftarkan dan konfigurasikan klien github untuk mengakses GitHub. Daftarkan dan konfigurasikan klien default untuk tujuan lain. - Mendukung pendaftaran dan rantai beberapa penangan pendelegasian untuk membangun alur middleware permintaan keluar. Pola ini mirip dengan alur middleware masuk ASP.NET Core. Pola tersebut menyediakan mekanisme untuk mengelola masalah lintas sektoral untuk permintaan HTTP, termasuk penembolokan, penanganan kesalahan, serialisasi, dan pengelogan.
- Terintegrasi dengan Polly, pustaka pihak ketiga yang populer untuk penanganan kesalahan sementara.
- Mengelola pengumpulan dan masa pakai instans
HttpClientHandler
yang mendasarinya untuk menghindari masalah DNS umum yang terjadi saat mengelola masa pakaiHttpClient
secara manual. - Menambahkan pengalaman pencatatan yang dapat dikonfigurasi melalui ILogger untuk semua permintaan yang dikirim melalui klien yang dibuat oleh pabrik.
Untuk informasi lebih lanjut, lihat Membuat permintaan HTTP menggunakan IHttpClientFactory di ASP.NET Core.
Akar konten
Akar konten adalah jalur dasar untuk:
- Hosting aplikasi yang dapat dieksekusi (.exe).
- Rakitan yang dikompilasi yang membentuk aplikasi (.dll).
- File konten yang digunakan oleh aplikasi, seperti:
- File Razor (
.cshtml
,.razor
) - File konfigurasi (
.json
,.xml
) - File data (
.db
)
- File Razor (
- Akar web, biasanya folder wwwroot.
Selama pengembangan, secara default, akar konten diatur ke direktori akar proyek. Direktori ini juga merupakan jalur dasar untuk file konten aplikasi dan akar Web. Tentukan akar konten yang berbeda dengan mengatur jalurnya saat membangun host. Untuk informasi lebih lanjut, lihat Akar konten.
Akar web
Akar web adalah jalur dasar untuk file sumber daya publik dan statis, seperti:
- Lembar Gaya (
.css
) - JavaScript (
.js
) - Gambar (
.png
,.jpg
)
Secara default, file statis hanya dilayani dari direktori akar web dan sub-direktorinya. Secara default, alur akar web diatur ke {content root}/wwwroot. Tentukan akar web yang berbeda dengan mengatur jalurnya saat membangun host. Untuk informasi lebih lanjut, lihat Akar web.
Cegah penerbitan file di wwwroot dengan item proyek <Konten> di file proyek. Contoh berikut mencegah penerbitan konten di wwwroot/local dan subdirektorinya:
<ItemGroup>
<Content Update="wwwroot\local\**\*.*" CopyToPublishDirectory="Never" />
</ItemGroup>
Dalam file Razor.cshtml
, ~/
mengarah ke akar web. Jalur yang diawali dengan ~/
disebut sebagai jalur virtual.
Untuk informasi selengkapnya, lihat File statis di ASP.NET Core.
Sumber Daya Tambahan:
Artikel ini memberikan ringkasan tentang dasar-dasar untuk membangun aplikasi ASP.NET Core, termasuk injeksi dependensi (DI), konfigurasi, middleware, dan banyak lagi.
Program.cs
Aplikasi ASP.NET Core yang dibuat dengan template web berisi kode pengaktifan aplikasi dalam file Program.cs
. File Program.cs
adalah tempat:
- Layanan yang diperlukan oleh aplikasi dikonfigurasi.
- Alur penanganan permintaan aplikasi didefinisikan sebagai serangkaian komponen middleware.
Kode startup aplikasi berikut mendukung:
var builder = WebApplication.CreateBuilder(args);
// Add services to the container.
builder.Services.AddRazorPages();
builder.Services.AddControllersWithViews();
var app = builder.Build();
// Configure the HTTP request pipeline.
if (!app.Environment.IsDevelopment())
{
app.UseExceptionHandler("/Error");
app.UseHsts();
}
app.UseHttpsRedirection();
app.UseStaticFiles();
app.UseAuthorization();
app.MapGet("/hi", () => "Hello!");
app.MapDefaultControllerRoute();
app.MapRazorPages();
app.Run();
Injeksi dependensi (layanan)
ASP.NET Core menyertakan injeksi dependensi (DI) yang membuat layanan yang dikonfigurasi tersedia di seluruh aplikasi. Layanan ditambahkan ke kontainer DI dengan WebApplicationBuilder.Services, builder.Services
dalam kode sebelumnya. Saat WebApplicationBuilder dibuat, banyak layanan yang disediakan kerangka kerja ditambahkan. builder
merupakan WebApplicationBuilder
dalam kode berikut:
var builder = WebApplication.CreateBuilder(args);
// Add services to the container.
builder.Services.AddRazorPages();
builder.Services.AddControllersWithViews();
var app = builder.Build();
Dalam kode yang disorot sebelumnya, builder
memiliki konfigurasi, pengelogan, dan banyak layanan lain yang ditambahkan ke kontainer DI.
Kode berikut menambahkan Halaman Razor, pengontrol MVC dengan tampilan, dan DbContext kustom ke kontainer DI:
using Microsoft.EntityFrameworkCore;
using RazorPagesMovie.Data;
var builder = WebApplication.CreateBuilder(args);
// Add services to the container.
builder.Services.AddRazorPages();
builder.Services.AddControllersWithViews();
builder.Services.AddDbContext<RazorPagesMovieContext>(options =>
options.UseSqlServer(builder.Configuration.GetConnectionString("RPMovieContext")));
var app = builder.Build();
Layanan biasanya diselesaikan dari DI menggunakan injeksi konstruktor. Kerangka kerja DI menyediakan instans layanan ini saat runtime.
Kode berikut menggunakan injeksi konstruktor untuk menyelesaikan konteks database dan pencatat dari DI:
public class IndexModel : PageModel
{
private readonly RazorPagesMovieContext _context;
private readonly ILogger<IndexModel> _logger;
public IndexModel(RazorPagesMovieContext context, ILogger<IndexModel> logger)
{
_context = context;
_logger = logger;
}
public IList<Movie> Movie { get;set; }
public async Task OnGetAsync()
{
_logger.LogInformation("IndexModel OnGetAsync.");
Movie = await _context.Movie.ToListAsync();
}
}
Middleware
Alur penanganan permintaan terdiri dari serangkaian komponen middleware. Setiap komponen melakukan operasi pada HttpContext
dan memanggil middleware berikutnya dalam alur atau menghentikan permintaan.
Berdasarkan konvensi, komponen middleware ditambahkan ke alur dengan menerapkan metode ekstensi Use{Feature}
. Middleware yang ditambahkan ke aplikasi disorot dalam kode berikut:
var builder = WebApplication.CreateBuilder(args);
// Add services to the container.
builder.Services.AddRazorPages();
builder.Services.AddControllersWithViews();
var app = builder.Build();
// Configure the HTTP request pipeline.
if (!app.Environment.IsDevelopment())
{
app.UseExceptionHandler("/Error");
app.UseHsts();
}
app.UseHttpsRedirection();
app.UseStaticFiles();
app.UseAuthorization();
app.MapGet("/hi", () => "Hello!");
app.MapDefaultControllerRoute();
app.MapRazorPages();
app.Run();
Untuk informasi lebih lanjut, lihat Middleware ASP.NET Core.
Host
Saat memulai, aplikasi ASP.NET Core membuat host. Host merangkum semua sumber daya aplikasi, seperti:
- Penerapan server HTTP
- Komponen middleware
- Pencatatan
- Layanan injeksi dependensi (DI)
- Konfigurasi
Ada tiga host berbeda yang mampu menjalankan aplikasi ASP.NET Core:
- ASP.NET Core WebApplication, juga dikenal sebagai Host Minimal
- Host Generik .NET dikombinasikan dengan ASP.NET Core ConfigureWebHostDefaults
- ASP.NET Core WebHost
ASP.NET Core WebApplication dan WebApplicationBuilder jenis direkomendasikan dan digunakan di semua templat ASP.NET Core. WebApplication
bersifat mirip dengan Host Generik .NET dan mengekspos banyak antarmuka yang sama tetapi membutuhkan lebih sedikit panggilan balik untuk dikonfigurasi. ASP.NET Core WebHost hanya tersedia untuk kompatibilitas mundur.
Contoh berikut membuat instans :WebApplication
var builder = WebApplication.CreateBuilder(args);
// Add services to the container.
builder.Services.AddRazorPages();
builder.Services.AddControllersWithViews();
var app = builder.Build();
Metode WebApplicationBuilder.Build mengonfigurasi host dengan serangkaian opsi default, seperti:
- Gunakan Kestrel sebagai server web dan aktifkan integrasi IIS.
- Muat konfigurasi dari
appsettings.json
, variabel lingkungan, argumen baris perintah, dan sumber konfigurasi lainnya. - Kirim output pengelogan ke konsol dan penyedia debug.
Skenario non-web
Generic Host memungkinkan jenis aplikasi lain menggunakan ekstensi kerangka kerja lintas sektoral, seperti pengelogan, injeksi dependensi (DI), konfigurasi, dan manajemen masa pakai aplikasi. Untuk informasi lebih lanjut, lihat .NET Generic Host di ASP.NET Core dan Tugas latar belakang dengan layanan yang dihosting di ASP.NET Core.
Server
Aplikasi ASP.NET Core menggunakan penerapan server HTTP untuk mendengarkan permintaan HTTP. Server memunculkan permintaan ke aplikasi sebagai kumpulan fitur permintaan yang terdiri dari HttpContext
.
ASP.NET Core menyediakan penerapan server berikut:
- Kestrel adalah server web lintas platform. Kestrel sering dijalankan dalam konfigurasi proksi terbalik menggunakan IIS. Di ASP.NET Core 2.0 atau yang lebih baru, Kestrel dapat dijalankan sebagai server tepi yang mengarah ke publik yang terhubung langsung ke Internet.
- Server HTTP IIS adalah server untuk Windows yang menggunakan IIS. Dengan server ini, aplikasi ASP.NET Core dan IIS berjalan dalam proses yang sama.
- HTTP.sys adalah server untuk Windows yang tidak digunakan dengan IIS.
Untuk informasi lebih lanjut, lihat Penerapan server web di ASP.NET Core.
Konfigurasi
ASP.NET Core menyediakan kerangka kerja konfigurasi yang mendapatkan pengaturan sebagai pasangan nama-nilai dari set penyedia konfigurasi yang diurutkan. Penyedia konfigurasi bawaan tersedia untuk berbagai sumber, seperti file .json
, file .xml
, variabel lingkungan, dan argumen baris perintah. Tulis penyedia konfigurasi kustom untuk mendukung sumber lain.
Secara default, aplikasi ASP.NET Core dikonfigurasi untuk membaca dari appsettings.json
, variabel lingkungan, baris perintah, dan banyak lagi. Saat konfigurasi aplikasi dimuat, nilai dari variabel lingkungan menggantikan nilai dari appsettings.json
.
Untuk mengelola data konfigurasi rahasia seperti kata sandi, .NET Core menyediakan Pengelola Rahasia. Untuk rahasia produksi, kami menyarankan Azure Key Vault.
Untuk informasi lebih lanjut, lihat Konfigurasi di ASP.NET Core.
Lingkungan
Lingkungan eksekusi, seperti Development
, Staging
, dan Production
, tersedia di ASP.NET Core. Tentukan lingkungan tempat aplikasi berjalan dengan mengatur variabel lingkungan ASPNETCORE_ENVIRONMENT
. ASP.NET Core membaca variabel lingkungan tersebut saat memulai aplikasi dan menyimpan nilainya dalam penerapan IWebHostEnvironment
. Penerapan ini tersedia di mana saja di aplikasi melalui injeksi dependensi (DI).
Contoh berikut mengonfigurasi penangan pengecualian dan middleware HTTP Strict Transport Security Protocol (HSTS) saat tidak berjalan di lingkungan Development
:
var builder = WebApplication.CreateBuilder(args);
// Add services to the container.
builder.Services.AddRazorPages();
builder.Services.AddControllersWithViews();
var app = builder.Build();
// Configure the HTTP request pipeline.
if (!app.Environment.IsDevelopment())
{
app.UseExceptionHandler("/Error");
app.UseHsts();
}
app.UseHttpsRedirection();
app.UseStaticFiles();
app.UseAuthorization();
app.MapGet("/hi", () => "Hello!");
app.MapDefaultControllerRoute();
app.MapRazorPages();
app.Run();
Untuk informasi lebih lanjut, lihat Menggunakan beberapa lingkungan di ASP.NET Core.
Pencatatan
ASP.NET Core mendukung API pengelogan yang bekerja dengan berbagai penyedia pengelogan bawaan dan pihak ketiga. Penyedia yang tersedia meliputi:
- Konsol
- Debug
- Pelacakan Peristiwa di Windows
- Log Peristiwa Windows
- TraceSource
- Azure App Service
- Azure Application Insights
Untuk membuat log, selesaikan layanan ILogger<TCategoryName> dari injeksi dependensi (DI) dan panggil metode pengelogan seperti LogInformation. Contohnya:
public class IndexModel : PageModel
{
private readonly RazorPagesMovieContext _context;
private readonly ILogger<IndexModel> _logger;
public IndexModel(RazorPagesMovieContext context, ILogger<IndexModel> logger)
{
_context = context;
_logger = logger;
}
public IList<Movie> Movie { get;set; }
public async Task OnGetAsync()
{
_logger.LogInformation("IndexModel OnGetAsync.");
Movie = await _context.Movie.ToListAsync();
}
}
Untuk informasi selengkapnya, lihat Pengelogan .NET Core dan ASP.NET Core.
Perutean
Rute adalah pola URL yang dipetakan ke penangan. Penangan biasanya adalah halaman Razor, metode tindakan dalam pengontrol MVC, atau middleware. Perutean ASP.NET core memberi Anda kontrol atas URL yang digunakan oleh aplikasi Anda.
Kode berikut, yang dibuat oleh template aplikasi web ASP.NET Core, memanggil UseRouting:
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddRazorPages();
var app = builder.Build();
// Configure the HTTP request pipeline.
if (!app.Environment.IsDevelopment())
{
app.UseExceptionHandler("/Error");
app.UseHsts();
}
app.UseHttpsRedirection();
app.UseStaticFiles();
app.UseRouting();
app.UseAuthorization();
app.MapRazorPages();
app.Run();
Untuk informasi lebih lanjut, lihat Perutean di ASP.NET Core.
Penanganan kesalahan
ASP.NET Core memiliki fitur bawaan untuk menangani kesalahan, seperti:
- Halaman pengecualian pengembang
- Halaman kesalahan kustom
- Halaman kode status statis
- Penanganan pengecualian startup
Untuk informasi lebih lanjut, lihat Menangani kesalahan di ASP.NET Core.
Membuat permintaan HTTP
Penerapan IHttpClientFactory
tersedia untuk membuat instans HttpClient
. Pabrik:
- Menyediakan lokasi pusat untuk penamaan dan konfigurasi instans
HttpClient
logis. Misalnya, daftarkan dan konfigurasikan klien github untuk mengakses GitHub. Daftarkan dan konfigurasikan klien default untuk tujuan lain. - Mendukung pendaftaran dan rantai beberapa penangan pendelegasian untuk membangun alur middleware permintaan keluar. Pola ini mirip dengan alur middleware masuk ASP.NET Core. Pola tersebut menyediakan mekanisme untuk mengelola masalah lintas sektoral untuk permintaan HTTP, termasuk penembolokan, penanganan kesalahan, serialisasi, dan pengelogan.
- Terintegrasi dengan Polly, pustaka pihak ketiga yang populer untuk penanganan kesalahan sementara.
- Mengelola pengumpulan dan masa pakai instans
HttpClientHandler
yang mendasarinya untuk menghindari masalah DNS umum yang terjadi saat mengelola masa pakaiHttpClient
secara manual. - Menambahkan pengalaman pencatatan yang dapat dikonfigurasi melalui ILogger untuk semua permintaan yang dikirim melalui klien yang dibuat oleh pabrik.
Untuk informasi lebih lanjut, lihat Membuat permintaan HTTP menggunakan IHttpClientFactory di ASP.NET Core.
Akar konten
Akar konten adalah jalur dasar untuk:
- Hosting aplikasi yang dapat dieksekusi (.exe).
- Rakitan yang dikompilasi yang membentuk aplikasi (.dll).
- File konten yang digunakan oleh aplikasi, seperti:
- File Razor (
.cshtml
,.razor
) - File konfigurasi (
.json
,.xml
) - File data (
.db
)
- File Razor (
- Akar web, biasanya folder wwwroot.
Selama pengembangan, secara default, akar konten diatur ke direktori akar proyek. Direktori ini juga merupakan jalur dasar untuk file konten aplikasi dan akar Web. Tentukan akar konten yang berbeda dengan mengatur jalurnya saat membangun host. Untuk informasi lebih lanjut, lihat Akar konten.
Akar web
Akar web adalah jalur dasar untuk file sumber daya publik dan statis, seperti:
- Lembar Gaya (
.css
) - JavaScript (
.js
) - Gambar (
.png
,.jpg
)
Secara default, file statis hanya dilayani dari direktori akar web dan sub-direktorinya. Secara default, alur akar web diatur ke {content root}/wwwroot. Tentukan akar web yang berbeda dengan mengatur jalurnya saat membangun host. Untuk informasi lebih lanjut, lihat Akar web.
Cegah penerbitan file di wwwroot dengan item proyek <Konten> di file proyek. Contoh berikut mencegah penerbitan konten di wwwroot/local dan subdirektorinya:
<ItemGroup>
<Content Update="wwwroot\local\**\*.*" CopyToPublishDirectory="Never" />
</ItemGroup>
Dalam file Razor.cshtml
, ~/
mengarah ke akar web. Jalur yang diawali dengan ~/
disebut sebagai jalur virtual.
Untuk informasi selengkapnya, lihat File statis di ASP.NET Core.
Sumber Daya Tambahan:
Artikel ini memberikan ringkasan tentang dasar-dasar untuk membangun aplikasi ASP.NET Core, termasuk injeksi dependensi (DI), konfigurasi, middleware, dan banyak lagi.
Kelas Startup
Kelas Startup
adalah tempat:
- Layanan yang diperlukan oleh aplikasi dikonfigurasi.
- Alur penanganan permintaan aplikasi didefinisikan, sebagai serangkaian komponen middleware.
Berikut adalah contoh kelas Startup
:
public class Startup
{
public void ConfigureServices(IServiceCollection services)
{
services.AddDbContext<RazorPagesMovieContext>(options =>
options.UseSqlServer(Configuration.GetConnectionString("RazorPagesMovieContext")));
services.AddControllersWithViews();
services.AddRazorPages();
}
public void Configure(IApplicationBuilder app)
{
app.UseHttpsRedirection();
app.UseStaticFiles();
app.UseRouting();
app.UseEndpoints(endpoints =>
{
endpoints.MapDefaultControllerRoute();
endpoints.MapRazorPages();
});
}
}
Untuk informasi selengkapnya, lihat Pengaktifan aplikasi di ASP.NET Core.
Injeksi dependensi (layanan)
ASP.NET Core menyertakan kerangka kerja injeksi dependensi (DI) bawaan yang membuat layanan yang dikonfigurasi tersedia di seluruh aplikasi. Misalnya, komponen pengelogan adalah layanan.
Kode untuk mengonfigurasi (atau mendaftarkan) layanan ditambahkan ke metode Startup.ConfigureServices
. Contohnya:
public void ConfigureServices(IServiceCollection services)
{
services.AddDbContext<RazorPagesMovieContext>(options =>
options.UseSqlServer(Configuration.GetConnectionString("RazorPagesMovieContext")));
services.AddControllersWithViews();
services.AddRazorPages();
}
Layanan biasanya diselesaikan dari DI menggunakan injeksi konstruktor. Dengan injeksi konstruktor, kelas mendeklarasikan parameter konstruktor dari jenis yang diperlukan atau antarmuka. Kerangka kerja DI menyediakan instans layanan ini saat runtime.
Contoh berikut menggunakan injeksi konstruktor untuk menyelesaikan RazorPagesMovieContext
dari DI:
public class IndexModel : PageModel
{
private readonly RazorPagesMovieContext _context;
public IndexModel(RazorPagesMovieContext context)
{
_context = context;
}
// ...
public async Task OnGetAsync()
{
Movies = await _context.Movies.ToListAsync();
}
}
Jika kontainer Inversion of Control (IoC) bawaan tidak memenuhi semua kebutuhan aplikasi, kontainer IoC pihak ketiga dapat digunakan sebagai gantinya.
Untuk informasi lebih lanjut, lihat Injeksi dependensi di ASP.NET Core.
Middleware
Alur penanganan permintaan terdiri dari serangkaian komponen middleware. Setiap komponen melakukan operasi pada HttpContext
dan memanggil middleware berikutnya dalam alur atau menghentikan permintaan.
Menurut konvensi, komponen middleware ditambahkan ke alur dengan memanggil metode ekstensi Use...
dalam metode Startup.Configure
. Misalnya, untuk mengaktifkan perenderan file statis, panggil UseStaticFiles
.
Contoh berikut mengonfigurasi alur penanganan permintaan:
public void Configure(IApplicationBuilder app)
{
app.UseHttpsRedirection();
app.UseStaticFiles();
app.UseRouting();
app.UseEndpoints(endpoints =>
{
endpoints.MapDefaultControllerRoute();
endpoints.MapRazorPages();
});
}
ASP.NET Core mencakup set middleware bawaan yang kaya. Komponen middleware kustom juga dapat ditulis.
Untuk informasi lebih lanjut, lihat Middleware ASP.NET Core.
Host
Saat memulai, aplikasi ASP.NET Core membuat host. Host merangkum semua sumber daya aplikasi, seperti:
- Penerapan server HTTP
- Komponen middleware
- Pencatatan
- Layanan injeksi dependensi (DI)
- Konfigurasi
Ada dua host yang berbeda:
- Host Umum .NET
- ASP.NET Core Web Host
.NET Generic Host direkomendasikan. Host Web ASP.NET Core hanya tersedia untuk kompatibilitas mundur.
Contoh berikut membuat .NET Generic Host:
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>();
});
}
Metode CreateDefaultBuilder
dan ConfigureWebHostDefaults
mengonfigurasi host dengan serangkaian opsi default, seperti:
- Gunakan Kestrel sebagai server web dan aktifkan integrasi IIS.
- Muat konfigurasi dari
appsettings.json
,appsettings.{Environment}.json
, variabel lingkungan, argumen baris perintah, dan sumber konfigurasi lainnya. - Kirim output pengelogan ke konsol dan penyedia debug.
Untuk informasi lebih lanjut, lihat .NET Generic Host di ASP.NET Core.
Skenario non-web
Generic Host memungkinkan jenis aplikasi lain menggunakan ekstensi kerangka kerja lintas sektoral, seperti pengelogan, injeksi dependensi (DI), konfigurasi, dan manajemen masa pakai aplikasi. Untuk informasi lebih lanjut, lihat .NET Generic Host di ASP.NET Core dan Tugas latar belakang dengan layanan yang dihosting di ASP.NET Core.
Server
Aplikasi ASP.NET Core menggunakan penerapan server HTTP untuk mendengarkan permintaan HTTP. Server memunculkan permintaan ke aplikasi sebagai kumpulan fitur permintaan yang terdiri dari HttpContext
.
ASP.NET Core menyediakan penerapan server berikut:
- Kestrel adalah server web lintas platform. Kestrel sering dijalankan dalam konfigurasi proksi terbalik menggunakan IIS. Di ASP.NET Core 2.0 atau yang lebih baru, Kestrel dapat dijalankan sebagai server tepi yang mengarah ke publik yang terhubung langsung ke Internet.
- Server HTTP IIS adalah server untuk Windows yang menggunakan IIS. Dengan server ini, aplikasi ASP.NET Core dan IIS berjalan dalam proses yang sama.
- HTTP.sys adalah server untuk Windows yang tidak digunakan dengan IIS.
Untuk informasi lebih lanjut, lihat Penerapan server web di ASP.NET Core.
Konfigurasi
ASP.NET Core menyediakan kerangka kerja konfigurasi yang mendapatkan pengaturan sebagai pasangan nama-nilai dari set penyedia konfigurasi yang diurutkan. Penyedia konfigurasi bawaan tersedia untuk berbagai sumber, seperti file .json
, file .xml
, variabel lingkungan, dan argumen baris perintah. Tulis penyedia konfigurasi kustom untuk mendukung sumber lain.
Secara default, aplikasi ASP.NET Core dikonfigurasi untuk membaca dari appsettings.json
, variabel lingkungan, baris perintah, dan banyak lagi. Saat konfigurasi aplikasi dimuat, nilai dari variabel lingkungan menggantikan nilai dari appsettings.json
.
Cara yang lebih disukai untuk membaca nilai konfigurasi terkait adalah menggunakan pola opsi. Untuk informasi lebih lanjut, lihat Mengikat data konfigurasi hierarki menggunakan pola opsi.
Untuk mengelola data konfigurasi rahasia seperti kata sandi, .NET Core menyediakan Pengelola Rahasia. Untuk rahasia produksi, kami menyarankan Azure Key Vault.
Untuk informasi lebih lanjut, lihat Konfigurasi di ASP.NET Core.
Lingkungan
Lingkungan eksekusi, seperti Development
, Staging
, dan Production
, adalah gagasan kelas satu di ASP.NET Core. Tentukan lingkungan tempat aplikasi berjalan dengan mengatur variabel lingkungan ASPNETCORE_ENVIRONMENT
. ASP.NET Core membaca variabel lingkungan tersebut saat memulai aplikasi dan menyimpan nilainya dalam penerapan IWebHostEnvironment
. Penerapan ini tersedia di mana saja di aplikasi melalui injeksi dependensi (DI).
Contoh berikut mengonfigurasi aplikasi untuk memberikan detail informasi kesalahan saat berjalan di lingkungan Development
:
public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
if (env.IsDevelopment())
{
app.UseDeveloperExceptionPage();
}
else
{
app.UseExceptionHandler("/Error");
app.UseHsts();
}
app.UseHttpsRedirection();
app.UseStaticFiles();
app.UseRouting();
app.UseEndpoints(endpoints =>
{
endpoints.MapDefaultControllerRoute();
endpoints.MapRazorPages();
});
}
Untuk informasi lebih lanjut, lihat Menggunakan beberapa lingkungan di ASP.NET Core.
Pencatatan
ASP.NET Core mendukung API pengelogan yang bekerja dengan berbagai penyedia pengelogan bawaan dan pihak ketiga. Penyedia yang tersedia meliputi:
- Konsol
- Debug
- Pelacakan Peristiwa di Windows
- Log Peristiwa Windows
- TraceSource
- Azure App Service
- Azure Application Insights
Untuk membuat log, selesaikan layanan ILogger<TCategoryName> dari injeksi dependensi (DI) dan panggil metode pengelogan seperti LogInformation. Contohnya:
public class TodoController : ControllerBase
{
private readonly ILogger _logger;
public TodoController(ILogger<TodoController> logger)
{
_logger = logger;
}
[HttpGet("{id}", Name = "GetTodo")]
public ActionResult<TodoItem> GetById(string id)
{
_logger.LogInformation(LoggingEvents.GetItem, "Getting item {Id}", id);
// Item lookup code removed.
if (item == null)
{
_logger.LogWarning(LoggingEvents.GetItemNotFound, "GetById({Id}) NOT FOUND", id);
return NotFound();
}
return item;
}
}
Metode pengelogan seperti LogInformation
mendukung sejumlah bidang. Bidang ini biasanya digunakan untuk membuat pesan string
, tetapi beberapa penyedia pengelogan mengirimkannya ke penyimpanan data sebagai bidang terpisah. Fitur ini memungkinkan penyedia pengelogan menerapkan pengelogan semantik, juga dikenal sebagai pengelogan terstruktur.
Untuk informasi selengkapnya, lihat Pengelogan .NET Core dan ASP.NET Core.
Perutean
Rute adalah pola URL yang dipetakan ke penangan. Penangan biasanya adalah halaman Razor, metode tindakan dalam pengontrol MVC, atau middleware. Perutean ASP.NET core memberi Anda kontrol atas URL yang digunakan oleh aplikasi Anda.
Untuk informasi lebih lanjut, lihat Perutean di ASP.NET Core.
Penanganan kesalahan
ASP.NET Core memiliki fitur bawaan untuk menangani kesalahan, seperti:
- Halaman pengecualian pengembang
- Halaman kesalahan kustom
- Halaman kode status statis
- Penanganan pengecualian startup
Untuk informasi lebih lanjut, lihat Menangani kesalahan di ASP.NET Core.
Membuat permintaan HTTP
Penerapan IHttpClientFactory
tersedia untuk membuat instans HttpClient
. Pabrik:
- Menyediakan lokasi pusat untuk penamaan dan konfigurasi instans
HttpClient
logis. Misalnya, daftarkan dan konfigurasikan klien github untuk mengakses GitHub. Daftarkan dan konfigurasikan klien default untuk tujuan lain. - Mendukung pendaftaran dan rantai beberapa penangan pendelegasian untuk membangun alur middleware permintaan keluar. Pola ini mirip dengan alur middleware masuk ASP.NET Core. Pola tersebut menyediakan mekanisme untuk mengelola masalah lintas sektoral untuk permintaan HTTP, termasuk penembolokan, penanganan kesalahan, serialisasi, dan pengelogan.
- Terintegrasi dengan Polly, pustaka pihak ketiga yang populer untuk penanganan kesalahan sementara.
- Mengelola pengumpulan dan masa pakai instans
HttpClientHandler
yang mendasarinya untuk menghindari masalah DNS umum yang terjadi saat mengelola masa pakaiHttpClient
secara manual. - Menambahkan pengalaman pencatatan yang dapat dikonfigurasi melalui ILogger untuk semua permintaan yang dikirim melalui klien yang dibuat oleh pabrik.
Untuk informasi lebih lanjut, lihat Membuat permintaan HTTP menggunakan IHttpClientFactory di ASP.NET Core.
Akar konten
Akar konten adalah jalur dasar untuk:
- Hosting aplikasi yang dapat dieksekusi (.exe).
- Rakitan yang dikompilasi yang membentuk aplikasi (.dll).
- File konten yang digunakan oleh aplikasi, seperti:
- File Razor (
.cshtml
,.razor
) - File konfigurasi (
.json
,.xml
) - File data (
.db
)
- File Razor (
- Akar web, biasanya folder wwwroot.
Selama pengembangan, secara default, akar konten diatur ke direktori akar proyek. Direktori ini juga merupakan jalur dasar untuk file konten aplikasi dan akar Web. Tentukan akar konten yang berbeda dengan mengatur jalurnya saat membangun host. Untuk informasi lebih lanjut, lihat Akar konten.
Akar web
Akar web adalah jalur dasar untuk file sumber daya publik dan statis, seperti:
- Lembar Gaya (
.css
) - JavaScript (
.js
) - Gambar (
.png
,.jpg
)
Secara default, file statis hanya dilayani dari direktori akar web dan sub-direktorinya. Secara default, alur akar web diatur ke {content root}/wwwroot. Tentukan akar web yang berbeda dengan mengatur jalurnya saat membangun host. Untuk informasi lebih lanjut, lihat Akar web.
Cegah penerbitan file di wwwroot dengan item proyek <Konten> di file proyek. Contoh berikut mencegah penerbitan konten di wwwroot/local dan subdirektorinya:
<ItemGroup>
<Content Update="wwwroot\local\**\*.*" CopyToPublishDirectory="Never" />
</ItemGroup>
Dalam file Razor.cshtml
, tilde-slash (~/
) menunjuk ke akar web. Jalur yang diawali dengan ~/
disebut sebagai jalur virtual.
Untuk informasi selengkapnya, lihat File statis di ASP.NET Core.
ASP.NET Core
Saran dan Komentar
https://aka.ms/ContentUserFeedback.
Segera hadir: Sepanjang tahun 2024 kami akan menghentikan penggunaan GitHub Issues sebagai mekanisme umpan balik untuk konten dan menggantinya dengan sistem umpan balik baru. Untuk mengetahui informasi selengkapnya, lihat:Kirim dan lihat umpan balik untuk