Une visite des API minimales dans .NET 6

Les API minimales vous permettent de créer des API sans la surcharge de la solution MVC compliquée. En savoir plus pour comprendre comment tout cela fonctionne et ce que cela signifie pour la création d'API dans ASP.NET Core.
Lors du développement d'API dans ASP.NET Core, vous êtes traditionnellement obligé d'utiliser ASP.NET Core MVC. Contrairement à de nombreux principes fondamentaux de .NET Core, les projets MVC vous offrent tout et l'évier de la cuisine. Après avoir créé un projet à partir du modèle MVC et remarqué tout ce qu'il contient, vous pensez peut-être : Tout ceci pour obtenir des produits à partir d'une base de données ? Malheureusement, avec MVC, il en faut tellement cérémonie pour créer une API.
En regardant les choses d'une autre manière : si je suis un nouveau développeur ou un développeur qui regarde .NET pour la première fois (ou après une longue pause), c'est une expérience frustrante – non seulement je dois apprendre à créer une API, je dois comprendre tout ce que j'ai à faire dans ASP.NET Core MVC. Si je peux créer des services dans Node avec seulement quelques lignes de code, pourquoi ne puis-je pas le faire dans .NET ?
À partir de .NET 6 Preview 4, vous le pouvez !
L'équipe ASP.NET a a déployé des API minimalesun nouveau moyen simple de créer de petits microservices et des API HTTP dans ASP.NET Core. Des API minimales s'intègrent aux capacités d'hébergement et de routage d'ASP.NET Core et vous permettent de créer des API entièrement fonctionnelles avec seulement quelques lignes de code. Cela ne remplace pas la création d'API avec MVC – si vous créez des API complexes ou préférez MVC, vous pouvez continuer à l'utiliser comme vous l'avez toujours fait – mais c'est une bonne approche pour écrire des API sans fioritures.
Dans cet article, je ' Je vais vous donner une visite guidée des API minimales. Je vais d'abord vous expliquer comment cela fonctionnera avec .NET 6 et C# 10. Ensuite, je décrirai comment commencer à jouer avec les bits de prévisualisation aujourd'hui. Enfin, nous examinerons la voie à suivre.
Écrire une API minimale avec trois lignes de code
Si vous souhaitez créer une API minimale, vous pouvez effectuer une simple requête GET avec seulement trois lignes de code.[19659009]var application = WebApplication.Créer(args);
app.MapGet("/", () => "Hello World!" );
wait app.RunAsync();
C'est tout ! Lorsque j'exécute ce code, j'obtiens une réponse 200 OK
avec ce qui suit :
HTTP/1.1 200 OK
Connexion : fermer
Date : mar. 01 juin 2021 02:52:42 GMT
Serveur : Crécerelle
Encodage de transfert : fragmenté
Bonjour le monde!
Comment est-ce possible ? Grâce aux instructions de haut niveau, une amélioration bienvenue de C# 9vous pouvez exécuter un programme sans déclaration d'espace de noms, déclaration de classe ou même méthode Main(string[] args)
. Cela seul vous permet d'économiser neuf lignes de code. Même sans la méthode Main
nous pouvons toujours déduire des arguments—le compilateur s'en charge pour vous.
Vous remarquerez également l'absence d'instructions using
. En effet, par défaut dans .NET 6, ASP.NET Core utilisera les utilisations globales—une nouvelle façon de déclarer vos utilisations
dans un seul fichier, évitant ainsi d'avoir à les déclarer dans des fichiers sources individuels. Je peux conserver mes utilisations globales dans un fichier dédié .usings
comme vous le verrez ici :
global using System;
global using Système.Net.Http;
global utilisant Système.Filetage.Tâches;
global en utilisant Microsoft.AspNetCore.Builder;
global en utilisant Microsoft .Extensions.Hébergement;
global en utilisant Microsoft.Extensions.DependencyInjection;
Si vous avez travaillé avec des fichiers Razor dans ASP.NET Core, cela revient à utiliser un fichier _Imports.razor
qui vous permet de conserver les directives @using
de vos vues Razor. Bien sûr, ce sera un comportement prêt à l'emploi mais ne doit pas remplacer ce que vous faites maintenant. Utilisez ce qui vous convient le mieux.
Pour revenir au code, après avoir créé une instance WebApplication
ASP.NET Core utilise MapGet
pour ajouter un point de terminaison qui correspond à n'importe quel GET
requêtes à la racine de l'API. Pour le moment, je ne renvoie qu'une chaîne. Je peux utiliser les améliorations lambda apportées à C# 10 pour transmettre un rappel. Les cas d'utilisation courants peuvent être un modèle ou un contexte Entity Framework. Nous fournirons quelques exemples pour montrer sa flexibilité.
Utiliser HttpClient avec des API minimales
Si vous écrivez une API, vous utilisez probablement HttpClient
pour consommer vous-même les API. Dans mon cas, j'utiliserai le HttpClient
pour appeler l'Ron Swanson Quotes API pour m'inspirer. Voici comment je peux passer un appel async
pour que cela se produise :
var app = WebApplication.Create( arguments);
app.MapGet("/quote", async () =>
wait[19659034]nouveau HttpClient().GetStringAsync("https://ron-swanson-quotes.herokuapp.com/v2/quotes"[19659011]));
wait app.RunAsync();
Lorsque j'exécute cette réponse, je vais obtenez une citation merveilleuse avec laquelle je ne serai jamais en désaccord :
HTTP/1.1 200 OK
Connexion : fermer
Date: ven. 04 juin 2021 11:27:47 GMT
Serveur : Crécerelle
Encodage de transfert : fragmenté
["Dear frozen yogurt, you are the celery of desserts. Be ice cream or be nothing. Zero stars."]
Dans des scénarios plus réels, vous appellerez probablement GetFromJsonAsync
avec un modèle, mais cela peut être fait tout aussi facilement. En parlant de modèles, voyons comment cela fonctionne.
Travailler avec des modèles
Avec juste une ligne de code supplémentaire, je peux travailler avec un enregistrement Person
. Les enregistrements, également une fonctionnalité C# 9, sont des types de référence qui utilisent l'égalité basée sur les valeurs et aident à imposer l'immuabilité. Avec les paramètres positionnels, vous pouvez déclarer un modèle en une seule ligne de code. Vérifiez ceci :
var application = WebApplication.Créer(args);
app.MapGet("/person", () => new Person[19659011]("Bill", "Gates"));
wait app.RunAsync( );
public record Person(string FirstName, string LastName)[19659011];
Dans ce cas, la liaison de modèle est gérée pour nous, car nous obtenons cette réponse en retour :
HTTP/1.1 200 OK
Connexion : fermer
Date: ven. 04 juin 2021 11:36:31 GMT
Type de contenu : application/json ; jeu de caractères=utf-8
Serveur : Crécerelle
Encodage de transfert : fragmenté
{
"firstName": "Bill",
"lastName": "Portes"
}
À mesure que nous nous rapprochons de la version .NET 6, cela fonctionnera probablement aussi avec les annotations, comme si je voulais que mon LastName
soit requis :
public record Personne(string FirstName, [Required] string LastName);
Jusqu'à présent , nous n'avons rien transmis à nos lambdas en ligne. Si nous définissons un point de terminaison POST
nous pouvons transmettre le Person
et afficher ce qui a été transmis. (Bien sûr, un scénario idéal plus courant du monde réel serait de passer dans une base de données Je vais vous laisser cela comme un exercice, car la configuration d'une base de données et l'initialisation des données sortent du cadre de cet article.)
var app = WebApplication. Créer(args);
app.MapPost("/person", (Person p) => $"Nous avons une nouvelle personne : {p.FirstName} {p.LastName}");
wait app.RunAsync([19659011]);
public record Person(string FirstName, string LastName);
Lorsque j'utilise un outil tel que Fiddler (wink, wink), j'obtiens la réponse suivante :
HTTP/1.1 200 OK
Connexion : fermer
Date: ven. 04 juin 2021 11:36:31 GMT
Type de contenu : application/json ; jeu de caractères=utf-8
Serveur : Crécerelle
Encodage de transfert : fragmenté
Nous avons une nouvelle personne : Ron Swanson
Utilisez le middleware et l'injection de dépendances avec des API minimales
Vos API de niveau production – sans vous offenser, Ron Swanson – devront gérer les dépendances et le middleware. Vous pouvez gérer tout cela via votre fichier Program.cs
car il n'y a pas de fichier Startup
prêt à l'emploi. Lorsque vous créez un WebApplicationBuilder
vous avez accès au fidèle IServiceCollection
pour enregistrer vos services.
Voici un exemple courant, lorsque vous souhaitez uniquement afficher les détails des exceptions lors du développement local.
var builder = WebApplication.CreateBuilder(args);
var application = builder.Build();
if (app.Environnement. Est-Développement())
{
app.UseDeveloperExceptionPage();
}
Rien ne vous empêche de créer vous-même un fichier Startup
comme vous l'avez toujours fait, mais vous pouvez également le faire ici dans Program.cs
.
Essayez des API minimales Vous-même
Si vous souhaitez essayer vous-même des API minimales dès maintenant, vous avez deux choix : vivre à la limite ou vivre à la pointe de la technologie.
Live On The Edge : Utilisation des bits de prévisualisation
Démarrage avec Preview 4, vous pouvez utiliser cette version pour explorer le fonctionnement des API minimales, avec quelques mises en garde :
- Vous ne pouvez pas utiliser les utilisations globales
- Les lambdas seront castés
Les deux sont résolus avec C# 10, mais l'Aperçu 4 bits utilise C# 9 pour l'instant. Si vous souhaitez utiliser Preview 4, installez le dernier SDK .NET 6 —Je vous recommande également d'installer le dernier Visual Studio 2019 Preview . Voici à quoi ressemblerait notre premier exemple. (Je sais, six lignes de code. Quelle traînée.)
using System;
using Microsoft.AspNetCore.Builder ;
en utilisant Microsoft.Extensions.Hébergement;
var app = WebApplication.Créer(args);
app.MapGet("/", (Func<string>) (() => "Bonjour tout le monde !"));
attendez application.[19659010]RunAsync();
Si vous souhaitez démarrer avec votre propre application, vous pouvez exécuter les opérations suivantes à partir de votre terminal préféré :
dotnet new web -o MyMinimalApi
Vivre à la pointe de la technologie : utilisez C# 10 et les derniers outils de compilation
Si vous souhaitez vivre à la pointe de la technologie, vous pouvez utiliser les derniers outils de compilation et C# 10.
Tout d'abord, vous aurez besoin pour ajouter un nuget.config
personnalisé à la racine de votre projet pour obtenir les derniers outils :
<configuration>
<packageSources>[19659220]<clear />
<add key="nuget" value ="https://api.nuget.org/v3/index.json" />
<ajouter clé ="dotnet6" value="https://dnceng.pkgs.visualstudio.com/public/_packaging/dotnet6/nuget /v3/index.json" />
<add key="dotnet-tools"[1 9459004] valeur="https://pkgs.dev.azure.com/dnceng/public/_packaging/dotnet-tools/nuget/v3/index.json" />
</packageSources>
</configuration>
Dans votre fichier de projet, ajoutez les éléments suivants à utiliser les derniers outils de compilation et permettent au projet de lire vos utilisations globales à partir d'un fichier .usings
:
<ItemGroup>
<PackageReference Include="Microsoft.Net.Compilers.Toolset" Version="4.0.0-2.21275.18">
<Private Assets >all</PrivateAssets>
<IncludeAssets>runtime; build; natif; contentfiles; analyseurs; buildtr ansitive</IncludeAssets>
</PackageReference>
</ItemGroup>[19659264]<ItemGroup>
<Compiler Inclure=".usings" />
</ ItemGroup>
Ensuite, vous pouvez créer et mettre à jour un fichier .usings
et vous êtes prêt à partir ! J'ai une dette de gratitude envers Khalid Abuhakmeh et son dépôt CsharpTenFeatures pour leur assistance. N'hésitez pas à vous référer à ce projet si vous rencontrez des problèmes pour obtenir les derniers outils.
Qu'est-ce que cela signifie pour les API dans ASP.NET Core ?
Si vous débutez dans la création d'API dans ASP.NET Core, c'est probablement une amélioration bienvenue. Vous pouvez vous soucier de la création d'API et non de tous les frais généraux fournis avec MVC.
Si vous avez développé des API ASP.NET Core pendant un certain temps, comme moi, vous accueillez peut-être cela avec enthousiasme et scepticisme. C'est génial, mais est-ce que cela correspond aux besoins d'une API à l'échelle de la production ? Et quand c'est le cas, sera-t-il difficile de passer aux capacités robustes d'ASP.NET Core MVC ? existent aujourd'hui dans MVC et permettent leur utilisation en dehors de MVC. Lors de l'extraction de ces composants vers un nouveau paradigme, vous pouvez compter sur des performances de type middleware. Ensuite, si vous devez passer des lambdas en ligne à MVC et à ses classes et contrôleurs, l'équipe ASP.NET prévoit de vous fournir une migration en douceur. Ce sont deux routes différentes avec un pont entre elles.
Si vous pensez à long terme, des API minimales pourraient être le moyen par défaut de créer des API dans ASP.NET Core. Dans la plupart des cas, il est préférable de commencer petit puis de grandir. , plutôt que de commencer par MVC et de ne pas exploiter toutes ses capacités. Une fois que vous en aurez besoin, il sera là.
Bien sûr, nous n'avons fait qu'effleurer le service dans tout ce que vous pouvez faire avec un minimum d'API. Je suis intéressé par ce que vous avez construit avec eux. Quelles sont vos pensées? Laissez un commentaire ci-dessous.
Source link