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

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.

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

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

Öznitelikler

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:

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

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. Örnek:

[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:

• Önceden belirtilen BindingInfo.BindingSource bir değerin üzerine hiçbir zaman yazılmaz.
• DI kapsayıcısında kayıtlı karmaşık tür parametresi atanır BindingSource.Services.
• DI kapsayıcısında kayıtlı olmayan karmaşık tür parametresine atanır BindingSource.Body.
• Herhangi bir yol şablonunda yol değeri olarak görünen ada sahip bir parametre atanırBindingSource.Path.
• Diğer tüm parametreler şunlardır: BindingSource.Query.

Çı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. Örnek:

{
  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 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 application/json ve application/xml dahil olmak üzere 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

• Örnek kodu görüntüleyin veya indirme. (Nasıl indirilir).
• ASP.NET Core web API'sinde denetleyici eylemi dönüş türleri
• ASP.NET Core web API'lerindeki hataları işleme
• ASP.NET Core Web API'sindeki özel biçimlendiriciler
• ASP.NET Core Web API'sinde yanıt verilerini biçimlendirme
• Swagger / OpenAPI ile web API belgeleri ASP.NET Core
• ASP.NET Core'de denetleyici eylemlerine yönlendirme
• Web API'lerinin hatalarını ayıklamak için Visual Studio bağlantı noktası tünelini kullanma
• ASP.NET Core ile web API'si oluşturma