ASP.NET Core ile web API’leri oluşturma

Makale
08/17/2021
Okumak için 8 dakika

ASP.NET Core, web API'leri olarak da bilinen RESTful hizmetleri oluşturulmasını C# kullanarak desteklemektedir. Web API'si istekleri işlemek için denetleyiciler kullanır. Bir web API'sinde bulunan denetleyiciler, 'den türeyen ControllerBase sınıflardır. Bu makalede, web API'si isteklerinin işlenmesi için denetleyicilerin nasıl kullanımı açıklanmıştır.

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

ControllerBase sınıfı

Web API'si, 'den türeten bir veya daha fazla denetleyici sınıflarından ControllerBase oluşur. Web API'si proje şablonu bir başlangıç denetleyicisi sağlar:

[ApiController]
[Route("[controller]")]
public class WeatherForecastController : ControllerBase

sınıfından türeterek bir web API denetleyicisi Controller oluşturma. Controller , görünümlerden türettir ve görünümler için destek ekler, bu nedenle ControllerBase web API'si isteklerini değil web sayfalarını işlemeye göredir. Bu kuralın bir istisnası vardır: Hem görünümler hem de web API'leri için aynı denetleyiciyi kullanmayı planlıyorsanız, 'den Controller türetin.

sınıfı, ControllerBase HTTP isteklerini işlemede yararlı olan birçok özellik ve yöntem sağlar. Örneğin, bir ControllerBase.CreatedAtAction 201 durum kodu döndürür:

[HttpPost]
[ProducesResponseType(StatusCodes.Status201Created)]
[ProducesResponseType(StatusCodes.Status400BadRequest)]
public ActionResult<Pet> Create(Pet pet)
{
    pet.Id = _petsInMemoryStore.Any() ? 
             _petsInMemoryStore.Max(p => p.Id) + 1 : 1;
    _petsInMemoryStore.Add(pet);

    return CreatedAtAction(nameof(GetById), new { id = pet.Id }, pet);
}

Aşağıda, sağlayan yöntemlere birkaç örnek daha ControllerBase verilmiştir.

Yöntem	Notlar
BadRequest	400 durum kodu döndürür.
NotFound	404 durum kodunu döndürür.
PhysicalFile	Bir dosya döndürür.
TryUpdateModelAsync	Model bağlamayı çağırır.
TryValidateModel	Model doğrulamasını çağırır.

Kullanılabilir tüm yöntemlerin ve özelliklerin listesi için bkz. ControllerBase .

Öznitelikler

Ad Microsoft.AspNetCore.Mvc alanı, web API'si denetleyicilerinin ve eylem yöntemlerinin davranışını yapılandırmak için kullanılan öznitelikler sağlar. Aşağıdaki örnekte, desteklenen HTTP eylem fiilini ve döndürül bilinen TÜM HTTP durum kodlarını belirtmek için öznitelikleri kullanır:

[HttpPost]
[ProducesResponseType(StatusCodes.Status201Created)]
[ProducesResponseType(StatusCodes.Status400BadRequest)]
public ActionResult<Pet> Create(Pet pet)
{
    pet.Id = _petsInMemoryStore.Any() ? 
             _petsInMemoryStore.Max(p => p.Id) + 1 : 1;
    _petsInMemoryStore.Add(pet);

    return CreatedAtAction(nameof(GetById), new { id = pet.Id }, pet);
}

Aşağıda, kullanılabilir özniteliklere birkaç örnek daha verilmiştir.

Öznitelik	Notlar
`[Route]`	Bir denetleyici veya eylem için URL desenini belirtir.
`[Bind]`	Model bağlaması için eklenecek ön eki ve özellikleri belirtir.
`[HttpGet]`	HTTP GET eylem fiilini destekleyen bir eylemi tanımlar.
`[Consumes]`	Bir eylemin kabul eden veri türlerini belirtir.
`[Produces]`	Bir eylemin döndür olduğu veri türlerini belirtir.

Kullanılabilir öznitelikleri içeren bir liste için bkz. ad Microsoft.AspNetCore.Mvc alanı.

ApiController özniteliği

Özniteliği, [ApiController] aşağıdaki api'ye özgü davranışları etkinleştirmek için bir denetleyici sınıfına uygulanabilir:

Öznitelik yönlendirme gereksinimi
Otomatik HTTP 400 yanıtları
Bağlama kaynak parametresi çıkarı
Çok parçalı/form-veri isteği çıkarı
Hata durum kodları için sorun ayrıntıları

