Page d'accueil>Code source ASP>Autres catégories
Télécharger

Les générateurs d'API Web client fortement typés génèrent des codes d'API client en C# et TypeScript à partir de l'API Web ASP.NET (Core) directement sans impliquer Swagger/OpenAPI ou Swashbuckle, maximisant ainsi la prise en charge des types de données de votre approche Code First de l'API Web ASP.NET. .

Produits

Ce projet fournit ces produits :

  1. Générateur de code pour API client fortement typée en C# prenant en charge .NET et Xamarin.Forms.
  2. Générateurs de code pour API client fortement typée en TypeScript pour jQuery, Angular 2+, Aurelia, Axios et Fetch API.
  3. TypeScript CodeDOM, un composant .NET CodeDOM pour TypeScript permettant de développer des générateurs de code TypeScript.
  4. POCO2TS.exe, un programme de ligne de commande qui génère des interfaces TypeScript à partir des classes POCO.
  5. Fonlow.Poco2Ts, un composant qui génère des interfaces TypeScript à partir de classes POCO.
  6. Plugins pour jQuery, AXIOS, Fetch API, Aurelia, Angular 2+ ainsi que les formulaires réactifs typés angulaires.
  7. Fonlow.DataOnlyExtensions avec des convertisseurs JSON pour gérer des scénarios de date uniquement entre les clients et le serveur situés dans des fuseaux horaires différents. Un package .NET Framework est également disponible.

Forfaits

Cas d'utilisation et téléchargements

Les produits sont publiés principalement via NuGet.

  1. Générez l'API client C#, puis utilisez le package Fonlow.WebApiClientGenCore
  2. Générez l'API client TypeScript, puis utilisez l'un des plugins de Fonlow.WebApiClientGenCore :
    1. Bibliothèque d'assistance jQuery et HttpClient
    2. Angulaire 6+
    3. Angular 6+, plus création de FormGroup pour les formulaires réactifs avec description
    4. AXIOS
    5. Aurélie
    6. Récupérer l'API
  3. Développez le générateur de code TypeScript via l'approche CodeDOM, puis utilisez le package Fonlow.TypeScriptCodeDOMCore.
  4. Développez un générateur de code TypeScript via l'approche CodeDOM pour POCO et plus, puis utilisez le package Fonlow.Poco2TSCore ou utilisez des scripts PowerShell 7.
  5. Générez des interfaces de type TypeScript, puis utilisez Poco2TSCore.exe, une application console.
  6. Développez une fonctionnalité qui lit le document XML d'un assembly .NET, puis utilisez le package Fonlow.DocCommentCore.

Conseils :

  • OpenApiClientGen basé sur des composants clés de WebApiClientGen est un spin-off permettant de générer des codes API client en C# et TypeScript selon un fichier de définition de Swagger/Open API Spécification.
  • WebApiClientGen n'utilise pas les définitions Swagger/OpenAPI, mais génère des codes à partir des informations de type d'exécution d'une API Web en cours d'exécution de la version de débogage, éliminant ainsi les limitations inhérentes d'OpenAPI par rapport aux types .NET et à l'API Web pour offrir une meilleure expérience de développement à ASP. NET (Core) Développeurs d'API Web.

Remarques :

  • Le développement a commencé en 2015 en prenant en charge .NET Framework, puis .NET Core 2. Et la balise "LastCore31" doit marquer le dernier instantané prenant en charge .NET Framework 4.6.2 et .NET Core 3.1.
  • À partir du 10/02/2021, le développement prendra en charge uniquement .NET 5 et versions ultérieures.
  • Le contenu du wiki sur .NET Framework sera conservé dans un avenir prévisible.

Principales fonctionnalités

  1. Les codes API client générés sont directement mappés à partir des méthodes du contrôleur API Web, des types primitifs .NET et des classes POCO. Ceci est similaire à ce que svcutil.exe dans WCF a proposé.
  2. Les commentaires Doc des méthodes du contrôleur et des classes POCO sont copiés.
  3. Certains attributs de validation sont utilisés pour générer des commentaires de documentation pour les codes TypeScript.

