ASP.NET Core web API'sinde denetleyici eylemi dönüş türleri

Örnek kodu görüntüleme veya indirme (indirme)

ASP.NET Core, web API denetleyicisi eylem dönüş türleri için aşağıdaki seçenekleri sağlar:

• Belirli tür
• IActionResult
• ActionResult<T>
• HttpResults

Bu makalede, her dönüş türünü kullanmanın en uygun olduğu zamanlar açıklanmaktadır.

Belirli tür

En temel eylem, örneğin string ilkel veya karmaşık bir veri türü ya da özel bir nesne döndürür. Özel Product nesne koleksiyonunu döndüren aşağıdaki eylemi göz önünde bulundurun:

[HttpGet]
public Task<List<Product>> Get() =>
    _productContext.Products.OrderBy(p => p.Name).ToListAsync();

Korunması gereken belirli koşullar olmadan, belirli bir tipi döndürmek yeterli olabilir. Yukarıdaki eylem parametre kabul etmediğinden parametre kısıtlamaları doğrulaması gerekmez.

Birden çok dönüş türü mümkün olduğunda, bir dönüş türünü ilkel veya karmaşık dönüş türüyle karıştırmak ActionResult yaygındır. Bu eylem türünü barındırmak için IActionResult veya ActionResult<T> gereklidir. Bu makalede birden çok dönüş türüne ait çeşitli örnekler sağlanmıştır.

IEnumerable<T> veya IAsyncEnumerable<T> döndürür

Performansla ilgili dikkat edilmesi gerekenler için Return IEnumerable<T> veya IAsyncEnumerable<T> bölümüne bakın.

ASP.NET Core, yanıta yazılmadan önce döndürülen IEnumerable<T> aksiyonlarının sonucunu arabelleğe alır. Zaman uyumsuz yinelemeyi garanti etmek için eylem imzasının dönüş türünü IAsyncEnumerable<T> olarak bildirmeyi göz önünde bulundurun. Sonuç olarak, yineleme modu döndürülen temel somut türü temel alır ve seçilen biçimlendirici sonucun nasıl işlendiğini etkiler:

• System.Text.Json biçimlendirici kullanılırken, MVC System.Text.Json tarafından eklenen desteğe dayanır ve sonucu aktarır.
• Newtonsoft.Json veya XML-based biçimlendiricileri kullanılırken sonuç arabelleğe alınıyor.

Satış fiyatına sahip ürün kayıtlarını IEnumerable<Product> olarak döndüren aşağıdaki eylemi göz önünde bulundurun:

[HttpGet("syncsale")]
public IEnumerable<Product> GetOnSaleProducts()
{
    var products = _productContext.Products.OrderBy(p => p.Name).ToList();

    foreach (var product in products)
    {
        if (product.IsOnSale)
        {
            yield return product;
        }
    }
}

Yukarıdaki IAsyncEnumerable<Product> eylemin eşdeğeri:

[HttpGet("asyncsale")]
public async IAsyncEnumerable<Product> GetOnSaleProductsAsync()
{
    var products = _productContext.Products.OrderBy(p => p.Name).AsAsyncEnumerable();

    await foreach (var product in products)
    {
        if (product.IsOnSale)
        {
            yield return product;
        }
    }
}

"IActionResult" türü

IActionResult dönüş türü, bir eylemde birden çok ActionResult dönüş türü mümkün olduğunda uygundur. Türler ActionResult çeşitli HTTP durum kodlarını temsil ediyor. ActionResult öğesinden türetilen soyut olmayan tüm sınıflar geçerli bir dönüş türü niteliğinde kabul edilir. Bu kategorideki bazı yaygın dönüş türleri şunlardır BadRequestResult : (400), NotFoundResult (404) ve OkObjectResult (200). Alternatif olarak, ControllerBase türlerini bir eylemden döndürmek için ActionResult sınıfındaki kolaylık yöntemleri kullanılabilir. Örneğin, return BadRequest(); kısaltma biçimidir return new BadRequestResult();.

Bu tür eylemlerde birden çok dönüş türü ve yolu olduğundan, özniteliğin [ProducesResponseType] liberal kullanımı gereklidir. Bu öznitelik, Swagger gibi araçlar tarafından oluşturulan web API'si yardım sayfaları için daha açıklayıcı yanıt ayrıntıları oluşturur. [ProducesResponseType] , eylem tarafından döndürülecek bilinen türleri ve HTTP durum kodlarını gösterir.

Zaman uyumlu eylem