Hata durum kodları için sorun ayrıntıları özelliği, 2.2 veya sonraki bir uyumluluk sürümü gerektirir. Diğer özellikler için 2.1 veya sonraki bir uyumluluk sürümü gerekir.

Öznitelik yönlendirme gereksinimi
Otomatik HTTP 400 yanıtları
Bağlama kaynak parametresi çıkarı
Çok parçalı/form-veri isteği çıkarı

Bu özellikler için 2.1 veya sonraki bir uyumluluk sürümü gerekir.

Belirli denetleyicilerde öznitelik

Öznitelik, [ApiController] proje şablonundan aşağıdaki örnekte olduğu gibi belirli denetleyicilere uygulanabilir:

[ApiController]
[Route("[controller]")]
public class WeatherForecastController : ControllerBase

Birden çok denetleyicide öznitelik

özniteliğini birden fazla denetleyicide kullanma yaklaşımlarından biri, özniteliğiyle açıklama ek açıklamalı özel bir temel denetleyici sınıfı [ApiController] oluşturmaktır. Aşağıdaki örnek, özel bir temel sınıf ve bundan türeten bir denetleyiciyi gösterir:

[ApiController]
public class MyControllerBase : ControllerBase
{
}

[Produces(MediaTypeNames.Application.Json)]
[Route("[controller]")]
public class PetsController : MyControllerBase

Derlemede öznitelik

Uyumluluk sürümü 2.2 veya sonraki bir sürüme ayarlanırsa, öznitelik bir [ApiController] derlemeye uygulanabilir. Bu şekilde ek açıklama, derlemedeki tüm denetleyicilere web API'si davranışını uygular. Tek tek denetleyicileri geri almak için hiçbir yol yoktur. Derleme düzeyi özniteliğini sınıfını çevreleyen ad alanı bildirimine Startup uygulama:

[assembly: ApiController]
namespace WebApiSample
{
    public class Startup
    {
        ...
    }
}

Öznitelik yönlendirme gereksinimi

özniteliği, [ApiController] öznitelik yönlendirmeyi bir gereksinim yapar. Örnek:

[ApiController]
[Route("[controller]")]
public class WeatherForecastController : ControllerBase

Eylemler, , veya ile tanımlanan geleneksel yollar UseEndpoints aracılığıyla UseMvc UseMvcWithDefaultRoute Startup.Configure erişilemez.

Otomatik HTTP 400 yanıtları

özniteliği, [ApiController] model doğrulama hatalarını otomatik olarak bir HTTP 400 yanıtı tetikler. Sonuç olarak, aşağıdaki kod bir eylem yönteminde gereksizdir:

if (!ModelState.IsValid)
{
    return BadRequest(ModelState);
}

ASP.NET Core MVC, ModelStateInvalidFilter önceki denetimi yapmak için eylem filtresini kullanır.

Varsayılan BadRequest yanıtı

Uyumluluk sürümü 2.1 ile, HTTP 400 yanıtı için varsayılan yanıt türü SerializableError olur. Aşağıdaki istek gövdesi, serileştirilmiş türün bir örneğidir:

{
  "": [
    "A non-empty request body is required."
  ]
}

2.2 veya sonraki bir uyumluluk sürümüyle, HTTP 400 yanıtı için varsayılan yanıt türü ValidationProblemDetails olur. Aşağıdaki istek gövdesi, serileştirilmiş türün bir örneğidir:

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "traceId": "|7fb5e16a-4c8f23bbfc974667.",
  "errors": {
    "": [
      "A non-empty request body is required."
    ]
  }
}

ValidationProblemDetailsTür:

Web API yanıtlarında hataları belirtmek için makine tarafından okunabilir bir biçim sağlar.
RFC 7807 belirtimleriyle uyumlu olur.

Otomatik ve özel yanıtları tutarlı hale etmek için yerine ValidationProblem yöntemini BadRequest çağırarak. ValidationProblem otomatik ValidationProblemDetails yanıtın yanı sıra bir nesnesi döndürür.

Otomatik 400 yanıtları günlüğe kaydedilir

Bkz. Model doğrulama hatalarında otomatik 400 yanıtları günlüğe AspNetCore.Docs#12157).

Otomatik 400 yanıtını devre dışı bırakma

Otomatik 400 davranışını devre dışı bırakmak için özelliğini SuppressModelStateInvalidFilter olarak true ayarlayın. aşağıdaki vurgulanmış kodu 'a Startup.ConfigureServices ekleyin:

