Créer une applet de commande Crescendo

  • Article

Les outils en ligne de commande modernes fournissent des commandes pour une gestion efficace des technologies spécifiques à un domaine. Les utilisateurs administratifs peuvent exécuter ces commandes en toute confiance à l’intérieur de PowerShell et obtenir les résultats attendus. Toutefois, les utilisateurs PowerShell préfèrent la syntaxe, la lisibilité et la sortie basée sur les objets que les applets de commande fournissent, en particulier dans l’automatisation.

Comme indiqué précédemment, il existe plusieurs raisons pour lesquelles vous souhaiterez peut-être amplifier un outil en ligne de commande :

  • La sortie de chaîne est difficile à utiliser dans l’automatisation
  • La syntaxe de commande est difficile à utiliser ou à mémoriser
  • L’outil manque de documentation d’aide informative

Dans l’article précédent, nous avons expliqué comment découvrir et choisir la fonctionnalité de l’outil que vous souhaitez amplifier avec Crescendo. Pour les exemples de cet article, nous continuons à utiliser l’outil azcmagent en ligne de commande qui a été introduit précédemment.

Création de la configuration d’une applet de commande Crescendo

Une configuration Crescendo décrit une nouvelle applet de commande. La définition de l’applet de commande inclut :

  • Emplacement de l’outil en ligne de commande d’origine
  • Sous-commandes et paramètres passés à l’outil en ligne de commande
  • Nom Verb-Noun de la nouvelle applet de commande
  • Paramètres utilisés par l’applet de commande

Crescendo prend le fichier de configuration et génère des applets de commande proxy pour l’outil en ligne de commande d’origine. Le code généré est stocké dans un module de script PowerShell, prêt pour le déploiement.

Vous pouvez créer votre propre fichier de configuration, copier un fichier existant et le modifier, ou démarrer une nouvelle configuration à l’aide de l’applet de New-CrescendoCommand commande. Les fichiers de configuration Crescendo sont écrits en JSON.

  • Le paramètre Verb spécifie le verbe de la nouvelle applet de commande. Utilisez Get-Verb pour obtenir une liste de noms de verbes approuvés.
  • Le paramètre Noun spécifie le nom sur lequel le verbe agit.
  • Le paramètre OriginalName spécifie le chemin d’accès à l’outil en ligne de commande d’origine.
$parameters = @{
    Verb = 'Show'
    Noun = 'AzCmAgent'
    OriginalName = "c:/program files/AzureConnectedMachineAgent/azcmagent.exe"
}
New-CrescendoCommand @parameters | Format-List *

New-CrescendoCommand crée un objet de commande Crescendo. L’applet de commande remplit toutes les valeurs de propriété possibles.

FunctionName            : Show-AzCmAgent
Verb                    : Show
Noun                    : AzCmAgent
OriginalName            : c:/program files/AzureConnectedMachineAgent/azcmagent.exe
OriginalCommandElements :
Platform                : {Windows, Linux, MacOS}
Elevation               :
Aliases                 :
DefaultParameterSetName :
SupportsShouldProcess   : False
ConfirmImpact           :
SupportsTransactions    : False
NoInvocation            : False
Description             :
Usage                   :
Parameters              : {}
Examples                : {}
OriginalText            :
HelpLinks               :
OutputHandlers          :

L’exemple suivant montre comment créer un fichier de configuration.

$parameters = @{
    Verb = 'Show'
    Noun = 'AzCmAgent'
    OriginalName = "c:/program files/AzureConnectedMachineAgent/azcmagent.exe"
}
$CrescendoCommands += New-CrescendoCommand @parameters
Export-CrescendoCommand -command $CrescendoCommands -fileName .\AzCmAgent.json

Le fichier de configuration Crescendo a un schéma JSON et peut contenir une ou plusieurs définitions d’applet de commande dans un tableau. Dans cet exemple, $NewConfiguration est un objet contenant le lien vers le schéma JSON et un tableau contenant les définitions d’applet de commande. La sortie de New-CrescendoCommand est ajoutée au tableau Commandes . est $NewConfiguration converti en JSON et écrit dans un fichier. Le fichier AzCmAgent.json contient le code suivant :

{
  "$schema": "https://aka.ms/PowerShell/Crescendo/Schemas/2022-06",
  "Commands": [
    {
      "Verb": "Show",
      "Noun": "AzCmAgent",
      "OriginalName": "c:/program files/AzureConnectedMachineAgent/azcmagent.exe",
      "Platform": [
        "Windows",
        "Linux",
        "MacOS"
      ],
      "SupportsShouldProcess": false,
      "SupportsTransactions": false,
      "NoInvocation": false,
      "Parameters": [],
      "Examples": []
    }
  ]
}

