.NET 10 Minimal APIs'de Veri Doğrulama

Ayar: Basit Minimal API

[0:44 - 1:35] Demo, .NET 10 üzerinde çalışan bir çıplak ASP.NET Core Minimal API projesi ile başlıyor. Yüzey alanı kasıtlı olarak küçük tutulmuş: her birinin farklı bir modeli kabul ettiği iki POST ucu.

app.MapPost("/person", (Person person) => Results.Ok(person));
app.MapPost("/login", (LoginModel login) => Results.Ok(login));

app.MapPost("/person", (Person person) => Results.Ok(person));
app.MapPost("/login", (LoginModel login) => Results.Ok(login));

Person modeli temel kimlik alanlarını taşır. LoginModel kimlik bilgilerini yönetir: bir e-posta adresi, bir parola ve bir parola onay alanı. Her ikisi de JSON gövdesi olarak gönderilir. Şu anda hiçbir giriş doğrulaması yoktur; API aldığı her şeyi kabul eder, boş dizeler ve hatalı biçimlendirilmiş e-posta adresleri dahil.

.NET 10 ile birlikte gelen modern OpenAPI arayüzü Scalar, test isteklerini doğrudan tarayıcıdan göndermekte kullanılır, böylece doğrulama bağlanmadan önce ve sonra API'nin tam olarak ne döndüğünü görmek kolaylaşır.

Doğrulama Servisini Kaydetme

[2:36 - 3:06] Herhangi bir doğrulama özelliği etkisini göstermeden önce, hizmet seviyesinde katılmanız gerekir. Hizmet kayıt bloğunuzda tek bir çağrı, tüm Minimal API uçları için zorlamayı etkinleştirir:

builder.Services.AddValidation();

builder.Services.AddValidation();

O tek satır, tüm yapılandırma adımıdır. Eklenen bir ara katman yok, takılacak bir boru hattı aşaması yok. Hizmet kaydedildikten sonra çerçeve otomatik olarak devralır. Bu çağrıyı atlarsanız, veri anotasyon özellikleriniz modelde mevcut olur ancak asla değerlendirilmez ve istekler içerdikleri şeylere bakılmaksızın geçebilir.

Bu, ilk hata ayıklama adımı olarak dikkate almaya değer: eğer doğrulama sessizce hiçbir şey yapmıyorsa, AddValidation() genellikle eksik parçadır.

Bir Sınıf Modeline Doğrulama Ekleme

[3:00 - 3:55] Servis kaydedildikten sonra, sınıf tabanlı bir modele doğrulama eklemek, özellikleri veri anotasyon özellikleri ile süslemekten ibarettir:

public class Person
{
    [Required]
    public string FirstName { get; set; }

    [Required]
    public string LastName { get; set; }
}

public class Person
{
    [Required]
    public string FirstName { get; set; }

    [Required]
    public string LastName { get; set; }
}

Dosyanın en üstüne System.ComponentModel.DataAnnotations using yönergesini ekledikten sonra FirstName ve LastName'yi [Required] olarak işaretlemek, bunların doğrulandığını sağlar. Scalar aracılığıyla boş bir gövdeyle POST isteği göndermek artık yapılandırılmış bir hata yanıtı içeren 400 Bad Request döndürür:

{
  "errors": {
    "FirstName": ["The FirstName field is required."],
    "LastName": ["The LastName field is required."]
  }
}

Özel hata işleme yok, filtre özellikleri yok. Çerçeve bu yanıtı otomatik olarak sağlar ve kontrol işleyici gövdeniz çalıştırılmadan önce yapılır, böylece uç nokta mantığı içinde boşa karşı koruma yapmanıza asla gerek kalmaz.

Bir Kayda Doğrulama Uygulama

[4:29 - 5:30] Aynı özellikler C# kayıtlarında çalışır, fakat genellikle ana yapıcıda tanımlandıkları için sözdizimi biraz farklıdır.

public record LoginModel(
    [Required] [EmailAddress] string Email,
    [Required] string Password,
    [Required] string ConfirmPassword
);

public record LoginModel(
    [Required] [EmailAddress] string Email,
    [Required] string Password,
    [Required] string ConfirmPassword
);

Yapıcı parametrelerindeki nitelikler üretilen özelliklere uygulanır; dolayısıyla [Required] ve [EmailAddress] bir sınıftaki gibi tam olarak davranır. "notanemail" gibi geçersiz bir e-posta ile gönderilen istek artık 400 döndürür ve Email alanını geçersiz olarak tanımlar.

