Web API 2’de Eylem Sonuçları

  • Makale

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 üzerinde barındırma olanağı.
  • 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 birini döndürebilir:

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

Bunlardan hangisinin döndürülürse, Web API'sinin HTTP yanıtını oluşturmak için farklı bir mekanizma kullanması gerekir.

Dönüş türü Web API'sinin yanıtı oluşturma şekli
void Boş 204 döndür (İçerik Yok)
HttpResponseMessage Doğrudan BIR HTTP yanıt iletisine dönüştürün.
IHttpActionResult HttpResponseMessage oluşturmak için ExecuteAsync'i çağırın ve ardından bir HTTP yanıt iletisine dönüştürün.
Diğer tür Serileştirilmiş dönüş değerini yanıt gövdesine yazın; 200 döndür (Tamam).

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'sinde yanıt gövdesine seri hale getirilmiş modeli yazmak için bir medya biçimlendirici kullanılı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 tanıtıldı. Temelde bir HttpResponseMessage fabrikası 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);
}

Bir denetleyici eylemi bir IHttpActionResult döndürürse, Web API'si Bir 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 dosyasını ç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'sinde dönüş değerini seri hale getirmek için bir medya biçimlendirici kullanılı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}]