ASP.NET Web API POST 參數為 Null 疑難雜症：缺少 "=" 前綴導致模型繫結失效

問題現象

在呼叫 ASP.NET Web API 的 POST 方法時，明明已在 Client 端設定 `Content-Type: application/x-www-form-urlencoded` 並送出資料，但 Server 端的 Action 參數永遠是 `null`，無論是基本型別還是複雜模型皆無法繫結。

根本原因

ASP.NET Web API 的預設模型繫結器在處理 `application/x-www-form-urlencoded` 時，期望請求主體為標準的 **鍵值對格式**，即 `key=value&key2=value2`。若 Client 直接發送裸字串 (如 `"abc"`) 而非 `=abc` 或 `param=abc`，繫結器無法解析參數名稱，導致繫結失敗。

錯誤與正確請求主體對比

Client 端修正範例

jQuery AJAX

// 錯誤：data 直接放字串
$.ajax({
    url: '/api/values',
    type: 'POST',
    data: 'abc', // 缺少參數名
    contentType: 'application/x-www-form-urlencoded'
});

// 正確：使用物件或編碼字串
$.ajax({
    url: '/api/values',
    type: 'POST',
    data: { '': 'abc' }, // 空鍵名對應單一參數
    // 或 data: '=abc'
    contentType: 'application/x-www-form-urlencoded'
});

HttpClient (C#)

// 錯誤
var content = new StringContent("abc", Encoding.UTF8, "application/x-www-form-urlencoded");

// 正確：使用 FormUrlEncodedContent 自動編碼
var content = new FormUrlEncodedContent(new[]
{
    new KeyValuePair("", "abc") // 空鍵名
    // 或 new KeyValuePair("param", "abc")
});

Server 端對應 Action 簽名

// 單一基本型別參數：模型繫結器會嘗試從請求主體讀取
public IHttpActionResult Post([FromBody] string value) { ... }

// 複雜模型：需具名鍵值對
public class MyModel { public string Name { get; set; } }
public IHttpActionResult Post([FromBody] MyModel model) { ... }

其他常見導致 Null 的原因

• 缺少 [FromBody]：Web API 預設從 URI 繫結基本型別，複雜型別才從 Body 讀取。加上 `[FromBody]` 強制從 Body 繫結。
• Content-Type 不符：確認請求標頭為 `application/x-www-form-urlencoded` 或 `application/json` (對應 JSON 格式)。
• 多重 [FromBody]：一個 Action 只能有一個參數標記 `[FromBody]`，因為請求主體只能讀取一次。
• 請求主體已被讀取：在 Filter、Handler 或 `Request.Content.ReadAsStringAsync()` 先讀取過，導致繫結器讀不到資料。

除錯技巧

1. 在 Action 開頭加入 `string raw = await Request.Content.ReadAsStringAsync();` 印出原始主體確認格式。
2. 使用 Fiddler / Postman 攔截實際發送的 HTTP 請求內容。
3. 啟用 Web API 追蹤 (`System.Web.Http.Tracing`) 觀察模型繫結過程。

總結

Web API 接收 `application/x-www-form-urlencoded` POST 資料時，**務必確保請求主體為合法的鍵值對格式** (至少包含一個 `=`)。單一參數可用空鍵名 `=value`，多參數用 `key1=val1&key2=val2`。搭配 `[FromBody]` 屬性即可正確繫結。