services.AddControllers()
    .ConfigureApiBehaviorOptions(options =>
    {
        options.SuppressConsumesConstraintForFormFileParameters = true;
        options.SuppressInferBindingSourcesForParameters = true;
        options.SuppressModelStateInvalidFilter = true;
        options.SuppressMapClientErrors = true;
        options.ClientErrorMapping[StatusCodes.Status404NotFound].Link =
            "https://httpstatuses.com/404";
    });

Bağlama kaynak parametresi çıkarı

Bağlama kaynak özniteliği, eylem parametresinin değerinin bulunduğu konumu tanımlar. Aşağıdaki bağlama kaynağı öznitelikleri vardır:

Öznitelik	Bağlama kaynağı
`[FromBody]`	İstek gövdesi
`[FromForm]`	İstek gövdesinde verileri oluşturma
`[FromHeader]`	İstek üst bilgisi
`[FromQuery]`	Sorgu dizesi parametresi isteğinde
`[FromRoute]`	Geçerli istekten verileri yönlendirme
`[FromServices]`	Eylem parametresi olarak ekleme yapılan istek hizmeti

Uyarı

Değerlerin [FromRoute] içerebiliyor olabileceği zaman (başka bir %2f ifade) / kullanmayın. %2f için kaçışsız / olmayacak. Değeri [FromQuery] içeriyorsa %2f kullanın.

[ApiController]özniteliği veya gibi bağlama kaynak öznitelikleri olmadan [FromQuery] , ASP.NET Core çalışma zamanı karmaşık nesne modeli cildi kullanmaya çalışır. Karmaşık nesne modeli Ciltçi, verileri değer sağlayıcılarından tanımlı bir düzende çeker.

Aşağıdaki örnekte [FromQuery] öznitelik, discontinuedOnly istek URL 'sinin sorgu dizesinde parametre değerinin sağlandığını gösterir:

[HttpGet]
public ActionResult<List<Product>> Get(
    [FromQuery] bool discontinuedOnly = false)
{
    List<Product> products = null;

    if (discontinuedOnly)
    {
        products = _productsInMemoryStore.Where(p => p.IsDiscontinued).ToList();
    }
    else
    {
        products = _productsInMemoryStore;
    }

    return products;
}

[ApiController]Öznitelik, eylem parametrelerinin varsayılan veri kaynakları için çıkarım kurallarını uygular. Bu kurallar, eylem parametrelerine öznitelikleri uygulayarak bağlama kaynaklarını el ile tanımlamak zorunda kalmadan sizi kaydeder. Bağlama kaynak çıkarımı kuralları aşağıdaki gibi davranır:

[FromBody] karmaşık tür parametreleri için algılanır. Çıkarım kuralı için bir özel durum, [FromBody] ve gibi özel bir anlamı olan karmaşık, yerleşik bir türdür IFormCollection CancellationToken . Bağlama kaynak çıkarımı kodu bu özel türleri yoksayar.
[FromForm] , ve türündeki eylem parametreleri için algılanır IFormFile IFormFileCollection . Bu, herhangi bir basit veya Kullanıcı tanımlı tür için çıkarsanamıyor.
[FromRoute] yol şablonundaki bir parametreyle eşleşen herhangi bir eylem parametresi adı için algılanır. Birden fazla yol bir eylem parametresiyle eşleştiğinde, herhangi bir rota değeri kabul edilir [FromRoute] .
[FromQuery] diğer eylem parametreleri için algılanır.

FromBody çıkarım notları

[FromBody] , veya gibi basit türler için çıkarsanamıyor string int . Bu nedenle, bu [FromBody] işlev gerektiğinde basit türler için özniteliği kullanılmalıdır.

Bir eylem, istek gövdesinden birden fazla parametre bağlamışsa, bir özel durum oluşturulur. Örneğin, aşağıdaki eylem yöntemi imzalarının tümü bir özel duruma neden olur:

[FromBody] karmaşık türler olduklarından her ikisi de üzerinde algılanır.
```
[HttpPost]
public IActionResult Action1(Product product, Order order)
```

[FromBody] karmaşık bir tür olduğundan, diğeri üzerinde olan özniteliği.

[HttpPost]
public IActionResult Action2(Product product, [FromBody] Order order)

[FromBody] her ikisinde de özniteliği.

[HttpPost]
public IActionResult Action3([FromBody] Product product, [FromBody] Order order)

