伺服器/虛擬主機不支援 AjaxPro 終極解決：.ashx 對映與 Web.config 完整配置

問題背景

ASP.NET AJAX 庫 **AjaxPro** (舊專案常見) 需透過 `.ashx` 處理器端點通訊。IIS 預設可能未對應 `.ashx`，導致呼叫失敗 (404/500)。

核心解決：三步驟完成

步驟 1：IIS 新增 .ashx 處理器對映 (ISAPI/Managed Handler)

1. IIS 管理員 → 選中網站 → **處理器對映**。
2. 右側 **新增受控處理常式...** (IIS 7+) 或 **新增腳本對映** (IIS 6)。
3. 填寫：
   • 要求路徑： `*.ashx`
   • 類型： `System.Web.UI.SimpleHandlerFactory` (或留空讓 ASP.NET 自動解析)
   • 名稱： `AjaxPro-ASHX`
   • 限制 → 動作： 勾選 `GET, HEAD, POST, DEBUG`
   • 取消勾選： 「只有當檔案存在時才叫用處理常式」 (關鍵！)
4. 確定 → 是 (加入 FastCgi/模組清單)。

對應的可執行檔路徑 (IIS 6 / 傳統模式)：
`C:\Windows\Microsoft.NET\Framework\v2.0.50727\aspnet_isapi.dll` (32-bit)
`C:\Windows\Microsoft.NET\Framework64\v2.0.50727\aspnet_isapi.dll` (64-bit)

步驟 2：Web.config 註冊 AjaxPro HttpHandler

<configuration>
  <system.web> <!-- IIS 6 / Classic 模式 -->
    <httpHandlers>
      <add verb="POST,GET" path="AjaxPro/*.ashx" type="AjaxPro.AjaxHandlerFactory, AjaxPro" />
      <!-- 或視版本 -->
      <add verb="POST,GET" path="ajaxpro/*.ashx" type="AjaxPro.AjaxHandlerFactory, AjaxPro.2" />
    </httpHandlers>
  </system.web>

  <system.webServer> <!-- IIS 7+ / Integrated 模式 -->
    <handlers>
      <remove name="AjaxPro" />
      <add name="AjaxPro" verb="POST,GET" path="AjaxPro/*.ashx" type="AjaxPro.AjaxHandlerFactory, AjaxPro" preCondition="integratedMode" />
    </handlers>
  </system.webServer>
</configuration>

**關鍵點：** `path="AjaxPro/*.ashx"` 必須與前端呼叫 URL 前綴一致 (預設 `AjaxPro/`)。

步驟 3：伺服器端註冊需 AJAX 的類別

// Page_Load 或建構函式
AjaxPro.Utility.RegisterTypeForAjax(typeof(YourPageClass)); 
// 或針對特定方法類別
AjaxPro.Utility.RegisterTypeForAjax(typeof(YourServiceClass));

前端呼叫範例 (JavaScript)

<script src="AjaxPro/prototype.ashx"></script> <!-- AjaxPro 自動產生的 Proxy -->
<script>
    // 呼叫伺服器端靜態方法
    YourNamespace.YourClass.YourMethod(parameters, callbackFunction);

    function callbackFunction(response) {
        if (response.error) {
            alert("錯誤: " + response.error.message);
        } else {
            var result = response.value; // 回傳值 (DataSet, String, Object...)
            // 處理結果
        }
    }
</script>

完整伺服器端範例 (C#)

[AjaxPro.AjaxNamespace("WebServer")] // 可選，指定 JS 命名空間
public partial class Index : System.Web.UI.Page
{
    protected void Page_Load(object sender, EventArgs e)
    {
        // 註冊當前頁面類別 (包含 AjaxMethod 的方法)
        AjaxPro.Utility.RegisterTypeForAjax(typeof(Index));
    }

    [AjaxPro.AjaxMethod(HttpSessionStateRequirement.Read)] // 需 Session 時
    public DataSet Change()
    {
        string sql = "SELECT xjh, xm FROM xs_jbxx";
        // 假設 cla.Bind 回傳 DataSet
        DataSet ds = cla.Bind(sql);
        return ds;
    }
}

前端對應呼叫

WebServer.Index.Change(change_callback); // 命名空間.類別.方法

function change_callback(response) {
    if (response.error) { alert(response.error.message); return; }
    var ds = response.value; // DataSet 物件 (AjaxPro 客戶端序列化格式)
    var content = document.getElementById("newDG");
    var html = "";
    for (var i = 0; i < ds.Tables[0].Rows.length; i++) {
        html += ds.Tables[0].Rows[i].xm + "<br/>";
    }
    content.innerHTML = html;
}

常見問題排查表

總結

AjaxPro 在 IIS 上運行需三大鐵律：**IIS 對應 *.ashx (取消檔案存在檢查) + Web.config 註冊 HttpHandler + 伺服器端 RegisterTypeForAjax**。逐項核對，舊專案即可平滑運行。新專案建議遷移至 **ASP.NET Web API / ASP.NET Core + fetch/axios**，架構更現代、維護性更佳。