Linux'ta .NET Aspire'da Doğrulama ile POST Ekleme Endpointi Ekleme

Kayıt Türü Eklemeyi Yaratma

[1:46 - 4:43] Tim, bir uç nokta oluşturmadan önce bir ekleme isteğinin şeklini temsil eden bir veri aktarım nesnesi oluşturur. Mevcut TicketModel veritabanının otomatik olarak oluşturduğu Id ve CreatedDate gibi alanlar içerir. Bunları bir POST gövdesinde kabul etmek ya göz ardı edilir ya da çatışmalara sebep olur, bu yüzden ayrı bir tür girişi yalnızca çağrının sağlaması gereken alanlarla sınırlar.

public record TicketInsertRecord(string Title, string Description, int Priority);

public record TicketInsertRecord(string Title, string Description, int Priority);

record yerine class kullanmak kasıtlı bir seçimdir. Kayıtlar, bir istek yük lemmaği semantiğine uyan varsayılan olarak değer tabanlı eşitlik ve değişmezlik sağlar: veri gelir, doğrulanır, veritabanına aktarılır ve arasında hiç değiştirilmez. Üç özellik (Başlık, Açıklama, Öncelik) doğrudan spTickets_Insert saklı prosedürünün parametrelerini eşleştirir.

POST Uç Noktasını Haritalama

[4:43 - 9:51] Kayıt türü tanımlandığında, uç nokta kaydı GET yollarıyla aynı deseni izler ancak MapPost kullanır ve isteği gövdesini ekleme kaydına bağlar.

app.MapPost("/api/tickets", async (TicketInsertRecord ticket, IDbConnection db) =>
{
    await db.SaveDataAsync("spTickets_Insert", ticket);
    return Results.NoContent();
});

app.MapPost("/api/tickets", async (TicketInsertRecord ticket, IDbConnection db) =>
{
    await db.SaveDataAsync("spTickets_Insert", ticket);
    return Results.NoContent();
});

Güzergahın bir ID segmenti olmadan, bir koleksiyon URL'sine POST gönderirken yeni bir kaynak oluşturduğu REST gelenekleriyle eşleşen /api/tickets olduğunu fark edin. İşleyici, tüm ticket nesnesini bir parametre paketi olarak kullanarak saklı prosedürü çağırır. Dapper, kayıt özelliklerini SQL parametrelerine isimle eşler.

Results.NoContent() döndürmek 204 durum kodunu gönderir. Tim, mantığı açıklar: ekleme başarılı oldu, ama yanıt gövdesinde anlamlı bir şey döndürmek yok. Bazı API'ler, yeni oluşturulan nesneyi 201 Created durumu ve yeni kaynağa işaret eden bir Location başlığı ile geri döndürür, bu geçerli bir alternatiftir. Tiny Ticket projesi için 204, işleri sade tutar.

Swagger Yoluyla Eklemeyi Test Etme

[9:51 - 14:43] Tim launches the project and navigates to Swagger. POST uç noktası, TicketInsertRecord özelliklerine uygun bir istek gövdesi şemasıyla görünür. Başlık, açıklama ve öncelik içeren bir test bileti doldurur, ardından isteği yürütür.

Bir 204 döner, eklemenin başarılı olduğunu onaylar. Verilerin gerçekten kaydedildiğini doğrulamak için, tüm GET uç noktasına geçer ve bunu yürütür. Yeni bilet, orijinal test kayıtlarının yanında listede görünür.

Testin ayrıca ortaya çıkardığı şey, doğrulama olmadan mevcut olan boşluktur: boş bir başlık göndermek, eksik bir açıklama veya 99 önceliği ile bir işlem yapmak, hepsi 204 durum kodu ile başarılı olur. Veritabanı, API'nin gönderdiği her şeyi kabul eder. Bu boşluk bir sonraki bölümü motive eder.

Yerleşik Doğrulama Ekleme

[14:43 - 18:28] .NET 10 ile başlayarak, minimal API'ler bir doğrulama hattı desteği sunar ve bu, girdi türünden veri açıklama özniteliklerini okuyarak, işleyici çalışmadan önce geçersiz istekleri reddeder. Tim, bunu iki adımda bağlar.

