IActionResult 介面

ASP.NET Core Web 應用開發–使用 MVC 框架 / PART I MVC 入門 / MVC - Controller 的部份 / IActionResult 介面

動作方法的回傳型別定義為IActionResult,因此只要實作此介面的類別,實體化之後的物件都可以進行回傳,Controller類別的View() 方法取得的 ViewResult 是學習控制器第一個會接觸到的IActionResult衍生類別,例如Index() 方法:

public IActionResult Index()
{
    return View();
}

從規格頁可以發現實作 IActionResult 介面的類別相當多,這也意謂著,任何宣告如上述 Index() 的動作方法,return 關鍵字能夠回傳的不是只有 View() 方法的 ViewResult 結果。

觀察 ViewResult 規格,會發現這個類別是 ActionResult 的子類別,而除了 ViewResult 底下同時還衍生了大量的其它子類別,當然,ActionResult 本身實作了 IActionResult 介面:

從 ActionResult 名稱可以理解這個類別所定義的是各種動作方法可能的執行結果,也因此底下的衍生類別名稱根據回傳的結果資料類型作命名,並且以Result作為結束的字尾。

除了ViewResult ,以下談談其它幾種常見的ActionResult類別。

ContentResult

如果想要回傳單純的文字內容,指定回傳ContentResult物件即可,與ViewResult原理相同,Content() 方法支援ContentResult物件的回傳,以下於控制器建立新的動作方法Message(),其中引用Content() 方法,並將要回傳的純文字內容,當作參數傳入,最後的return敘述回傳封裝字串的ContentResult物件。

public IActionResult Message()
{
    return Content("康廷數位技術教學");
}

於瀏覽器直接輸入「https://localhost:xxxxx/home/message」,得到以下的結果畫面:


左截圖是瀏覽器呈現的內容,只有字串參數,右圖則是切換至原始碼內容,可以看到其中除了字串並沒有任何其它網頁元素。

比較View() 與Content() 兩個方法,可以發現前者回傳的是完整的網頁檔案內容,後者是單純的字串,從這裏對於控制器回傳型別IActionResult介面應該有更深一層的認識,當然只要是IActionResult介面的實作型別,均是回傳的目標對像之一。

EmptyResult

如果沒有回傳任何的內容,可以指定直接回傳一個EmptyResult物件,例如以下的配置:

return new EmptyResult();

這一行程式碼,會導致一個完全空的回應。

當一個要求傳送進控制器的對應方法中,如果只是執行特定的邏輯,而沒有打算回傳任何的結果,可以將一個新建立的EmptyResult物件進行回傳即可。

Web應用針對網路要求的回應,並非只有網頁或字串等內容,根據執行的狀況,可能會有進一步的轉向動作,甚至回應HTTP 404或Not Found這一類表示錯誤訊息的HTTP狀態碼,無論那一種狀況,ASP.NET Core均有對應的IActionResult介面實作物件可供使用。

StatusCodeResult

StatusCodeResult是ActionResult類別的子類別,如果動作方法要回應的是特定的Http狀態碼,可以回傳對應的StatusCodeResult狀態碼物件,子類別針對各種常見的狀態碼進行封裝以方便動作方法回傳,下表列舉可用的子類別與其代表的意義。

子類別HTTP 狀態碼說明
BadRequestResult400 Bad Request 無效語法的錯誤要求
ConflictResult 409 Conflict 與伺服器目前狀態衝突的要求
NoContentResult 204 No Content 無內容回應
NotFoundResult 404 Not Found 找不到要求的資源回應
OkResult 200 OK 成功的要求
UnauthorizedResult 401 Unauthorized 未授權的回應
UnprocessableEntityResult 422 Unprocessable Entity 語意錯誤無法處理
UnsupportedMediaTypeResult 415 Unsupported Media Type 不支援的媒體格式要求
InternalServerErrorResult 500 Internal Server Error 未知或無法處理的伺服器要求

當Web應用需要回傳HTTP狀態碼,利用return 敘述回傳上述對應的狀態碼物件即可。

以下建立動作方法HttpNotFound(),於其中回傳NotFoundResult物件,如下式:

public IActionResult HttpNotFound()
{
    return new NotFoundResult();
}

嘗試在瀏覽器傳送要求如下網址列,會得到找不到網頁的回應畫面:

每一個StatusCodeResult狀態碼結果物件,都對應至一個Http狀態碼,來看看以下為其類別建構式:

public StatusCodeResult (int statusCode);

其中接受一個代表特定Http狀態碼的整數,如果不想指定子類別物件,可以直接傳入對應的狀態碼,例如以下的設定:

public IActionResult HttpNotFound()
{
    return new StatusCodeResult(404);
    //return new NotFoundResult();
}

上下兩行的效果相同。

實務開發的過程中,並不會直接回應狀態碼物件,通常會設計轉向機制配合狀態物件達到回應的目的。

沒有留言: