Ajout d'un point de terminaison PUT Update dans .NET Aspire sur Linux

Créer le type d'enregistrement de mise à jour

[1:54 - 4:04] L'enregistrement d'insertion de l'épisode précédent acceptait Titre, Description et Priorité. L'enregistrement de mise à jour a besoin de deux champs supplémentaires : l'ID du billet en cours de modification et le timestamp DateCompleted. Tim copie l'enregistrement d'insertion et le ajuste.

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
);

Marquer Id comme [Required] avec une contrainte [Range(1, int.MaxValue)] empêche les valeurs négatives ou zéro d'atteindre la base de données. DateCompleted est un DateTime? nullable car un billet qui n'a pas encore été résolu ne devrait pas nécessiter une date de réalisation. Aucun attribut de validation n'est nécessaire dessus puisqu'un null est un état valide.

Pour s'assurer que les propriétés de l'enregistrement correspondent exactement, Tim extrait la liste des champs de la procédure stockée spTickets_Update. Cet alignement permet à Dapper de mapper l'enregistrement directement sans aucun câblage manuel de propriété à paramètre.

Mapping du point d'extrémité PUT

[4:04 - 5:44] L'enregistrement du point d'extrémité suit le modèle établi. MapPut se lie à la route /api/tickets, et le gestionnaire appelle la procédure stockée avec l'enregistrement de mise à jour :

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();
});

Déclarer Results<NoContent, ValidationProblem> comme type de retour indique au framework que le point de terminaison produit soit un 204 en cas de succès ou un 400 si la validation échoue. La variante ValidationProblem est gérée automatiquement par le pipeline enregistré dans l'épisode précédent ; le gestionnaire lui-même n'a besoin que de retourner le cas de succès.

Il est à noter comment le wrapper Dapper maintient l'accès aux données concis : nom de la procédure stockée, modèle, nom de la chaîne de connexion. Trois paramètres couvrent l'ensemble de l'appel de la base de données. Le wrapper a été écrit plus tôt dans la série et continue de rapporter des bénéfices à mesure que chaque nouveau point d'extrémité le réutilise sans modification.

PUT vs. PATCH : Quand le remplacement complet est important

[6:06 - 6:46] Avant de tester, Tim fait une pause pour clarifier la différence entre PUT et PATCH. Une requête PUT remplace l'intégralité de la ressource : chaque champ dans le corps de la requête remplace la colonne de base de données correspondante, même si l'appelant n'a pas l'intention de le changer. Une requête PATCH met à jour uniquement les champs inclus dans le corps.

Pour le projet Tiny Ticket, PUT est le bon choix parce que le front-end chargera le billet complet, laissera l'utilisateur modifier des champs et renverra l'objet complet. Dans une application de production, Tim mentionne qu'il ajouterait probablement un point d'extrémité PATCH spécifiquement pour les opérations communes à champ unique comme marquer un billet comme terminé, où envoyer l'objet entier juste pour basculer une date semble gaspillé.

Tester la mise à jour via Swagger

[6:46 - 8:26] Tim launches the API and opens Swagger. Avant de tester le PUT, il exécute le point d'extrémité GET all pour vérifier l'état actuel des données. Un des enregistrements de test (ID 109) a des valeurs vides pour titre, description, et priorité de tests antérieurs. Cela devient la cible de la mise à jour.

Il remplit le corps de la requête PUT avec l'ID 109, un titre "Sample Record", une description et une priorité de 5. Après exécution, la réponse revient comme 204. Exécuter GET all à nouveau confirme que l'enregistrement a désormais les valeurs mises à jour.

Pour vérifier la validation, il vide le champ titre et exécute à nouveau. La réponse retourne un 400 avec un message d'erreur structuré : "Le champ titre du billet est requis." Les mêmes attributs de validation du point d'insertion s'appliquent à l'enregistrement de mise à jour car ils utilisent le même modèle d'annotation.

En conclusion : Progrès CRUD

[8:26 - 8:43] Avec le point d'extrémité PUT terminé, la Tiny Ticket API couvre désormais trois des quatre opérations CRUD : lecture (GET all et GET par ID), création (POST) et mise à jour (PUT). Chaque point d'extrémité suit le même modèle structurel, ce qui rend la base de code prévisible. L'opération restante est DELETE, que Tim présente comme le prochain épisode.

Conclusion

[8:38 - 8:43] Ajouter un point de terminaison PUT à une API minimale nécessite un enregistrement de mise à jour dédié avec des attributs de validation, un enregistrement MapPut avec l'URL de la collection, et un appel de procédure stockée via le wrapper d'accès aux données. Le type de retour Results<NoContent, ValidationProblem> permet au framework de gérer les réponses tant sur la réussite que sur l'échec de la validation. Les champs nullables comme DateTime? passent sans nécessiter d'attribut de validation puisque null est une valeur valide pour des données incomplètes.

Navigation de la série : Cet article fait partie de la série C# sur Linux qui construit l'application Tiny Ticket. Précédent : Ajouter un point d'extrémité d'insertion POST. Prochain : Ajouter un point d'extrémité DELETE.

Astuce Exemple : Si votre procédure stockée de mise à jour retourne le compte de ligne modifiée, vérifiez-le avant de retourner 204. Un compte de zéro signifie que l'ID ne correspondait à aucun enregistrement, et vous devriez retourner un 404 au lieu de réussir silencieusement.

Regardez la vidéo complète sur sa chaîne YouTube et obtenez plus d'informations sur la construction de points d'extrémité CRUD dans la série C# sur Linux.