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

  • Makale

ASP.NET Core, denetleyicileri veya minimum API'leri kullanarak web API'leri oluşturmayı destekler. Bir web API'sindeki denetleyiciler, ControllerBase öğesinden türetilen sınıflardır. Denetleyiciler isteğe göre etkinleştirilir ve atılır.

Bu makalede, web API'si isteklerini işlemek için denetleyicilerin nasıl kullanılacağı gösterilmektedir. Denetleyiciler olmadan web API'leri oluşturma hakkında bilgi için bkz . Öğretici: ASP.NET Core ile minimum API oluşturma.

ControllerBase sınıfı

Denetleyici tabanlı bir web API'si, ControllerBase öğesinden türetilen bir veya daha fazla denetleyici sınıfından oluşur. Web API proje şablonu bir başlangıç denetleyicisi sağlar:

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

Web API denetleyicileri tipik olarak Controller öğesi yerine ControllerBase öğesinden türetilmelidir. ControllerBase öğesinden Controller türetilir ve görünümler için destek ekler, bu nedenle web API'si isteklerini değil web sayfalarını işlemeye yöneliktir. Aynı denetleyicinin görünümleri ve web API'lerini desteklemesi gerekiyorsa, Controller öğesinden türetilir.

ControllerBase sınıfı, HTTP isteklerini işlemek için yararlı olan birçok özellik ve yöntem sağlar. Örneğin, 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);
}

Aşağıdaki tabloda ControllerBase içindeki yöntemlerin örnekleri yer alır.

Metot 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ğlamayı çağırır.
TryValidateModel Model doğrulamayı çağırır.

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

Özellikler

Microsoft.AspNetCore.Mvc ad alanı, web API denetleyicilerinin ve eylem yöntemlerinin davranışını yapılandırmak için kullanılabilecek öznitelikler sağlar. Aşağıdaki örnek, desteklenen HTTP eylem fiilini ve döndürülebilecek bilinen 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 özniteliklerin bazı örnekleri verilmiştir.

Öznitelik Notlar
[Route] Bir denetleyici veya eylem için URL deseni 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 ettiği veri türlerini belirtir.
[Produces] Bir eylemin kabul döndürdüğü veri türlerini belirtir.

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

ApiController özniteliği

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

Belirli denetleyicilerdeki öznitelik

[ApiController] özniteliği, 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, [ApiController] özniteliğiyle ek açıklama ekli özel bir temel denetleyici sınıfı oluşturmaktır. Aşağıdaki örnekte, özel bir temel sınıf ve bundan türetilen bir denetleyici gösterilmektedir:

[ApiController]
public class MyControllerBase : ControllerBase
{
}

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

Bir derlemedeki öznitelik

[ApiController] özniteliği bir derlemeye uygulanabilir. [ApiController] özniteliği bir derlemeye uygulandığında, derlemedeki tüm denetleyicilerde [ApiController] özniteliği uygulanır. Tek tek denetleyicileri geri çevirmenin hiçbir yolu yoktur. Program.cs dosyasına derleme düzeyi özniteliğini uygulayın:

using Microsoft.AspNetCore.Mvc;
[assembly: ApiController]

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers();

var app = builder.Build();

app.UseHttpsRedirection();

app.UseAuthorization();

app.MapControllers();

app.Run();

Öznitelik yönlendirme gereksinimi

[ApiController] özniteliği, öznitelik yönlendirmeyi bir gereksinim haline getirir. Örneğin:

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

Eylemlere UseEndpoints, UseMvc veya UseMvcWithDefaultRoute tarafından tanımlanan geleneksel yollar aracılığıyla erişilemez.

Otomatik HTTP 400 yanıtları

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

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

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

Varsayılan BadRequest yanıtı

HTTP 400 yanıtı için varsayılan yanıt türü ValidationProblemDetails şeklindedir. Aşağıdaki yanıt gövdesi, seri hale getirilmiş 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."
    ]
  }
}

ValidationProblemDetails türü:

  • Web API’si yanıtlarındaki hataları belirtmek için makine tarafından okunabilir bir biçim sağlar.
  • RFC 7807 belirtimi ile uyumludur.

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

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

Otomatik 400 yanıtlarını günlüğe kaydetmek için özel işleme gerçekleştirmek için InvalidModelStateResponseFactory temsilci özelliğini ayarlayın. Varsayılan olarak, ValidationProblemDetails öğesinin bir örneğini oluşturmak için InvalidModelStateResponseFactory, ProblemDetailsFactory kullanır.

Aşağıdaki örnek, otomatik 400 yanıtıyla ilgili bilgileri günlüğe kaydetmek için bir ILogger<TCategoryName> örneğinin nasıl alınacağını gösterir:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers()
    .ConfigureApiBehaviorOptions(options =>
    {
      // To preserve the default behavior, capture the original delegate to call later.
        var builtInFactory = options.InvalidModelStateResponseFactory;

        options.InvalidModelStateResponseFactory = context =>
        {
            var logger = context.HttpContext.RequestServices
                                .GetRequiredService<ILogger<Program>>();

            // Perform logging here.
            // ...

            // Invoke the default behavior, which produces a ValidationProblemDetails
            // response.
            // To produce a custom response, return a different implementation of 
            // IActionResult instead.
            return builtInFactory(context);
        };
    });

var app = builder.Build();

app.UseHttpsRedirection();

app.UseAuthorization();

app.MapControllers();

app.Run();

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

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

using Microsoft.AspNetCore.Mvc;

var builder = WebApplication.CreateBuilder(args);

builder.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";
    });

var app = builder.Build();

app.UseHttpsRedirection();

app.UseAuthorization();

app.MapControllers();

app.Run();

Kaynak parametre çıkarımı bağlama

