萬盛學電腦網

您现在的位置: 萬盛學電腦網 >> 程式設計 >  >> 腳本程式專題 >> JavaScript

jQuery Ajax 呼叫 ASP.NET WebMethod 完整實戰指南(無參數、帶參數、回傳陣列)

前置需求

  • ASP.NET Web Forms 或 MVC 專案
  • 引用 jQuery 1.4+(現代專案建議 3.x)
  • 後台方法需標記 [WebMethod] 且為 static
  • 專案需引用 System.Web.Extensions(含 JSON 序列化)

核心原理

ASP.NET AJAX 透過 ScriptMethod 將靜態方法暴露為 HTTP 端點(頁面.aspx/方法名)。jQuery $.ajax() 以 POST 發送 JSON 格式參數,後台自動反序列化,回傳 JSON 格式資料(外層包裹在 .d 屬性中,ASP.NET AJAX 安全慣例)。

場景一:無參數呼叫

後台

[WebMethod]
public static string SayHello() {
    return "Hello Ajax!";
}

前台

$.ajax({
  type: "POST",
  url: "Data.aspx/SayHello",
  contentType: "application/json; charset=utf-8",
  dataType: "json",
  data: "{}",  // 無參數也需傳空物件字串
  success: function(response) {
    alert(response.d);  // 取得 "Hello Ajax!"
  },
  error: function(xhr, status, error) {
    console.error("呼叫失敗:", error, xhr.responseText);
  }
});

場景二:帶參數呼叫

後台

[WebMethod]
public static string GetStr(string str, string str2) {
    return str + str2;
}

前台

$.ajax({
  type: "POST",
  url: "Data.aspx/GetStr",
  contentType: "application/json; charset=utf-8",
  dataType: "json",
  // 參數名必須與後台形參完全一致(區分大小寫)
  data: JSON.stringify({ str: "我是", str2: "XXX" }),
  success: function(response) {
    alert(response.d);  // "我是XXX"
  }
});

場景三:回傳陣列/集合

後台

[WebMethod]
public static List<string> GetArray() {
    var list = new List<string>();
    for (int i = 0; i < 10; i++) {
        list.Add("Item " + i);
    }
    return list;
}

前台

$.ajax({
  type: "POST",
  url: "Data.aspx/GetArray",
  contentType: "application/json; charset=utf-8",
  dataType: "json",
  data: "{}",
  success: function(response) {
    var arr = response.d;  // 已自動反序列化為 JS 陣列
    $.each(arr, function(i, val) {
      $("#result").append("<li>" + val + "</li>");
    });
  }
});

關鍵注意事項

1. 必須使用 POST

ASP.NET WebMethod 預設拒絕 GET 請求(防止 CSRF/JSON Hijacking)。若必須用 GET,需加裝 [ScriptMethod(UseHttpGet = true)],但強烈不建議。

2. 參數序列化:用 JSON.stringify

手拼 JSON 字串極易出錯(引號、逸出字元)。永遠使用 JSON.stringify():

var params = { name: "張三", age: 25, tags: ["a", "b"] };
data: JSON.stringify(params)

3. 回傳資料在 response.d 中

ASP.NET AJAX 為防止 JSON Hijacking,將回傳值包裹在 { "d": actualData } 中。jQuery dataType: "json" 會自動解析,但不會自動解包 .d,需手動取 response.d。

4. 日期時間序列化格式

預設回傳 "/Date(1234567890123)/" 格式。前端處理:

function parseMSDate(jsonDate) {
  var match = jsonDate.match(/\/Date\((\d+)\)\//);
  return match ? new Date(parseInt(match[1])) : null;
}

或後台使用 JavaScriptSerializer + IsoDateTimeConverter 指定 ISO 8601 格式。

5. 錯誤處理最佳化

error: function(xhr, status, error) {
  var msg = "請求失敗";
  if (xhr.responseText) {
    try {
      var err = JSON.parse(xhr.responseText);
      msg = err.Message || err.ExceptionMessage || msg;
    } catch (e) { msg = xhr.responseText; }
  }
  alert(msg);
  console.error("AJAX Error:", status, error, xhr);
}

完整前台封裝範例

function callWebMethod(pageMethod, params, onSuccess, onError) {
  $.ajax({
    type: "POST",
    url: pageMethod,
    contentType: "application/json; charset=utf-8",
    dataType: "json",
    data: JSON.stringify(params || {}),
    success: function(response) {
      onSuccess && onSuccess(response.d);
    },
    error: function(xhr, status, error) {
      onError && onError(xhr, status, error);
    }
  });
}

// 使用範例
callWebMethod("Data.aspx/GetStr", { str: "Hello", str2: "World" },
  function(result) { alert(result); },
  function(xhr) { alert("錯誤:" + xhr.responseText); }
);

現代替代方案建議

  • ASP.NET Core / Web API:使用 Controller + [HttpPost],回傳標準 JSON,無 .d 包裹,支援屬性路由、模型驗證、Swagger 文檔。
  • PageMethods:ScriptManager 產生的 Proxy 類別,提供強型別 IntelliSense,但綁定 Web Forms 生命週期。
  • Fetch API:現代原生替代方案,配合 async/await 語法更清晰。

掌握 WebMethod 呼叫細節,能快速為舊專案加入 AJAX 功能;新專案建議直接採用 Web API 架構,獲得更好的可測試性、文檔化與前後端分離能力。

copyright © 萬盛學電腦網 all rights reserved