Il est important d’avoir le lien de schéma dans le fichier de configuration Crescendo. Le schéma fournit des outils tels que Visual Studio Code avec IntelliSense et des info-bulles pendant l’expérience de création.

Fin de la configuration de la commande Crescendo

Dans cet exemple, nous créons une configuration pour la azcmagent show commande . L’applet de commande ne nécessite aucun paramètre supplémentaire. Étant azcmagent donné qu’il s’agit d’un outil moderne qui fournit une sortie JSON, l’exemple inclut un gestionnaire de sortie simple pour convertir la sortie JSON en objets.

La définition de commande comprend les propriétés suivantes :

  • Verbe : nom du verbe d’applet de commande
  • Nom : nom du nom de l’applet de commande
  • Plateforme : plateforme sur laquelle cette commande Crescendo s’exécute (Windows, Linux, MacOS)
  • OriginalName : nom et emplacement de la commande native d’origine
  • OriginalCommandElements : certains outils en ligne de commande ont des commutateurs obligatoires supplémentaires pour un scénario donné
  • Description : description de l’applet de commande affichée dans l’aide
  • Alias : alias, ou nom court, pour la nouvelle applet de commande
  • OutputHandlers : gestionnaire de sortie qui capture la sortie de chaîne à partir de l’outil en ligne de commande et la transforme en objets PowerShell
  • HandlerType : peut être Inline, Functionou Script. Cet exemple utilise Inline

L’exemple suivant montre la définition JSON complète de la nouvelle applet de commande après une modification supplémentaire.

{
  "$schema": "https://aka.ms/PowerShell/Crescendo/Schemas/2022-06",
  "Commands": [
    {
      "Verb": "Show",
      "Noun": "AzCmAgent",
      "OriginalName": "c:/program files/AzureConnectedMachineAgent/azcmagent.exe",
      "OriginalCommandElements": [
         "show",
         "--json"
      ],
      "Platform": [
        "Windows"
      ],
      "Description": "Gets machine metadata and Agent status. This is primarily useful for troubleshooting.",
      "Aliases": [
        "azinfo"
      ],
      "OutputHandlers": [
        {
            "ParameterSetName": "Default",
            "HandlerType": "Inline",
            "Handler": "$args[0] | ConvertFrom-Json"
        }
      ],
      "SupportsShouldProcess": false,
      "SupportsTransactions": false,
      "NoInvocation": false,
      "Parameters": [],
      "Examples": []
    }
  ]
}

Définition d’une autre applet de commande qui a des paramètres

Dans cet exemple, nous créons une configuration Crescendo pour la azcmagent config get commande qui répertorie les informations de propriété. Un paramètre nommé Property est mappé au paramètre d’origine de Get.

Une définition de paramètre comprend les propriétés suivantes :

  • DefaultParameterSetName : définit le jeu de paramètres par défaut si plusieurs ensembles de paramètres sont implémentés
  • Paramètres : bloc de code qui contient la définition des paramètres de la commande
  • Nom : il s’agit du nom du paramètre PowerShell pour l’applet de commande générée.
  • OriginalName : nom du paramètre
  • ParameterType : définit le type de données de la valeur de paramètre
  • ParameterSetName : définit le jeu de paramètres auquel ce paramètre appartient
  • Obligatoire : paramètre qui détermine si le paramètre doit avoir une valeur
  • Description : Description du paramètre affiché dans l’aide

L’exemple suivant montre la définition JSON complète de la nouvelle applet de commande. Vous pouvez placer cela dans une définition dans un nouveau fichier JSON ou l’ajouter au tableau Commandes du fichier JSON précédent.

{
    "Verb": "Get",
    "Noun": "AzCmAgentConfigProperty",
    "Platform": [
        "Windows"
    ],
    "OriginalCommandElements": [
        "config",
        "--json"
    ],
    "OriginalName": "c:/program files/AzureConnectedMachineAgent/azcmagent.exe",
    "Description": " Get a configuration property's value",
    "DefaultParameterSetName": "Default",
    "Parameters": [
        {
            "OriginalName": "get",
            "Name": "Property",
            "ParameterType": "string",
            "ParameterSetName": [
                "Default"
            ],
            "Mandatory": true,
            "Description": "Specify the name of the property to return"
        }
    ],
    "OutputHandlers": [
        {
            "ParameterSetName": "Default",
            "HandlerType": "Inline",
            "Handler": "$args[0] | ConvertFrom-Json"
        }
    ],
    "SupportsShouldProcess": false,
    "SupportsTransactions": false,
    "NoInvocation": false,
    "Examples": []
}

Pour obtenir un exemple de configuration plus détaillé, consultez le billet de blog A look to the Crescendo configuration.

Étapes suivantes

Maintenant que vous avez défini vos applets de commande, vous êtes prêt à générer votre nouveau module.

Générer et tester votre module