Çıkarım kurallarını devre dışı bırak

Bağlama kaynak çıkarımını devre dışı bırakmak için, SuppressInferBindingSourcesForParameters olarak ayarlayın true . Aşağıdaki kodu içine ekleyin Startup.ConfigureServices :

services.AddControllers()
    .ConfigureApiBehaviorOptions(options =>
    {
        options.SuppressConsumesConstraintForFormFileParameters = true;
        options.SuppressInferBindingSourcesForParameters = true;
        options.SuppressModelStateInvalidFilter = true;
        options.SuppressMapClientErrors = true;
        options.ClientErrorMapping[StatusCodes.Status404NotFound].Link =
            "https://httpstatuses.com/404";
    });

Multipart/form-veri isteği çıkarımı

Özniteliği [ApiController] ile bir eylem parametresine ek açıklama eklendiğinde öznitelik bir çıkarım kuralı uygular [FromForm] . multipart/form-dataİstek içerik türü çıkarsandı.

Varsayılan davranışı devre dışı bırakmak için SuppressConsumesConstraintForFormFileParameters özelliğini true olarak ayarlayın Startup.ConfigureServices :

services.AddControllers()
    .ConfigureApiBehaviorOptions(options =>
    {
        options.SuppressConsumesConstraintForFormFileParameters = true;
        options.SuppressInferBindingSourcesForParameters = true;
        options.SuppressModelStateInvalidFilter = true;
        options.SuppressMapClientErrors = true;
        options.ClientErrorMapping[StatusCodes.Status404NotFound].Link =
            "https://httpstatuses.com/404";
    });

Hata durum kodları için sorun ayrıntıları

Uyumluluk sürümü 2,2 veya üzeri olduğunda, MVC bir hata sonucunu (durum kodu 400 veya üzeri olan bir sonuç) ile bir sonuçla dönüştürür ProblemDetails . ProblemDetailsTürü, BIR http yanıtında makine tarafından okunabilen hata ayrıntılarını sağlamak Için RFC 7807 belirtimine dayalıdır.

Bir denetleyici eyleminde aşağıdaki kodu göz önünde bulundurun:

if (pet == null)
{
    return NotFound();
}

NotFoundYöntemi, gövdesi olan BIR HTTP 404 durum kodu üretir ProblemDetails . Örnek:

{
  type: "https://tools.ietf.org/html/rfc7231#section-6.5.4",
  title: "Not Found",
  status: 404,
  traceId: "0HLHLV31KRN83:00000001"
}

ProblemDetails yanıtını devre dışı bırak

ProblemDetailsÖzelliği olarak ayarlandığında hata durumu kodlarının otomatik olarak oluşturulması devre dışı bırakılır SuppressMapClientErrors true . Aşağıdaki kodu içine ekleyin Startup.ConfigureServices :

services.AddControllers()
    .ConfigureApiBehaviorOptions(options =>
    {
        options.SuppressConsumesConstraintForFormFileParameters = true;
        options.SuppressInferBindingSourcesForParameters = true;
        options.SuppressModelStateInvalidFilter = true;
        options.SuppressMapClientErrors = true;
        options.ClientErrorMapping[StatusCodes.Status404NotFound].Link =
            "https://httpstatuses.com/404";
    });

Desteklenen istek içerik türlerini [tüketir] özniteliğiyle tanımlayın

Varsayılan olarak, bir eylem tüm kullanılabilir istek içerik türlerini destekler. Örneğin, bir uygulama hem JSON hem de XML giriş formatlarınıdestekleyecek şekilde yapılandırıldıysa, bir eylem, ve dahil olmak üzere birden çok içerik türünü destekler application/json application/xml .

[Tüketir] özniteliği, desteklenen istek içerik türlerini sınırlama eylemi sağlar. Özniteliği bir [Consumes] eylem veya denetleyiciye uygulayarak bir veya daha fazla içerik türü belirtin:

[HttpPost]
[Consumes("application/xml")]
public IActionResult CreateProduct(Product product)

Yukarıdaki kodda, CreateProduct eylem içerik türünü belirtir application/xml . Bu eyleme yönlendirilen isteklerin bir Content-Type üst bilgisi belirtmesi gerekir application/xml . Content-TypeÜst bilgisi belirtmeyen istekler, application/xml 415 desteklenmeyen medya türü yanıtı ile sonuçlanır.

[Consumes]Öznitelik Ayrıca bir eylemin bir tür kısıtlaması uygulayarak bir gelen isteğin içerik türüne göre seçimini etkilemesini sağlar. Aşağıdaki örneği inceleyin:

