Geliştirme

.NET 10 Minimal API Doğrulaması: AddValidation Rehberi

Mehmet Fatih Ünal
31 Ekim 2026
6 dk okuma
#.NET 10#ASP.NET Core#Minimal API#Validation#C#
.NET 10 Minimal API Doğrulaması: AddValidation Rehberi

.NET 10 Minimal API doğrulaması nasıl çalışır?

.NET 10 Minimal API doğrulaması, desteklenen istek modellerine tanımlanan DataAnnotations kurallarını endpoint işleyicisi çalışmadan önce kontrol edebilir. Microsoft.Extensions.Validation paketi ve AddValidation kaydı bu akışın temel parçalarıdır. Microsoft'un doğrulama rehberi, servis kaydını ve model keşfini açıklar.

Bir görev oluşturma API'si düşünün. Başlık boş olmamalı, belirli bir uzunluğu aşmamalı ve öncelik izin verilen aralıkta kalmalı. Her endpoint'in başına aynı kontrolleri yazmak yerine bu giriş sözleşmesini model üzerinde tanımlamak daha kolay izlenebilir bir yapı sunar.

Bu özellik ASP.NET Core'un .NET 10 sürümü içindir. Eski bir Minimal API projesine yalnızca attribute ekleyip otomatik olarak aynı davranışı beklemeyin. Sürüm geçişi planlanıyorsa .NET 10 geçiş rehberi başlangıç noktası olabilir.

AddValidation için nasıl bir kurulum gerekir?

net10.0 hedefleyen bir web projesine Microsoft.Extensions.Validation paketinin uyumlu bir 10.x sürümünü ekleyin ve builder.Services.AddValidation çağrısını uygulama oluşturulmadan önce yapın. Aşağıdaki Program.cs, yalnızca doğrulama davranışını gösterir; veri kaydetmez:

using System.ComponentModel.DataAnnotations;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddValidation();

var app = builder.Build();

app.MapPost("/tasks", (CreateTaskRequest request) =>
    TypedResults.Ok(new { request.Title, request.Priority }));

app.Run();

public sealed class CreateTaskRequest
{
    [Required]
    [StringLength(120, MinimumLength = 3)]
    public string? Title { get; init; }

    [Range(1, 5)]
    public int Priority { get; init; }
}

Modeli örnekteki gibi endpoint ile aynı projede tutmak, ilk denemeyi sadeleştirir. Doğrulama metadata'sı kaynak üreteciyle oluşturulduğundan, modelleri ayrı bir assembly'ye taşımak ek yapılandırma gerektirebilir. Bir paketin kurulu olması, bütün modellerin otomatik olarak keşfedildiğini kanıtlamaz.

Kurulumu kontrol ederken yalnızca derlemenin tamamlanmasına bakmayın. Endpoint'e gerçekten geçersiz bir gövde gönderin ve handler'ın çalışmadan isteğin reddedildiğini doğrulayın.

Required, StringLength ve Range aynı işi mi yapar?

Required alanın zorunluluğunu, StringLength metin uzunluğunu, Range ise sayısal sınırı ifade eder. Birini kullanmak diğerinin sağladığı kontrolü otomatik olarak eklemez. Required, StringLength ve Range referansları bu kuralları ayrı ayrı tanımlar.

Örnekte Title nullable tanımlanmıştır; boş veya eksik girişin nasıl ele alınacağına doğrulama kuralı karar verir. Öncelik alanı gövdede gönderilmezse int türünün varsayılan değeri sıfır olur ve 1–5 aralığına uymaz. Bu yüzden eksik alan denemesi de gereklidir.

Başlığı boşluklardan temizlemek ise farklı bir karardır. Uzunluk denetiminin gelen ham metne mi yoksa normalleştirilmiş metne mi uygulanacağını baştan belirleyin. Doğrulama, içeriği sizin yerinize düzenleyen bir mekanizma değildir.

