Web API 2 中的動作結果

發行項
09/27/2024

考慮使用 ASP.NET Core Web API。與 ASP.NET 4.x Web API 相比，它具有以下優點：

ASP.NET Core 是一個開源跨平台架構，用於在 Windows、macOS 和 Linux 上建立基於雲端的現代 Web 應用程式。
ASP.NET Core MVC 控制器和 Web API 控制器是統一的。
可測試性架構。
能夠在 Windows、macOS 和 Linux 上開發並執行。
開放原始碼和社群導向。
整合的用戶端架構和開發工作流程。
雲端就緒、以環境為基礎的組態系統。
內建的相依性插入。
輕量型、高效能且模組化的 HTTP 要求管線。
能夠在 Kestrel、IIS、HTTP.sys、Nginx、Apache 和 Docker 上裝載。
並存版本。
可簡化現代網頁程式開發的工具。

本主題介紹 ASP.NET Web API 如何將控制器動作的回傳值轉換為 HTTP 回應訊息。

Web API 控制器動作可以傳回以下任何內容：

void
HttpResponseMessage
IHttpActionResult
其他類型

根據傳回的內容，Web API 使用不同的機制來建立 HTTP 回應。

傳回類型	Web API 如何建立回應
void	傳回空白 204 (無內容)
HttpResponseMessage	直接轉換為 HTTP 回應訊息。
IHttpActionResult	呼叫 ExecuteAsync 建立 HttpResponseMessage，然後轉換為 HTTP 回應訊息。
其他類型	將序列化的回傳值寫入回應本文中；傳回 200 (成功)。

本主題的其餘部分更詳細地描述每個選項。

void

如果回傳類型為 void，Web API 僅傳回一個空的 HTTP 回應，狀態碼為 204 (無內容)。

控制器範例：

public class ValuesController : ApiController
{
    public void Post()
    {
    }
}

HTTP 回應：

HTTP/1.1 204 No Content
Server: Microsoft-IIS/8.0
Date: Mon, 27 Jan 2014 02:13:26 GMT

HttpResponseMessage

如果動作傳回 HttpResponseMessage，Web API 會將回傳值直接轉換為 HTTP 回應訊息，並使用 HttpResponseMessage 物件的屬性來填入回應。

此選項可讓您對回應訊息進行各種控制。例如，以下控制器動作會設定 Cache-Control 標頭。

public class ValuesController : ApiController
{
    public HttpResponseMessage Get()
    {
        HttpResponseMessage response = Request.CreateResponse(HttpStatusCode.OK, "value");
        response.Content = new StringContent("hello", Encoding.Unicode);
        response.Headers.CacheControl = new CacheControlHeaderValue()
        {
            MaxAge = TimeSpan.FromMinutes(20)
        };
        return response;
    } 
}

回應：

HTTP/1.1 200 OK
Cache-Control: max-age=1200
Content-Length: 10
Content-Type: text/plain; charset=utf-16
Server: Microsoft-IIS/8.0
Date: Mon, 27 Jan 2014 08:53:35 GMT

hello

如果將領域模型傳遞給 CreateResponse 方法，Web API 將使用媒體格式器將序列化模型寫入回應本文。

public HttpResponseMessage Get()
{
    // Get a list of products from a database.
    IEnumerable<Product> products = GetProductsFromDB();

    // Write the list to the response body.
    HttpResponseMessage response = Request.CreateResponse(HttpStatusCode.OK, products);
    return response;
}

Web API 使用請求中的 Accept 標頭來選擇格式器。有關詳細資訊，請參閱「內容協商」。

IHttpActionResult

IHttpActionResult 介面是在 Web API 2 中引入的。基本上，它定義了一個 HttpResponseMessage 工廠。以下是使用 IHttpActionResult 介面的優點：

簡化控制器的單元測試。
將建立 HTTP 回應的通用邏輯移至單獨的類別中。
透過隱藏構建回應的低階細節，使控制器動作的意圖更加清晰。

IHttpActionResult 包含一個方法 ExecuteAsync，該方法會以非同步方式建立 HttpResponseMessage 執行個體。

public interface IHttpActionResult
{
    Task<HttpResponseMessage> ExecuteAsync(CancellationToken cancellationToken);
}

如果控制器動作傳回 IHttpActionResult，則 Web API 會呼叫 ExecuteAsync 方法來建立 HttpResponseMessage。然後它會將 HttpResponseMessage 轉換為 HTTP 回應訊息。

以下是簡單的 IHttpActionResult 實作，建立純文字回應：

public class TextResult : IHttpActionResult
{
    string _value;
    HttpRequestMessage _request;

    public TextResult(string value, HttpRequestMessage request)
    {
        _value = value;
        _request = request;
    }
    public Task<HttpResponseMessage> ExecuteAsync(CancellationToken cancellationToken)
    {
        var response = new HttpResponseMessage()
        {
            Content = new StringContent(_value),
            RequestMessage = _request
        };
        return Task.FromResult(response);
    }
}

控制器動作範例：

public class ValuesController : ApiController
{
    public IHttpActionResult Get()
    {
        return new TextResult("hello", Request);
    }
}

回應：

HTTP/1.1 200 OK
Content-Length: 5
Content-Type: text/plain; charset=utf-8
Server: Microsoft-IIS/8.0
Date: Mon, 27 Jan 2014 08:53:35 GMT

hello

通常，您會使用 System.Web.Http.Results 命名空間中定義的 IHttpActionResult 實作。 ApiController 類別會定義傳回這些內建動作結果的輔助方法。

在下列範例中，如果要求與現有產品 ID 不匹配，控制器將呼叫 ApiController.NotFound 以建立 404 (找不到) 回應。否則，控制器會呼叫 ApiController.OK，這會建立包含產品的 200 (確定) 回應。

public IHttpActionResult Get (int id)
{
    Product product = _repository.Get (id);
    if (product == null)
    {
        return NotFound(); // Returns a NotFoundResult
    }
    return Ok(product);  // Returns an OkNegotiatedContentResult
}

其他傳回類型

對於其他傳回類型，Web API 會使用媒體格式器來序列化傳回值。 Web API 會將序列化值寫入回應本文。回應狀態代碼為 200 (成功)。

public class ProductsController : ApiController
{
    public IEnumerable<Product> Get()
    {
        return GetAllProductsFromDB();
    }
}

這種方法的缺點是不能直接回傳錯誤碼，例如 404。但是，您可以針對錯誤碼擲回 HttpResponseException。有關詳細資訊，請參閱「ASP.NET Web API 中的例外狀況處理」。

Web API 使用請求中的 Accept 標頭來選擇格式器。有關詳細資訊，請參閱「內容協商」。

範例要求

GET http://localhost/api/products HTTP/1.1
User-Agent: Fiddler
Host: localhost:24127
Accept: application/json

範例回應

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Server: Microsoft-IIS/8.0
Date: Mon, 27 Jan 2014 08:53:35 GMT
Content-Length: 56

[{"Id":1,"Name":"Yo-yo","Category":"Toys","Price":6.95}]

共用方式為

Web API 2 中的動作結果

void

HttpResponseMessage

IHttpActionResult

其他傳回類型

意見反應

其他資源