İki olası dönüş türünün bulunduğu aşağıdaki zaman uyumlu eylemi göz önünde bulundurun:

[HttpGet("{id}")]
[ProducesResponseType<Product>(StatusCodes.Status200OK)]
[ProducesResponseType(StatusCodes.Status404NotFound)]
public IActionResult GetById_IActionResult(int id)
{
    var product = _productContext.Products.Find(id);
    return product == null ? NotFound() : Ok(product);
}

Önceki eylemde:

• tarafından temsil edilen id ürün temel alınan veri deposunda mevcut olmadığında 404 durum kodu döndürülür. NotFound rahatlık yöntemi, return new NotFoundResult(); için bir kısaltma olarak çağrılır.
• Ürün mevcut olduğunda nesnesiyle birlikte Product 200 durum kodu döndürülür. Ok rahatlık yöntemi, return new OkObjectResult(product); için bir kısaltma olarak çağrılır.

Zaman uyumsuz eylem

İki olası dönüş türünün bulunduğu aşağıdaki zaman uyumsuz eylemi göz önünde bulundurun:

[HttpPost()]
[Consumes(MediaTypeNames.Application.Json)]
[ProducesResponseType(StatusCodes.Status201Created)]
[ProducesResponseType(StatusCodes.Status400BadRequest)]
public async Task<IActionResult> CreateAsync_IActionResult(Product product)
{
    if (product.Description.Contains("XYZ Widget"))
    {
        return BadRequest();
    }

    _productContext.Products.Add(product);
    await _productContext.SaveChangesAsync();

    return CreatedAtAction(nameof(GetById_IActionResult), new { id = product.Id }, product);
}

Önceki eylemde:

• Ürün açıklamasında "XYZ Pencere Öğesi" bulunduğunda 400 durum kodu döndürülür. BadRequest rahatlık yöntemi, return new BadRequestResult(); için bir kısaltma olarak çağrılır.

• Bir ürün oluşturulduğunda kolaylık yöntemi tarafından CreatedAtAction 201 durum kodu oluşturulur. Aşağıdaki kod çağrısı CreatedAtActionyapmak için bir alternatiftir:

  return new CreatedAtActionResult(nameof(GetByIdAsync), 
                                  "Products", 
                                  new { id = product.Id }, 
                                  product);
  

  Önceki kod yolunda Product nesnesi yanıt gövdesinde sağlanır. Location Yeni oluşturulan ürünün URL'sini içeren bir yanıt üst bilgisi sağlanır.

Örneğin, aşağıdaki model, isteklerin Name ve Description özelliklerini içermesi gerektiğini gösterir. Name ve Description'un istek içinde sağlanmaması, model doğrulamasının başarısız olmasına neden olur.

public class Product
{
    public int Id { get; set; }

    [Required]
    public string Name { get; set; } = string.Empty;

    [Required]
    public string Description { get; set; } = string.Empty;

    public bool IsOnSale { get; set; }
}

[ApiController] Öznitelik uygulanırsa model doğrulama hataları 400 durum koduyla sonuçlanır. Daha fazla bilgi için bkz . Otomatik HTTP 400 yanıtları.

ActionResult vs IActionResult

Aşağıdaki bölüm, ActionResult'yi IActionResult ile karşılaştırır

ActionResult<T> türü

ASP.NET Core, web API denetleyicisi eylemleri için ActionResult<T> dönüş türünü içerir. ActionResult türevinden türetilen bir tür döndürmeyi ya da bir belirli tür döndürmeyi etkinleştirir. ActionResult<T>IActionResult türüne göre aşağıdaki avantajları sunar:

• Özniteliğin [ProducesResponseType]Type özelliği dışlanabilir. Örneğin, [ProducesResponseType(200, Type = typeof(Product))] olarak basitleştirilmiştir [ProducesResponseType(200)]. Eylemin beklenen dönüş türü, T içinde ActionResult<T> ile çıkarılır.
• Örtük atama işleçleri, T ve ActionResult'nin ActionResult<T>'ye dönüştürülmesini destekler. T ObjectResult olarak dönüştürülür, bu da anlamına gelir ki return new ObjectResult(T);, return T; olarak basitleştirilmiştir.

C# arabirimlerde örtük atama işleçlerini desteklemez. Sonuç olarak, ActionResult<T>'i kullanmak için arabirimin somut bir türe dönüştürülmesi gerekir. Örneğin, aşağıdaki örnekte öğesinin IEnumerable kullanımı çalışmıyor:

[HttpGet]
public ActionResult<IEnumerable<Product>> Get() =>
    _repository.GetProducts();

Önceki kodu düzeltmek için bir seçenek olarak _repository.GetProducts().ToList(); döndürmektir.

Çoğu eylemin belirli bir dönüş türü vardır. Eylem yürütme sırasında beklenmeyen koşullar oluşabilir ve bu durumda belirli bir tür geri döndürülmez. Örneğin, bir eylemin giriş parametresi model doğrulamasında başarısız olabilir. Böyle bir durumda, belirli bir tür yerine uygun ActionResult türü döndürmek yaygın bir durum olur.

Zaman uyumlu eylem

İki olası dönüş türünün bulunduğu zaman uyumlu bir eylem düşünün:

[HttpGet("{id}")]
[ProducesResponseType(StatusCodes.Status200OK)]
[ProducesResponseType(StatusCodes.Status404NotFound)]
public ActionResult<Product> GetById_ActionResultOfT(int id)
{
    var product = _productContext.Products.Find(id);
    return product == null ? NotFound() : product;
}

Önceki eylemde:

• Ürün veritabanında mevcut olmadığında 404 durum kodu döndürülür.
• Ürün mevcut olduğunda ilgili Product nesneyle birlikte 200 durum kodu döndürülür.

Zaman uyumsuz eylem

İki olası dönüş türünün bulunduğu asenkron bir işlem düşünün:

[HttpPost()]
[Consumes(MediaTypeNames.Application.Json)]
[ProducesResponseType(StatusCodes.Status201Created)]
[ProducesResponseType(StatusCodes.Status400BadRequest)]
public async Task<ActionResult<Product>> CreateAsync_ActionResultOfT(Product product)
{
    if (product.Description.Contains("XYZ Widget"))
    {
        return BadRequest();
    }

    _productContext.Products.Add(product);
    await _productContext.SaveChangesAsync();

    return CreatedAtAction(nameof(GetById_ActionResultOfT), new { id = product.Id }, product);
}

Önceki eylemde:

• Aşağıdaki durumlarda ASP.NET Core çalışma zamanı tarafından 400 durum kodu (BadRequest) döndürülür:
  • [ApiController] Özniteliği uygulandı ve model doğrulaması başarısız oluyor.
  • Ürün açıklaması "XYZ Widget" içerir.
• CreatedAtAction yöntemi tarafından bir ürün oluşturulduğunda 201 durum kodu oluşturulur. Bu kod yolunda, Product nesnesi yanıt gövdesinde sağlanmaktadır. Location Yeni oluşturulan ürünün URL'sini içeren bir yanıt üst bilgisi sağlanır.

HttpResults türü

MVC'ye özgü yerleşik sonuç türlerine (IActionResult ve ActionResult<T>) ek olarak, ASP.NET Core hem En Az API'lerde hem de Web API'sinde kullanılabilen HttpResults türlerini içerir.

MVC'ye özgü sonuç türlerinden farklı olarak HttpResults:

• IResult.ExecuteAsync çağrısı ile işlenen sonuçların bir uygulamasıdır.

• Yapılandırılan Biçimlendiriciler'i kullanmaz. Yapılandırılan biçimlendiricilerden yararlanılmaması şu anlama gelir:

  • gibi Content negotiation bazı özellikler kullanılamaz.
  • Üretilen Content-Type, HttpResults uygulaması tarafından belirlenir.

, HttpResults Minimum API'ler ve Web API'leri arasında kod paylaşırken yararlı olabilir.

IResult türü

Microsoft.AspNetCore.Http.HttpResults namespace'i, IResult arabirimini uygulayan sınıfları içerir. Arabirimi, IResult HTTP uç noktasının sonucunu temsil eden bir sözleşme tanımlar. Statik Results sınıfı, farklı yanıt türlerini temsil eden farklı IResult nesneler oluşturmak için kullanılır.

Yerleşik sonuçlar tablosu, ortak sonuç yardımcılarını gösterir.

Aşağıdaki kodu inceleyin:

[HttpGet("{id}")]
[ProducesResponseType<Product>(StatusCodes.Status200OK)]
[ProducesResponseType(StatusCodes.Status404NotFound)]
public IResult GetById(int id)
{
    var product = _productContext.Products.Find(id);
    return product == null ? Results.NotFound() : Results.Ok(product);
}

Önceki eylemde:

• Ürün veritabanında mevcut olmadığında 404 durum kodu döndürülür.
• Ürün mevcut olduğunda ilgili Product nesneyle birlikte results.Ok<T>() tarafından oluşturulan 200 durum kodu döndürülür.

