Aujourd’hui il est de plus en plus fréquent de devoir utiliser des Webservices Restful, que cela soit avec Azure, pour gerer un firewall voire même pour avoir des informations sur une bière (https://brewerydb.com/developers/docs/library, mais avec Modération) ou sur l’espace (https://api.nasa.gov/).

L’utilisation de ces API en PowerShell implique de construire un client avec le cmdlet invoke-RestMethod (ou invoke-WebRequest). Ce qui peut paraitre simple au départ, peut devenir compliqué, il faut non seulement pouvoir gerer les paramètres que l’on envois à l’API mais aussi construire un objet à partir des informations renvoyées par celle ci.

Pour une utilisation ponctuelle, c’est possible, mais si l’on doit construire un client pour toute une API la tache est bien plus ardue. Il faut bien sure construire toutes les fonctions associées à l’API, les tests unitaires qui vont avec et les tests d’acceptance en plus de la logique applicative. Et cela, sans oublier la gestion des différentes versions de l’API.

L’outil AutoRest, permet d’automatiser cette tâche. Cette application, construite avec Node.js il permet de construire une libraire cliente à partir d’un fichier de spécification de cette API.

Cet outil est largement utilisé pour générer les clients pour les différentes API d’Azure.

Cet outil est aujourd’hui disponible en version beta pour PowerShell.

L’outil étant développé en Node.js, pour l’installer, il est nécessaire d’installer Node.js en version 10.15.xx LTS.

Il est nécessaire de disposer aussi de PowerShell Core et du DotNet SDK 2.1

Il ne reste plus qu’à installer AutoRest en version beta pour pouvoir l’utiliser avec l’option PowerShell.

npm install -g autorest@beta

Si vous avez déjà une installation d’Autorest ou si vous voulez installer la dernière version.

Autorest -reset

Apres l’installation il est alors possible de générer un module PowerShell servant de client à une API.

Pour cela nous avons besoin d’un fichier OpenAPI ou un Swagger File. Ce fichier décrit toutes les actions possibles sur l’API, suivant les directives de l’OpenApi Specification. Il permet aux hommes et aux machines de pouvoir comprendre les différentes fonctions présenter par l’API, avec les paramètres requis, les données qui sont renvoyées et les d’autres informations. Ce fichier peut être sous la forme Json ou Yaml.

C’est à partir de ce fichier qu’Autorest génère un module PowerShell. Cela veut dire que si une méthode n’est pas disponible dans le fichier, il ne sera pas disponible non plus dans le module.

Avec l’installation du module Node Autorest Beta et si l’on dispose d’un fichier de spécification d’une API, on peut commencer à générer un module PowerShell pour consommer cette API.

autorest --powershell --input-file:<Chemin Du Fichier de Spec>

Ce sont les options de base nécessaire pour la création du module ; –powershell pour indiquer que nous voulons un module PowerShell, –input-file le fichier yaml de spécification de l’API.

Il est aussi possible de créer un fichier de commande en yaml ou json.

AutoRest genere alors un module dans un dossier generated. Il est possible de changer le chemin du dossier par défaut en utilisant l’option –outPutFolder:

Le module est généré mais il n’est pas encore construit. Si l’on regarde dans le dossier généré par l’outil, on peut y voir plusieurs scripts et sous dossiers.

Parmi ces fichiers il y a les fichiers du module, un dossier « test » pour les tests Pester (le dossier est créé, mais il reste à ajouter les tests dans un ou plusieurs fichiers .ps1).

Un dossier custom pour les éventuel cmdlets supplémentaires et la logique applicative lié au module. Tous les fichiers .ps1 dans ce dossier feront partie du module et les fonctions seront donc exportées L’outil rajoute aussi le module PlatyPs et un script, generate-help.ps1 pour générer la documentation. Un dossier Doc pour la doc et un dossier examples sont en place à cet effet.

Enfin l’outil rajoute deux scripts pour construire et packager le module.

L’étape de Build n’est pas optionnelle, le module généré étant un module écrit en C#, il est nécessaire d’effectuer une compilation pour avoir les DLL du module.

Pour lancer le Build du module, il faut lancer le script build-module.ps1. Il effectue les actions de Build dans tous les cas, mais certains switches permettent de lancer des actions supplémentaires.

• Run, charge le module dans un Runspace
• Test, lance le script test-module pour exécuter les scripts de test se trouvant dans le dossier test
• Docs, lance le script generate-help.ps1 pour créer la doc au format MD grâce au module PlatyPs
• Code, lance VsCode apres le build
• Release, Compile le module en configuration de prod

.\generated\build-module.ps1 -Run

AutoRest.PowerShell génère également un fichier Nuspec et il est possible de packager le module pour le publier sur un repos public ou privé. L’outil fournis aussi un script pour lancer le packaging, pack-module.ps1, mais il faut avant cela modifier le fichier NeoWs.nuspec en ajoutant l’Auteur, la Description, l’url du projet et de la licence.

.\pack-module.ps1 

Le fichier Nuget est généré dans le dossier bin prêt à être publié.

AutoRest.PowerShell est toujours en version Beta. Il y a encore quelques bugs et quelques défauts. Mais cet outil deviendra nécessaire pour gerer des clients de Rest API dans un module PowerShell sous peu.