Partager via

Guide pratique pour créer un prédicteur de ligne de commande

PSReadLine 2.1.0 a introduit le concept de prédiction de ligne de commande intelligente en implémentant la fonctionnalité IntelliSense prédictive. PSReadLine 2.2.2 a développé cette fonctionnalité en ajoutant un modèle de plug-in qui vous permet de créer vos propres prédicteurs de ligne de commande.

IntelliSense prédictif améliore l’achèvement de l’onglet en fournissant des suggestions, sur la ligne de commande, à mesure que vous tapez. La suggestion de prédiction s’affiche sous forme de texte coloré suivant votre curseur. Cela vous permet de découvrir, de modifier et d’exécuter des commandes complètes en fonction des prédictions correspondantes à partir de votre historique de commandes ou d’autres plug-ins spécifiques au domaine.

Configuration requise

Pour créer et utiliser un prédicteur de plug-in, vous devez utiliser les versions suivantes du logiciel :

  • PowerShell 7.2 (ou version ultérieure) : fournit les API nécessaires à la création d’un prédicteur de commandes
  • PSReadLine 2.2.2 (ou version ultérieure) : vous permet de configurer PSReadLine pour utiliser le plug-in

Vue d’ensemble d’un prédicteur

Un prédicteur est un module binaire PowerShell. Le module doit implémenter l’interface System.Management.Automation.Subsystem.Prediction.ICommandPredictor. Cette interface déclare les méthodes utilisées pour interroger les résultats de prédiction et fournir des commentaires.

Un module de prédiction doit inscrire un sous-système CommandPredictor avec le SubsystemManager de PowerShell lorsqu'il est chargé et se désinscrire lorsqu'il est déchargé.

Le diagramme suivant montre l’architecture d’un prédicteur dans PowerShell.

Architecture

Création du code

Pour créer un prédicteur, vous devez installer le Kit de développement logiciel (SDK) .NET 6 pour votre plateforme. Pour plus d’informations sur le SDK, consultez Télécharger .NET 6.0.

Créez un projet de module PowerShell en procédant comme suit :

  1. Utilisez l’outil en ligne de commande dotnet pour créer un projet classlib de démarrage.

    dotnet new classlib --name SamplePredictor

  2. Modifiez le SamplePredictor.csproj pour contenir les informations suivantes :

    <Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <TargetFramework>net6.0</TargetFramework>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.PowerShell.SDK" Version="7.2.0" />
  </ItemGroup>

</Project>

  3. Supprimez le fichier Class1.cs par défaut créé par dotnet et copiez le code suivant dans un fichier SamplePredictorClass.cs dans votre dossier de projet.

    using System;
using System.Collections.Generic;
using System.Threading;
using System.Management.Automation;
using System.Management.Automation.Subsystem;
using System.Management.Automation.Subsystem.Prediction;

namespace PowerShell.Sample
{
    public class SamplePredictor : ICommandPredictor
    {
        private readonly Guid _guid;

        internal SamplePredictor(string guid)
        {
            _guid = new Guid(guid);
        }

        /// <summary>
        /// Gets the unique identifier for a subsystem implementation.
        /// </summary>
        public Guid Id => _guid;

        /// <summary>
        /// Gets the name of a subsystem implementation.
        /// </summary>
        public string Name => "SamplePredictor";

        /// <summary>
        /// Gets the description of a subsystem implementation.
        /// </summary>
        public string Description => "A sample predictor";

        /// <summary>
        /// Get the predictive suggestions. It indicates the start of a suggestion rendering session.
        /// </summary>
        /// <param name="client">Represents the client that initiates the call.</param>
        /// <param name="context">The <see cref="PredictionContext"/> object to be used for prediction.</param>
        /// <param name="cancellationToken">The cancellation token to cancel the prediction.</param>
        /// <returns>An instance of <see cref="SuggestionPackage"/>.</returns>
        public SuggestionPackage GetSuggestion(PredictionClient client, PredictionContext context, CancellationToken cancellationToken)
        {
            string input = context.InputAst.Extent.Text;
            if (string.IsNullOrWhiteSpace(input))
            {
                return default;
            }

            return new SuggestionPackage(new List<PredictiveSuggestion>{
                new PredictiveSuggestion(string.Concat(input, " HELLO WORLD"))
            });
        }

        #region "interface methods for processing feedback"

        /// <summary>
        /// Gets a value indicating whether the predictor accepts a specific kind of feedback.
        /// </summary>
        /// <param name="client">Represents the client that initiates the call.</param>
        /// <param name="feedback">A specific type of feedback.</param>
        /// <returns>True or false, to indicate whether the specific feedback is accepted.</returns>
        public bool CanAcceptFeedback(PredictionClient client, PredictorFeedbackKind feedback) => false;

