使用 C++Builder 開發 ISAPI 擴充應用程式完整指南

前言：ISAPI 架構與優勢

ISAPI (Internet Server API) 是 Microsoft IIS 提供的高效能 Web 擴充介面。相較於傳統 CGI 為每個請求建立新進程，ISAPI 以 **DLL 形式載入 IIS 處理序空間**，僅首次請求載入，後續請求以 **執行緒** 服務，極大降低資源消耗與延遲。ISAPI 分為 擴充 (Extension) 與 過濾器 兩類，本文專注於 ISAPI 擴充開發。

ISAPI 擴充運作流程

1. 用戶端請求 URL 指向 DLL (如 <img src="myGetGrp.dll">)
2. IIS 檢查 DLL 是否已快取，否則載入
3. 呼叫 DLL 匯出函數 HttpExtensionProc，傳遞 EXTENSION_CONTROL_BLOCK (ECB) 結構
4. 開發者在 HttpExtensionProc 內透過 ECB 回呼函數 (WriteClient, ReadClient, ServerSupportFunction 等) 處理請求、回應資料
5. 返回狀態碼 (HSE_STATUS_SUCCESS 等) 結束請求

注意：IIS 以多執行緒並行處理請求，開發者**必須正確處理執行緒同步**，否則導致資料損毀或服務崩潰。

C++Builder 建立 ISAPI 專案步驟

1. File → New → Web Server Application
2. 選擇 ISAPI/NSAPI Dynamic Link Library
3. IDE 產生專案主模組 Project.cpp，包含三個必要匯出函數

三大核心匯出函數詳解

1. GetExtensionVersion — 版本協商與初始化

BOOL __export WINAPI GetExtensionVersion(HSE_VERSION_INFO &Ver)
{
    Ver.dwExtensionVersion = MAKELONG(HSE_VERSION_MAJOR, HSE_VERSION_MINOR);
    Ver.lpszExtensionDesc = "My ISAPI Extension";
    // 可在此進行全域資源初始化
    return TRUE;
}

DLL 首次載入時由 IIS 呼叫，僅執行一次。

2. HttpExtensionProc — 核心請求處理

每個 HTTP 請求觸發一次呼叫。ECB 結構關鍵欄位：

Hello World 範例

DWORD __export WINAPI HttpExtensionProc(EXTENSION_CONTROL_BLOCK *ECB)
{
    char header[] = "200 OK\r\nContent-Type: text/html\r\n\r\n";
    DWORD len = strlen(header);
    ECB->ServerSupportFunction(ECB->ConnID, HSE_REQ_SEND_RESPONSE_HEADER, header, &len, NULL);

    char body[] = "Hello from ISAPI!";
    len = strlen(body);
    ECB->WriteClient(ECB->ConnID, body, &len, 0);

    return HSE_STATUS_SUCCESS;
}

回呼函數原型對照

• WriteClient：`BOOL (ConnID, Buffer, &Bytes, Reserved)`
• ReadClient：`BOOL (ConnID, Buffer, &Size)`
• ServerSupportFunction：`BOOL (ConnID, HSE_REQ_*, Buffer, &Size, DataType)`
  常用 HSE_REQ_SEND_RESPONSE_HEADER, HSE_REQ_SEND_URL, HSE_REQ_MAP_URL_TO_PATH, HSE_REQ_DONE_WITH_SESSION

3. TerminateExtension — 卸載通知

BOOL __export WINAPI TerminateExtension(DWORD dwFlags)
{
    // dwFlags: HSE_TERM_ADVISORY_UNLOAD (可拒絕) 或 HSE_TERM_MUST_UNLOAD (強制)
    // 執行清理工作：關閉資料庫連線、釋放記憶體等
    return TRUE; // 同意卸載
}

編譯部署

專案選項設定輸出為 DLL，編譯產生的 `.dll` 複製至 IIS 腳本目錄 (如 `C:\Inetpub\Scripts\`)，在 IIS 管理員中確保目錄具備「執行」權限，即可透過 URL 呼叫。

進階：C++Builder WebSnap 架構

除手寫 ECB 處理，C++Builder 亦提供 WebSnap 高階架構：TWebModule, TISAPIApplication, TISAPIRequest, TISAPIResponse 等類別，封裝 HTTP 解析與回應生成，開發效率更高。詳細用法請參閱產品文件。

結語

ISAPI 擴充是打造高效能 Web 應用的關鍵技術。掌握 ECB 結構與回呼機制，配合 C++Builder 強大的 C++ 編譯優化，可開發出承載高併發的企業級 Web 服務。