[ApiController]
[Route("api/[controller]")]
public class ConsumesController : ControllerBase
{
    [HttpPost]
    [Consumes("application/json")]
    public IActionResult PostJson(IEnumerable<int> values) =>
        Ok(new { Consumes = "application/json", Values = values });

    [HttpPost]
    [Consumes("application/x-www-form-urlencoded")]
    public IActionResult PostForm([FromForm] IEnumerable<int> values) =>
        Ok(new { Consumes = "application/x-www-form-urlencoded", Values = values });
}

Önceki kodda, ConsumesController URL 'ye gönderilen istekleri işleyecek şekilde yapılandırılır https://localhost:5001/api/Consumes . Denetleyicinin eylemlerinin her ikisi de PostJson PostForm aynı URL 'ye sahip post isteklerini işler. [Consumes]Öznitelik bir tür kısıtlaması uygulamadan, belirsiz eşleşme özel durumu oluşur.

[Consumes]Özniteliği her iki eyleme de uygulanır. PostJsonEylem, üst bilgisi ile gönderilen istekleri işler Content-Type application/json . PostFormEylem, üst bilgisi ile gönderilen istekleri işler Content-Type application/x-www-form-urlencoded .

Ek kaynaklar

[Route("api/[controller]")]
[ApiController]
public class ValuesController : ControllerBase

Sınıfından türeterek bir Web API denetleyicisi oluşturmayın Controller . Controller ' dan türetilir ControllerBase ve görünümler için destek ekler, bu nedenle Web API istekleri için değil Web sayfalarını işlemeye yöneliktir. Bu kural için bir özel durum var: aynı denetleyiciyi hem görünümler hem de Web API 'Leri için kullanmayı planlıyorsanız, öğesinden türetirsiniz Controller .

ControllerBaseSınıfı, http isteklerini işlemek için yararlı olan birçok özellik ve yöntem sağlar. Örneğin, ControllerBase.CreatedAtAction bir 201 durum kodu döndürür:

[HttpPost]
[ProducesResponseType(StatusCodes.Status201Created)]
[ProducesResponseType(StatusCodes.Status400BadRequest)]
public ActionResult<Pet> Create(Pet pet)
{
    pet.Id = _petsInMemoryStore.Any() ? 
             _petsInMemoryStore.Max(p => p.Id) + 1 : 1;
    _petsInMemoryStore.Add(pet);

    return CreatedAtAction(nameof(GetById), new { id = pet.Id }, pet);
}

Sağladığı yöntemlere ilişkin bazı örnekler aşağıda verilmiştir ControllerBase .

Yöntem	Notlar
BadRequest	400 durum kodunu döndürür.
NotFound	404 durum kodunu döndürür.
PhysicalFile	Bir dosya döndürür.
TryUpdateModelAsync	Model bağlamasınıçağırır.
TryValidateModel	Model doğrulamasınıçağırır.

Tüm kullanılabilir yöntemlerin ve özelliklerin listesi için bkz ControllerBase ..

Öznitelikler

Microsoft.AspNetCore.MvcAd alanı, Web API denetleyicileri ve eylem yöntemlerinin davranışını yapılandırmak için kullanılabilecek öznitelikleri sağlar. Aşağıdaki örnek, desteklenen HTTP eylem fiilini ve döndürülebilecek bilinen HTTP durum kodlarını belirtmek için özniteliklerini kullanır:

[HttpPost]
[ProducesResponseType(StatusCodes.Status201Created)]
[ProducesResponseType(StatusCodes.Status400BadRequest)]
public ActionResult<Pet> Create(Pet pet)
{
    pet.Id = _petsInMemoryStore.Any() ? 
             _petsInMemoryStore.Max(p => p.Id) + 1 : 1;
    _petsInMemoryStore.Add(pet);

    return CreatedAtAction(nameof(GetById), new { id = pet.Id }, pet);
}

Aşağıda, kullanılabilecek özniteliklerin daha fazla örneği verilmiştir.

Öznitelik	Notlar
`[Route]`	Bir denetleyicinin veya eylemin URL modelini belirtir.
`[Bind]`	Model bağlama için dahil edilecek öneki ve özellikleri belirtir.
`[HttpGet]`	HTTP GET ACTION fiilini destekleyen bir eylemi tanımlar.
`[Consumes]`	Bir eylemin kabul ettiği veri türlerini belirtir.
`[Produces]`	Bir eylemin döndürdüğü veri türlerini belirtir.