İlk olarak, doğrulama hizmetlerini Program.cs içine kaydedin. Bu tek satır, tüm işlem hattını etkinleştirir:

builder.Services.AddValidation();

builder.Services.AddValidation();

Hizmet kaydedildikten sonra, çerçeve, işleyici çalışmadan önce her istek gövdesini doğrulama nitelikleri için inceler. İkinci adım, her bir alanın uyması gereken kurallarla ekleme kaydını açıklamaktır:

public record TicketInsertRecord(
    [Required, MinLength(1)] string Title,
    [Required] string Description,
    [Range(1, 5)] int Priority
);

public record TicketInsertRecord(
    [Required, MinLength(1)] string Title,
    [Required] string Description,
    [Range(1, 5)] int Priority
);

[Required], alanın mevcut ve null olmadığından emin olur. [MinLength(1)], boş dizelerin gerekli kontrolünden geçmesini engeller (çünkü boş bir dize teknik olarak null değildir). [Range(1, 5)] önceliği geçerli bir katmana sınırlar. Bu özellikler, yıllardır ASP.NET MVC denetleyicilerinin kullandığı aynı System.ComponentModel.DataAnnotations türleridir, ancak şimdi ekstra ara yazılım olmadan minimalist API'lerde çalışır.

Kaydettikten ve yeniden başlattıktan sonra, Tim boş bir başlık ve 10 öncelik ile bir istek gönderir. Yanıt, 400 Hatalı İstek olarak yapılandırılmış bir hata gövdesi ile geri döner:

{
    "errors": {
        "Title": ["The Title field is required."],
        "Priority": ["The field Priority must be between 1 and 5."]
    }
}

Doğrulama hattı, çalıştırıcı devreye girmeden önce isteği kısa devre yapar, böylece geçersiz veri veritabanına ulaşmaz. Hata yanıtı, API tüketicilerinin programlı bir şekilde ayrıştırabileceği RFC 7807 Problem Detayları formatını takip eder.

Başlangıçta Swagger'ı Otomatik Başlatma

[19:44 - 20:31] Küçük bir yaşam kalitesi iyileştirmesi bölümü kapatıyor. Tim her API başlattığında /swagger'ı tarayıcı URL'sine el ile yazmak zorundaydı. Bunu otomatikleştirmek için API projesinin Properties/launchSettings.json dosyasını açar ve HTTPS profiline bir launchUrl özelliği ekler.

{
    "profiles": {
        "https": {
            "launchUrl": "swagger"
        }
    }
}

Bir sonraki başlatmada, tarayıcı varsayılan sayfa yerine doğrudan Swagger UI sayfasını açar. Bu, bir tam geliştirme oturumu boyunca biriken birkaç saniye tasarrufu sağlar.

Sonuç

[20:09 - 20:31] Minimal bir API'ye bir POST uç noktası eklemek, özel bir giriş kaydı oluşturmayı, onu koleksiyon URL'si ile MapPost eşlemeyi ve kayıt nesnesi olarak saklı prosedürü çağırmayı içerir. .NET 10'da doğrulama, bir hizmet kaydı ve kayıt özelliklerinde standart veri notu özniteliklerini gerektirir. Çerçeve, 400 yanıt biçimlendirmesini otomatik olarak işler.

Dizi gezintisi: Bu makale Linux üzerinde C# serisinin bir parçası olup Tiny Ticket uygulamasını inşa etmektedir. Önceki: ID'ye Göre Getirme Uç Noktası Ekleme. Sonraki: PUT Güncelleme Uç Noktası Ekleme.

Örnek İpucu: Eklenen kayıt prosedürünüz yeni kaydın ID'sini döndürdüğünde, çağrıcılara ulaşabilecekleri 201 durumu ve yer başlığı ile dönecek şekilde Results.NoContent() iadesini Results.Created($"/api/tickets/{newId}", result) olarak değiştirin.

Tam videoyu YouTube Kanalında izleyin ve Linux serisinde C# ile yazma uç noktaları oluşturma hakkında daha fazla bilgi edinin.