Catatan
Akses ke halaman ini memerlukan otorisasi. Anda dapat mencoba masuk atau mengubah direktori.
Akses ke halaman ini memerlukan otorisasi. Anda dapat mencoba mengubah direktori.
Catatan
Ini bukan versi terbaru dari artikel ini. Untuk rilis saat ini, lihat versi .NET 10 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 10 dari artikel ini.
Middleware adalah perangkat lunak yang dirakit menjadi alur aplikasi untuk menangani permintaan dan respons. Setiap middleware:
- Memilih apakah akan meneruskan permintaan ke middleware berikutnya dalam alur.
- Dapat melakukan proses kerja sebelum dan sesudah middleware berikutnya dalam jalur pemrosesan.
Delegasi permintaan digunakan untuk membangun alur permintaan. Delegasi permintaan menangani setiap permintaan HTTP.
Delegasi permintaan dikonfigurasi menggunakan metode ekstensi Run, Map, dan Use. Delegasi permintaan individu dapat ditentukan dalam baris sebagai metode anonim (disebut middleware dalam baris) atau didefinisikan dalam kelas yang dapat digunakan kembali. Metode anonim sebaris atau kelas yang dapat digunakan kembali ini disebut komponen middleware atau middleware. Setiap middleware dalam jalur permintaan bertanggung jawab untuk memanggil middleware berikutnya dalam jalur atau menghentikan jalur. Saat middleware memutus, ini disebut middleware terminal karena mencegah middleware selanjutnya memproses permintaan.
Untuk informasi selengkapnya tentang perbedaan antara alur permintaan di ASP.NET Core dan ASP.NET 4.x dengan sampel middleware tambahan, lihat Memigrasikan modul HTTP ke middleware ASP.NET Core.
Peran middleware menurut jenis aplikasi
Server-side Blazor, Razor Pages, dan MVC memproses permintaan browser di server dengan middleware. Panduan dalam artikel ini berlaku untuk jenis aplikasi ini.
Aplikasi Blazor WebAssembly mandiri berjalan sepenuhnya pada klien dan tidak memproses permintaan dengan alur middleware. Panduan dalam artikel ini tidak berlaku untuk aplikasi Blazor WebAssembly mandiri.
Analisis kode middleware
Untuk informasi selengkapnya tentang penganalisa platform kompilator ASP.NET Core yang memeriksa kode aplikasi untuk kualitas, lihat Analisis Kode Diagnostik di ASP.NET Core Apps.
Membuat saluran middleware dengan WebApplication
Alur permintaan ASP.NET Core terdiri dari urutan delegasi permintaan, yang dipanggil satu demi satu. Diagram berikut menunjukkan konsep tersebut. Aliran eksekusi mengikuti panah hitam.
Setiap delegasi dapat melakukan operasi sebelum dan sesudah delegasi berikutnya. Delegasi penanganan pengecualian harus dipanggil di awal alur, sehingga mereka dapat menangkap pengecualian yang terjadi di tahap selanjutnya dari alur.
Catatan
Untuk bereksperimen secara lokal dengan contoh kode di bagian ini, buat aplikasi ASP.NET Core menggunakan templat proyek ASP.NET Core Empty . Jika menggunakan .NET CLI, nama pendek templat adalah web (dotnet new web).
Aplikasi ASP.NET Core paling sederhana memanggil Run untuk menyiapkan middleware terminal tunggal sebagai delegasi permintaan fungsi anonim untuk menangani permintaan tanpa alur permintaan.
Pada contoh berikut:
- Panggilan ke RunExtensions.Run dieksekusi pada setiap permintaan dan menulis "Hello world!" ke respons.
- Panggilan ke WebApplication.Run di akhir blok kode menjalankan aplikasi dan memblokir utas panggilan hingga host dimatikan.
var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();
app.Run(async context =>
{
await context.Response.WriteAsync("Hello world!");
});
app.Run();
Respons saat mengakses aplikasi di browser di URL peluncurannya:
Hello world!
Tautkan beberapa delegasi permintaan bersama dengan Use. Parameter next mewakili delegasi berikutnya dalam alur. Anda biasanya dapat melakukan tindakan baik sebelum dan sesudah next delegasi.
Contoh berikut menunjukkan:
- Dua Use panggilan, masing-masing menulis ke layar konsol:
- Pekerjaan dapat dilakukan di tempat yang dapat menulis ke respons (
context.Response, HttpResponse). - Di mana pekerjaan dapat dilakukan yang tidak menulis ke respon setelah parameter
nextdipanggil.
- Pekerjaan dapat dilakukan di tempat yang dapat menulis ke respons (
- Permintaan terminal mendelegasikan dengan panggilan ke RunExtensions.Run yang menulis "Hello world!" ke respons.
- Panggilan akhir Use , yang tidak pernah dijalankan karena mengikuti Run delegasi permintaan terminal.
- Panggilan ke WebApplication.Run di akhir blok kode untuk menjalankan aplikasi dan memblokir utas panggilan hingga host dimatikan.
var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();
app.Use(async (context, next) =>
{
Console.WriteLine("Work that can write to the response. (1)");
await next.Invoke(context);
Console.WriteLine("Work that doesn't write to the response. (1)");
});
app.Use(async (context, next) =>
{
Console.WriteLine("Work that can write to the response. (2)");
await next.Invoke(context);
Console.WriteLine("Work that doesn't write to the response. (2)");
});
app.Run(async context =>
{
await context.Response.WriteAsync("Hello world!");
});
app.Use(async (context, next) =>
{
Console.WriteLine("This statement isn't reached. (3)");
await next.Invoke(context);
Console.WriteLine("This statement isn't reached. (3)");
});
app.Run();
Di jendela konsol aplikasi saat aplikasi dijalankan:
Pekerjaan yang dapat menuliskan sesuatu ke dalam pesan balasan. (1)
Pekerjaan yang dapat menuliskan sesuatu ke dalam pesan balasan. (2)
Pekerjaan yang tidak menghasilkan respons. (2)
Pekerjaan yang tidak menghasilkan respons. (1)
Pemutusan jalur permintaan sering kali diinginkan karena menghindari tugas yang tidak perlu. Misalnya, Middleware File Statis dapat bertindak sebagai middleware terminal dengan memproses permintaan file statis dan menghentikan sisa jalur pemrosesan. Middleware ditambahkan ke alur sebelum middleware terminal masih memproses kode setelah pernyataan mereka next.Invoke . Jika Anda tidak berencana untuk memanggil next.Invoke karena tujuan Anda adalah mengakhiri alur, gunakan Run delegasi alih-alih memanggil Use metode ekstensi.
Jangan menelepon next.Invoke selama atau setelah respons dikirim ke klien. Setelah suatu HttpResponse dimulai, perubahan menghasilkan pengecualian. Misalnya, mengatur header atau kode status respons menghasilkan pengecualian setelah respons dimulai. Menulis ke bagian respons setelah memanggil next dapat:
- Menyebabkan pelanggaran protokol, seperti menulis lebih banyak byte ke dalam respons dibandingkan dengan panjang konten respons yang dinyatakan (nilai header
Content-Length). - Merusak format isi, seperti menulis footer HTML ke file CSS.
Untuk menentukan apakah respons telah dimulai, periksa nilai HasStarted.
Untuk informasi selengkapnya, lihat Middleware sirkuit pendek setelah perutean.
Run Mendelegasikan
Run Delegasi tidak menerima next parameter. Delegasi pertama Run selalu menghentikan rangkaian proses.
Run juga merupakan konvensi, dan beberapa middleware dapat mengekspos Run metode yang dijalankan di akhir alur.
Setiap Use atau Run delegasi setelah delegasi pertama Run tidak dipanggil.
Membuat cabang alur middleware
Map ekstensi digunakan sebagai konvensi untuk mencabangkan alur pemrosesan permintaan. Map membuat cabang alur permintaan berdasarkan pencocokan jalur permintaan yang diberikan. Jika jalur permintaan dimulai dengan jalur yang diberikan, cabang akan dijalankan.
Dalam contoh berikut, HandleMap1 dipanggil untuk permintaan ke /map1, dan HandleMap2 dipanggil untuk permintaan ke /map2:
var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();
app.Map("/map1", HandleMap1);
app.Map("/map2", HandleMap2);
app.Run(async context =>
{
await context.Response.WriteAsync("Hello from the non-Map delegate!");
});
app.Run();
private static void HandleMap1(IApplicationBuilder app)
{
app.Run(async context =>
{
await context.Response.WriteAsync("Map 1");
});
}
private static void HandleMap2(IApplicationBuilder app)
{
app.Run(async context =>
{
await context.Response.WriteAsync("Map 2");
});
}
Tabel berikut menunjukkan permintaan dan respons menggunakan kode sebelumnya.
| Permintaan | Tanggapan |
|---|---|
/ |
Hello from the non-Map delegate. |
/map1 |
Map 1 |
/map2 |
Map 2 |
/map3 |
Hello from the non-Map delegate. |
Saat Map digunakan, segmen jalur yang cocok akan dihapus dari HttpRequest.Path dan ditambahkan ke HttpRequest.PathBase untuk setiap permintaan.
Map dapat mencocokkan beberapa segmen sekaligus:
var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();
app.Map("/map1/segment1", HandleMultipleSegments);
app.Run(async context =>
{
await context.Response.WriteAsync("Hello from the non-Map delegate.");
});
app.Run();
private static void HandleMultipleSegments(IApplicationBuilder app)
{
app.Run(async context =>
{
await context.Response.WriteAsync("Processing '/map1/segment1'");
});
}
Tabel berikut menunjukkan permintaan dan respons menggunakan kode sebelumnya.
| Permintaan | Tanggapan |
|---|---|
/ |
Hello from the non-Map delegate. |
/map1/segment1 |
Processing '/map1/segment1' |
Map mendukung bersarang:
var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();
app.Map("/level1", level1App => {
level1App.Map("/level2a", level2AApp => {
level2AApp.Run(async context =>
{
await context.Response.WriteAsync("Processing '/level1/level2a'");
});
});
level1App.Map("/level2b", level2BApp => {
level2BApp.Run(async context =>
{
await context.Response.WriteAsync("Processing '/level1/level2b'");
});
});
});
app.Run(async context =>
{
await context.Response.WriteAsync("Hello from the non-Map delegate!");
});
app.Run();
Tabel berikut menunjukkan permintaan dan respons menggunakan kode sebelumnya.
| Permintaan | Tanggapan |
|---|---|
/ |
Hello from the non-Map delegate. |
/level1/level2a |
Processing '/level1/level2a' |
/level1/level2b |
Processing '/level1/level2b' |
MapWhen membuat cabang alur permintaan berdasarkan hasil dari predikat yang diberikan. Semua predikat berjenis Func<HttpContext, bool> dapat digunakan untuk memetakan permintaan ke cabang baru dari alur. Dalam contoh berikut, predikat digunakan untuk mendeteksi keberadaan variabel string kueri bernama "branch":
var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();
app.MapWhen(context => context.Request.Query.ContainsKey("branch"), HandleBranch);
app.Run(async context =>
{
await context.Response.WriteAsync("Hello from the non-Map delegate.");
});
app.Run();
private static void HandleBranch(IApplicationBuilder app)
{
app.Run(async context =>
{
var branchVer = context.Request.Query["branch"];
await context.Response.WriteAsync($"Branch used = '{branchVer}'");
});
}
Tabel berikut menunjukkan permintaan dan respons menggunakan kode sebelumnya.
| Permintaan | Tanggapan |
|---|---|
/ |
Hello from the non-Map delegate. |
/?branch=main |
Branch used = 'main' |
UseWhen dapat mencabangkan alur permintaan berdasarkan hasil predikat yang diberikan. Tidak seperti MapWhen, cabang tersebut akan bergabung kembali ke jalur utama jika tidak berisi middleware terminal.
var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();
app.UseWhen(context => context.Request.Query.ContainsKey("branch"),
appBuilder => HandleBranchAndRejoin(appBuilder));
app.Run(async context =>
{
await context.Response.WriteAsync("Hello from the non-Map delegate.");
});
app.Run();
void HandleBranchAndRejoin(IApplicationBuilder app)
{
var logger = app.ApplicationServices.GetRequiredService<ILogger<Program>>();
app.Use(async (context, next) =>
{
var branchVer = context.Request.Query["branch"];
logger.LogInformation("Branch used = {branchVer}", branchVer.ToString());
Console.WriteLine("Work that can write to the response.");
await next.Invoke(context);
Console.WriteLine("Work that doesn't write to the response.");
});
}
Dalam contoh sebelumnya, respons "Hello from the non-Map delegate." ditulis untuk semua permintaan. Jika permintaan menyertakan variabel string kueri bernama "branch," nilainya dicatat sebelum alur utama bergabung kembali.
Membuat saluran middleware dengan IApplicationBuilder
Alur permintaan ASP.NET Core terdiri dari urutan delegasi permintaan, yang dipanggil satu demi satu. Diagram berikut menunjukkan konsep tersebut. Aliran eksekusi mengikuti panah hitam.
Setiap delegasi dapat melakukan operasi sebelum dan sesudah delegasi berikutnya. Delegasi penanganan pengecualian harus dipanggil di awal alur, sehingga mereka dapat menangkap pengecualian yang terjadi di tahap selanjutnya dari alur.
Aplikasi ASP.NET Core yang paling sederhana menyiapkan delegasi permintaan tunggal yang menangani semua permintaan. Kasus ini tidak termasuk alur permintaan yang sebenarnya. Sebagai gantinya, satu fungsi anonim dipanggil sebagai respons terhadap setiap permintaan HTTP.
public class Startup
{
public void Configure(IApplicationBuilder app)
{
app.Run(async context =>
{
await context.Response.WriteAsync("Hello, World!");
});
}
}
Tautkan beberapa delegasi permintaan bersama dengan Use. Parameter next mewakili delegasi berikutnya dalam alur. Anda dapat mengakhiri alur dengan tidak memanggil parameter berikutnya. Anda biasanya dapat melakukan tindakan sebelum dan sesudah delegasi berikutnya, seperti yang diperlihatkan contoh berikut:
app.Use(async (context, next) =>
{
// Do work that doesn't write to the Response.
await next.Invoke();
// Do logging or other work that doesn't write to the Response.
});
Saat delegasi tidak meneruskan permintaan ke delegasi berikutnya, hal itu disebut mengakhiri alur permintaan. Pemutusan rangkaian pendek seringkali diinginkan karena menghindari pekerjaan yang tidak perlu. Misalnya, Middleware File Statis dapat bertindak sebagai middleware terminal dengan memproses permintaan file statis dan menghentikan sisa jalur pemrosesan. Middleware yang ditambahkan ke alur sebelum middleware yang menghentikan pemrosesan lebih lanjut masih memproses kode setelah pernyataan next.Invoke-nya. Akan tetapi, perhatikan peringatan berikut mengenai upaya menulis ke dalam respons yang telah terkirim.
Peringatan
Jangan panggil next.Invoke setelah respons dikirim ke klien. Perubahan ke HttpResponse setelah respons dimulai akan memunculkan pengecualian. Misalnya, mengatur header dan kode status akan memunculkan pengecualian. Menulis ke isi respons setelah memanggil next:
- Dapat menyebabkan pelanggaran protokol. Misalnya, menulis lebih dari yang telah dinyatakan
Content-Length. - Dapat merusak format badan. Misalnya, menulis catatan kaki HTML ke file CSS.
HasStarted adalah petunjuk yang berguna untuk menunjukkan apakah tajuk telah dikirim atau isi pesan telah ditulis.
Delegasi Run tidak menerima parameter next. Delegasi Run pertama selalu bersifat akhir dan mengakhiri pipeline.
Run adalah sebuah konvensi. Beberapa komponen middleware dapat mengekspos metode Run[Middleware] yang berjalan di akhir alur:
app.Run(async context =>
{
await context.Response.WriteAsync("Hello from 2nd delegate.");
});
Dalam contoh sebelumnya, delegasi Run menulis "Hello from 2nd delegate." ke respons dan kemudian mengakhiri alur. Jika delegasi Use atau Run lain ditambahkan setelah delegasi Run, delegasi tersebut tidak dipanggil.
Membuat cabang alur middleware
Ekstensi Map digunakan sebagai konvensi untuk membuat cabang alur.
Map membuat cabang alur permintaan berdasarkan pencocokan jalur permintaan yang diberikan. Jika jalur permintaan dimulai dengan jalur yang diberikan, cabang akan dijalankan.
public class Startup
{
private static void HandleMapTest1(IApplicationBuilder app)
{
app.Run(async context =>
{
await context.Response.WriteAsync("Map Test 1");
});
}
private static void HandleMapTest2(IApplicationBuilder app)
{
app.Run(async context =>
{
await context.Response.WriteAsync("Map Test 2");
});
}
public void Configure(IApplicationBuilder app)
{
app.Map("/map1", HandleMapTest1);
app.Map("/map2", HandleMapTest2);
app.Run(async context =>
{
await context.Response.WriteAsync("Hello from non-Map delegate.");
});
}
}
Tabel berikut menunjukkan permintaan dan respons dari http://localhost:1234 menggunakan kode sebelumnya.
| Permintaan | Tanggapan |
|---|---|
| localhost:1234 | Halo dari delegasi bukan Peta. |
| localhost:1234/map1 | Pengujian Peta 1 |
| localhost:1234/map2 | Pengujian Peta 2 |
| localhost:1234/map3 | Halo dari delegasi bukan Peta. |
Saat Map digunakan, segmen jalur yang cocok akan dihapus dari HttpRequest.Path dan ditambahkan ke HttpRequest.PathBase untuk setiap permintaan.
Map mendukung bersarang, misalnya:
app.Map("/level1", level1App => {
level1App.Map("/level2a", level2AApp => {
// "/level1/level2a" processing
});
level1App.Map("/level2b", level2BApp => {
// "/level1/level2b" processing
});
});
Map juga dapat mencocokkan beberapa segmen sekaligus:
public class Startup
{
private static void HandleMultiSeg(IApplicationBuilder app)
{
app.Run(async context =>
{
await context.Response.WriteAsync("Map multiple segments.");
});
}
public void Configure(IApplicationBuilder app)
{
app.Map("/map1/seg1", HandleMultiSeg);
app.Run(async context =>
{
await context.Response.WriteAsync("Hello from non-Map delegate.");
});
}
}
MapWhen membuat cabang alur permintaan berdasarkan hasil dari predikat yang diberikan. Semua predikat berjenis Func<HttpContext, bool> dapat digunakan untuk memetakan permintaan ke cabang baru dari alur. Dalam contoh berikut, predikat digunakan untuk mendeteksi keberadaan variabel string kueri branch:
public class Startup
{
private static void HandleBranch(IApplicationBuilder app)
{
app.Run(async context =>
{
var branchVer = context.Request.Query["branch"];
await context.Response.WriteAsync($"Branch used = {branchVer}");
});
}
public void Configure(IApplicationBuilder app)
{
app.MapWhen(context => context.Request.Query.ContainsKey("branch"),
HandleBranch);
app.Run(async context =>
{
await context.Response.WriteAsync("Hello from non-Map delegate.");
});
}
}
Tabel berikut menunjukkan permintaan dan respons dari http://localhost:1234 menggunakan kode sebelumnya:
| Permintaan | Tanggapan |
|---|---|
| localhost:1234 | Halo dari delegasi bukan Peta. |
| localhost:1234/?branch=main | Cabang yang digunakan = utama |
UseWhen juga membuat cabang alur permintaan berdasarkan hasil dari predikat yang diberikan. Tidak seperti MapWhen, cabang ini digabungkan kembali ke alur utama jika tidak diakhiri atau berisi middleware terminal:
public class Startup
{
private void HandleBranchAndRejoin(IApplicationBuilder app, ILogger<Startup> logger)
{
app.Use(async (context, next) =>
{
var branchVer = context.Request.Query["branch"];
logger.LogInformation("Branch used = {branchVer}", branchVer.ToString());
// Do work that doesn't write to the Response.
await next();
// Do other work that doesn't write to the Response.
});
}
public void Configure(IApplicationBuilder app, ILogger<Startup> logger)
{
app.UseWhen(context => context.Request.Query.ContainsKey("branch"),
appBuilder => HandleBranchAndRejoin(appBuilder, logger));
app.Run(async context =>
{
await context.Response.WriteAsync("Hello from main pipeline.");
});
}
}
Dalam contoh sebelumnya, respons "Halo dari alur utama." dicantumkan untuk semua permintaan. Jika permintaan menyertakan branch variabel string kueri, nilainya dicatat sebelum alur utama bergabung kembali.
Urutan middleware
Urutan middleware yang muncul dalam file aplikasi Program menentukan urutan pemanggilan middleware pada permintaan, dengan urutan terbalik untuk respons.
Anda memiliki kontrol penuh atas urutan middleware dan kemampuan untuk menambahkan middleware kustom untuk skenario pemrosesan permintaan, mengingat bahwa urutan middleware dapat sangat penting untuk keamanan, performa, dan fungsionalitas.
Contoh berikut menunjukkan urutan middleware untuk skenario aplikasi umum. Setiap metode ekstensi middleware diekspos pada WebApplicationBuilder melalui namespace Microsoft.AspNetCore.Builder.
- Penanganan pengecualian/kesalahan
- Saat aplikasi berjalan di
Developmentlingkungan:- Middleware Halaman Pengecualian Pengembang (UseDeveloperExceptionPage) melaporkan kesalahan runtime aplikasi.
- Middleware Halaman Kesalahan Database (UseDatabaseErrorPage) melaporkan kesalahan runtime database.
- Saat aplikasi berjalan di
Productionlingkungan:- Middleware Penanganan Pengecualian (UseExceptionHandler) menangkap pengecualian yang dilemparkan oleh middleware berikutnya.
- Middleware HTTP Strict Transport Security Protocol (HSTS) (UseHsts) menambahkan header
Strict-Transport-Security.
- Saat aplikasi berjalan di
- Middleware Pengalihan HTTPS (UseHttpsRedirection) mengalihkan permintaan HTTP ke HTTPS.
- Middleware File Statis (jika diperlukan, UseStaticFiles) mengembalikan file statis dan menghentikan pemrosesan permintaan lebih lanjut.
- Cookie Policy Middleware (UseCookiePolicy) memastikan aplikasi mematuhi Peraturan Perlindungan Data Umum (GDPR) Uni Eropa.
- Middleware Perutean (UseRouting) untuk merutekan permintaan.
- Middleware Autentikasi (UseAuthentication) mencoba mengautentikasi pengguna sebelum mereka diizinkan mengakses sumber daya yang aman.
- Middleware Otorisasi (UseAuthorization) memberi wewenang kepada pengguna untuk mengakses sumber daya yang aman.
- Middleware Antiforgery (UseAntiforgery) menambahkan middleware antiforgery ke alur UseAntiforgery harus ditempatkan setelah panggilan ke UseAuthentication dan UseAuthorization.
- Middleware Sesi (Razor untuk Halaman dan MVC saja, UseSession) mengatur dan mempertahankan status sesi. Jika aplikasi menggunakan status sesi, panggil Middleware Sesi setelah Cookie Middleware Kebijakan dan sebelum Razor Pages/MVC Middleware.
- Middleware Perutean Titik Akhir
- MapRazorComponents untuk menambahkan Razor titik akhir komponen ke alur permintaan.
- MapRazorPages untuk menambahkan Razor titik akhir Pages ke alur permintaan.
- MapControllerRoute untuk menambahkan titik akhir pengontrol ke alur permintaan.
Jalur middleware umum Blazor Web App :
app.UseWebAssemblyDebugging(); // Development environment with client-side rendering
app.UseMigrationsEndPoint(); // Development environment with ASP.NET Core Identity
app.UseExceptionHandler("/Error", createScopeForErrors: true); // Non-Development environment
app.UseHsts(); // Non-Development environment with HTTPS protocol
app.UseStatusCodePagesWithReExecute("/not-found", createScopeForStatusCodePages: true);
app.UseHttpsRedirection(); // With HTTPS protocol
app.UseAntiforgery();
app.MapStaticAssets();
app.MapRazorComponents<App>(); // With additional extension methods for render modes
app.MapAdditionalIdentityEndpoints(); // With ASP.NET Core Identity
app.Run();
Alur middleware umum untuk Halaman/MVC Razor
app.UseMigrationsEndPoint(); // Development environment with ASP.NET Core Identity
app.UseExceptionHandler("/Error"); // Non-Development environment
app.UseHsts(); // Non-Development environment with HTTPS protocol
app.UseHttpsRedirection(); // With HTTPS protocol
// app.UseCookiePolicy();
app.UseRouting(); // If not called, runs at the beginning of the pipeline by default
// app.UseRateLimiter();
// app.UseRequestLocalization();
// app.UseCors();
// app.UseAuthentication(); // Called internally for ASP.NET Core Identity
app.UseAuthorization();
// app.UseSession();
// app.UseResponseCompression();
// app.UseResponseCaching();
app.MapStaticAssets();
app.MapControllerRoute(...); // For MVC controllers
app.MapRazorPages(); // For Razor Pages pages
app.MapControllers(); // With authentication in a Razor Pages app
app.Run();
Dalam kode sebelumnya:
- CORS Middleware (UseCors), Middleware Autentikasi (UseAuthentication), dan Middleware Otorisasi (UseAuthorization) harus muncul dalam urutan yang ditampilkan.
- CORS Middleware (UseCors) harus muncul sebelum Middleware Cache Respons (UseResponseCaching) untuk menambahkan header CORS pada setiap permintaan, termasuk respons yang di-cache. Untuk informasi selengkapnya, lihat Tidak jelas bahwa UseCORS harus datang sebelum UseResponseCaching (
dotnet/aspnetcore#23218. - Middleware Pelokalan Permintaan (UseRequestLocalization) harus ditempatkan sebelum middleware lainnya yang mungkin memeriksa kultur permintaan, misalnya, Middleware File Statis (UseStaticFiles).
- Middleware Pembatasan Laju (UseRateLimiter) harus dipanggil setelah Middleware Perutean (UseRouting) ketika pembatasan laju digunakan pada API yang spesifik untuk titik akhir. Misalnya, jika
[EnableRateLimiting]atribut digunakan, Middleware Pembatasan Laju harus dipanggil setelah Middleware Perutean. Saat hanya memanggil pembatas global, Middleware Pembatasan Laju dapat dipanggil sebelum Middleware Perutean.
Dalam beberapa skenario, middleware memiliki urutan yang berbeda. Misalnya, penggunaan cache dan urutannya untuk kompresi tergantung pada spesifikasi aplikasi. Dalam urutan berikut ini, penggunaan CPU mungkin dikurangi dengan melakukan caching pada respons terkompresi, namun aplikasi mungkin akhirnya menyimpan dalam cache beberapa bentuk representasi dari sebuah sumber daya menggunakan algoritma kompresi yang berbeda, seperti Gzip atau Brotli.
app.UseResponseCaching();
app.UseResponseCompression();
Aset statis biasanya disajikan di awal alur sehingga aplikasi dapat memotong pemrosesan permintaan untuk meningkatkan performa.
Autentikasi tidak mengakhiri permintaan yang tidak diautentikasi. Meskipun Middleware Autentikasi mengotentikasi permintaan, otorisasi terjadi setelah kerangka kerja memilih komponen Razor, halaman dalam aplikasi Pages Blazor Web App, atau pengontrol dan tindakan dalam aplikasi MVC Razor.
Diagram berikut menunjukkan alur pemrosesan permintaan lengkap untuk aplikasi ASP.NET Core MVC dan Razor Pages. Anda dapat melihat bagaimana, dalam aplikasi pada umumnya, middleware yang ada diurutkan dan di mana middleware kustom ditambahkan. Anda memiliki kendali penuh dalam bagaimana cara mengurutkan kembali middleware yang ada atau menyuntikkan middleware kustom baru yang diperlukan untuk skenario Anda.
Middleware Endpoint dalam diagram sebelumnya menjalankan alur filter untuk jenis aplikasi yang sesuai—MVC atau Razor Halaman.
Middleware Routing dalam diagram sebelumnya ditampilkan setelah File Statis. Ini adalah urutan yang diimplementasikan oleh template proyek dengan memanggil app.UseRouting secara eksplisit. Jika Anda tidak memanggil app.UseRouting, middleware Perutean berjalan di awal alur secara default. Untuk informasi selengkapnya, lihat Perutean.
Urutan penambahan komponen middleware dalam file Program.cs menentukan urutan komponen middleware dipanggil pada permintaan dan urutan terbalik untuk respons. Urutan ini penting untuk keamanan, performa, dan fungsionalitas.
Kode yang disorot berikut ini di Program.cs menambahkan komponen middleware terkait keamanan dalam urutan yang disarankan pada umumnya:
using Microsoft.AspNetCore.Identity;
using Microsoft.EntityFrameworkCore;
using WebMiddleware.Data;
var builder = WebApplication.CreateBuilder(args);
var connectionString = builder.Configuration.GetConnectionString("DefaultConnection")
?? throw new InvalidOperationException("Connection string 'DefaultConnection' not found.");
builder.Services.AddDbContext<ApplicationDbContext>(options =>
options.UseSqlServer(connectionString));
builder.Services.AddDatabaseDeveloperPageExceptionFilter();
builder.Services.AddDefaultIdentity<IdentityUser>(options => options.SignIn.RequireConfirmedAccount = true)
.AddEntityFrameworkStores<ApplicationDbContext>();
builder.Services.AddRazorPages();
builder.Services.AddControllersWithViews();
var app = builder.Build();
if (app.Environment.IsDevelopment())
{
app.UseMigrationsEndPoint();
}
else
{
app.UseExceptionHandler("/Error");
app.UseHsts();
}
app.UseHttpsRedirection();
app.UseStaticFiles();
// app.UseCookiePolicy();
app.UseRouting();
// app.UseRateLimiter();
// app.UseRequestLocalization();
// app.UseCors();
app.UseAuthentication();
app.UseAuthorization();
// app.UseSession();
// app.UseResponseCompression();
// app.UseResponseCaching();
app.MapRazorPages();
app.MapDefaultControllerRoute();
app.Run();
Dalam kode sebelumnya:
- Middleware yang tidak ditambahkan ketika membuat aplikasi web baru dengan akun pengguna individu akan dikomentari.
- Tidak setiap middleware muncul dalam urutan yang persis seperti ini, tetapi banyak yang demikian. Misalnya:
-
UseCors,UseAuthentication, danUseAuthorizationharus muncul dalam urutan yang ditampilkan. -
UseCorssaat ini harus muncul sebelumUseResponseCaching. Persyaratan ini dijelaskan dalam Masalah GitHub dotnet/aspnetcore #23218. -
UseRequestLocalizationharus muncul sebelum middleware apa pun yang mungkin memeriksa budaya permintaan, misalnya,app.UseStaticFiles(). -
UseRateLimiter harus dipanggil setelah
UseRoutingketika API yang spesifik untuk titik akhir menggunakan batasan laju. Misalnya, jika[EnableRateLimiting]atribut digunakan,UseRateLimiterharus dipanggil setelahUseRouting. Saat hanya memanggil pembatas global,UseRateLimiterdapat dipanggil sebelumUseRouting.
-
Dalam beberapa skenario, middleware memiliki urutan yang berbeda. Misalnya, urutan caching dan kompresi tergantung pada skenario, dan ada beberapa urutan yang valid. Contohnya:
app.UseResponseCaching();
app.UseResponseCompression();
Dengan kode sebelumnya, penggunaan CPU dapat dikurangi dengan melakukan caching pada respons yang telah dikompresi, tetapi Anda mungkin akan melakukan caching beberapa representasi sumber daya menggunakan algoritma kompresi yang berbeda seperti Gzip atau Brotli.
Proses berikut menggabungkan file statis untuk memungkinkan penyimpanan file statis yang terkompresi.
app.UseResponseCaching();
app.UseResponseCompression();
app.UseStaticFiles();
Kode Program.cs berikut menambahkan komponen middleware untuk skenario aplikasi umum:
- Penanganan pengecualian/kesalahan
- Saat aplikasi berjalan di
Developmentlingkungan:- Middleware Halaman Pengecualian Pengembang (UseDeveloperExceptionPage) melaporkan kesalahan runtime aplikasi.
- Middleware Halaman Kesalahan Database (UseDatabaseErrorPage) melaporkan kesalahan runtime database.
- Saat aplikasi berjalan di
Productionlingkungan:- Middleware Penanganan Pengecualian (UseExceptionHandler) menangkap pengecualian yang dilemparkan oleh middleware berikutnya.
- Middleware HTTP Strict Transport Security Protocol (HSTS) (UseHsts) menambahkan header
Strict-Transport-Security.
- Saat aplikasi berjalan di
- Middleware Pengalihan HTTPS (UseHttpsRedirection) mengalihkan permintaan HTTP ke HTTPS.
- Middleware File Statis (UseStaticFiles) mengembalikan file statis dan mengakhiri pemrosesan permintaan lebih lanjut.
- Middleware Kebijakan Cookie (UseCookiePolicy) menyelaraskan aplikasi dengan Peraturan Perlindungan Data Umum (GDPR) Uni Eropa.
- Middleware Perutean (UseRouting) untuk merutekan permintaan.
- Middleware Autentikasi (UseAuthentication) mencoba mengautentikasi pengguna sebelum mereka diizinkan mengakses sumber daya yang aman.
- Middleware Otorisasi (UseAuthorization) memberi wewenang kepada pengguna untuk mengakses sumber daya yang aman.
- Middleware Sesi (UseSession) mengatur dan mempertahankan keadaan sesi. Jika aplikasi menggunakan status sesi, panggil Middleware Sesi setelah Middleware Kebijakan Cookie dan sebelum Middleware MVC.
- Middleware Perutean Titik Akhir (UseEndpoints dengan MapRazorPages) untuk menambahkan titik akhir Razor Pages ke alur permintaan.
if (env.IsDevelopment())
{
app.UseDeveloperExceptionPage();
app.UseDatabaseErrorPage();
}
else
{
app.UseExceptionHandler("/Error");
app.UseHsts();
}
app.UseHttpsRedirection();
app.UseStaticFiles();
app.UseCookiePolicy();
app.UseRouting();
app.UseAuthentication();
app.UseAuthorization();
app.UseSession();
app.MapRazorPages();
Dalam kode contoh sebelumnya, setiap metode ekstensi middleware diekspos pada WebApplicationBuilder melalui namespace Microsoft.AspNetCore.Builder.
UseExceptionHandler adalah komponen middleware pertama yang ditambahkan ke alur. Oleh karena itu, Middleware Penanganan Pengecualian menangkap pengecualian yang terjadi di panggilan-panggilan kemudian.
Middleware File Statis dipanggil di awal alur sehingga dapat menangani permintaan dan memotong alur tanpa melewati komponen lain. Middleware File Statis tidak melakukan cek otorisasi. File apa pun yang disajikan oleh Middleware File Statis, termasuk yang berada di bawah wwwroot, tersedia untuk umum. Untuk pendekatan pengamanan file statis, lihat File statis di ASP.NET Core.
Jika permintaan tidak ditangani oleh Middleware File Statis, permintaan akan diteruskan ke Middleware Autentikasi (UseAuthentication), yang melakukan autentikasi. Autentikasi tidak mengakhiri permintaan yang tidak diautentikasi. Meskipun Middleware Autentikasi mengautentikasi permintaan, otorisasi (dan penolakan) hanya terjadi setelah MVC memilih Razor Page atau pengontrol dan tindakan MVC tertentu.
Contoh berikut menunjukkan urutan middleware di mana permintaan untuk file statis ditangani oleh Middleware File Statis sebelum Middleware Pemadatan Respons. File statis tidak dipadatkan dengan urutan middleware ini. Respon dari Razor Pages dapat dikompres.
// Static files aren't compressed by Static File Middleware.
app.UseStaticFiles();
app.UseRouting();
app.UseResponseCompression();
app.MapRazorPages();
Diagram berikut menunjukkan alur pemrosesan permintaan lengkap untuk aplikasi ASP.NET Core MVC dan Razor Pages. Anda dapat melihat bagaimana, dalam aplikasi pada umumnya, middleware yang ada diurutkan dan di mana middleware kustom ditambahkan. Anda memiliki kendali penuh dalam bagaimana cara mengurutkan kembali middleware yang ada atau menyuntikkan middleware kustom baru yang diperlukan untuk skenario Anda.
Middleware Endpoint dalam diagram sebelumnya menjalankan alur filter untuk jenis aplikasi yang sesuai—MVC atau Razor Halaman.
Middleware Routing dalam diagram sebelumnya ditampilkan setelah File Statis. Ini adalah urutan yang diimplementasikan oleh template proyek dengan memanggil app.UseRouting secara eksplisit. Jika Anda tidak memanggil app.UseRouting, middleware Perutean berjalan di awal alur secara default. Untuk informasi selengkapnya, lihat Perutean.
Urutan penambahan komponen middleware dalam file Program.cs menentukan urutan komponen middleware dipanggil pada permintaan dan urutan terbalik untuk respons. Urutan ini penting untuk keamanan, performa, dan fungsionalitas.
Kode yang disorot berikut ini di Program.cs menambahkan komponen middleware terkait keamanan dalam urutan yang disarankan pada umumnya:
using IndividualAccountsExample.Data;
using Microsoft.AspNetCore.Identity;
using Microsoft.EntityFrameworkCore;
var builder = WebApplication.CreateBuilder(args);
// Add services to the container.
var connectionString = builder.Configuration.GetConnectionString("DefaultConnection");
builder.Services.AddDbContext<ApplicationDbContext>(options =>
options.UseSqlServer(connectionString));
builder.Services.AddDatabaseDeveloperPageExceptionFilter();
builder.Services.AddDefaultIdentity<IdentityUser>(options => options.SignIn.RequireConfirmedAccount = true)
.AddEntityFrameworkStores<ApplicationDbContext>();
builder.Services.AddRazorPages();
var app = builder.Build();
// Configure the HTTP request pipeline.
if (app.Environment.IsDevelopment())
{
app.UseMigrationsEndPoint();
}
else
{
app.UseExceptionHandler("/Error");
// The default HSTS value is 30 days. You may want to change this for production scenarios, see https://aka.ms/aspnetcore-hsts.
app.UseHsts();
}
app.UseHttpsRedirection();
app.UseStaticFiles();
// app.UseCookiePolicy();
app.UseRouting();
// app.UseRequestLocalization();
// app.UseCors();
app.UseAuthentication();
app.UseAuthorization();
// app.UseSession();
// app.UseResponseCompression();
// app.UseResponseCaching();
app.MapRazorPages();
app.MapControllerRoute(
name: "default",
pattern: "{controller=Home}/{action=Index}/{id?}");
app.Run();
Dalam kode sebelumnya:
- Middleware yang tidak ditambahkan ketika membuat aplikasi web baru dengan akun pengguna individu akan dikomentari.
- Tidak setiap middleware muncul dalam urutan yang persis seperti ini, tetapi banyak yang demikian. Misalnya:
-
UseCors,UseAuthentication, danUseAuthorizationharus muncul dalam urutan yang ditampilkan. -
UseCorssaat ini harus muncul sebelumUseResponseCaching. Persyaratan ini dijelaskan dalam Masalah GitHub dotnet/aspnetcore #23218. -
UseRequestLocalizationharus muncul sebelum middleware apa pun yang mungkin memeriksa budaya permintaan (misalnya,app.UseMvcWithDefaultRoute()).
-
Dalam beberapa skenario, middleware memiliki urutan yang berbeda. Misalnya, urutan caching dan kompresi tergantung pada skenario, dan ada beberapa urutan yang valid. Contohnya:
app.UseResponseCaching();
app.UseResponseCompression();
Dengan kode sebelumnya, penggunaan CPU dapat dikurangi dengan melakukan caching pada respons yang telah dikompresi, tetapi Anda mungkin akan melakukan caching beberapa representasi sumber daya menggunakan algoritma kompresi yang berbeda seperti Gzip atau Brotli.
Proses berikut menggabungkan file statis untuk memungkinkan penyimpanan file statis yang terkompresi.
app.UseResponseCaching();
app.UseResponseCompression();
app.UseStaticFiles();
Kode Program.cs berikut menambahkan komponen middleware untuk skenario aplikasi umum:
- Penanganan pengecualian/kesalahan
- Saat aplikasi berjalan di
Developmentlingkungan:- Middleware Halaman Pengecualian Pengembang (UseDeveloperExceptionPage) melaporkan kesalahan runtime aplikasi.
- Middleware Halaman Kesalahan Database (UseDatabaseErrorPage) melaporkan kesalahan runtime database.
- Saat aplikasi berjalan di
Productionlingkungan:- Middleware Penanganan Pengecualian (UseExceptionHandler) menangkap pengecualian yang dilemparkan oleh middleware berikutnya.
- Middleware HTTP Strict Transport Security Protocol (HSTS) (UseHsts) menambahkan header
Strict-Transport-Security.
- Saat aplikasi berjalan di
- Middleware Pengalihan HTTPS (UseHttpsRedirection) mengalihkan permintaan HTTP ke HTTPS.
- Middleware File Statis (UseStaticFiles) mengembalikan file statis dan mengakhiri pemrosesan permintaan lebih lanjut.
- Middleware Kebijakan Cookie (UseCookiePolicy) menyelaraskan aplikasi dengan Peraturan Perlindungan Data Umum (GDPR) Uni Eropa.
- Middleware Perutean (UseRouting) untuk merutekan permintaan.
- Middleware Autentikasi (UseAuthentication) mencoba mengautentikasi pengguna sebelum mereka diizinkan mengakses sumber daya yang aman.
- Middleware Otorisasi (UseAuthorization) memberi wewenang kepada pengguna untuk mengakses sumber daya yang aman.
- Middleware Sesi (UseSession) mengatur dan mempertahankan keadaan sesi. Jika aplikasi menggunakan status sesi, panggil Middleware Sesi setelah Middleware Kebijakan Cookie dan sebelum Middleware MVC.
- Middleware Perutean Titik Akhir (UseEndpoints dengan MapRazorPages) untuk menambahkan titik akhir Razor Pages ke alur permintaan.
if (env.IsDevelopment())
{
app.UseDeveloperExceptionPage();
app.UseDatabaseErrorPage();
}
else
{
app.UseExceptionHandler("/Error");
app.UseHsts();
}
app.UseHttpsRedirection();
app.UseStaticFiles();
app.UseCookiePolicy();
app.UseRouting();
app.UseAuthentication();
app.UseAuthorization();
app.UseSession();
app.MapRazorPages();
Dalam kode contoh sebelumnya, setiap metode ekstensi middleware diekspos pada WebApplicationBuilder melalui namespace Microsoft.AspNetCore.Builder.
UseExceptionHandler adalah komponen middleware pertama yang ditambahkan ke alur. Oleh karena itu, Middleware Penanganan Pengecualian menangkap pengecualian yang terjadi di panggilan-panggilan kemudian.
Middleware File Statis dipanggil di awal alur sehingga dapat menangani permintaan dan memotong alur tanpa melewati komponen lain. Middleware File Statis tidak melakukan cek otorisasi. File apa pun yang disajikan oleh Middleware File Statis, termasuk yang berada di bawah wwwroot, tersedia untuk umum. Untuk pendekatan pengamanan file statis, lihat File statis di ASP.NET Core.
Jika permintaan tidak ditangani oleh Middleware File Statis, permintaan akan diteruskan ke Middleware Autentikasi (UseAuthentication), yang melakukan autentikasi. Autentikasi tidak mengakhiri permintaan yang tidak diautentikasi. Meskipun Middleware Autentikasi mengautentikasi permintaan, otorisasi (dan penolakan) hanya terjadi setelah MVC memilih Razor Page atau pengontrol dan tindakan MVC tertentu.
Contoh berikut menunjukkan urutan middleware di mana permintaan untuk file statis ditangani oleh Middleware File Statis sebelum Middleware Pemadatan Respons. File statis tidak dipadatkan dengan urutan middleware ini. Respon dari Razor Pages dapat dikompres.
// Static files aren't compressed by Static File Middleware.
app.UseStaticFiles();
app.UseRouting();
app.UseResponseCompression();
app.MapRazorPages();
Diagram berikut menunjukkan alur pemrosesan permintaan lengkap untuk aplikasi ASP.NET Core MVC dan Razor Pages. Anda dapat melihat bagaimana, dalam aplikasi pada umumnya, middleware yang ada diurutkan dan di mana middleware kustom ditambahkan. Anda memiliki kendali penuh dalam bagaimana cara mengurutkan kembali middleware yang ada atau menyuntikkan middleware kustom baru yang diperlukan untuk skenario Anda.
Middleware Endpoint dalam diagram sebelumnya menjalankan alur filter untuk jenis aplikasi yang sesuai—MVC atau Razor Halaman.
Urutan komponen middleware yang ditambahkan dalam metode Startup.Configure menentukan urutan pemanggilan komponen middleware pada permintaan dan urutan terbalik untuk respons. Urutan ini penting untuk keamanan, performa, dan fungsionalitas.
Metode Startup.Configure berikut menambahkan komponen middleware terkait keamanan dalam urutan yang disarankan pada umumnya:
public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
if (env.IsDevelopment())
{
app.UseDeveloperExceptionPage();
app.UseDatabaseErrorPage();
}
else
{
app.UseExceptionHandler("/Error");
app.UseHsts();
}
app.UseHttpsRedirection();
app.UseStaticFiles();
// app.UseCookiePolicy();
app.UseRouting();
// app.UseRequestLocalization();
// app.UseCors();
app.UseAuthentication();
app.UseAuthorization();
// app.UseSession();
// app.UseResponseCompression();
// app.UseResponseCaching();
app.UseEndpoints(endpoints =>
{
endpoints.MapRazorPages();
endpoints.MapControllerRoute(
name: "default",
pattern: "{controller=Home}/{action=Index}/{id?}");
});
}
Dalam kode sebelumnya:
- Middleware yang tidak ditambahkan ketika membuat aplikasi web baru dengan akun pengguna individu akan dikomentari.
- Tidak setiap middleware muncul dalam urutan yang persis seperti ini, tetapi banyak yang demikian. Misalnya:
-
UseCors,UseAuthentication, danUseAuthorizationharus muncul dalam urutan yang ditampilkan. -
UseCorssaat ini harus muncul sebelumUseResponseCachingkarena bug ini. -
UseRequestLocalizationharus muncul sebelum middleware apa pun yang mungkin memeriksa budaya permintaan (misalnya,app.UseMvcWithDefaultRoute()).
-
Dalam beberapa skenario, middleware memiliki urutan yang berbeda. Misalnya, urutan penembolokan dan pemadatan bergantung pada skenario, dan ada beberapa urutan yang valid. Contohnya:
app.UseResponseCaching();
app.UseResponseCompression();
Dengan kode sebelumnya, penggunaan CPU dapat dihemat dengan melakukan caching pada respons terkompresi, tetapi Anda mungkin akan menyimpan beberapa perwakilan sumber daya menggunakan algoritma kompresi yang berbeda seperti Gzip atau Brotli.
Proses berikut menggabungkan file statis untuk memungkinkan penyimpanan file statis yang terkompresi.
app.UseResponseCaching();
app.UseResponseCompression();
app.UseStaticFiles();
Metode Startup.Configure berikut menambahkan komponen middleware untuk skenario aplikasi umum:
- Penanganan pengecualian/kesalahan
- Saat aplikasi berjalan di
Developmentlingkungan:- Middleware Halaman Pengecualian Pengembang (UseDeveloperExceptionPage) melaporkan kesalahan runtime aplikasi.
- Middleware Halaman Kesalahan Database melaporkan kesalahan runtime database.
- Saat aplikasi berjalan di
Productionlingkungan:- Middleware Penanganan Pengecualian (UseExceptionHandler) menangkap pengecualian yang dilemparkan oleh middleware berikutnya.
- Middleware HTTP Strict Transport Security Protocol (HSTS) (UseHsts) menambahkan header
Strict-Transport-Security.
- Saat aplikasi berjalan di
- Middleware Pengalihan HTTPS (UseHttpsRedirection) mengalihkan permintaan HTTP ke HTTPS.
- Middleware File Statis (UseStaticFiles) mengembalikan file statis dan mengakhiri pemrosesan permintaan lebih lanjut.
- Middleware Kebijakan Cookie (UseCookiePolicy) menyelaraskan aplikasi dengan Peraturan Perlindungan Data Umum (GDPR) Uni Eropa.
- Middleware Perutean (UseRouting) untuk merutekan permintaan.
- Middleware Autentikasi (UseAuthentication) mencoba mengautentikasi pengguna sebelum mereka diizinkan mengakses sumber daya yang aman.
- Middleware Otorisasi (UseAuthorization) memberi wewenang kepada pengguna untuk mengakses sumber daya yang aman.
- Middleware Sesi (UseSession) mengatur dan mempertahankan keadaan sesi. Jika aplikasi menggunakan status sesi, panggil Middleware Sesi setelah Middleware Kebijakan Cookie dan sebelum Middleware MVC.
- Middleware Perutean Titik Akhir (UseEndpoints dengan MapRazorPages) untuk menambahkan titik akhir Razor Pages ke alur permintaan.
public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
if (env.IsDevelopment())
{
app.UseDeveloperExceptionPage();
app.UseDatabaseErrorPage();
}
else
{
app.UseExceptionHandler("/Error");
app.UseHsts();
}
app.UseHttpsRedirection();
app.UseStaticFiles();
app.UseCookiePolicy();
app.UseRouting();
app.UseAuthentication();
app.UseAuthorization();
app.UseSession();
app.UseEndpoints(endpoints =>
{
endpoints.MapRazorPages();
});
}
Dalam kode contoh sebelumnya, setiap metode ekstensi middleware diekspos pada IApplicationBuilder melalui namespace Microsoft.AspNetCore.Builder.
UseExceptionHandler adalah komponen middleware pertama yang ditambahkan ke alur. Oleh karena itu, Middleware Penanganan Pengecualian menangkap pengecualian yang terjadi di panggilan-panggilan kemudian.
Middleware File Statis dipanggil di awal alur sehingga dapat menangani permintaan dan memotong alur tanpa melewati komponen lain. Middleware File Statis tidak melakukan cek otorisasi. File apa pun yang disajikan oleh Middleware File Statis, termasuk yang berada di bawah wwwroot, tersedia untuk umum. Untuk pendekatan pengamanan file statis, lihat File statis di ASP.NET Core.
Jika permintaan tidak ditangani oleh Middleware File Statis, permintaan akan diteruskan ke Middleware Autentikasi (UseAuthentication), yang melakukan autentikasi. Autentikasi tidak mengakhiri permintaan yang tidak diautentikasi. Meskipun Middleware Autentikasi mengautentikasi permintaan, otorisasi (dan penolakan) hanya terjadi setelah MVC memilih Razor Page atau pengontrol dan tindakan MVC tertentu.
Contoh berikut menunjukkan urutan middleware di mana permintaan untuk file statis ditangani oleh Middleware File Statis sebelum Middleware Pemadatan Respons. File statis tidak dipadatkan dengan urutan middleware ini. Respon dari Razor Pages dapat dikompres.
public void Configure(IApplicationBuilder app)
{
// Static files aren't compressed by Static File Middleware.
app.UseStaticFiles();
app.UseRouting();
app.UseResponseCompression();
app.UseEndpoints(endpoints =>
{
endpoints.MapRazorPages();
});
}
Untuk Aplikasi Halaman Tunggal (SPA), UseSpaStaticFiles middleware SPA biasanya berada di urutan terakhir dalam alur middleware. Middleware SPA diletakkan terakhir.
- Untuk mengizinkan semua middleware lain untuk merespons permintaan yang cocok terlebih dahulu.
- Untuk mengizinkan SPA yang menggunakan perutean sisi klien agar dapat berjalan pada semua rute yang tidak dikenali oleh aplikasi server.
Guna mengetahui detail lebih lanjut tentang SPA, lihat panduan untuk template proyek React dan Angular.
Untuk informasi tentang Aplikasi Halaman Tunggal, lihat panduan untuk template proyek React dan Angular.
UseCors dan UseStaticFiles pesanan
Untuk informasi selengkapnya tentang pemesanan UseCors dan UseStaticFiles, lihat Mengaktifkan Permintaan Lintas Asal (CORS) di ASP.NET Core.
Urutan Middleware Header yang Diteruskan
Jalankan Middleware Header yang Diteruskan sebelum middleware lainnya untuk memastikan bahwa middleware yang mengandalkan informasi header yang diteruskan dapat menggunakan nilai header untuk diproses. Untuk menjalankan Middleware Header yang Diteruskan setelah Middleware Diagnostik dan Penanganan Kesalahan, lihat pada Urutan Middleware Header yang Diteruskan.
Middleware bawaan
Rilis terbaru ASP.NET Core dilengkapi dengan middleware berikut. Kolom tumpukan UI menunjukkan tumpukan UI umum tempat middleware digunakan [Semua, Blazor Web App (BWA), Razor Pages dan MVC (RP/MVC)]. Kolom Urutan memberikan catatan tentang penempatan middleware di alur pemrosesan permintaan dan dalam kondisi apa middleware dapat menghentikan pemrosesan permintaan. Saat middleware mengakhiri alur pemrosesan permintaan dan mencegah middleware downstream berikutnya memproses permintaan, itu disebut middleware terminal. Untuk informasi selengkapnya tentang sirkuit pendek, lihat bagian Membuat alur middleware dengan WebApplication .
| Middleware | Deskripsi | Tumpukan UI | Pesanan |
|---|---|---|---|
| Antipemalsuan | Menyediakan dukungan anti-pemalsuan permintaan. | All | Setelah autentikasi dan otorisasi, sebelum titik akhir. |
| Autentikasi | Menyediakan dukungan autentikasi. | All | Sebelum HttpContext.User diperlukan. Terminal untuk panggilan balik OAuth. |
| Otorisasi | Menyediakan dukungan otorisasi. | All | Segera setelah Middleware Autentikasi. |
| Kebijakan Cookie | Melacak persetujuan dari pengguna untuk menyimpan informasi pribadi dan menerapkan standar minimum untuk bidang cookie, seperti secure dan SameSite. |
All | Sebelum middleware yang mengeluarkan kukis. Contoh: Autentikasi, Sesi, MVC (TempData). |
| CORS | Mengonfigurasi Cross-Origin Resource Sharing. | All | Sebelum middleware yang menggunakan CORS.
UseCors harus ditempatkan sebelum UseResponseCaching. Untuk informasi selengkapnya, lihat Tidak jelas bahwa UseCORS harus datang sebelum UseResponseCaching (dotnet/aspnetcore #23218. |
| Halaman Pengecualian Pengembang | Menghasilkan halaman dengan informasi kesalahan yang hanya dimaksudkan untuk digunakan di lingkungan Development. |
All | Sebelum middleware yang menghasilkan kesalahan. Templat proyek secara otomatis mendaftarkan middleware ini sebagai middleware pertama dalam alur ketika lingkungan adalah Development. |
| Diagnostik | Beberapa middleware terpisah yang menyediakan halaman pengecualian pengembang, penanganan pengecualian, halaman kode status, dan halaman web default untuk aplikasi baru. | All | Sebelum middleware yang menghasilkan kesalahan. Terminal untuk pengecualian atau menampilkan halaman web default untuk aplikasi baru. |
| Header yang Diteruskan | Meneruskan header yang telah diproksi ke request saat ini. | All | Sebelum middleware yang mengonsumsi bidang yang telah diperbarui. Contoh: skema, host, IP klien, metode. |
| Pemeriksaan Kesehatan | Memeriksa kesehatan aplikasi ASP.NET Core dan dependensinya, seperti memeriksa ketersediaan database. | All | Terminal jika permintaan cocok dengan titik akhir pemeriksaan kesehatan. |
| Propagasi Header | Mempropagasi header HTTP dari permintaan masuk ke permintaan Klien HTTP keluar. | ||
| All | |||
| Pengelogan HTTP | Mencatat Permintaan dan Respons HTTP. | All | Pada awal alur middleware. |
| Penggantian Metode HTTP | Mengizinkan permintaan POST yang masuk untuk menggantikan metode. | All | "Sebelum middleware yang mengonsumsi metode yang diperbarui." |
| Pengalihan HTTPS | Mengalihkan semua permintaan HTTP ke HTTPS. | All | Sebelum middleware yang memproses URL. |
| Http Strict Transport Security (HSTS) | Middleware untuk peningkatan keamanan yang menambahkan header respons khusus. | All | Sebelum respons dikirim dan setelah middleware memodifikasi permintaan. Contoh: Header yang Diteruskan, Penulisan Ulang URL. |
| MVC | Memproses permintaan dengan MVC/Razor Pages. | RP/MVC | Terminal jika permintaan cocok dengan rute. |
| OWIN | Interop dengan aplikasi, server, dan middleware berbasis OWIN. | RP/MVC | Terminal jika Middleware OWIN sepenuhnya memproses permintaan. |
| Cache Output | Menyediakan dukungan untuk penyimpanan sementara respons berdasarkan konfigurasi. | RP/MVC | Sebelum middleware yang memerlukan penyimpanan sementara. UseRouting, , UseCorsUseAuthentication, dan UseAuthorization harus datang sebelum UseOutputCache. |
| Cache Respons | Menyediakan dukungan untuk caching respons. Ini memerlukan partisipasi klien agar dapat berjalan dengan baik. Gunakan cache output untuk kontrol penuh atas server. | RP/MVC | Sebelum middleware yang memerlukan penyimpanan sementara. UseCors harus sebelum UseResponseCaching. Pencaching respons biasanya tidak bermanfaat untuk aplikasi UI, seperti Razor Pages, karena browser umumnya mengatur header permintaan yang mencegah caching. Cache output bermanfaat bagi aplikasi UI. |
| Permintaan Dekompresi | Menyediakan dukungan untuk mendekompresi permintaan. | All | Sebelum middleware yang membaca isi permintaan. |
| Kompresi Respons | Memberikan dukungan untuk mengompresi respons. | All | Sebelum middleware yang membutuhkan kompresi. |
| Pelokalan Permintaan | Menyediakan dukungan pelokalan. | All | Sebelum middleware sensitif pelokalan. Harus muncul setelah Middleware Perutean saat menggunakan RouteDataRequestCultureProvider. |
| Batas Waktu Permintaan | Menyediakan dukungan untuk mengonfigurasi batas waktu permintaan, global, dan per titik akhir. | All | UseRequestTimeouts harus datang setelah UseExceptionHandler, UseDeveloperExceptionPage, dan UseRouting. |
| Perutean Titik Akhir. | Mendefinisikan dan membatasi rute permintaan. | All | Terminal untuk pencocokan rute. |
| SPA | Menangani semua permintaan dari titik ini dalam rantai middleware dengan mengembalikan halaman default untuk Aplikasi Halaman Tunggal (SPA). | All | Muncul terlambat di alur, jadi middleware lain untuk menyajikan file statis, seperti tindakan MVC, lebih diutamakan. |
| Sesi | Menyediakan dukungan untuk mengelola sesi pengguna. | RP/MVC | Sebelum middleware yang memerlukan Sesi. |
| File Statis | Menyediakan dukungan untuk menyajikan file statis dan penjelajahan direktori. | All | Terminal jika permintaan cocok dengan file. |
| Pengubahan URL | Memberikan dukungan untuk menulis kembali URL dan mengalihkan permintaan. | All | Sebelum middleware yang memproses URL. |
| Pengelogan W3C | Menghasilkan log akses server dalam Format File Log yang Diperluas W3C. | All | Pada awal alur middleware. |
| Blazor WebAssembly Debugging | Debugging Blazor Web App yang mengadopsi rendering sisi klien (CSR) dalam alat pengembang Chromium. | BWA | Pada awal alur middleware. |
| WebSocket | Mengaktifkan protokol WebSocket. | All | Sebelum middleware yang diperlukan untuk menerima permintaan WebSocket. |
Sumber Daya Tambahan:
- Opsi seumur hidup dan pendaftaran (termasuk sampel middleware)
- Menulis middleware ASP.NET Core kustom
- Menguji middleware ASP.NET Core
- Mengonfigurasikan gRPC-Web di ASP.NET Core
- Memigrasikan modul HTTP ke middleware ASP.NET Core
- Startup aplikasi di ASP.NET Core
- Fitur Permintaan di ASP.NET Core
- Aktivasi middleware berbasis pabrik di ASP.NET Core
- Aktivasi middleware dengan kontainer pihak ketiga di ASP.NET Core
ASP.NET Core