Wyniki akcji we wzorcu Web API 2

Artykuł
07/16/2024

Rozważ użycie internetowego interfejsu API platformy ASP.NET Core. Ma następujące zalety w porównaniu z interfejsem API sieci Web ASP.NET 4.x:

ASP.NET Core to międzyplatformowa platforma typu open source do tworzenia nowoczesnych, opartych na chmurze aplikacji internetowych w systemach Windows, macOS i Linux.
Kontrolery MVC i kontrolery internetowego interfejsu API platformy ASP.NET Core są ujednolicone.
Zaprojektowano architekturę pod kątem możliwości testowania.
Możliwość tworzenia i uruchamiania w systemach Windows, macOS i Linux.
Open source i koncentracja na społeczności.
Integracja nowoczesnych struktur po stronie klienta i programistycznych przepływów pracy.
Gotowy do pracy w chmurze, oparty na środowisku system konfiguracji.
Wbudowane wstrzykiwanie zależności.
Uproszczony, modułowy potok żądań HTTP zapewniający wysoką wydajność.
Możliwość hostowania na platformie Kestrel, IIS, HTTP.sys, Nginx, Apache i Docker.
Przechowywanie wersji równoległych.
Narzędzia, które upraszczają tworzenie nowoczesnych aplikacji internetowych.

W tym temacie opisano, jak ASP.NET internetowy interfejs API konwertuje wartość zwracaną z akcji kontrolera na komunikat odpowiedzi HTTP.

Akcja kontrolera internetowego interfejsu API może zwrócić dowolną z następujących czynności:

void
HttpResponseMessage
IHttpActionResult
Inny typ

W zależności od tego, który z tych elementów jest zwracany, internetowy interfejs API używa innego mechanizmu do tworzenia odpowiedzi HTTP.

Typ zwracany	Jak internetowy interfejs API tworzy odpowiedź
void	Zwracanie pustego 204 (brak zawartości)
HttpResponseMessage	Przekonwertuj bezpośrednio na komunikat odpowiedzi HTTP.
IHttpActionResult	Wywołaj metodę ExecuteAsync , aby utworzyć komunikat HttpResponseMessage, a następnie przekonwertuj na komunikat odpowiedzi HTTP.
Inny typ	Zapisz serializowaną wartość zwracaną w treści odpowiedzi; zwróć 200 (OK).

W pozostałej części tego tematu opisano każdą opcję bardziej szczegółowo.

void

Jeśli zwracany typ to void, internetowy interfejs API po prostu zwraca pustą odpowiedź HTTP z kodem stanu 204 (Brak zawartości).

Przykładowy kontroler:

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

Odpowiedź HTTP:

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

HttpResponseMessage

Jeśli akcja zwraca komunikat HttpResponseMessage, internetowy interfejs API konwertuje wartość zwracaną bezpośrednio na komunikat odpowiedzi HTTP, używając właściwości obiektu HttpResponseMessage w celu wypełnienia odpowiedzi.

Ta opcja zapewnia dużą kontrolę nad komunikatem odpowiedzi. Na przykład poniższa akcja kontrolera ustawia nagłówek 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;
    } 
}

Reakcja:

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

Jeśli przekażesz model domeny do metody CreateResponse , internetowy interfejs API używa formatującego nośnika do zapisania serializowanego modelu w treści odpowiedzi.

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

Internetowy interfejs API używa nagłówka Accept w żądaniu, aby wybrać formater. Aby uzyskać więcej informacji, zobacz Negocjowanie zawartości.

IHttpActionResult

Interfejs IHttpActionResult został wprowadzony w internetowym interfejsie API 2. Zasadniczo definiuje fabrykę HttpResponseMessage . Poniżej przedstawiono niektóre zalety korzystania z interfejsu IHttpActionResult :

Upraszcza testowanie jednostkowe kontrolerów.
Przenosi wspólną logikę tworzenia odpowiedzi HTTP do oddzielnych klas.
Sprawia, że intencja akcji kontrolera jest jaśniejsza, ukrywając szczegóły niskiego poziomu konstruowania odpowiedzi.

IHttpActionResult zawiera jedną metodę ExecuteAsync, która asynchronicznie tworzy wystąpienie httpResponseMessage .

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

Jeśli akcja kontrolera zwraca element IHttpActionResult, internetowy interfejs API wywołuje metodę ExecuteAsync w celu utworzenia komunikatu HttpResponseMessage. Następnie konwertuje komunikat HttpResponseMessage na komunikat odpowiedzi HTTP.

Oto prosta implementacja IHttpActionResult , która tworzy odpowiedź w postaci zwykłego tekstu:

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);
    }
}

Przykładowa akcja kontrolera:

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

Reakcja:

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

Częściej używasz implementacji IHttpActionResult zdefiniowanych w przestrzeni nazw System.Web.Http.Results. Klasa ApiController definiuje metody pomocnicze, które zwracają te wbudowane wyniki akcji.

W poniższym przykładzie, jeśli żądanie nie jest zgodne z istniejącym identyfikatorem produktu, kontroler wywołuje element ApiController.NotFound , aby utworzyć odpowiedź 404 (nie znaleziono). W przeciwnym razie kontroler wywołuje element ApiController.OK, który tworzy odpowiedź 200 (OK), która zawiera produkt.

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

Inne typy zwracane

W przypadku wszystkich innych typów zwracanych interfejs API sieci Web używa formatnika multimediów do serializacji zwracanej wartości. Internetowy interfejs API zapisuje serializowaną wartość w treści odpowiedzi. Kod stanu odpowiedzi to 200 (OK).

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

Wadą tego podejścia jest to, że nie można bezpośrednio zwrócić kodu błędu, takiego jak 404. Można jednak zgłosić wyjątek HttpResponseException dla kodów błędów. Aby uzyskać więcej informacji, zobacz Obsługa wyjątków w interfejsie API sieci Web ASP.NET.

Internetowy interfejs API używa nagłówka Accept w żądaniu, aby wybrać formater. Aby uzyskać więcej informacji, zobacz Negocjowanie zawartości.

Przykładowe żądanie

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

Przykładowa odpowiedź

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

Udostępnij za pośrednictwem

Wyniki akcji we wzorcu Web API 2

void

HttpResponseMessage

IHttpActionResult

Inne typy zwracane

Opinia

Dodatkowe zasoby