Bir bağlama kaynağı özniteliği, bir eylem parametresinin değerinin bulunduğu konumu tanımlar. Aşağıdaki bağlama kaynağı öznitelikleri mevcuttur:

Öznitelik Bağlama kaynağı
[FromBody] Request body
[FromForm] İstek gövdesindeki form verileri
[FromHeader] İstek üst bilgisi
[FromQuery] Sorgu dizesi parametresi isteme
[FromRoute] Geçerli istekten verileri yönlendirme
[FromServices] Bir eylem parametresi olarak eklenen istek hizmeti
[AsParameters] Yöntem parametreleri

Uyarı

Değerlerin %2f (yani /) içerebileceği durumlarda [FromRoute] kullanmayın. %2f, / öğesine ayarlanmamış olmayacaktır. %2f değerini içermesi gerekiyorsa [FromQuery] kullanın.

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

Aşağıdaki örnekte [FromQuery] özniteliği, discontinuedOnly parametre değerinin istek URL'sinin sorgu dizesinde 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] özniteliği, eylem parametrelerinin varsayılan veri kaynakları için çıkarım kuralları uygular. Bu kurallar, eylem parametrelerine öznitelikler uygulayarak bağlama kaynağını el ile tanımlamak zorunda olmamanızı engeller. Bağlama kaynağı çıkarım kuralları aşağıdaki gibi davranır:

  • [FromServices], DI Kapsayıcısında kayıtlı karmaşık tür parametreleri için çıkarılır.
  • [FromBody], DI Kapsayıcısında kayıtlı olmayan karmaşık tür parametreleri için çıkarılır. [FromBody] çıkarım kuralının özel bir istisnası, IFormCollection ve CancellationToken gibi özel bir anlamı olan karmaşık ve yerleşik türdür. Bağlama kaynağı çıkarım kodu bu özel türleri yok sayar.
  • IFormFile ve IFormFileCollection türündeki eylem parametreleri için [FromForm] çıkarılır. Basit veya kullanıcı tanımlı türler için çıkarılmaz.
  • [FromRoute] yol şablonundaki bir parametreyle eşleşen herhangi bir eylem parametresi adı için çıkarılır. Bir eylem parametresiyle birden fazla yol eşleştiğinde, herhangi bir yol değeri [FromRoute] olarak kabul edilir.
  • [FromQuery], diğer eylem parametreleri için çıkarılır.

FromBody çıkarım notları

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

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

  • [FromBody] karmaşık türler olduğundan her ikisinde de çıkarılır.

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

  • [FromBody] özniteliği, karmaşık bir tür olduğundan diğerinde çıkarılır.

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

  • [FromBody] özniteliği her ikisinde.

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

FromServices çıkarım notları

Parametre bağlama, tür hizmet olarak yapılandırıldığında bağımlılık ekleme yoluyla parametreleri bağlar. Bu, özniteliğin bir parametreye açıkça uygulanması [FromServices] gerekmediği anlamına gelir. Aşağıdaki kodda, her iki eylem de saati döndürür:

[Route("[controller]")]
[ApiController]
public class MyController : ControllerBase
{
    public ActionResult GetWithAttribute([FromServices] IDateTime dateTime) 
                                                        => Ok(dateTime.Now);

    [Route("noAttribute")]
    public ActionResult Get(IDateTime dateTime) => Ok(dateTime.Now);
}

Nadir durumlarda, otomatik DI, BIR API denetleyicisinin eylem yöntemlerinde de kabul edilen DI türüne sahip uygulamaları bozabilir. DI'de ve API denetleyicisi eyleminde bağımsız değişken olarak bir türe sahip olmak yaygın değildir.

Tek bir eylem parametresinin [FromServices] çıkarımını devre dışı bırakmak için, istenen bağlama kaynağı özniteliğini parametresine uygulayın. Örneğin, [FromBody] özniteliğini isteğin gövdesinden bağlanması gereken bir eylem parametresine uygulayın.

Çıkarımı genel olarak devre dışı bırakmak [FromServices] için DisableImplicitFromServicesParameters değerini olarak trueayarlayın:

using Microsoft.AspNetCore.Mvc;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers();
builder.Services.AddSingleton<IDateTime, SystemDateTime>();

builder.Services.Configure<ApiBehaviorOptions>(options =>
{
    options.DisableImplicitFromServicesParameters = true;
});

var app = builder.Build();

app.MapControllers();

app.Run();

Api denetleyicisi eylemindeki bir bağımsız değişkenin DI'den mi yoksa diğer kaynaklardan mı geldiğini belirlemek için ile uygulama başlangıcında IServiceProviderIsService türler denetleniyor.

API Denetleyicisi eylem parametrelerinin bağlama kaynağını çıkarsama mekanizması aşağıdaki kuralları kullanır:

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

Bağlama kaynağı çıkarımı devre dışı bırakmak için SuppressInferBindingSourcesForParameters öğesini true olarak ayarlayın:

using Microsoft.AspNetCore.Mvc;

var builder = WebApplication.CreateBuilder(args);

builder.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";
        options.DisableImplicitFromServicesParameters = true;
    });

var app = builder.Build();

app.UseHttpsRedirection();

app.UseAuthorization();

app.MapControllers();

app.Run();

Çok parçalı/form-veri isteği çıkarımı

[ApiController] özniteliği, IFormFile ve IFormFileCollection türünde eylem parametreleri için bir çıkarım kuralı uygular. multipart/form-data isteği içerik türü bu türler için çıkarılır.

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

using Microsoft.AspNetCore.Mvc;

var builder = WebApplication.CreateBuilder(args);

builder.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";
    });

var app = builder.Build();

app.UseHttpsRedirection();

app.UseAuthorization();

app.MapControllers();

