Web API 2’de Eylem Sonuçları

ASP.NET Core web API'lerini kullanmayı göz önünde bulundurun. ASP.NET 4.x Web API'sine göre aşağıdaki avantajlara sahiptir:

• ASP.NET Core, Windows, macOS ve Linux üzerinde modern, bulut tabanlı web uygulamaları oluşturmaya yönelik açık kaynaklı, platformlar arası bir çerçevedir.
• ASP.NET Core MVC denetleyicileri ve web API denetleyicileri birleştirilir.
• Test edilebilirlik için tasarlanmış.
• Windows, macOS ve Linux üzerinde geliştirme ve çalıştırma olanağı.
• Açık kaynak ve topluluk odaklı.
• Modern istemci tarafı çerçeveler ile geliştirme iş akışlarının tümleştirilmesi.
• Bulutta kullanıma hazır, ortam tabanlı bir yapılandırma sistemi.
• Yerleşik bağımlılık ekleme.
• Basit, yüksek performanslı ve modüler bir HTTP istek işlem hattı.
• Kestrel, IIS, HTTP.sys, Nginx, Apache ve Docker'da barındırabilme.
• Yan yana sürüm oluşturma.
• Modern web geliştirmeyi basitleştiren araçlar.

Bu konuda, ASP.NET Web API'sinin bir denetleyici eyleminden dönüş değerini HTTP yanıt iletisine nasıl dönüştürdüğü açıklanmaktadır.

Web API denetleyicisi eylemi aşağıdakilerden herhangi birini döndürebilir:

1. void
2. HttpResponseMessage
3. IHttpActionResult
4. Başka bir tür

Bunlardan hangilerinin döndürüldüklerine bağlı olarak, Web API'si HTTP yanıtını oluşturmak için farklı bir mekanizma kullanır.

Bu konunun geri kalanında her seçenek daha ayrıntılı olarak açıklanmaktadır.

void

Dönüş türü ise, Web API'sinin 204 (İçerik Yok) durum koduyla boş bir HTTP yanıtı döndürmesi yeterlidir void.

Örnek denetleyici:

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

HTTP yanıtı:

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

HttpResponseMessage

Eylem bir HttpResponseMessage döndürürse, Web API'si yanıtı doldurmak için HttpResponseMessage nesnesinin özelliklerini kullanarak dönüş değerini doğrudan bir HTTP yanıt iletisine dönüştürür.

Bu seçenek, yanıt iletisi üzerinde çok fazla denetim sağlar. Örneğin, aşağıdaki denetleyici eylemi Cache-Control üst bilgisini ayarlar.

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

Yanıt:

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 yöntemine bir etki alanı modeli geçirirseniz, Web API'si yanıt gövdesine seri hale getirilmiş modeli yazmak için bir medya biçimlendirici kullanır.

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'sinde, biçimlendiriciyi seçmek için istekteki Accept üst bilgisi kullanılır. Daha fazla bilgi için bkz . İçerik Anlaşması.

IHttpActionResult

IHttpActionResult arabirimi Web API 2'de kullanıma sunulmuştur. Temelde, bir HttpResponseMessage fabrikasını tanımlar. IHttpActionResult arabirimini kullanmanın bazı avantajları şunlardır:

• Denetleyicilerinizin birim testini basitleştirir.
• HTTP yanıtları oluşturmak için ortak mantığı ayrı sınıflara taşır.
• Yanıtı oluşturmanın alt düzey ayrıntılarını gizleyerek denetleyici eyleminin amacını daha net hale getirir.

IHttpActionResult, zaman uyumsuz olarak bir HttpResponseMessage örneği oluşturan ExecuteAsync adlı tek bir yöntem içerir.

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

Denetleyici eylemi bir IHttpActionResult döndürürse, Web API'si HttpResponseMessage oluşturmak için ExecuteAsync yöntemini çağırır. Ardından HttpResponseMessage'ı bir HTTP yanıt iletisine dönüştürür.

IHttpActionResult'un düz metin yanıtı oluşturan basit bir uygulaması aşağıdadır:

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

Örnek denetleyici eylemi:

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

Yanıt:

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

Daha sık, System.Web.Http.Results ad alanında tanımlanan IHttpActionResult uygulamalarını kullanırsınız. ApiController sınıfı, bu yerleşik eylem sonuçlarını döndüren yardımcı yöntemleri tanımlar.

Aşağıdaki örnekte, istek mevcut bir ürün kimliğiyle eşleşmiyorsa, denetleyici 404 (Bulunamadı) yanıtı oluşturmak için ApiController.NotFound öğesini çağırır. Aksi takdirde denetleyici, ürünü içeren bir 200 (Tamam) yanıtı oluşturan ApiController.Ok'u çağırır.

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

Diğer Dönüş Türleri

Diğer tüm dönüş türlerinde, Web API'si dönüş değerini seri hale getirmek için bir medya biçimlendirici kullanır. Web API'si, yanıt gövdesine seri hale getirilmiş değeri yazar. Yanıt durum kodu 200'dür (Tamam).

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

Bu yaklaşımın dezavantajı, 404 gibi bir hata kodunu doğrudan döndürememenizdir. Ancak, hata kodları için bir HttpResponseException oluşturabilirsiniz. Daha fazla bilgi için bkz . ASP.NET Web API'sinde Özel Durum İşleme.

Web API'sinde, biçimlendiriciyi seçmek için istekteki Accept üst bilgisi kullanılır. Daha fazla bilgi için bkz . İçerik Anlaşması.

Örnek istek

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

Örnek yanıt

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