Quoi de neuf dans .NET 7 pour les API minimales ?

.NET 7 est arrivé et a apporté trois fonctionnalités intéressantes aux API minimales. Découvrez dans cet article de blog les nouveautés avec des exemples pratiques.

Les API minimales sont arrivées avec la promesse de simplifier la création de microservices et d’API Web REST, et bien qu’elles aient déjà eu plusieurs fonctionnalités lors de leur lancement dans .NET 6, de nombreuses fonctionnalités sont encore en cours de développement. Avec l’arrivée récente de .NET 7, trois nouvelles fonctionnalités sont disponibles pour les API minimales.

Tout au long de l’article, nous explorerons chacun d’eux à travers des exemples pratiques.

Un bref sur les API minimales

API minimales sont des modèles ASP.NET Core qui sont arrivés avec .NET 6 et ont été très bien accueillis par le public en raison de leur polyvalence et de leur simplicité.

Avec quelques lignes de code et sans cérémonie, des API minimales permettent aux développeurs de créer des microservices sans trop d’effort, car ils éliminent de nombreuses exigences du MVC traditionnel, telles que la création de contrôleurs (bien qu’il soit toujours possible de les utiliser, ils ne sont plus obligatoires maintenant).

Le passé et le présent des API minimales

Les API minimales ont apporté plusieurs fonctionnalités prêtes à l’emploi, telles que le routage, l’autorisation et le CORS hérités de MVC, mais la bonne nouvelle est que des fonctionnalités supplémentaires étaient également présentes depuis la sortie officielle, telles que des déclarations de haut niveau, des types naturels pour les lambdas. et des groupes de méthodes, des utilisations globales par défaut, un nouvel hôte WebApplication et de nouvelles méthodes Map.

Grâce à ces ressources, il est possible de créer une nouvelle API avec quelques lignes de code, en instanciant simplement l’hôte de l’application Web. Ainsi toutes les ressources sont prêtes à l’emploi, permettant au développeur de se concentrer sur les règles métier de l’application et de ne plus perdre de temps avec des cérémonies auparavant obligatoires.

Avec la sortie officielle de .NET 7 le 8 novembre 2022, certaines améliorations précédemment spéculées sont désormais 100 % fonctionnelles et disponibles, telles que les filtres de point de terminaison, les groupes de routage et les résultats typés, ce qui rend les API minimales encore plus puissantes et efficaces.

Quelles nouvelles fonctionnalités .NET 7 a-t-il apportées aux API minimales ?

Comme prévu, .NET 7 a apporté des améliorations significatives à plusieurs technologies de l’univers .NET telles que gRPC, SignalR, Blazor, etc. Et les API minimales n’étaient pas en reste ! Trois grandes améliorations sont désormais disponibles. Ci-dessous, nous allons explorer chacun d’eux.

💡 Tous les exemples présentés dans cet article sont 100 % fonctionnels et sont accessibles dans ce référentiel : code source.

1. Filtres de point de terminaison

Validation d’un paramètre d’URL

Les filtres de point de terminaison sont utiles pour valider les paramètres et le corps envoyés dans une demande à un point de terminaison, enregistrer des informations sur la demande et la réponse, et valider que la demande est redirigée vers une version d’API valide.

Notez dans l’exemple ci-dessous que nous ajoutons la méthode d’extension « AddEndpointFilter » qui valide si les données envoyées dans l’URL de la demande ont plus de 10 caractères. Si c’est le cas, il renvoie un message d’erreur ; sinon, un message de réussite.

Une nouvelle fonctionnalité de .NET 7 est également utilisée, qui est le fournisseur de journaux natif de l’hôte, il n’est donc plus obligatoire d’utiliser d’autres alternatives pour exécuter les journaux.

app.MapPost("sellers/create/{sellerName}", (string sellerName, SellerDb db) =>
{
    var newSeller = new Seller(Guid.NewGuid(), sellerName);
    db.Add(newSeller);
    db.SaveChanges();
    return Results.Ok("Seller created successfully");
})
.AddEndpointFilter(async (invocationContext, next) =>
{
    var sellerName = invocationContext.GetArgument<string>(0);

    if (sellerName.Length > 10)
    {
        app.Logger.LogInformation($"Error when creating the new seller");
        return Results.Problem("Seller Name must be a maximum of 10 characters!");
    }
    return await next(invocationContext);
});