app.Run();

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

MVC, hata sonucunu (durum kodu 400 veya üzeri olan bir sonuç) ProblemDetails ile bir sonuca dönüştürür. ProblemDetails türü, bir HTTP yanıtında makine tarafından okunabilir hata ayrıntıları sağlamaya yönelik RFC 7807 belirtimini temel alır.

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

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

NotFound yöntemi, ProblemDetails gövdeli bir HTTP 404 durum kodu üretir. Örneğin:

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

ProblemDetails yanıtlarını devre dışı bırakma

SuppressMapClientErrors özelliği true olarak ayarlandığında hata durum kodları için otomatik bir ProblemDetails oluşturma devre dışı bırakılır. Şu kodu ekleyin:

using Microsoft.AspNetCore.Mvc;

var builder = WebApplication.CreateBuilder(args);

builder.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";
    });

var app = builder.Build();

app.UseHttpsRedirection();

app.UseAuthorization();

app.MapControllers();

app.Run();

Desteklenen istek içerik türlerini [Consumes] özniteliğiyle tanımlama

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ş biçimlendiricilerini destekleyecek şekilde yapılandırılmışsa, bir eylem ve application/xmldahil olmak üzere application/json birden çok içerik türünü destekler.

[Consumes] özniteliği, desteklenen istek içerik türlerini sınırlamak için bir eyleme izin verir. [Consumes] özniteliğini bir eyleme veya denetleyiciye uygulayarak bir veya daha fazla içerik türü belirtin:

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

Önceki kodda CreateProduct eylemi, application/xml içerik türünü belirtir. Bu eyleme yönlendirilen istekler application/xml üst bilgisinin Content-Type öğesini belirtmelidir. 415 Desteklenmeyen Medya Türü yanıtında sonucun application/xml üst bilgisinin Content-Type öğesini belirtmeyen istekler.

[Consumes] özniteliği, bir eylemin bir tür kısıtlaması uygulayarak gelen isteğin içerik türüne göre seçimini etkilemesine de olanak tanır. 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 });
}

Yukarıdaki kodda, ConsumesController, https://localhost:5001/api/Consumes URL'sine gönderilen istekleri işleyecek şekilde yapılandırılmıştır. PostJson ve PostForm denetleyici eylemlerinin her ikisi de POST isteklerini aynı URL ile işler. Bir tür kısıtlaması uygulayan [Consumes] özniteliği olmadan, belirsiz bir eşleşme özel durumu oluşturulur.

[Consumes] özniteliği her iki eyleme de uygulanır. PostJson eylemi, application/json üst bilgisi ile gönderilen bir Content-Type için istekleri işler. PostForm eylemi, application/x-www-form-urlencoded üst bilgisi ile gönderilen bir Content-Type için istekleri işler.

Ek kaynaklar

ASP.NET Core, denetleyicileri veya minimum API'leri kullanarak web API'leri oluşturmayı destekler. Bir web API'sindeki denetleyiciler, ControllerBase öğesinden türetilen sınıflardır. Bu makalede, web API'si isteklerini işlemek için denetleyicilerin nasıl kullanılacağı gösterilmektedir. Denetleyiciler olmadan web API'leri oluşturma hakkında bilgi için bkz . Öğretici: ASP.NET Core ile minimum API oluşturma.

ControllerBase sınıfı

Denetleyici tabanlı bir web API'si, ControllerBase öğesinden türetilen bir veya daha fazla denetleyici sınıfından oluşur. Web API proje şablonu bir başlangıç denetleyicisi sağlar:

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

Web API denetleyicileri tipik olarak Controller öğesi yerine ControllerBase öğesinden türetilmelidir. ControllerBase öğesinden Controller türetilir ve görünümler için destek ekler, bu nedenle web API'si isteklerini değil web sayfalarını işlemeye yöneliktir. Aynı denetleyicinin görünümleri ve web API'lerini desteklemesi gerekiyorsa, Controller öğesinden türetilir.

ControllerBase sınıfı, HTTP isteklerini işlemek için yararlı olan birçok özellik ve yöntem sağlar. Örneğin, 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);
}

Aşağıdaki tabloda ControllerBase içindeki yöntemlerin örnekleri yer alır.

Metot 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ğlamayı çağırır.
TryValidateModel Model doğrulamayı çağırır.

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

Özellikler

Microsoft.AspNetCore.Mvc ad alanı, web API denetleyicilerinin ve eylem yöntemlerinin davranışını yapılandırmak için kullanılabilecek öznitelikler sağlar. Aşağıdaki örnek, desteklenen HTTP eylem fiilini ve döndürülebilecek bilinen 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 özniteliklerin bazı örnekleri verilmiştir.

Öznitelik Notlar
[Route] Bir denetleyici veya eylem için URL deseni 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 ettiği veri türlerini belirtir.
[Produces] Bir eylemin kabul döndürdüğü veri türlerini belirtir.

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

ApiController özniteliği

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

Belirli denetleyicilerdeki öznitelik

[ApiController] özniteliği, 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, [ApiController] özniteliğiyle ek açıklama ekli özel bir temel denetleyici sınıfı oluşturmaktır. Aşağıdaki örnekte, özel bir temel sınıf ve bundan türetilen bir denetleyici gösterilmektedir:

[ApiController]
public class MyControllerBase : ControllerBase
{
}

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

Bir derlemedeki öznitelik

[ApiController] özniteliği bir derlemeye uygulanabilir. [ApiController] özniteliği bir derlemeye uygulandığında, derlemedeki tüm denetleyicilerde [ApiController] özniteliği uygulanır. Tek tek denetleyicileri geri çevirmenin hiçbir yolu yoktur. Program.cs dosyasına derleme düzeyi özniteliğini uygulayın:

using Microsoft.AspNetCore.Mvc;
[assembly: ApiController]

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers();

var app = builder.Build();

app.UseHttpsRedirection();

app.UseAuthorization();

app.MapControllers();

app.Run();

Öznitelik yönlendirme gereksinimi

[ApiController] özniteliği, öznitelik yönlendirmeyi bir gereksinim haline getirir. Örneğin:

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

Eylemlere UseEndpoints, UseMvc veya UseMvcWithDefaultRoute tarafından tanımlanan geleneksel yollar aracılığıyla erişilemez.

Otomatik HTTP 400 yanıtları

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

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

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

Varsayılan BadRequest yanıtı

Aşağıdaki yanıt gövdesi, seri hale getirilmiş türün bir örneğidir:

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

HTTP 400 yanıtı için varsayılan yanıt türü ValidationProblemDetails şeklindedir. Aşağıdaki yanıt gövdesi, seri hale getirilmiş 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."
    ]
  }
}

ValidationProblemDetails türü:

  • Web API’si yanıtlarındaki hataları belirtmek için makine tarafından okunabilir bir biçim sağlar.
  • RFC 7807 belirtimi ile uyumludur.

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

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

Otomatik 400 yanıtlarını günlüğe kaydetmek için özel işleme gerçekleştirmek için InvalidModelStateResponseFactory temsilci özelliğini ayarlayın. Varsayılan olarak, ValidationProblemDetails öğesinin bir örneğini oluşturmak için InvalidModelStateResponseFactory, ProblemDetailsFactory kullanır.

Aşağıdaki örnek, otomatik 400 yanıtıyla ilgili bilgileri günlüğe kaydetmek için bir ILogger<TCategoryName> örneğinin nasıl alınacağını gösterir:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers()
    .ConfigureApiBehaviorOptions(options =>
    {
      // To preserve the default behavior, capture the original delegate to call later.
        var builtInFactory = options.InvalidModelStateResponseFactory;

        options.InvalidModelStateResponseFactory = context =>
        {
            var logger = context.HttpContext.RequestServices
                                .GetRequiredService<ILogger<Program>>();

            // Perform logging here.
            // ...

            // Invoke the default behavior, which produces a ValidationProblemDetails
            // response.
            // To produce a custom response, return a different implementation of 
            // IActionResult instead.
            return builtInFactory(context);
        };
    });

var app = builder.Build();

app.UseHttpsRedirection();

app.UseAuthorization();

app.MapControllers();

app.Run();

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

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

using Microsoft.AspNetCore.Mvc;

var builder = WebApplication.CreateBuilder(args);

builder.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";
    });

var app = builder.Build();

app.UseHttpsRedirection();

app.UseAuthorization();

app.MapControllers();

app.Run();

Kaynak parametre çıkarımı bağlama

Bir bağlama kaynağı özniteliği, bir eylem parametresinin değerinin bulunduğu konumu tanımlar. Aşağıdaki bağlama kaynağı öznitelikleri mevcuttur:

Öznitelik Bağlama kaynağı
[FromBody] Request body
[FromForm] İstek gövdesindeki form verileri
[FromHeader] İstek üst bilgisi
[FromQuery] Sorgu dizesi parametresi isteme
[FromRoute] Geçerli istekten verileri yönlendirme
[FromServices] Bir eylem parametresi olarak eklenen istek hizmeti

Uyarı

Değerlerin %2f (yani /) içerebileceği durumlarda [FromRoute] kullanmayın. %2f, / öğesine ayarlanmamış olmayacaktır. %2f değerini içermesi gerekiyorsa [FromQuery] kullanın.

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

Aşağıdaki örnekte [FromQuery] özniteliği, discontinuedOnly parametre değerinin istek URL'sinin sorgu dizesinde 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] özniteliği, eylem parametrelerinin varsayılan veri kaynakları için çıkarım kuralları uygular. Bu kurallar, eylem parametrelerine öznitelikler uygulayarak bağlama kaynağını el ile tanımlamak zorunda olmamanızı engeller. Bağlama kaynağı çıkarım kuralları aşağıdaki gibi davranır:

  • [FromBody], DI Kapsayıcısında kayıtlı olmayan karmaşık tür parametreleri için çıkarılır. [FromBody] çıkarım kuralının özel bir istisnası, IFormCollection ve CancellationToken gibi özel bir anlamı olan karmaşık ve yerleşik türdür. Bağlama kaynağı çıkarım kodu bu özel türleri yok sayar.
  • IFormFile ve IFormFileCollection türündeki eylem parametreleri için [FromForm] çıkarılır. Basit veya kullanıcı tanımlı türler için çıkarılmaz.
  • [FromRoute] yol şablonundaki bir parametreyle eşleşen herhangi bir eylem parametresi adı için çıkarılır. Bir eylem parametresiyle birden fazla yol eşleştiğinde, herhangi bir yol değeri [FromRoute] olarak kabul edilir.
  • [FromQuery], diğer eylem parametreleri için çıkarılır.

FromBody çıkarım notları

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

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

  • [FromBody] karmaşık türler olduğundan her ikisinde de çıkarılır.

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

  • [FromBody] özniteliği, karmaşık bir tür olduğundan diğerinde çıkarılır.

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

  • [FromBody] özniteliği her ikisinde.

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

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

Bağlama kaynağı çıkarımı devre dışı bırakmak için SuppressInferBindingSourcesForParameters öğesini true olarak ayarlayın:

using Microsoft.AspNetCore.Mvc;

var builder = WebApplication.CreateBuilder(args);

builder.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";
    });

var app = builder.Build();

app.UseHttpsRedirection();

app.UseAuthorization();

app.MapControllers();

app.Run();

Çok parçalı/form-veri isteği çıkarımı