[Compare] niteligini ConfirmPassword'in Password ile eslesmesi gerektigini zorunlu kilmak icin de kullanabilirsiniz. Bir kayıtta, öz nitelik hedefleri, derleyicinin oluşturulan üyeyi kastettiğinizi bilmesi gerektiğinden, yapıcı parametresi yerine açık bir yönlendirme gerektirir:

[property: Compare(nameof(Password))]
string ConfirmPassword

[property: Compare(nameof(Password))]
string ConfirmPassword

[property:] hedefi, derleyiciye niteliği parametre yerine üretilen üye ile ilişkilendirmesini bildirir. Bu olmadan [Compare] derlenir ancak çalışma zamanında hiçbir zaman çalışmaz. Bu bağlamda kayıtlar ve sınıflarla çalışmanın en zorlu kısmı budur: sınıf özellikleri nitelikleri doğal olarak kabul eder, kayıt parametreleri ise üye seviyesinde çalışan herhangi bir şey için açık hedef gerektirir.

Genel Erişim Belirleyicisi Gereksinimi

[7:51 - 9:00] Yaygın bir tuzaktır, gözden kaçırmak kolaydır ve üzerine düşüldüğünde hata mesajı üretmez. Doğrulama sistemi, çalışma zamanında model türlerinizi incelemek için yansımayı kullanır; yansımanın bir türün üyelerini bulabilmesi için türün kendisinin public olarak işaretlenmesi gerekir.

// Validation will NOT run; the class is internal by default
class Person { ... }

// Validation runs correctly
public class Person { ... }

// Validation will NOT run; the class is internal by default
class Person { ... }

// Validation runs correctly
public class Person { ... }

Aynı kural kayıtlara da uygulanır. Eger modeliniz erişim belirticisi olmadan ilan edilirse, C# varsayılan olarak internal olarak kabul eder ve hizmet bunu tamamen atlar. Uç noktanız hala isteği alır, işleyici yine de çalıştırılır ve hata döndürülmez; kontroller sadece sessizce hiçbir şey yapmaz.

Bu, ASP.NET Core davranışıdır, Minimal API'lere özgü değildir; ancak bu projeler genellikle kompakt olduğundan burada daha sık karşılaşılır ve geliştiriciler bazen görünürlüğü düşünmeden modelleri iç içe ya da Program.cs'da tanımlar.

Projenizi denetlemenin hizli bir yolu: bir uç nokta işlemcisine gonderilen her model türü, acık bir sekilde public olarak isaretlenmelidir. Değilse, ne kadar çok özellik olursa olsun, çerçeve çalışmaz.

Ne Doğrulayabilirsiniz?

Yerleşik veri anotasyon özellikleri, herhangi bir ekstra iş yapmadan en yaygın senaryoları kapsar:

• [Required] boş veya null değerleri reddeder
• [EmailAddress] bir e-posta dizesinin biçimini doğrular
• [Compare] iki özelliğin eşleşip eşleşmediğini kontrol eder, parola doğrulama için faydalıdır
• [Range] sayısal veya tarih sınırlarını zorunlu kılar
• [StringLength] isteğe bağlı bir minimum ile dize uzunluğunu sınırlandırır
• [RegularExpression] özel bir desene karşı doğrular

Bunların hepsi, sorgu dizesi parametreleri, istek başlıkları ve JSON gövdeleri arasında çalışır. Aynı model sınıfı veya kayıt, özelliklerinden herhangi birini değiştirmeden farklı kaynaklardan bağlanabilir.

Sonuç

[7:46 - end] AddValidation() kayıtlı ve modelleriniz veri anotasyonu özelliklerine sahip olduğunda, Minimal API'ler sınıflar ve kayıtlar dahil olmak üzere giriş kısıtlamalarını otomatik olarak uygular. Bunu .NET 10'da çalışır hale getirmek için builder.Services.AddValidation()'ı bir kez çağırın, model özelliklerinizi standart doğrulama nitelikleriyle işaretleyin ve her model türünü public olarak bildirdiğinizden emin olun.

Kayıt ve public değiştirici gereksinimindeki [property:] hedefine gercekten dikkat edilmesi gereken tek onemli konudur. Gözden kaçırmak kolaydır ve derleme hatası yerine sessiz başarısızlıklar üretir, bu yüzden giriş kontrolleri hiçbir şey yapmıyor gibi göründüğünde onları kontrol listenizde tutun.

Eksiksiz kaynak kodu incelemesi için Tim Corey's YouTube kanalındaki tam videoyu izleyin.