        /// <summary>
        /// One or more suggestions provided by the predictor were displayed to the user.
        /// </summary>
        /// <param name="client">Represents the client that initiates the call.</param>
        /// <param name="session">The mini-session where the displayed suggestions came from.</param>
        /// <param name="countOrIndex">
        /// When the value is greater than 0, it's the number of displayed suggestions from the list
        /// returned in <paramref name="session"/>, starting from the index 0. When the value is
        /// less than or equal to 0, it means a single suggestion from the list got displayed, and
        /// the index is the absolute value.
        /// </param>
        public void OnSuggestionDisplayed(PredictionClient client, uint session, int countOrIndex) { }

        /// <summary>
        /// The suggestion provided by the predictor was accepted.
        /// </summary>
        /// <param name="client">Represents the client that initiates the call.</param>
        /// <param name="session">Represents the mini-session where the accepted suggestion came from.</param>
        /// <param name="acceptedSuggestion">The accepted suggestion text.</param>
        public void OnSuggestionAccepted(PredictionClient client, uint session, string acceptedSuggestion) { }

        /// <summary>
        /// A command line was accepted to execute.
        /// The predictor can start processing early as needed with the latest history.
        /// </summary>
        /// <param name="client">Represents the client that initiates the call.</param>
        /// <param name="history">History command lines provided as references for prediction.</param>
        public void OnCommandLineAccepted(PredictionClient client, IReadOnlyList<string> history) { }

        /// <summary>
        /// A command line was done execution.
        /// </summary>
        /// <param name="client">Represents the client that initiates the call.</param>
        /// <param name="commandLine">The last accepted command line.</param>
        /// <param name="success">Shows whether the execution was successful.</param>
        public void OnCommandLineExecuted(PredictionClient client, string commandLine, bool success) { }

        #endregion;
    }

    /// <summary>
    /// Register the predictor on module loading and unregister it on module un-loading.
    /// </summary>
    public class Init : IModuleAssemblyInitializer, IModuleAssemblyCleanup
    {
        private const string Identifier = "843b51d0-55c8-4c1a-8116-f0728d419306";

        /// <summary>
        /// Gets called when assembly is loaded.
        /// </summary>
        public void OnImport()
        {
            var predictor = new SamplePredictor(Identifier);
            SubsystemManager.RegisterSubsystem(SubsystemKind.CommandPredictor, predictor);
        }

        /// <summary>
        /// Gets called when the binary module is unloaded.
        /// </summary>
        public void OnRemove(PSModuleInfo psModuleInfo)
        {
            SubsystemManager.UnregisterSubsystem(SubsystemKind.CommandPredictor, new Guid(Identifier));
        }
    }
}

    L’exemple de code suivant renvoie la chaîne « HELLO WORLD » comme résultat de prédiction pour toute saisie utilisateur. Étant donné que l’exemple de prédiction ne traite pas de commentaires, le code n’implémente pas les méthodes de commentaires de l’interface. Modifiez le code de prédiction et de commentaires pour répondre aux besoins de votre prédicteur.

    Remarque

    La vue Liste de PSReadLine ne prend pas en charge les suggestions multilignes. Chaque suggestion doit être une seule ligne. Si votre code a une suggestion multiligne, vous devez fractionner les lignes en suggestions distinctes ou joindre les lignes avec un point-virgule (;).

  4. Exécuter dotnet build pour produire l’assemblage. Vous trouverez l’assembly compilé à l’emplacement bin/Debug/net6.0 de votre dossier de projet.

    Remarque

    Pour garantir une expérience utilisateur réactive, l’interface ICommandPredictor a un délai d’attente de 20 ms pour les réponses des predictors. Votre code de prédiction doit renvoyer des résultats en moins de 20 ms pour être affichés.

Utilisation de votre module prédictif

Pour tester votre nouveau prédicteur, ouvrez une nouvelle session PowerShell 7.2 et exécutez les commandes suivantes :

Set-PSReadLineOption -PredictionSource HistoryAndPlugin
Import-Module .\bin\Debug\net6.0\SamplePredictor.dll

Lorsque l’assembly est chargé dans la session, le texte « HELLO WORLD » s’affiche lorsque vous tapez dans le terminal. Vous pouvez appuyer sur F2 pour basculer entre la vue Inline et la vue List.

Pour plus d’informations sur les options PSReadLine, consultez Set-PSReadLineOption.

Vous pouvez obtenir la liste des prédicteurs installés à l’aide de la commande suivante :

Get-PSSubsystem -Kind CommandPredictor

Kind              SubsystemType      IsRegistered Implementations
----              -------------      ------------ ---------------
CommandPredictor  ICommandPredictor          True {SamplePredictor}

Remarque

Get-PSSubsystem est une applet de commande expérimentale introduite dans PowerShell 7.1 Vous devez activer la fonctionnalité expérimentale PSSubsystemPluginModel pour utiliser cette applet de commande. Pour plus d’informations, consultez Utilisation des fonctionnalités expérimentales.

  • Last updated on