Middleware adalah komponen perangkat lunak yang disusun dalam sebuah pipeline, masing-masing menangani sebagian dari proses request dan response sebelum diteruskan ke middleware berikutnya atau dikembalikan ke client. Setiap request yang masuk ke aplikasi ASP.NET Core selalu melewati pipeline ini.

Middleware bisa melakukan berbagai hal: memeriksa autentikasi, mencatat log, menangani error secara terpusat, mengompresi response, atau bahkan menghentikan pipeline lebih awal tanpa meneruskan request ke middleware berikutnya jika kondisi tertentu terpenuhi.

Artikel ini membahas cara kerja middleware pipeline, urutan eksekusinya yang penting diperhatikan, serta cara membuat middleware custom untuk kebutuhan spesifik yang tidak tersedia secara bawaan.

Urutan Middleware Sangat Menentukan Perilaku Aplikasi

Urutan middleware memengaruhi hasil akhir pemrosesan request

var app = builder.Build(); app.UseExceptionHandler("/error"); app.UseHttpsRedirection(); app.UseAuthentication(); // HARUS sebelum UseAuthorization app.UseAuthorization(); app.MapControllers(); app.Run();
Middleware dieksekusi persis sesuai urutan pendaftarannya, sehingga UseAuthentication harus didaftarkan sebelum UseAuthorization karena proses otorisasi membutuhkan informasi identitas pengguna yang sudah ditetapkan oleh middleware autentikasi sebelumnya. Membalik urutan keduanya akan menyebabkan otorisasi selalu gagal karena identitas pengguna belum tersedia.

Request Delegate dan Konsep Next

Middleware bisa menjalankan kode sebelum dan sesudah next()

