學習C#

在Linux上新增.NET Aspire中的PUT更新端點

Tim Corey

8m 43s

當API能夠讀取和建立記錄後，下一步的操作就是更新現有的記錄。 PUT端點用呼叫者提供的資料替換整個資源，這意味著請求正文需要每個欄位，而不僅僅是更改的那些。 PUT（完全替換）和PATCH（部分修改）之間的區別對於您如何設計輸入型別和呼叫者如何與端點交互至關重要。

在他的视频"在Linux中通過.NET Aspire建立PUT更新端點"中，Tim Corey為Tiny Ticket API新增了更新端點，建立了包含插入記錄時未包括的字段（如ID和完成日期）的專用更新記錄型別，應用了驗證屬性，並通過Swagger進行了往返測試。此集遵循先前部分建立的同樣模式，但引入了一個可空的DateTime字段以及PUT和PATCH語義的區別。如果您正在生成最小API中的CRUD端點，這篇文章涵蓋了更新方面。

建立更新記錄型別

[1:54 - 4:04] 上一集的插入記錄接受了標題、描述和優先順序。更新記錄需要兩個額外的字段：被修改工單的ID和DateCompleted時間戳。Tim複製了插入記錄並進行調整。

public record TicketUpdateRecord(
    [Required, Range(1, int.MaxValue)] int Id,
    [Required, MinLength(1)] string Title,
    [Required] string Description,
    DateTime? DateCompleted,
    [Range(1, 5)] int Priority
);

public record TicketUpdateRecord(
    [Required, Range(1, int.MaxValue)] int Id,
    [Required, MinLength(1)] string Title,
    [Required] string Description,
    DateTime? DateCompleted,
    [Range(1, 5)] int Priority
);

將[Range(1, int.MaxValue)]約束可以防止負值或零進入資料庫。 DateTime?，因為尚未解決的票證不應要求完成日期。因為null是有效狀態，所以不需要驗證屬性。

為了確保記錄屬性完全匹配，Tim從spTickets_Update儲存過程中抽取字段列表。這種對齊方式讓Dapper能夠直接映射記錄，而不需要手動的屬性到參數的連接。

映射PUT端點

[4:04 - 5:44] 端點註冊遵循既定的模式。 /api/tickets路由，處理程式使用更新記錄調用儲存過程：

app.MapPut("/api/tickets", async Task<Results<NoContent, ValidationProblem>>
    (TicketUpdateRecord ticket, ISqlDataAccess sql) =>
{
    await sql.SaveDataAsync("dbo.spTickets_Update", ticket, "TicketDB");
    return TypedResults.NoContent();
});

app.MapPut("/api/tickets", async Task<Results<NoContent, ValidationProblem>>
    (TicketUpdateRecord ticket, ISqlDataAccess sql) =>
{
    await sql.SaveDataAsync("dbo.spTickets_Update", ticket, "TicketDB");
    return TypedResults.NoContent();
});

宣告Results<NoContent, ValidationProblem>為返回型別告訴框架端點在成功時產生204或當驗證失敗時產生400。 ValidationProblem變體由先前部分註冊的管道自動處理；處理程式本身只需要返回成功的情況。

值得注意的是Dapper包裝器如何保持資料存取簡潔明快：儲存過程名稱、模型、連接字串名稱。三個參數涵蓋整個資料庫調用。包裝器是在本系列早些時候編寫的，並且隨著每個新端點不做更改而重複使用，繼續發揮作用。

PUT vs. PATCH：何時完全替換很重要

[6:06 - 6:46] 在測試之前，Tim暫停以澄清PUT和PATCH之間的區別。 PUT請求替換整個資源：請求正文中的每一個欄位都覆蓋相應的資料庫列，即使呼叫者並不打算更改它。 PATCH請求僅更新正文中包含的字段。

對於Tiny Ticket項目，PUT是正確的選擇，因為前端將會載入完整的票據，允許使用者編輯欄位，然後將完整的物件發回。 Tim提到在生產應用程式中，他可能會專門為標記票證為已完成等常見的單字段操作新增一個PATCH端點，因為僅為更改一個日期而發送整個物件顯得浪費。

通過Swagger測試更新

[6:46 - 8:26] Tim launches the API and opens Swagger. 在測試PUT之前，他運行GET all端點以檢查資料的當前狀態。其中一個測試記錄（ID 109）從 tidigare 測試中具有空的標題、描述和優先順序值。這成為更新的目標。

他用ID 109填寫PUT請求正文，標題"Sample Record"，描述，和優先順序5。在執行後，響應回來204。再一次運行GET all確認記錄現在具有更新的值。

為了驗證驗證規則，他清空標題欄位並再次執行。響應返回400，帶有結構化的錯誤資訊："需要票證標題欄位。"來自插入端點的同樣驗證屬性被沿用到更新記錄中，因為它們使用相同的註解模式。

結尾總結：CRUD進展

[8:26 - 8:43] 隨著PUT端點的完成，Tiny Ticket API現已涵蓋四個CRUD操作中的三個：讀取（GET all和GET by ID）、建立（POST）和更新（PUT）。每個端點都遵循相同的結構模式，這使得程式碼庫的預測性變得更高。剩餘的操作是DELETE，Tim預覽作為下一集的內容。

結論

[8:38 - 8:43] 新增PUT端點到最小API需要專用的更新記錄與驗證屬性，與集合URL的MapPut註冊，通過資料存取包裝器調用儲存過程。 Results<NoContent, ValidationProblem>返回型別讓框架處理成功和驗證失敗的回應。像DateTime?這樣的可空字段可以通過而不需要驗證屬性，因為null是未完成資料的有效值。

**系列導覽：**這篇文章是C# on Linux系列的一部分，構建Tiny Ticket應用程式。上一章：新增POST插入端點。下一章：新增DELETE端點。

範例提示：如果您的更新儲存過程返回已修改的行數，在返回204之前檢查它。行數為零意味著ID與任何記錄不匹配，您應返回404而不是靜默成功。

在他的YouTube頻道上觀看完整影片，獲得更多關於在C# on Linux系列中構建CRUD端點的見解。