Kullanılabilir öznitelikleri içeren bir liste için, bkz Microsoft.AspNetCore.Mvc . ad alanı.

ApiController özniteliği

[ApiController]Özniteliği bir denetleyici sınıfına uygulanabilir ve bu, API 'ye özgü aşağıdaki davranışları etkinleştirmek için kullanılabilir:

Öznitelik yönlendirme gereksinimi
Otomatik HTTP 400 yanıtları
Bağlama kaynak parametresi çıkarımı
Multipart/form-veri isteği çıkarımı
Hata durum kodları için sorun ayrıntıları

Hata durum kodları özelliği Için sorun ayrıntıları , 2,2 veya üzeri bir Uyumluluk sürümü gerektirir. Diğer özellikler, 2,1 veya üzeri bir uyumluluk sürümü gerektirir.

Öznitelik yönlendirme gereksinimi
Otomatik HTTP 400 yanıtları
Bağlama kaynak parametresi çıkarımı
Multipart/form-veri isteği çıkarımı

Bu özellikler, 2,1 veya üzeri bir Uyumluluk sürümü gerektirir.

Belirli denetleyicilerde öznitelik

[ApiController]Özniteliği, proje şablonundan aşağıdaki örnekte olduğu gibi belirli denetleyicilere uygulanabilir:

[Route("api/[controller]")]
[ApiController]
public class ValuesController : ControllerBase

Birden çok denetleyicilerde öznitelik

Özniteliği birden fazla denetleyicide kullanmanın bir yaklaşımı, özniteliğiyle birlikte açıklanan özel bir temel denetleyici sınıfı oluşturmaktır [ApiController] . Aşağıdaki örnekte, özel bir temel sınıf ve ondan türetilen bir denetleyici gösterilmektedir:

[ApiController]
public class MyControllerBase : ControllerBase
{
}

[Produces(MediaTypeNames.Application.Json)]
[Route("api/[controller]")]
public class PetsController : MyControllerBase

Bir derlemedeki öznitelik

Uyumluluk sürümü 2,2 veya üzeri bir sürüme ayarlandıysa, [ApiController] öznitelik bir derlemeye uygulanabilir. Bu şekilde ek açıklama, derlemedeki tüm denetleyicilere Web API davranışını uygular. Tek tek denetleyiciler için geri alma yöntemi yoktur. Derleme düzeyi özniteliğini sınıfı çevreleyen ad alanı bildirimine uygulayın Startup :

[assembly: ApiController]
namespace WebApiSample
{
    public class Startup
    {
        ...
    }
}

Öznitelik yönlendirme gereksinimi

[ApiController]Öznitelik, öznitelik yönlendirme bir gereksinim yapar. Örnek:

[Route("api/[controller]")]
[ApiController]
public class ValuesController : ControllerBase

Eylemlere, veya içinde tanımlanan geleneksel yollar aracılığıyla UseMvc erişilemez UseMvcWithDefaultRoute Startup.Configure .

Otomatik HTTP 400 yanıtları

[ApiController]Öznitelik, model doğrulama hatalarının otomatik olarak BIR HTTP 400 yanıtı tetiklenmesine neden olur. Sonuç olarak, aşağıdaki kod bir eylem yönteminde gereksizdir:

if (!ModelState.IsValid)
{
    return BadRequest(ModelState);
}

ASP.NET Core MVC, ModelStateInvalidFilter önceki denetimi yapmak için eylem filtresini kullanır.

Varsayılan BadRequest yanıtı

Uyumluluk sürümü 2,1 ile, bir HTTP 400 yanıtı için varsayılan yanıt türü ' dir SerializableError . Aşağıdaki istek gövdesi, serileştirilmiş türün bir örneğidir:

{
  "": [
    "A non-empty request body is required."
  ]
}

2,2 veya üzeri bir uyumluluk sürümü ile, bir HTTP 400 yanıtı için varsayılan yanıt türü ' dir ValidationProblemDetails . Aşağıdaki istek gövdesi, serileştirilmiş türün bir örneğidir:

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "traceId": "|7fb5e16a-4c8f23bbfc974667.",
  "errors": {
    "": [
      "A non-empty request body is required."
    ]
  }
}

ValidationProblemDetailsTür:

Web API yanıtlarında hata belirtmek için makine tarafından okunabilen bir biçim sağlar.
RFC 7807 belirtimineuyar.