[ApiController] özniteliği, IFormFile ve IFormFileCollection türünde eylem parametreleri için bir çıkarım kuralı uygular. multipart/form-data isteği içerik türü bu türler için çıkarılır.

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

using Microsoft.AspNetCore.Mvc;

var builder = WebApplication.CreateBuilder(args);

builder.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";
    });

var app = builder.Build();

app.UseHttpsRedirection();

app.UseAuthorization();

app.MapControllers();

app.Run();

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

MVC, hata sonucunu (durum kodu 400 veya üzeri olan bir sonuç) ProblemDetails ile bir sonuca dönüştürür. ProblemDetails türü, bir HTTP yanıtında makine tarafından okunabilir hata ayrıntıları sağlamaya yönelik RFC 7807 belirtimini temel alır.

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

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

NotFound yöntemi, ProblemDetails gövdeli bir HTTP 404 durum kodu üretir. Örneğin:

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

ProblemDetails yanıtlarını devre dışı bırakma

SuppressMapClientErrors özelliği true olarak ayarlandığında hata durum kodları için otomatik bir ProblemDetails oluşturma devre dışı bırakılır:

using Microsoft.AspNetCore.Mvc;

var builder = WebApplication.CreateBuilder(args);

builder.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";
    });

var app = builder.Build();

app.UseHttpsRedirection();

app.UseAuthorization();

app.MapControllers();

app.Run();

Desteklenen istek içerik türlerini [Consumes] özniteliğiyle tanımlama

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ş biçimlendiricilerini destekleyecek şekilde yapılandırılmışsa, bir eylem ve application/xmldahil olmak üzere application/json birden çok içerik türünü destekler.

[Consumes] özniteliği, desteklenen istek içerik türlerini sınırlamak için bir eyleme izin verir. [Consumes] özniteliğini bir eyleme veya denetleyiciye uygulayarak bir veya daha fazla içerik türü belirtin:

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

Önceki kodda CreateProduct eylemi, application/xml içerik türünü belirtir. Bu eyleme yönlendirilen istekler application/xml üst bilgisinin Content-Type öğesini belirtmelidir. 415 Desteklenmeyen Medya Türü yanıtında sonucun application/xml üst bilgisinin Content-Type öğesini belirtmeyen istekler.

[Consumes] özniteliği, bir eylemin bir tür kısıtlaması uygulayarak gelen isteğin içerik türüne göre seçimini etkilemesine de olanak tanır. 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 });
}

Yukarıdaki kodda, ConsumesController, https://localhost:5001/api/Consumes URL'sine gönderilen istekleri işleyecek şekilde yapılandırılmıştır. PostJson ve PostForm denetleyici eylemlerinin her ikisi de POST isteklerini aynı URL ile işler. Bir tür kısıtlaması uygulayan [Consumes] özniteliği olmadan, belirsiz bir eşleşme özel durumu oluşturulur.

[Consumes] özniteliği her iki eyleme de uygulanır. PostJson eylemi, application/json üst bilgisi ile gönderilen bir Content-Type için istekleri işler. PostForm eylemi, application/x-www-form-urlencoded üst bilgisi ile gönderilen bir Content-Type için istekleri işler.

Ek kaynaklar

ASP.NET Core, web API'leri olarak da bilinen RESTful hizmetleri oluşturulmasını C# kullanarak desteklemektedir. İstekleri işlemek için web API'sinde denetleyiciler kullanılır. Bir web API'sindeki denetleyiciler, ControllerBase öğesinden türetilen sınıflardır. Bu makalede, web API'si isteklerini işlemek için denetleyicilerin nasıl kullanılacağı gösterilmektedir.

Örnek kodu görüntüleyin veya indirme. (Nasıl indirilir).

ControllerBase sınıfı

Bir web API'si, ControllerBase öğesinden türetilen bir veya daha fazla denetleyici sınıfından oluşur. Web API proje şablonu bir başlangıç denetleyicisi sağlar:

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

Controller sınıfından türeterek bir web API’si denetleyicisi oluşturmayın. ControllerBase öğesinden Controller türetilir ve görünümler için destek ekler, bu nedenle web API'si isteklerini değil web sayfalarını işlemeye yöneliktir. 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, bunu Controller öğesinden türetin.

ControllerBase sı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);
}

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

Metot 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ğlamayı çağırır.
TryValidateModel Model doğrulamayı çağırır.

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

Özellikler

Microsoft.AspNetCore.Mvc ad alanı, web API denetleyicilerinin ve eylem yöntemlerinin davranışını yapılandırmak için kullanılabilecek öznitelikler sağlar. Aşağıdaki örnek, desteklenen HTTP eylem fiilini ve döndürülebilecek bilinen 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 özniteliklerin bazı örnekleri verilmiştir.

Öznitelik Notlar
[Route] Bir denetleyici veya eylem için URL deseni 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 ettiği veri türlerini belirtir.
[Produces] Bir eylemin kabul döndürdüğü veri türlerini belirtir.

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

ApiController özniteliği

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

Belirli denetleyicilerdeki öznitelik

[ApiController] özniteliği, 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, [ApiController] özniteliğiyle ek açıklama ekli özel bir temel denetleyici sınıfı oluşturmaktır. Aşağıdaki örnekte, özel bir temel sınıf ve bundan türetilen bir denetleyici gösterilmektedir:

[ApiController]
public class MyControllerBase : ControllerBase
{
}

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

Bir derlemedeki öznitelik

[ApiController] özniteliği bir derlemeye uygulanabilir. Bu şekilde ek açıklama, derlemedeki tüm denetleyicilere web API'sinin davranışını uygular. Tek tek denetleyicileri geri çevirmenin hiçbir yolu yoktur. Startup sınıfını çevreleyen ad alanı bildirimine derleme düzeyi özniteliğini uygulayın:

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

