Web API 2 中的動作結果

發行項
07/13/2023

請考慮使用ASP.NET Core Web API。其優點高於 ASP.NET 4.x Web API：

ASP.NET Core是開放原始碼的跨平臺架構，可用於在 Windows、macOS 和 Linux 上建置現代化、雲端式 Web 應用程式。
MVC 控制器和 Web API 控制器 ASP.NET Core統一。
可測試性架構。
能夠在 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 (OK) 。

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

void

如果傳回類型為 void ，Web API 只會傳回狀態碼為 204 (沒有內容) 的空 HTTP 回應。

範例控制器：

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 會使用 HttpResponseMessage 物件的屬性，將傳回值直接轉換成 HTTP 回應訊息，以填入回應。

此選項可讓您控制回應訊息。例如，下列控制器動作會設定 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 Factory。以下是使用 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類別會定義可傳回這些內建動作結果的協助程式方法。

在下列範例中，如果要求不符合現有的產品識別碼，控制器會呼叫 ApiController.NotFound 來建立 404 (找不到) 回應。否則，控制器會呼叫 ApiController.OK，這會建立包含產品的 200 (OK) 回應。

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 (OK) 。

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}]