Aşağıdaki kodu inceleyin:

[HttpPost]
[Consumes(MediaTypeNames.Application.Json)]
[ProducesResponseType<Product>(StatusCodes.Status201Created)]
[ProducesResponseType(StatusCodes.Status400BadRequest)]
public async Task<IResult> CreateAsync(Product product)
{
    if (product.Description.Contains("XYZ Widget"))
    {
        return Results.BadRequest();
    }

    _productContext.Products.Add(product);
    await _productContext.SaveChangesAsync();

    var location = Url.Action(nameof(CreateAsync), new { id = product.Id }) ?? $"/{product.Id}";
    return Results.Created(location, product);
}

Önceki eylemde:

• Aşağıdaki durumlarda 400 durum kodu döndürülür:
  • [ApiController] Özniteliği uygulandı ve model doğrulaması başarısız oluyor.
  • Ürün açıklaması "XYZ Widget" içerir.
• Results.Created yöntemi tarafından bir ürün oluşturulduğunda 201 durum kodu oluşturulur. Bu kod yolunda, Product nesnesi yanıt gövdesinde sağlanmaktadır. Location Yeni oluşturulan ürünün URL'sini içeren bir yanıt üst bilgisi sağlanır.

Sonuçlar<TResult1, TResultN> türü

Statik TypedResults sınıfı, dönüş türü olarak kullanılmasına IResult izin veren somut IResult uygulamayı döndürür. Somut IResult uygulamanın kullanımı IResult türüne göre aşağıdaki avantajı sunar:

• [ProducesResponseType] uygulaması uç nokta meta verilerine otomatik olarak katkıda bulunduğundan, tüm HttpResult öznitelikler dışlanabilir.

Birden fazla IResult dönüş türü gerektiğinde, Results<TResult1, TResultN> döndürmek, IResult döndürmeye tercih edilir. Uç nokta meta verilerini otomatik olarak koruduğu için genel birleşim türlerini döndürmek Results<TResult1, TResultN> tercih edilir.

Birleşim Results<TResult1, TResultN> türleri, derleyicinin genel bağımsız değişkenlerde belirtilen türleri birleşim türünün bir örneğine otomatik olarak dönüştürebilmesi için örtük dönüştürme işleçlerini uygular. Bu, bir yol işleyicisinin aslında yalnızca bildirdiği sonuçları döndürdüğüne ilişkin derleme zamanı denetimi sağlamanın ek avantajına sahiptir. Genel bağımsız değişkenlerden biri olarak bildirilmemiş bir türü döndürmeye çalışmak derleme hatasıyla sonuçlanır.

Aşağıdaki kodu inceleyin:

[HttpGet("{id}")]
public Results<NotFound, Ok<Product>> GetById(int id)
{
    var product = _productContext.Products.Find(id);
    return product == null ? TypedResults.NotFound() : TypedResults.Ok(product);
}

Önceki eylemde:

• Ürün veritabanında mevcut olmadığında 404 durum kodu döndürülür.
• Ürün mevcut olduğunda ilgili Product nesneyle birlikte 200 durum kodu döndürülür ve TypedResults.Ok<T> tarafından oluşturulur.

[HttpPost]
public async Task<Results<BadRequest, Created<Product>>> CreateAsync(Product product)
{
    if (product.Description.Contains("XYZ Widget"))
    {
        return TypedResults.BadRequest();
    }

    _productContext.Products.Add(product);
    await _productContext.SaveChangesAsync();

    var location = Url.Action(nameof(CreateAsync), new { id = product.Id }) ?? $"/{product.Id}";
    return TypedResults.Created(location, product);
}

Önceki eylemde:

• Aşağıdaki durumlarda 400 durum kodu döndürülür:
  • [ApiController] Özniteliği uygulandı ve model doğrulaması başarısız oldu.
  • Ürün açıklaması "XYZ Widget" içerir.
• TypedResults.Created yöntemi tarafından bir ürün oluşturulduğunda 201 durum kodu oluşturulur. Bu kod yolunda, Product nesnesi yanıt gövdesinde sağlanmaktadır. Location Yeni oluşturulan ürünün URL'sini içeren bir yanıt üst bilgisi sağlanır.

Ek kaynaklar

• ASP.NET Core MVC'de denetleyicileriyle istekleri işleme
• ASP.NET Core MVC'de model doğrulama
• ASP.NET Core web API belgeleri Swagger / OpenAPI ile