Nouveautés de Crescendo 1.1

Cette préversion inclut une nouvelle applet de commande, un nouveau schéma, la prise en charge de la transformation de valeur d’argument, la possibilité de contourner le gestionnaire de sortie et une gestion améliorée des erreurs.

Nouvelle version de schéma

Le schéma Crescendo prend désormais en charge trois nouveaux membres de la classe Parameter : ExcludeAsArgument, ArgumentTransform et ArgumentTransformType. Avec des outils tels que Visual Studio Code, le schéma fournit IntelliSense et des info-bulles pendant l’expérience de création.

Emplacement d’URL du schéma Crescendo toujours disponible :

{
   "$schema": "https://aka.ms/PowerShell/Crescendo/Schemas/2022-06",
   "Commands": []
}

Nouvelle Export-CrescendoCommand applet de commande

Cette applet de commande crée des fichiers de configuration JSON pour les objets Crescendo Command . Il peut créer un fichier JSON par objet Command ou créer un fichier JSON contenant tous les objets qui lui sont passés.

Les objets Crescendo Command peuvent être créés à l’aide New-CrescendoCommand d’une configuration existante ou importés à l’aide Import-CommandConfigurationde .

Pour plus d’informations, consultez Export-CrescendoCommand.

Empêcher le remplacement du manifeste du module

Crescendo crée à la fois le module .psm1 et le manifeste .psd1 du module lors Export-CrescendoModule de l’exécution. Cela peut créer des problèmes lorsque vous avez personnalisé le manifeste du module au-delà de l’étendue de Crescendo. L’applet Export-CrescendoModule de commande fournit désormais un paramètre de commutateur NoClobberManifest pour empêcher le remplacement du manifeste.

Export-CrescendoModule -ConfigurationFile .\myconfig.json -ModuleName .\Mymodule -NoClobberManifest

Notes

Le paramètre NoClobberManifest empêche Crescendo de mettre à jour le manifeste du module. Vous êtes responsable de la mise à jour manuelle du manifeste avec les nouvelles applets de commande et paramètres.

Ignorer entièrement la gestion des sorties

Certaines commandes natives créent une sortie différente selon que la sortie est envoyée à l’écran ou au pipeline. Pastel est un exemple de commande qui modifie sa sortie d’une représentation graphique à l’écran en une seule valeur de chaîne lorsqu’elle est utilisée dans un pipeline. La gestion des sorties Crescendo est basée sur un pipeline et peut entraîner le retour de résultats indésirables par ces applications. Crescendo prend désormais en charge la possibilité de contourner entièrement le gestionnaire de sortie.

Pour contourner toute la gestion de la sortie par Crescendo :

"OutputHandlers": [
    {
        "ParameterSetName": "Default",
        "HandlerType": "ByPass"
    }
]

Gestion de la sortie d’erreur

Auparavant, les erreurs de commande native étaient diffusées directement à l’utilisateur. Ils n’ont pas été capturés par Crescendo. Cela vous a empêché de créer une gestion améliorée des erreurs. Crescendo capture désormais la sortie d’erreur de commande générée (stderr). Si vous ne définissez pas de gestionnaire de sortie, Crescendo utilise le gestionnaire par défaut. Le gestionnaire de sortie par défaut garantit que les erreurs respectent les -ErrorVariable paramètres et et -ErrorAction ajoute des erreurs à $Error.

Crescendo v1.1 ajoute deux fonctions internes pour gérer les erreurs.

• Push-CrescendoNativeError ajoute une erreur à une file d’attente d’erreurs. Cette fonction est automatiquement appelée par le gestionnaire de sortie. Tu n’as pas besoin de l’appeler directement.
• Pop-CrescendoNativeError supprime une erreur de la file d’attente d’erreurs. Utilisez cette fonction pour inspecter les erreurs dans le gestionnaire de sortie.

L’ajout d’un gestionnaire de sortie qui inclut Pop-CrescendoNativeError vous permet d’inspecter les erreurs dans le gestionnaire de sortie afin de les gérer ou de les transmettre à l’appelant.