Geçersiz istek hangi HTTP yanıtını alır?

Desteklenen bir modelin doğrulaması başarısız olduğunda Minimal API, hata ayrıntılarıyla birlikte HTTP 400 yanıtı üretir. Minimal API referansı, bu davranışı ve IProblemDetailsService üzerinden özelleştirmeyi açıklar.

Şu gövde iki alan kuralına da uymaz:

{
  "title": "",
  "priority": 9
}

İstemci tarafında hata metnini parçalayarak alan bulmaya çalışmak yerine yapılandırılmış alan hatalarını kullanın. İnsan tarafından okunan mesajlar dil veya yapılandırmaya göre değişebilir. API hata işleme rehberi, tutarlı problem yanıtları için seçenekler sunar.

Bozuk JSON, bağlama hatası ve model kuralına aykırı bir değer aynı aşamada oluşmaz. Hepsinin görünümünü aynı varsaymak yerine istemcinizin her birinde nasıl davranacağını deneyin.

Model doğrulaması iş kurallarını da garanti eder mi?

Model doğrulaması, bir isteğin biçim ve alan kurallarına uygunluğunu denetler. Kullanıcının bu görevi oluşturma yetkisi, ait olduğu hesap ve işlem anındaki veritabanı durumu ayrıca değerlendirilmelidir.

Örneğin "başlık en az üç karakter" model üzerinde ifade edilebilir. "Bu hesap aynı anda en fazla belirli sayıda açık görev tutabilir" kuralı ise mevcut veriyi ve eşzamanlı işlemleri ilgilendirir. İki istek aynı anda geldiğinde ikisinin de eski durumu okuyabileceğini hesaba katın.

Benzersizlik ve atomiklik gerektiren kurallarda veritabanı sınırlarıyla işlem tasarımı birlikte düşünülür. Webhook idempotency yazısı, geçerli bir isteğin tekrarının neden ayrı bir sorun olduğunu gösterir. AddValidation bu tekrar sorununu çözmez.

Endpoint'i nasıl doğrulamalı?

İyi bir deneme, yalnızca başarılı isteği değil sınır değerlerini ve reddedilen istekte oluşmaması gereken etkileri de kontrol eder. Bu örnekte üç karakterli başlık ve 1 ya da 5 önceliği geçerli; iki karakterli başlık ve 0 ya da 6 önceliği geçersiz olmalıdır.

Eksik başlık, boşluklardan oluşan başlık ve eksik öncelik için de ayrı istekler gönderin. Handler'a geçişi veya veritabanı yazmasını gözleyin. Gövdedeki tanınmayan ek alanların otomatik olarak reddedildiğini varsaymayın; bu, JSON serileştirme sözleşmesinin ayrı bir parçasıdır.

Formdaki istemci kontrollerini kullanıcı deneyimi için koruyun. Sunucu doğrulamasını ise doğrudan HTTP isteğiyle deneyin; tarayıcı formunun engellediği bir veri API'ye başka bir istemciden ulaşabilir.

Sık sorulan sorular

.NET 9 Minimal API projesine aynı kod doğrudan taşınabilir mi? Bu yazıdaki yerleşik akış .NET 10 içindir; eski sürümlerin doğrulama seçenekleri ayrıca değerlendirilmelidir.

StringLength, alanı zorunlu yapar mı? Hayır. Zorunluluk gerektiğinde Required gibi uygun bir kural da tanımlanmalıdır.

AddValidation kullanıcı yetkisini kontrol eder mi? Hayır. Kimlik doğrulama, yetkilendirme ve hesap kapsamı ayrı sorumluluklardır.

Geçerli bir model işlem mutlaka başarılı demek mi? Hayır. İş kuralları, eşzamanlılık ve depolama hataları sonraki aşamaları etkileyebilir.

Daha Fazla İçerik

Blog sayfasında diğer yazılarımı keşfedin

Tüm Yazılar