Avantages clés pour l'expérience des développeurs

  1. WebApiClientGen est parfaitement intégré à l'API Web ASP.NET Core avec très peu d'étapes/surcharges pour configurer, maintenir et synchroniser entre l'API Web et les API client, pendant le développement de logiciels RAD ou Agile.
  2. Prend en charge tous les types primitifs .NET, y compris décimal.
  3. Prise en charge de DataTime, DataTimeOffset, DateOnly, Array, Tuple, Dynamic Object, Dictionary et KeyValuePair
  4. Les codes générés fortement typés sont soumis à une vérification de type au moment de la conception et à une vérification du type au moment de la compilation.
  5. Fournit un haut niveau d'abstraction, protégeant les développeurs d'applications des détails techniques répétitifs des pratiques RESTful et des codes traditionnels des appels AJAX.
  6. Les méta-informations riches, y compris les commentaires de la documentation, rendent l'IDE Intellisense plus utile, de sorte que les développeurs d'applications ont moins besoin de lire des documents API séparés.
  7. Commentaires de document générés basés sur les attributs de validation .NET.
  8. Commentaires de document générés basés sur des types numériques, DateOnly et GUID pour les codes TypeScript.
  9. Les codes TypeScript générés sont conformes au mode strict TypeScript et les codes Angular 2+ générés sont conformes au mode strict Angular.

Exemples

  1. Cours POCO
  2. API Web
  3. Codes C# de l'API client générés
  4. Codes clients utilisant la bibliothèque générée en C#
  5. Génération de modèles de données client et API en TypeScript pour jQuery, pour Angular 2, pour Aurelia et pour Axios
  6. Codes clients utilisant la bibliothèque générée dans TypeScript
  7. Démo en ligne avec Angular Heroes hébergée dans GitHub.IO parlant à un vrai backend

Remarques :

  1. Les codes JavaScript compilés à partir de codes TypeScript générés pourraient être utilisés dans les applications JS. Cependant, aucune information de type ne sera évidemment disponible, tandis que les programmeurs d'applications pourront toujours profiter de l'intellisense et de l'abstraction des détails AJAX.
    1. Les applications React et Vue.js utilisent généralement l'API Axios ou Fetch pour les requêtes HTTP. Depuis juin 2019, babel prend en charge les espaces de noms grâce à cette pull request, vous devriez donc pouvoir faire de la programmation React TSX avec les codes TypeScript générés.

Concepts

  1. Les fournisseurs/développeurs d'API Web devraient fournir des bibliothèques d'API client aux développeurs de programmes clients, comme le feraient Google et Amazon, etc., afin que l'API Web RESTful atteigne efficacement des consommateurs plus larges (internes et externes).
  2. Pour les développeurs clients, les prototypes de fonctions classiques comme ReturnType DoSomething(Type1 t1, Type2 t2 ...) constituent la fonction API, et le reste concerne les détails techniques de mise en œuvre du transport : TCP/IP, HTTP, SOAP, orienté ressources, CRUD- URI basés sur RESTful, XML et JSON, etc. Le prototype de fonction et un morceau de document API devraient être suffisants pour appeler la fonction API.
  3. Mieux vous séparerez les préoccupations dans la conception de votre API Web, plus vous bénéficierez des composants de ce projet afin de fournir des valeurs commerciales plus rapidement, avec moins de codes fabriqués à la main, moins de tâches répétitives et moins de risques d'erreurs humaines.

Pratiques de programmation attendues

Prototype de fonction fortement typée

ReturnType DoSomething(Type1 t1, Type2 t2 ...)

		[ HttpGet ]
		[ Route ( "getPerson/{id}" ) ]
		public Person GetPerson ( long id )

Validation du modèle via middleware