Öznitelik yönlendirme gereksinimi

[ApiController] özniteliği, öznitelik yönlendirmeyi bir gereksinim haline getirir. Örneğin:

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

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

Otomatik HTTP 400 yanıtları

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

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

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

Varsayılan BadRequest yanıtı

Aşağıdaki istek gövdesi, seri hale getirilmiş türün bir örneğidir:

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

HTTP 400 yanıtı için varsayılan yanıt türü ValidationProblemDetails şeklindedir. Aşağıdaki istek gövdesi, seri hale getirilmiş 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."
    ]
  }
}

ValidationProblemDetails türü:

  • Web API’si yanıtlarındaki hataları belirtmek için makine tarafından okunabilir bir biçim sağlar.
  • RFC 7807 belirtimi ile uyumludur.

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

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

Otomatik 400 yanıtlarını günlüğe kaydetmek için Startup.ConfigureServices içinde özel işleme gerçekleştirmek için InvalidModelStateResponseFactory temsilci özelliğini ayarlayın. Varsayılan olarak, ValidationProblemDetails öğesinin bir örneğini oluşturmak için InvalidModelStateResponseFactory, ProblemDetailsFactory kullanır.

Aşağıdaki örnek, otomatik 400 yanıtıyla ilgili bilgileri günlüğe kaydetmek için bir ILogger<TCategoryName> örneğinin nasıl alınacağını gösterir:

services.AddControllers()
    .ConfigureApiBehaviorOptions(options =>
    {
        // To preserve the default behavior, capture the original delegate to call later.
        var builtInFactory = options.InvalidModelStateResponseFactory;

        options.InvalidModelStateResponseFactory = context =>
        {
            var logger = context.HttpContext.RequestServices.GetRequiredService<ILogger<Startup>>();

            // Perform logging here.
            // ...

            // Invoke the default behavior, which produces a ValidationProblemDetails response.
            // To produce a custom response, return a different implementation of IActionResult instead.
            return builtInFactory(context);
        };
    });

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

Otomatik 400 davranışını devre dışı bırakmak için, SuppressModelStateInvalidFilter özelliğini true olarak ayarlayın. Startup.ConfigureServices içinde aşağıdaki vurgulanan kodu 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";
        options.DisableImplicitFromServicesParameters = true;
    });

Kaynak parametre çıkarımı bağlama

Bir bağlama kaynağı özniteliği, bir eylem parametresinin değerinin bulunduğu konumu tanımlar. Aşağıdaki bağlama kaynağı öznitelikleri mevcuttur:

Öznitelik Bağlama kaynağı
[FromBody] Request body
[FromForm] İstek gövdesindeki form verileri
[FromHeader] İstek üst bilgisi
[FromQuery] Sorgu dizesi parametresi isteme
[FromRoute] Geçerli istekten verileri yönlendirme
[FromServices] Bir eylem parametresi olarak eklenen istek hizmeti

Uyarı

Değerlerin %2f (yani /) içerebileceği durumlarda [FromRoute] kullanmayın. %2f, / öğesine ayarlanmamış olmayacaktır. %2f değerini içermesi gerekiyorsa [FromQuery] kullanın.

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

Aşağıdaki örnekte [FromQuery] özniteliği, discontinuedOnly parametre değerinin istek URL'sinin sorgu dizesinde 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] özniteliği, eylem parametrelerinin varsayılan veri kaynakları için çıkarım kuralları uygular. Bu kurallar, eylem parametrelerine öznitelikler uygulayarak bağlama kaynağını el ile tanımlamak zorunda olmamanızı engeller. Bağlama kaynağı çıkarım kuralları aşağıdaki gibi davranır:

  • [FromBody] karmaşık tür parametreleri için çıkarılır. [FromBody] çıkarım kuralının özel bir istisnası, IFormCollection ve CancellationToken gibi özel bir anlamı olan karmaşık ve yerleşik türdür. Bağlama kaynağı çıkarım kodu bu özel türleri yok sayar.
  • IFormFile ve IFormFileCollection türündeki eylem parametreleri için [FromForm] çıkarılır. Basit veya kullanıcı tanımlı türler için çıkarılmaz.
  • [FromRoute] yol şablonundaki bir parametreyle eşleşen herhangi bir eylem parametresi adı için çıkarılır. Bir eylem parametresiyle birden fazla yol eşleştiğinde, herhangi bir yol değeri [FromRoute] olarak kabul edilir.
  • [FromQuery], diğer eylem parametreleri için çıkarılır.

FromBody çıkarım notları

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

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

  • [FromBody] karmaşık türler olduğundan her ikisinde de çıkarılır.

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

  • [FromBody] özniteliği, karmaşık bir tür olduğundan diğerinde çıkarılır.

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

  • [FromBody] özniteliği her ikisinde.

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

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

Bağlama kaynağı çıkarımı devre dışı bırakmak için SuppressInferBindingSourcesForParameters öğesini true olarak ayarlayın. Aşağıdaki kodu Startup.ConfigureServices içine 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";
        options.DisableImplicitFromServicesParameters = true;
    });

Çok parçalı/form-veri isteği çıkarımı

[ApiController] özniteliği, IFormFile ve IFormFileCollection türünde eylem parametreleri için bir çıkarım kuralı uygular. multipart/form-data isteği içerik türü bu türler için çıkarılır.

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

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";
        options.DisableImplicitFromServicesParameters = true;
    });

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

MVC, hata sonucunu (durum kodu 400 veya üzeri olan bir sonuç) ProblemDetails ile bir sonuca dönüştürür. ProblemDetails türü, bir HTTP yanıtında makine tarafından okunabilir hata ayrıntıları sağlamaya yönelik RFC 7807 belirtimini temel alır.

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

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

