Aktionsergebnisse in Web-API 2

Erwägen Sie die Verwendung ASP.NET Core-Web-API. Es hat die folgenden Vorteile gegenüber ASP.NET 4.x Web-API:

• ASP.NET Core ist ein plattformübergreifendes Open Source-Framework zum Erstellen moderner, cloudbasierter Web-Apps unter Windows, macOS und Linux.
• Die ASP.NET Core MVC-Controller und Web-API-Controller sind vereinheitlicht.
• Für Testfähigkeit entwickelt.
• Fähigkeit zur Entwicklung und Ausführung unter Windows, macOS und Linux.
• Open Source und mit Fokus auf der Community
• Integration von modernen clientseitigen Frameworks und Entwicklungsworkflows
• Ein cloudfähiges auf der Umgebung basierendes Konfigurationssystem
• Integrierte Abhängigkeitsinjektion
• Eine schlanke, leistungsstarke und modulare HTTP-Anforderungspipeline
• Möglichkeit zum Hosten auf Kestrel, IIS, HTTP.sys, Nginx, Apache und Docker.
• Parallele Versionsverwaltung
• Tools zum Vereinfachen einer modernen Webentwicklung

In diesem Thema wird beschrieben, wie ASP.NET-Web-API den Rückgabewert einer Controlleraktion in eine HTTP-Antwortnachricht konvertiert.

Eine Web-API-Controlleraktion kann eine der folgenden Aktionen zurückgeben:

1. void
2. HttpResponseMessage
3. IHttpActionResult
4. Ein anderer Typ

Je nachdem, welche dieser Elemente zurückgegeben wird, verwendet die Web-API einen anderen Mechanismus zum Erstellen der HTTP-Antwort.

Im restlichen Thema werden die einzelnen Optionen ausführlicher beschrieben.

void

Wenn der Rückgabetyp lautet void, gibt die Web-API einfach eine leere HTTP-Antwort mit Statuscode 204 (Kein Inhalt) zurück.

Beispielcontroller:

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

HTTP-Antwort:

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

HttpResponseMessage

Wenn die Aktion eine HttpResponseMessage zurückgibt, konvertiert die Web-API den Rückgabewert direkt in eine HTTP-Antwortnachricht mithilfe der Eigenschaften des HttpResponseMessage -Objekts, um die Antwort aufzufüllen.

Diese Option bietet Ihnen eine menge Kontrolle über die Antwortnachricht. Die folgende Controlleraktion legt beispielsweise den Cache-Control-Header fest.

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

Antwort:

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

Wenn Sie ein Domänenmodell an die CreateResponse-Methode übergeben, verwendet die Web-API einen Medienformatierer , um das serialisierte Modell in den Antworttext zu schreiben.

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

Die Web-API verwendet den Accept-Header in der Anforderung, um den Formatierer auszuwählen. Weitere Informationen finden Sie unter Content Negotiation.

IHttpActionResult

Die IHttpActionResult-Schnittstelle wurde in Web API 2 eingeführt. Im Wesentlichen definiert es eine HttpResponseMessage-Factory . Hier sind einige Vorteile der Verwendung der IHttpActionResult-Schnittstelle :

• Vereinfacht das Testen ihrer Controller.
• Verschiebt allgemeine Logik zum Erstellen von HTTP-Antworten in separate Klassen.
• Macht die Absicht der Controlleraktion klarer, indem die Details auf niedriger Ebene zum Erstellen der Antwort ausgeblendet werden.

IHttpActionResult enthält eine einzelne Methode ExecuteAsync, die asynchron eine HttpResponseMessage-Instanz erstellt.

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

Wenn eine Controlleraktion ein IHttpActionResult zurückgibt, ruft Web-API die ExecuteAsync-Methode auf, um eine HttpResponseMessage zu erstellen. Anschließend wird die HttpResponseMessage in eine HTTP-Antwortnachricht konvertiert.

Hier ist eine einfache Implementierung von IHttpActionResult , die eine Nur-Text-Antwort erstellt:

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

Beispiel-Controlleraktion:

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

Antwort:

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

Häufiger verwenden Sie die im Namespace "System.Web.Http.Results" definierten IHttpActionResult-Implementierungen. Die ApiController-Klasse definiert Hilfsmethoden, die diese integrierten Aktionsergebnisse zurückgeben.

Wenn die Anforderung im folgenden Beispiel nicht mit einer vorhandenen Produkt-ID übereinstimmt, ruft der Controller ApiController.NotFound auf, um eine 404 (Not Found)-Antwort zu erstellen. Andernfalls ruft der Controller ApiController.OK auf, wodurch eine 200 (OK)-Antwort erstellt wird, die das Produkt enthält.

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

Andere Rückgabetypen

Für alle anderen Rückgabetypen verwendet die Web-API einen Medienformatierer , um den Rückgabewert zu serialisieren. Die Web-API schreibt den serialisierten Wert in den Antworttext. Der Antwortstatuscode ist 200 (OK).

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

Ein Nachteil dieses Ansatzes besteht darin, dass Sie keinen Fehlercode wie 404 direkt zurückgeben können. Sie können jedoch eine HttpResponseException für Fehlercodes auslösen. Weitere Informationen finden Sie unter "Ausnahmebehandlung" in ASP.NET-Web-API.

Die Web-API verwendet den Accept-Header in der Anforderung, um den Formatierer auszuwählen. Weitere Informationen finden Sie unter Content Negotiation.

Beispielanforderung

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

Beispielantwort

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