La définition de gestionnaire de sortie suivante utilise Pop-CrescendoNativeError pour renvoyer des erreurs à l’utilisateur.

"OutputHandlers": [
    {
        "ParameterSetName": "Default",
        "StreamOutput": true,
        "HandlerType": "Inline",
        "Handler": "PROCESS { $_ } END { Pop-CrescendoNativeError -EmitAsError }"
    }
]

Transformation de valeur d’argument

Vous pouvez trouver des situations où les valeurs d’entrée transmises à une commande encapsulée Crescendo doivent être traduites en une autre valeur pour la commande native sous-jacente. Crescendo prend désormais en charge la transformation des arguments pour prendre en charge ces scénarios. Nous avons mis à jour le schéma pour ajouter deux nouveaux membres à la classe Parameter , ArgumentTransform et ArgumentTransformType. Ces membres fonctionnent comme les Handler membres et HandlerType . La valeur ArgumentTransformType peut être Inline, Functionou Script. La valeur par défaut pour ArgumentTransformType est Inline.

• Si est ArgumentTransformTypeInline, la valeur de ArgumentTransform doit être une chaîne contenant un scriptblock.
• Si est ArgumentTransformTypeFunction, la valeur de ArgumentTransform doit être le nom d’une fonction chargée dans la session active.
• Si est ArgumentTransformTypeScript, la valeur de ArgumentTransform doit être le chemin d’accès à un fichier de script.

Crescendo transmet les valeurs d’argument du paramètre au code de transformation d’argument. Le code doit retourner les valeurs transformées.

Exemple : Multiplication d’une valeur.

"Parameters": [
    {
        "Name": "mult2",
        "OriginalName": "--p3",
        "ParameterType": "int",
        "OriginalPosition": 2,
        "ArgumentTransform": "param([int]$v) $v * 2",
        "ArgumentTransformType": "Inline"
    }
]

Exemple : acceptation d’une table de hachage ordonnée.

"Parameters": [
    {
        "Name": "hasht2",
        "OriginalName": "--p1ordered",
        "ParameterType": "System.Collections.Specialized.OrderedDictionary",
        "OriginalPosition": 0,
        "ArgumentTransform": "param([System.Collections.Specialized.OrderedDictionary]$v) $v.Keys.ForEach({''{0}={1}'' -f $_,$v[$_]}) -join '',''",
        "ArgumentTransformType": "Inline"
    }
]

Exemple : transformation d’argument avec jointure.

"Parameters": [
    {
        "Name": "join",
        "OriginalName": "--p2",
        "ParameterType": "string[]",
        "OriginalPosition": 1,
        "ArgumentTransform": "param([string[]]$v) $v -join '',''",
        "ArgumentTransformType": "Inline"
    }
]

Exemple : Appel d’une transformation basée sur une fonction.

"Parameters": [
    {
        "Name" : "Param1",
        "ArgumentTransform": "myfunction",
        "ArgumentTransformType" : "function"
    }
]

Création de paramètres d’applet de commande qui ne sont pas utilisés par la commande native

Crescendo est conçu pour passer les paramètres définis dans la configuration en tant qu’arguments à l’application native. Il arrive que vous souhaitiez utiliser une valeur de paramètre dans le gestionnaire de sortie, mais pas dans l’application native. Pour activer cette option, une nouvelle propriété ExcludeAsArgument de paramètre booléenne définie sur true empêche l’envoi de l’argument à l’application native. Par défaut, il s’agit de false.

"Parameters": [
        {
            "Name": "Filter",
            "ParameterType": "string",
            "ExcludeAsArgument": true,
            "Mandatory": false,
            "Description": "Variable not sent to native app"
        }
    ],

Pour cet exemple, l’argument de chaîne passé au paramètre Filter est stocké dans la variable $Filter. Cette variable peut être utilisée dans votre gestionnaire de sortie. Le gestionnaire de sortie peut utiliser la valeur de la $Filter variable pour filtrer la sortie de la commande native, plutôt que de retourner toute la sortie.

Installation de Crescendo

Pour plus d’informations sur l’installation de Crescendo, consultez Installation de Crescendo.