Plutôt que d'écrire des codes explicites de validation de la charge utile de la requête, il est prévu que vous utilisiez un middleware pour valider. Par exemple: 

 public void ConfigureServices ( IServiceCollection services )
{
	services . AddControllers (
		options =>
		{
			options . Filters . Add ( new ValidateModelAttribute ( ) ) ; // wholesale style to check model binding for all API calls.

Références :

  • Validation du modèle dans l'API Web ASP.NET
  • Validation du modèle dans ASP.NET Core MVC et Razor Pages

Validation du modèle via ApiControllerAttribute

Par exemple: 

	[ ApiController ]
	[ Route ( "api/[controller]" ) ]
	public class HeroesController : ControllerBase
	{

Codes d'état HTTP non-2xx gérés par le middleware, facultatif

Même si vous écrivez explicitement des codes dans une fonction API pour gérer les exceptions et renvoyer un code d'état HTTP non 2xx, vous devez disposer d'un filet de sécurité pour détecter les exceptions non interceptées et renvoyer les codes d'état HTTP.

Références :

  • Intergiciel ASP.NET Core

Conditions préalables

Côté serveur :

  1. .NET 7/8
  2. Ajoutez CodeGenController.
  3. Dans les codes de démarrage du service, ajoutez ce qui suit : 
 services . AddControllers (
	options =>
	{
#if DEBUG
		options . Conventions . Add ( new Fonlow . CodeDom . Web . ApiExplorerVisibilityEnabledConvention ( ) ) ;
#endif
	}
)

Remarques :

  • Microsoft publie une mise à niveau majeure de .NET (Core) chaque année depuis 2016, les bibliothèques de ce référentiel suivront généralement la dernière environ six mois plus tard.
  • Les bibliothèques publiques sont avec .NET une version derrière la dernière version, tandis que l'application de démonstration ASP.NET et les suites de tests d'intégration avec l'API client .NET générée sont avec la version actuelle de .NET.

Côté client .NET :

  1. .NET Framework 4.5.2, ou Universal Windows, ou Mono.Android, ou Xamarin.iOS, ou .NET Core 2.0/2.1/3 et .NET 5
  2. Bibliothèques clientes de l'API Web ASP.NET 2.2
  3. Json.NET de Newtonsoft pour l'application Content-Type/json
  4. Outils de génération Microsoft 2015

NewtonSoft.Json ou System.Text.Json

Depuis .NET 7, pour la sérialisation, System.Text.Json réassemble plus de 95 % de NewtonSoft.Json. Il n'existe que quelques cas extrêmes de structures POCO complexes que System.Text.Json ne peut pas gérer.

WebApiClientGen prend en charge à la fois côté serveur et côté client C#. Pour les clients C#, vous pouvez utiliser « UseSystemTextJson » dans les paramètres de codegen.

Néanmoins, si votre application implique des structures POCO complexes, utiliser NewtonSoft.Json est une valeur sûre à partir de .NET 7.

Côté client TypeScript :

  1. Compilateur TypeScript
  2. jQuery
  3. Angulaire 2-17
  4. Aurélie
  5. Axios
  6. Récupérer l'API

Pour plus de détails, veuillez vérifier :

  1. Wiki
  2. Paramètres expliqués
  3. Générer une API client C# .NET pour l'API Web ASP.NET
  4. Générer l'API client TypeScript pour l'API Web ASP.NET
  5. API Web ASP.NET, Angular2, TypeScript et WebApiClientGen
  6. Générer une API client C# pour l'API Web ASP.NET Core
  7. Solutions prévues pour les limitations intentionnelles des générateurs de clients OpenAPI fortement typés. L'article utilise simplement OpenApiClientGen comme exemple, tandis que les principes et les solutions peuvent être appliqués aux codes générés par WebApiClientGen pour vos applications client.
  8. DateOnly dans ASP.NET Core 6

Applications de démonstration

Les applications de démonstration de ce référentiel sont principalement destinées à tester WebApiClientGen pendant le développement. Et il existe d'autres applications de démonstration dans les référentiels suivants, démontrant comment les applications du monde réel pourraient utiliser WebApiClientGen :

  1. Exemples WebApiClientGen pour .NET Framework, .NET Standard, Xamarin et vue TS.
  2. Démo .NET Core pour ASP.NET Core MVC, Web API, ASP.NET Core + Angular, MAUI, fetchAPI, vue TS et React TS.
  3. WebApiClientGen et Swagger

Ces applications de démonstration sont activement entretenues et mises à jour avec les derniers frameworks. Si vous utilisez toujours certains frameworks plus anciens comme Angular 4 ou 5 ou .NET Core 2.0, vous pouvez accéder aux balises respectives des référentiels et procéder au paiement.

Tour des Héros

Tour of Heroes est l'application de démonstration officielle du didacticiel Angular.

Pour illustrer l'expérience du programmeur lors de l'utilisation de WebApiClientGen, les applications de démonstration suivantes sont conçues avec une conception architecturale similaire pour les mêmes fonctionnalités fonctionnelles sur divers frameworks ou bibliothèques de développement, mais s'adressent à un véritable backend.

  1. Angulaire 2+ et formulaires réactifs typés
  2. Xamarin
  3. MAUI. Migré de Xamarin Heroes.
  4. Aurélie. Suite de tests d'intégration incluse.
  5. Réagir. Suite de tests d'intégration incluse.
  6. Blazor autonome

NewtonSoft.Json ou System.Text.Json

Bien que WebApiClientGen prenne en charge les deux, le support principal est passé à System.Text.Json depuis 2024.

NewtonSoft.Json présente encore quelques avantages sur certains scénarios et contextes :

  1. Si vous avez beaucoup de classes POCO décorées par DataContractAttributes, en raison de la prise en charge d'applications héritées ou de la prise en charge de la sérialisation XML et JSON, NewtonSoft.Json vous offre une prise en charge inhérente, tandis que System.Text.Json fournit une prise en charge gênante et indirecte depuis .NET 7.
  2. Pour certains types de tableaux et dynamiques, NewtonSoft.Json est encore meilleur.
Développer
Informations supplémentaires
Applications connexes
Recommandé pour vous
Actualités connexes Tout