IHttpHandler 是 ASP.NET 處理特定請求的低層介面,適用於:圖片動態生成、檔案下載、API 端點、AJAX 端點、靜態資源處理。比完整 Page 生命週期輕量、效能高。
public class ApiHandler : IHttpHandler {
public bool IsReusable => true; // 無狀態可重用
public void ProcessRequest(HttpContext context) {
var response = context.Response;
response.ContentType = "application/json; charset=utf-8";
response.CacheControl = "no-cache";
try {
// 業務邏輯
var data = GetData(context.Request);
var json = JsonConvert.SerializeObject(new { success = true, data });
response.Write(json);
} catch (Exception ex) {
response.StatusCode = 500;
response.Write(JsonConvert.SerializeObject(new {
success = false,
message = ex.Message
}));
}
}
private object GetData(HttpRequest request) {
// 解析參數、查詢資料庫、回傳物件
return new { message = "Hello " + request.QueryString["name"] };
}
}
public class ImageHandler : IHttpHandler {
public bool IsReusable => true;
public void ProcessRequest(HttpContext context) {
var response = context.Response;
response.ContentType = "image/jpeg";
response.Cache.SetCacheability(HttpCacheability.Public);
response.Cache.SetMaxAge(TimeSpan.FromHours(1));
try {
// 1. 從資料庫/檔案系統取得圖片
// 2. 處理:縮圖、水印、格式轉換
using (var bitmap = GenerateDynamicImage(context.Request)) {
// 關鍵:輸出至 OutputStream,不落地臨時檔
bitmap.Save(response.OutputStream, System.Drawing.Imaging.ImageFormat.Jpeg);
}
} catch {
// 回傳預設佔位圖或 404
response.StatusCode = 404;
}
}
private Bitmap GenerateDynamicImage(HttpRequest request) {
var text = request.QueryString["text"] ?? "Dynamic";
var bmp = new Bitmap(400, 200);
using (var g = Graphics.FromImage(bmp)) {
g.Clear(Color.White);
g.DrawString(text, new Font("Arial", 24), Brushes.Black, 50, 80);
}
return bmp;
}
}
public class DownloadHandler : IHttpHandler {
public bool IsReusable => true;
public void ProcessRequest(HttpContext context) {
var response = context.Response;
var filePath = context.Server.MapPath("~/App_Data/report.txt");
if (!File.Exists(filePath)) {
response.StatusCode = 404;
response.Write("檔案不存在");
return;
}
var fileName = "報表_" + DateTime.Now.ToString("yyyyMMdd") + ".txt";
// 關鍵 Header
response.ContentType = "application/octet-stream";
response.AddHeader("Content-Disposition",
"attachment; filename=" + HttpUtility.UrlEncode(fileName, Encoding.UTF8));
response.AddHeader("Content-Length", new FileInfo(filePath).Length.ToString());
// 高效傳輸:TransmitFile 直接由 IIS 發送,不經 managed heap
response.TransmitFile(filePath);
response.Flush();
response.End();
}
}
public void ProcessRequest(HttpContext context) {
var filePath = ...;
var fileInfo = new FileInfo(filePath);
long fileSize = fileInfo.Length;
var rangeHeader = context.Request.Headers["Range"];
if (!string.IsNullOrEmpty(rangeHeader)) {
// 解析 Range: bytes=0-1023
var range = ParseRange(rangeHeader, fileSize);
context.Response.StatusCode = 206; // Partial Content
context.Response.AddHeader("Content-Range",
$"bytes {range.Start}-{range.End}/{fileSize}");
context.Response.AddHeader("Accept-Ranges", "bytes");
context.Response.ContentLength64 = range.Length;
TransmitFileRange(filePath, range.Start, range.Length, context.Response);
} else {
// 完整檔案
context.Response.AddHeader("Content-Length", fileSize.ToString());
context.Response.TransmitFile(filePath);
}
}
public class AsyncApiHandler : IHttpAsyncHandler {
public IAsyncResult BeginProcessRequest(HttpContext context, AsyncCallback cb, object extraData) {
var task = Task.Run(() => DoWorkAsync(context));
return task.ContinueWith(t => cb(t));
}
public void EndProcessRequest(IAsyncResult result) {
var task = (Task)result;
task.Wait(); // 傳播例外
}
// .NET 4.5+ 可直接實作 Task-based
public Task ProcessRequestAsync(HttpContext context) {
return DoWorkAsync(context);
}
private async Task DoWorkAsync(HttpContext context) {
var data = await GetDataFromDbAsync();
context.Response.ContentType = "application/json";
await context.Response.WriteAsync(JsonConvert.SerializeObject(data));
}
}
<system.webServer>
<handlers>
<add name="ApiHandler" verb="*" path="api/*"
type="MyApp.Handlers.ApiHandler" preCondition="integratedMode" />
<add name="ImageHandler" verb="GET" path="img/*"
type="MyApp.Handlers.ImageHandler" preCondition="integratedMode" />
<add name="DownloadHandler" verb="GET" path="download/*"
type="MyApp.Handlers.DownloadHandler" preCondition="integratedMode" />
</handlers>
</system.webServer>
| 特性 | HttpHandler | Web API / Controller |
|---|---|---|
| 效能 | 極高 (無生命週期) | 中等 (模型繫結、過濾器管線) |
| 開發效率 | 低 (手動解析、序列化) | 高 (屬性路由、模型驗證、Swagger) |
| 測試性 | 難 (依賴 HttpContext) | 易 (依賴注入、MOQ) |
| 適用場景 | 高頻、低延遲、二進位、舊系統整合 | 標準 REST API、複雜業務邏輯 |