Otomatik ve özel yanıtları tutarlı hale getirmek için ValidationProblem yerine yöntemi çağırın BadRequest . ValidationProblemValidationProblemDetailsotomatik yanıtı da bir nesne ve döndürür.

Otomatik 400 yanıtlarını günlüğe kaydet

Bkz. otomatik 400 yanıtlarını model doğrulama hatalarında günlüğe kaydetme (DotNet/AspNetCore.Docs # 12157).

Otomatik 400 yanıtını devre dışı bırak

Otomatik 400 davranışını devre dışı bırakmak için SuppressModelStateInvalidFilter özelliğini olarak ayarlayın true . Aşağıdaki Vurgulanan kodu içine ekleyin Startup.ConfigureServices :

services.Configure<ApiBehaviorOptions>(options =>
{
    options.SuppressConsumesConstraintForFormFileParameters = true;
    options.SuppressInferBindingSourcesForParameters = true;
    options.SuppressModelStateInvalidFilter = true;
});

Bağlama kaynak parametresi çıkarımı

Bağlama kaynak özniteliği, bir eylem parametresi değerinin bulunduğu konumu tanımlar. Aşağıdaki bağlama kaynak öznitelikleri var:

Öznitelik	Bağlama kaynağı
`[FromBody]`	İstek gövdesi
`[FromForm]`	İstek gövdesinde form verileri
`[FromHeader]`	İstek üst bilgisi
`[FromQuery]`	İstek sorgusu dize parametresi
`[FromRoute]`	Geçerli istekten veri yönlendir
`[FromServices]`	Eylem parametresi olarak eklenen istek hizmeti

Uyarı

[FromRoute]Değerler %2f (yani) içerdiğinde kullanmayın / . %2f atlanmaz / . [FromQuery]Değer içermesi gerekiyorsa kullanın %2f .

Aşağıdaki örnekte [FromQuery] öznitelik, discontinuedOnly istek URL 'sinin sorgu dizesinde parametre değerinin sağlandığını gösterir:

[HttpGet]
public ActionResult<List<Product>> Get(
    [FromQuery] bool discontinuedOnly = false)
{
    List<Product> products = null;

    if (discontinuedOnly)
    {
        products = _productsInMemoryStore.Where(p => p.IsDiscontinued).ToList();
    }
    else
    {
        products = _productsInMemoryStore;
    }

    return products;
}

[FromBody] karmaşık tür parametreleri için algılanır. Çıkarım kuralı için bir özel durum, [FromBody] ve gibi özel bir anlamı olan karmaşık, yerleşik bir türdür IFormCollection CancellationToken . Bağlama kaynak çıkarımı kodu bu özel türleri yoksayar.
[FromForm] , ve türündeki eylem parametreleri için algılanır IFormFile IFormFileCollection . Bu, herhangi bir basit veya Kullanıcı tanımlı tür için çıkarsanamıyor.
[FromRoute] yol şablonundaki bir parametreyle eşleşen herhangi bir eylem parametresi adı için algılanır. Birden fazla yol bir eylem parametresiyle eşleştiğinde, herhangi bir rota değeri kabul edilir [FromRoute] .
[FromQuery] diğer eylem parametreleri için algılanır.

FromBody çıkarım notları

[FromBody] , veya gibi basit türler için çıkarsanamıyor string int . Bu nedenle, bu [FromBody] işlev gerektiğinde basit türler için özniteliği kullanılmalıdır.

Bir eylem, istek gövdesinden birden fazla parametre bağlamışsa, bir özel durum oluşturulur. Örneğin, aşağıdaki eylem yöntemi imzalarının tümü bir özel duruma neden olur:

[FromBody] karmaşık türler olduklarından her ikisi de üzerinde algılanır.
```
[HttpPost]
public IActionResult Action1(Product product, Order order)
```

[FromBody] karmaşık bir tür olduğundan, diğeri üzerinde olan özniteliği.

[HttpPost]
public IActionResult Action2(Product product, [FromBody] Order order)

[FromBody] her ikisinde de özniteliği.

[HttpPost]
public IActionResult Action3([FromBody] Product product, [FromBody] Order order)

Not

ASP.NET Core 2,1 ' de, listeler ve diziler gibi koleksiyon türü parametreleri yanlış olarak algılanır [FromQuery] . [FromBody]Öznitelik, istek gövdesinden bağlanmaları durumunda bu parametreler için kullanılmalıdır. bu davranış ASP.NET Core 2,2 veya sonraki bir sürümde düzeltilir. burada, koleksiyon türü parametrelerinin varsayılan olarak gövdeden bağlanacak şekilde çıkarsandır.

Çıkarım kurallarını devre dışı bırak

Bağlama kaynak çıkarımını devre dışı bırakmak için, SuppressInferBindingSourcesForParameters olarak ayarlayın true . Aşağıdaki kodu içine ekleyin Startup.ConfigureServices :

services.Configure<ApiBehaviorOptions>(options =>
{
    options.SuppressConsumesConstraintForFormFileParameters = true;
    options.SuppressInferBindingSourcesForParameters = true;
    options.SuppressModelStateInvalidFilter = true;
});

Multipart/form-veri isteği çıkarımı

Varsayılan davranışı devre dışı bırakmak için SuppressConsumesConstraintForFormFileParameters özelliğini true olarak ayarlayın Startup.ConfigureServices :

services.Configure<ApiBehaviorOptions>(options =>
{
    options.SuppressConsumesConstraintForFormFileParameters = true;
    options.SuppressInferBindingSourcesForParameters = true;
    options.SuppressModelStateInvalidFilter = true;
});

Hata durum kodları için sorun ayrıntıları

Bir denetleyici eyleminde aşağıdaki kodu göz önünde bulundurun:

if (pet == null)
{
    return NotFound();
}

NotFoundYöntemi, gövdesi olan BIR HTTP 404 durum kodu üretir ProblemDetails . Örnek:

{
  type: "https://tools.ietf.org/html/rfc7231#section-6.5.4",
  title: "Not Found",
  status: 404,
  traceId: "0HLHLV31KRN83:00000001"
}

ProblemDetails yanıtını devre dışı bırak

Desteklenen istek içerik türlerini [tüketir] özniteliğiyle tanımlayın

[HttpPost]
[Consumes("application/xml")]
public IActionResult CreateProduct(Product product)

[Consumes]Öznitelik Ayrıca bir eylemin bir tür kısıtlaması uygulayarak bir gelen isteğin içerik türüne göre seçimini etkilemesini sağlar. Aşağıdaki örneği inceleyin:

[ApiController]
[Route("api/[controller]")]
public class ConsumesController : ControllerBase
{
    [HttpPost]
    [Consumes("application/json")]
    public IActionResult PostJson(IEnumerable<int> values) =>
        Ok(new { Consumes = "application/json", Values = values });

    [HttpPost]
    [Consumes("application/x-www-form-urlencoded")]
    public IActionResult PostForm([FromForm] IEnumerable<int> values) =>
        Ok(new { Consumes = "application/x-www-form-urlencoded", Values = values });
}

ASP.NET Core ile web API’leri oluşturma

Lütfen deneyiminizi değerlendirin

ControllerBase sınıfı

Öznitelikler

ApiController özniteliği

Belirli denetleyicilerde öznitelik

Birden çok denetleyicide öznitelik

Derlemede öznitelik

Öznitelik yönlendirme gereksinimi

Otomatik HTTP 400 yanıtları

Varsayılan BadRequest yanıtı

Otomatik 400 yanıtları günlüğe kaydedilir

Otomatik 400 yanıtını devre dışı bırakma

Bağlama kaynak parametresi çıkarı

FromBody çıkarım notları

Çıkarım kurallarını devre dışı bırak

Multipart/form-veri isteği çıkarımı

Hata durum kodları için sorun ayrıntıları

ProblemDetails yanıtını devre dışı bırak

Desteklenen istek içerik türlerini [tüketir] özniteliğiyle tanımlayın

Ek kaynaklar

Öznitelikler

ApiController özniteliği

Belirli denetleyicilerde öznitelik

Birden çok denetleyicilerde öznitelik

Bir derlemedeki öznitelik

Öznitelik yönlendirme gereksinimi

Otomatik HTTP 400 yanıtları

Varsayılan BadRequest yanıtı

Otomatik 400 yanıtlarını günlüğe kaydet

Otomatik 400 yanıtını devre dışı bırak

Bağlama kaynak parametresi çıkarımı

FromBody çıkarım notları

Çıkarım kurallarını devre dışı bırak

Multipart/form-veri isteği çıkarımı

Hata durum kodları için sorun ayrıntıları

ProblemDetails yanıtını devre dışı bırak

Desteklenen istek içerik türlerini [tüketir] özniteliğiyle tanımlayın

Ek kaynaklar