NotFound yöntemi, ProblemDetails gövdeli bir HTTP 404 durum kodu üretir. Örneğin:

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

ProblemDetails yanıtlarını devre dışı bırakma

SuppressMapClientErrors özelliği true olarak ayarlandığında hata durum kodları için otomatik bir ProblemDetails oluşturma devre dışı bırakılır. Aşağıdaki kodu Startup.ConfigureServices içine 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";
        options.DisableImplicitFromServicesParameters = true;
    });

Desteklenen istek içerik türlerini [Consumes] özniteliğiyle tanımlama

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ş biçimlendiricilerini destekleyecek şekilde yapılandırılmışsa, bir eylem ve application/xmldahil olmak üzere application/json birden çok içerik türünü destekler.

[Consumes] özniteliği, desteklenen istek içerik türlerini sınırlamak için bir eyleme izin verir. [Consumes] özniteliğini bir eyleme veya denetleyiciye uygulayarak bir veya daha fazla içerik türü belirtin:

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

Önceki kodda CreateProduct eylemi, application/xml içerik türünü belirtir. Bu eyleme yönlendirilen istekler application/xml üst bilgisinin Content-Type öğesini belirtmelidir. 415 Desteklenmeyen Medya Türü yanıtında sonucun application/xml üst bilgisinin Content-Type öğesini belirtmeyen istekler.

[Consumes] özniteliği, bir eylemin bir tür kısıtlaması uygulayarak gelen isteğin içerik türüne göre seçimini etkilemesine de olanak tanır. 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 });
}

Yukarıdaki kodda, ConsumesController, https://localhost:5001/api/Consumes URL'sine gönderilen istekleri işleyecek şekilde yapılandırılmıştır. PostJson ve PostForm denetleyici eylemlerinin her ikisi de POST isteklerini aynı URL ile işler. Bir tür kısıtlaması uygulayan [Consumes] özniteliği olmadan, belirsiz bir eşleşme özel durumu oluşturulur.

[Consumes] özniteliği her iki eyleme de uygulanır. PostJson eylemi, application/json üst bilgisi ile gönderilen bir Content-Type için istekleri işler. PostForm eylemi, application/x-www-form-urlencoded üst bilgisi ile gönderilen bir Content-Type için istekleri işler.

Ek kaynaklar

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

Controller sınıfından türeterek bir web API’si denetleyicisi oluşturmayın. ControllerBase öğesinden Controller türetilir ve görünümler için destek ekler, bu nedenle web API'si isteklerini değil web sayfalarını işlemeye yöneliktir. 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, bunu Controller öğesinden türetin. ControllerBase sı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);
}

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

Metot 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ğlamayı çağırır.
TryValidateModel Model doğrulamayı çağırır.

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

Özellikler

Microsoft.AspNetCore.Mvc ad alanı, web API denetleyicilerinin ve eylem yöntemlerinin davranışını yapılandırmak için kullanılabilecek öznitelikler sağlar. Aşağıdaki örnek, desteklenen HTTP eylem fiilini ve döndürülebilecek bilinen 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 özniteliklerin bazı örnekleri verilmiştir:

Öznitelik Notlar
[Route] Bir denetleyici veya eylem için URL deseni 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 ettiği veri türlerini belirtir.
[Produces] Bir eylemin kabul döndürdüğü veri türlerini belirtir.

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

ApiController özniteliği

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

Belirli denetleyicilerdeki ö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 denetleyicide öznitelik

Özniteliğini birden fazla denetleyicide kullanma yaklaşımlarından biri, [ApiController] özniteliğiyle ek açıklama ekli özel bir temel denetleyici sınıfı oluşturmaktır. Aşağıdaki örnekte, özel bir temel sınıf ve bundan 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 olarak ayarlandıysa, [ApiController] özniteliği bir derlemeye uygulanabilir. Bu şekilde ek açıklama, derlemedeki tüm denetleyicilere web API'sinin davranışını uygular. Tek tek denetleyicileri geri çevirmenin hiçbir yolu yoktur. Startup sınıfını çevreleyen ad alanı bildirimine derleme düzeyi özniteliğini uygulayın:

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

Öznitelik yönlendirme gereksinimi

[ApiController] özniteliği, öznitelik yönlendirmeyi bir gereksinim haline getirir. Örneğin:

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

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

Otomatik HTTP 400 yanıtları

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

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

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

Varsayılan BadRequest yanıtı

Uyumluluk sürümü 2.1 olduğunda, HTTP 400 yanıtı için varsayılan yanıt türü SerializableError şeklindedir. Aşağıdaki istek gövdesi, seri hale getirilmiş türün bir örneğidir:

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

Uyumluluk sürümü 2.2 veya sonrası olduğunda, HTTP 400 yanıtı için varsayılan yanıt türü ValidationProblemDetails şeklindedir. Aşağıdaki istek gövdesi, seri hale getirilmiş 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."
    ]
  }
}

ValidationProblemDetails türü:

  • Web API’si yanıtlarındaki hataları belirtmek için makine tarafından okunabilir bir biçim sağlar.
  • RFC 7807 belirtimi ile uyumludur.

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

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

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

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

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

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

Kaynak parametre çıkarımı bağlama

Bir bağlama kaynağı özniteliği, bir eylem parametresinin değerinin bulunduğu konumu tanımlar. Aşağıdaki bağlama kaynağı öznitelikleri mevcuttur:

Öznitelik Bağlama kaynağı
[FromBody] Request body
[FromForm] İstek gövdesindeki form verileri
[FromHeader] İstek üst bilgisi
[FromQuery] Sorgu dizesi parametresi isteme
[FromRoute] Geçerli istekten verileri yönlendirme
[FromServices] Bir eylem parametresi olarak eklenen istek hizmeti