app.Use(async (context, next) => { Console.WriteLine("Sebelum request diproses"); await next(); // meneruskan ke middleware berikutnya Console.WriteLine("Setelah response dihasilkan"); });
Setiap middleware menerima parameter next yang merepresentasikan middleware berikutnya dalam pipeline. Kode sebelum memanggil next() dieksekusi saat request masuk, sementara kode setelah next() dieksekusi saat response sudah dihasilkan dan sedang dalam perjalanan kembali ke client, membentuk pola seperti onion yang berlapis-lapis.

Membuat Middleware Custom

Middleware custom sebagai class terpisah untuk logika reusable

public class LoggingMiddleware { private readonly RequestDelegate _next; public LoggingMiddleware(RequestDelegate next) => _next = next; public async Task InvokeAsync(HttpContext context) { Console.WriteLine($"Request: {context.Request.Path}"); await _next(context); } } // Didaftarkan di Program.cs: app.UseMiddleware<LoggingMiddleware>();
Middleware custom sebagai class terpisah memudahkan logika yang kompleks untuk diorganisasikan dengan rapi dan diuji secara independen, dibanding menuliskan semuanya sebagai inline lambda di Program.cs yang bisa menjadi sangat panjang jika banyak logika middleware yang dibutuhkan.

Menghentikan Pipeline Lebih Awal

Tidak memanggil next() menghentikan pipeline lebih awal

app.Use(async (context, next) => { if (!context.Request.Headers.ContainsKey("X-Api-Key")) { context.Response.StatusCode = 401; await context.Response.WriteAsync("API Key dibutuhkan"); return; // TIDAK memanggil next(), pipeline berhenti di sini } await next(); });
Middleware bisa memilih untuk tidak memanggil next() sama sekali, secara efektif menghentikan pipeline dan langsung mengirim response ke client tanpa meneruskan request ke controller atau middleware lain setelahnya, berguna untuk validasi awal seperti pemeriksaan API key sebelum logika bisnis utama dijalankan.

Selain Use dan UseMiddleware, ASP.NET Core juga menyediakan method Map dan MapWhen yang memungkinkan percabangan pipeline berdasarkan kondisi tertentu, misalnya mengarahkan request dengan path tertentu ke rangkaian middleware yang berbeda sama sekali dari pipeline utama, berguna untuk memisahkan penanganan request API dan request halaman statis dalam satu aplikasi yang sama.

Urutan Middleware dan Mengapa Posisinya Tidak Bisa Sembarangan

Urutan middleware yang benar pada Program.cs

var app = builder.Build(); app.UseExceptionHandler("/error"); // 1. tangkap exception paling awal app.UseHttpsRedirection(); // 2. redirect http -> https app.UseStaticFiles(); // 3. layani file statis, skip pipeline lanjut app.UseRouting(); // 4. tentukan endpoint mana yang cocok app.UseAuthentication(); // 5. identifikasi siapa user-nya app.UseAuthorization(); // 6. cek apakah user berhak akses endpoint app.MapControllers(); // 7. eksekusi endpoint app.Run(); // Jika UseAuthorization() diletakkan SEBELUM UseRouting(), // aplikasi akan melempar InvalidOperationException saat start.

Middleware di ASP.NET Core bekerja seperti rantai (chain of responsibility): setiap komponen menerima HttpContext, bisa melakukan sesuatu sebelum memanggil middleware berikutnya lewat delegate next(), dan bisa melakukan sesuatu lagi setelah middleware berikutnya selesai dieksekusi. Karena sifatnya berurutan, posisi pendaftaran middleware di Program.cs sangat menentukan perilaku aplikasi, bukan sekadar urutan kode yang bisa ditukar bebas.

Contoh paling konkret adalah UseAuthentication() yang wajib diletakkan sebelum UseAuthorization(), dan keduanya wajib berada setelah UseRouting() tetapi sebelum MapControllers(). Jika urutan ini dilanggar, ASP.NET Core versi modern akan langsung melempar exception saat aplikasi start karena middleware otorisasi membutuhkan informasi endpoint yang baru tersedia setelah proses routing selesai dijalankan.

UseStaticFiles() biasanya diletakkan di awal pipeline karena jika request menuju file statis seperti gambar atau CSS, middleware ini akan langsung menangani dan mengirim response tanpa perlu meneruskan request ke middleware berikutnya, sehingga menghemat proses routing dan autentikasi yang tidak relevan untuk permintaan file statis semacam itu.

Membuat Custom Middleware dengan Short-Circuiting

Middleware yang menghentikan pipeline lebih awal tanpa memanggil next()

public class ApiKeyMiddleware { private readonly RequestDelegate _next; private const string HeaderName = "X-Api-Key"; public ApiKeyMiddleware(RequestDelegate next) => _next = next; public async Task InvokeAsync(HttpContext context, IConfiguration config) { if (!context.Request.Headers.TryGetValue(HeaderName, out var extractedKey) || extractedKey != config["ApiKey"]) { context.Response.StatusCode = StatusCodes.Status401Unauthorized; await context.Response.WriteAsJsonAsync(new { error = "API Key tidak valid." }); return; // short-circuit: next() TIDAK dipanggil } await _next(context); } } // Program.cs app.UseMiddleware<ApiKeyMiddleware>(); app.MapControllers(); // Request tanpa header X-Api-Key yang benar -> 401, tidak pernah sampai ke controller

Setiap middleware kustom di ASP.NET Core menerima RequestDelegate bernama next lewat constructor, yang mewakili middleware berikutnya dalam pipeline. Memanggil await _next(context) meneruskan request ke komponen selanjutnya, sedangkan tidak memanggilnya sama sekali, seperti pada contoh ApiKeyMiddleware di atas ketika validasi gagal, membuat pipeline berhenti di titik tersebut dan response langsung dikirim tanpa pernah mencapai controller atau middleware setelahnya. Instance middleware sendiri bersifat singleton sepanjang umur aplikasi, sehingga field yang disimpan langsung di dalam class middleware harus bersifat stateless atau thread-safe.

Teknik short-circuiting ini banyak dipakai untuk kebutuhan seperti validasi API key sederhana, rate limiting kustom, atau pengecekan maintenance mode yang harus memblokir seluruh request tanpa terkecuali sebelum masuk ke logika aplikasi. Karena middleware dieksekusi dalam urutan pendaftarannya, menempatkan middleware pemblokir ini di posisi paling awal pipeline memastikan request yang tidak valid tidak membebani proses routing atau autentikasi yang lebih berat di belakangnya. Dependency seperti IConfiguration pada contoh di atas disuntikkan lewat parameter method InvokeAsync, bukan lewat constructor, karena constructor middleware hanya dipanggil sekali saat aplikasi start.

Selain pola berbasis class seperti ApiKeyMiddleware yang membutuhkan method InvokeAsync, ASP.NET Core juga mendukung middleware inline lewat app.Use(async (context, next) => { ... }) langsung di Program.cs untuk logika singkat yang tidak perlu dipisah ke file tersendiri. Pendekatan class lebih disarankan ketika middleware membutuhkan dependency injection tambahan atau logikanya cukup kompleks untuk diuji secara terpisah lewat unit test. Middleware inline lebih cocok untuk eksperimen cepat atau logging sementara yang tidak akan menjadi bagian permanen dari arsitektur aplikasi.

Middleware vs Action Filter: Memilih Tempat yang Tepat untuk Logika Lintas Request

public class LogExecutionTimeFilter : IActionFilter { private Stopwatch _sw; public void OnActionExecuting(ActionExecutingContext ctx) => _sw = Stopwatch.StartNew(); public void OnActionExecuted(ActionExecutedContext ctx) => Console.WriteLine($"{ctx.ActionDescriptor.DisplayName} selesai dalam {_sw.ElapsedMilliseconds}ms"); } // Filter hanya aktif untuk action MVC, bukan untuk semua request seperti middleware

Middleware bekerja di level pipeline HTTP paling luar sehingga cocok untuk hal yang berlaku ke semua request tanpa memandang controller tujuannya, seperti logging mentah, penanganan header, atau autentikasi awal. Action filter bekerja lebih dekat dengan MVC pipeline sehingga punya akses ke ActionDescriptor, argumen yang sudah melalui model binding, dan hasil action sebelum diserialisasi menjadi response, akses yang tidak tersedia secara langsung di middleware biasa karena middleware belum tahu action mana yang akan dieksekusi.

Memilih salah satu pendekatan bergantung pada seberapa spesifik konteks yang dibutuhkan oleh logika tersebut. Validasi header API key lebih pas ditulis sebagai middleware karena berlaku global ke seluruh endpoint, sementara pengukuran durasi eksekusi action tertentu lebih mudah dibaca sebagai action filter karena punya akses langsung ke nama action yang sedang dieksekusi beserta parameter yang dikirimkan klien, sehingga log yang dihasilkan lebih informatif.

Kesalahan Umum yang Sering Terjadi

Mendaftarkan Middleware dalam Urutan yang Salah

Kesalahan urutan middleware, seperti UseAuthorization sebelum UseAuthentication, adalah salah satu penyebab paling umum bug autentikasi dan otorisasi yang membingungkan karena tidak ada error eksplisit yang muncul saat kompilasi.

Lupa Memanggil next() pada Middleware Custom

Middleware yang lupa memanggil next() tanpa maksud menghentikan pipeline secara sengaja akan membuat seluruh middleware dan controller setelahnya tidak pernah dieksekusi, menghasilkan response yang tidak sesuai ekspektasi tanpa pesan error yang jelas.

Menaruh Logika Berat di Middleware yang Dijalankan Setiap Request

Middleware dieksekusi untuk SETIAP request yang masuk ke aplikasi, sehingga menaruh operasi berat seperti query database kompleks di dalamnya tanpa pertimbangan matang bisa menjadi bottleneck performa pada aplikasi dengan trafik tinggi.

Kapan Pendekatan Ini Tidak Cocok Dipakai

Middleware bawaan ASP.NET Core sudah mencakup kebutuhan umum seperti autentikasi, routing, dan penanganan error, sehingga untuk kebanyakan kasus tidak perlu membuat middleware custom dari awal.

Middleware custom memberikan fleksibilitas penuh untuk kebutuhan spesifik aplikasi, namun menambah kompleksitas pipeline yang harus dipahami seluruh tim, sehingga sebaiknya dibuat hanya ketika kebutuhan tersebut benar-benar tidak tercakup oleh middleware bawaan yang sudah teruji.

Ringkasan

Middleware pipeline adalah jantung dari pemrosesan request di ASP.NET Core, dengan urutan pendaftaran yang sangat menentukan perilaku akhir aplikasi. Pahami konsep next() dan kemampuan menghentikan pipeline lebih awal untuk membangun middleware custom yang efektif sesuai kebutuhan spesifik aplikasi.

Seri Belajar .NET Core:

← Sebelumnya: Membuat Project ASP.NET Core Web API Pertama

→ Selanjutnya: Routing dan Controller di ASP.NET Core