Come creare un predictor della riga di comando

PSReadLine 2.1.0 ha introdotto il concetto di predictor intelligente della riga di comando implementando la funzionalità Predictive IntelliSense. PSReadLine 2.2.2 espansa su tale funzionalità aggiungendo un modello di plug-in che permette di creare i propri predittori della riga di comando.

IntelliSense predittivo migliora il completamento delle schede fornendo suggerimenti, nella riga di comando, durante la digitazione. Il suggerimento di stima viene visualizzato come testo colorato dopo il cursore. In questo modo è possibile individuare, modificare ed eseguire comandi completi in base alle previsioni corrispondenti dalla cronologia dei comandi o da plug-in aggiuntivi specifici per il dominio.

Requisiti di sistema

Per creare e usare un predictor plug-in, è necessario usare le versioni seguenti del software:

PowerShell 7.2 (o versione successiva): fornisce le API necessarie per la creazione di un predictor dei comandi
PSReadLine 2.2.2 (o versione successiva): consente di configurare PSReadLine per l'uso del plug-in

Panoramica di un predittore

Un predictor è un modulo binario di PowerShell. Il modulo deve implementare l'interfaccia System.Management.Automation.Subsystem.Prediction.ICommandPredictor. Questa interfaccia dichiara i metodi usati per eseguire query sui risultati della stima e fornire feedback.

Un modulo predictor deve registrare un sottosistema CommandPredictor con il SubsystemManager di PowerShell quando viene caricato e deregistrarsi quando viene scaricato.

Il diagramma seguente illustra l'architettura di un predictor in PowerShell.

Architettura

Creazione del codice

Per creare un predictor, è necessario che .NET 6 SDK sia installato per la piattaforma. Per altre informazioni sull'SDK, vedere Scaricare .NET 6.0.

Creare un nuovo progetto di modulo di PowerShell seguendo questa procedura:

Usare lo strumento da riga di comando dotnet per creare un progetto classlib di base.
```
dotnet new classlib --name SamplePredictor
```

Modificare il SamplePredictor.csproj in modo da contenere le informazioni seguenti:

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

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

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

</Project>

Eliminare il file di Class1.cs predefinito creato da dotnet e copiare il codice seguente in un file SamplePredictorClass.cs nella cartella del progetto.

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));
        }
    }
}

Il codice di esempio seguente restituisce la stringa "HELLO WORLD" per il risultato della stima per tutti gli input dell'utente. Poiché il predictor di esempio non elabora alcun feedback, il codice non implementa i metodi di feedback dall'interfaccia. Modificare il codice di previsione e feedback per soddisfare le esigenze del predictor.

Nota

La visualizzazione elenco di PSReadLine non supporta i suggerimenti su più righe. Ogni suggerimento deve essere una singola riga. Se il codice include un suggerimento su più righe, è necessario suddividere le righe in suggerimenti separati o unire le righe con un punto e virgola (;).

Eseguire dotnet build per produrre l'assemblaggio. È possibile trovare l'assembly compilato nel percorso bin/Debug/net6.0 della cartella del progetto.

Nota

Per garantire un'esperienza utente reattiva, l'interfaccia ICommandPredictor ha un timeout di 20 ms per le risposte dei predictor. Il codice del predictor deve restituire i risultati in meno di 20 ms affinché possano essere visualizzati.

Utilizzo del plug-in di previsione

Per provare il nuovo predictor, aprire una nuova sessione di PowerShell 7.2 ed eseguire i comandi seguenti:

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

Quando l'assembly viene caricato nella sessione, viene visualizzato il testo "HELLO WORLD" durante la digitazione nel terminale. È possibile premere F2 per passare dalla visualizzazione Inline alla visualizzazione List.

Per altre informazioni sulle opzioni PSReadLine, vedere Set-PSReadLineOption.

È possibile ottenere un elenco di predittori installati usando il comando seguente:

Get-PSSubsystem -Kind CommandPredictor

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

Nota

Get-PSSubsystem è un cmdlet sperimentale introdotto in PowerShell 7.1 È necessario abilitare la funzionalità sperimentale PSSubsystemPluginModel per usare questo cmdlet. Per ulteriori informazioni, vedere Utilizzo delle funzionalità sperimentali.

Commenti e suggerimenti

Questa pagina è stata utile?

Last updated on 2025-12-08