Uyarı

Değerlerin %2f (yani /) içerebileceği durumlarda [FromRoute] kullanmayın. %2f, / öğesine ayarlanmamış olmayacaktır. %2f değerini içermesi gerekiyorsa [FromQuery] kullanın. [ApiController] özniteliği veya [FromQuery] gibi bağlama kaynağı öznitelikleri olmadan, ASP.NET Core çalışma zamanı karmaşık nesne modeli bağlayıcısını kullanmaya çalışır. Karmaşık nesne modeli bağlayıcısı, değer sağlayıcılarından verileri, tanımlı bir sırada çeker.

Aşağıdaki örnekte [FromQuery] özniteliği, discontinuedOnly parametre değerinin istek URL'sinin sorgu dizesinde 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] özniteliği, eylem parametrelerinin varsayılan veri kaynakları için çıkarım kuralları uygular. Bu kurallar, eylem parametrelerine öznitelikler uygulayarak bağlama kaynağını el ile tanımlamak zorunda olmamanızı engeller. Bağlama kaynağı çıkarım kuralları aşağıdaki gibi davranır:

  • [FromBody] karmaşık tür parametreleri için çıkarılır. [FromBody] çıkarım kuralının özel bir istisnası, IFormCollection ve CancellationToken gibi özel bir anlamı olan karmaşık ve yerleşik türdür. Bağlama kaynağı çıkarım kodu bu özel türleri yok sayar.
  • IFormFile ve IFormFileCollection türündeki eylem parametreleri için [FromForm] çıkarılır. Basit veya kullanıcı tanımlı türler için çıkarılmaz.
  • [FromRoute] yol şablonundaki bir parametreyle eşleşen herhangi bir eylem parametresi adı için çıkarılır. Bir eylem parametresiyle birden fazla yol eşleştiğinde, herhangi bir yol değeri [FromRoute] olarak kabul edilir.
  • [FromQuery], diğer eylem parametreleri için çıkarılır.

FromBody çıkarım notları

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

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

  • [FromBody] karmaşık türler olduğundan her ikisinde de çıkarılır.

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

  • [FromBody] özniteliği, karmaşık bir tür olduğundan diğerinde çıkarılır.

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

  • [FromBody] özniteliği her ikisinde.

    [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ış bir şekilde [FromQuery] olarak çıkarılır. [FromBody] özniteliği, istek gövdesinden bağlanacaksa bu parametreler için kullanılmalıdır. Bu davranış, koleksiyon türü parametrelerinin varsayılan olarak gövdeden bağlandığı ASP.NET Core 2.2 veya sonraki sürümlerinde düzeltilir.

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

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

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

Çok parçalı/form-veri isteği çıkarımı

[ApiController] özniteliği, IFormFile ve IFormFileCollection türünde eylem parametreleri için bir çıkarım kuralı uygular. multipart/form-data isteği içerik türü bu türler için çıkarılır. Varsayılan davranışı devre dışı bırakmak için SuppressConsumesConstraintForFormFileParameters özelliğini Startup.ConfigureServices içinde true olarak ayarlayın:

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

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ç) ProblemDetails ile bir sonuca dönüştürür. ProblemDetails türü, bir HTTP yanıtında makine tarafından okunabilir hata ayrıntıları sağlamaya yönelik RFC 7807 belirtimini temel alır. Denetleyici eyleminde aşağıdaki kodu göz önünde bulundurun:

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

NotFound yöntemi, ProblemDetails gövdeli bir HTTP 404 durum kodu üretir. Örneğin:

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

ProblemDetails yanıtlarını devre dışı bırakma

SuppressMapClientErrors özelliği true olarak ayarlandığında hata durum kodları için otomatik bir ProblemDetails oluşturma devre dışı bırakılır. Aşağıdaki kodu Startup.ConfigureServices içine ekleyin:

Desteklenen istek içerik türlerini [Consumes] özniteliğiyle tanımlama

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ş biçimlendiricilerini destekleyecek şekilde yapılandırılmışsa, bir eylem ve application/xmldahil olmak üzere application/json birden çok içerik türünü destekler.

[Consumes] özniteliği, desteklenen istek içerik türlerini sınırlamak için bir eyleme izin verir. [Consumes] özniteliğini bir eyleme veya denetleyiciye uygulayarak bir veya daha fazla içerik türü belirtin:

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

Önceki kodda CreateProduct eylemi, application/xml içerik türünü belirtir. Bu eyleme yönlendirilen istekler application/xml üst bilgisinin Content-Type öğesini belirtmelidir. 415 Desteklenmeyen Medya Türü yanıtında sonucun application/xml üst bilgisinin Content-Type öğesini belirtmeyen istekler. [Consumes] özniteliği, bir eylemin bir tür kısıtlaması uygulayarak gelen isteğin içerik türüne göre seçimini etkilemesine de olanak tanır. 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 });
}

Yukarıdaki kodda, ConsumesController, https://localhost:5001/api/Consumes URL'sine gönderilen istekleri işleyecek şekilde yapılandırılmıştır. PostJson ve PostForm denetleyici eylemlerinin her ikisi de POST isteklerini aynı URL ile işler. Bir tür kısıtlaması uygulayan [Consumes] özniteliği olmadan, belirsiz bir eşleşme özel durumu oluşturulur. [Consumes] özniteliği her iki eyleme de uygulanır. PostJson eylemi, application/json üst bilgisi ile gönderilen bir Content-Type için istekleri işler. PostForm eylemi, application/x-www-form-urlencoded üst bilgisi ile gönderilen bir Content-Type için istekleri işler.

Ek kaynaklar