Validation d’un objet

En plus des paramètres d’URL, il est également possible de valider les objets envoyés par le corps de la requête, comme illustré dans l’exemple ci-dessous :

app.MapPut("/sellers/update/{id}", async (Seller seller, int id, SellerDb db) =>
{
    var dbSeller = await db.Sellers.FindAsync(id);

    if (dbSeller is null) return Results.NotFound();

    dbSeller.Name = seller.Name;

    await db.SaveChangesAsync();

    return Results.NoContent();
}).AddEndpointFilter(async (efiContext, next) =>
{
    var tdparam = efiContext.GetArgument<Seller>(0);

    var validationError = Utilities.IsValid(tdparam);

    if (!string.IsNullOrEmpty(validationError))
    {
        app.Logger.LogInformation($"Error when updating the new seller: {validationError}");
        return Results.Problem(validationError);
    }
    return await next(efiContext);
});

Notez que de manière simple, il est possible de valider un ou plusieurs objets passés par le corps de la requête avant même que le point de terminaison ne soit exécuté. La méthode « IsValid » est une méthode statique personnalisée pour valider les données envoyées et renvoyer un message d’erreur si elles ne sont pas valides.

public static class Utilities
{
    public static string IsValid(Seller seller)
    {
        string errorMessage = string.Empty;

        if (string.IsNullOrEmpty(seller.Name))
            errorMessage = "Seller name is required";

        return errorMessage;
    }
}

La validation des données avant le point de terminaison empêche les erreurs simples d’atteindre la couche de service et d’être rapidement interceptées.

2. Résultats typés

Avec des résultats typés, il est possible de retourner des résultats fortement typés par des API minimales.

Notez dans l’exemple ci-dessous que la méthode GetSeller renvoie un TypedResults quel que soit le résultat, de manière simple et avec peu de code.

app.MapGet("sellers/getSeller/{sellerId}", (Guid id, SellerDb db) =>
{
    return GetSeller(id, db);
});

static async Task<Results<Ok<Seller>, NotFound>> GetSeller(Guid id, SellerDb db) =>
    await db.Sellers.FirstOrDefaultAsync(x => x.Id == id) is Seller item ? TypedResults.Ok(item) : TypedResults.NotFound();

3. Groupes de routage

Les groupes routés sont une nouvelle fonctionnalité de .NET 7 qui vous permet d’organiser des groupes de points de terminaison avec un préfixe commun.

À l’aide de MapGroup, vous pouvez réduire le code répétitif et également personnaliser des groupes entiers de points de terminaison avec un seul appel à des méthodes telles que RequireAuthorization et WithMetadata, qui ajoutent des métadonnées de point de terminaison.

Observez dans le code suivant comment l’organisation des groupes de routes peut être faite :

app.MapGroup("/public/sellers")
    .MapSellersApi()
    .WithTags("Public");

app.MapGroup("/private/sellers")
    .MapSellersApi()
    .WithTags("Private")
    .RequireAuthorization("Manager");

Le code ci-dessus définit deux groupes de routes, la première publique et la seconde privée.

Remarquez maintenant comment la méthode « MapSellersApi » est implémentée : elle reçoit et renvoie un objet de type « RouteGroupBuilder » et implémente la méthode « GetAllSellers », qui renvoie une liste de vendeurs.

public static class MapSellers
{
    public static RouteGroupBuilder MapSellersApi(this RouteGroupBuilder group)
    {
        group.MapGet("https://www.telerik.com/", GetAllSellers);
        return group;
    }

    public static Ok<List<Seller>> GetAllSellers(SellerDb db)
    {
        var sellers = db.Sellers;
        return TypedResults.Ok(sellers.ToList());
    }
}

Dans l’interface Swagger, les points de terminaison apparaissent séparés par les balises Public et Private, comme indiqué dans l’image ci-dessous :

Conclusion

Les API minimales sont une fonctionnalité très utile et ont attiré l’attention de Microsoft en raison de leur excellente réception publique.

Comme indiqué tout au long de l’article, .NET 7 a apporté trois nouvelles fonctionnalités qui facilitent encore plus le développement ASP.NET Core applications. Donc, chaque fois que l’occasion se présente, assurez-vous de les utiliser.

Les références