Creare finestre degli strumenti di Visual Studio

Le finestre degli strumenti sono un modo per aggiungere interazioni e interfaccia utente complesse a Visual Studio. In genere forniscono un modo semplice per interagire con varie API e funzionalità. Ad esempio, la finestra degli strumenti Esplora soluzioni fornisce una visualizzazione basata su albero del progetto/soluzione/cartella corrente e fornisce semplici movimenti per l'apertura, la ridenominazione e la creazione di file.

Le finestre degli strumenti sono a istanza singola, ovvero è possibile aprire una sola istanza della finestra degli strumenti alla volta. Quando una finestra degli strumenti viene chiusa nell'IDE, è visibile solo invece di essere completamente chiusa e eliminata come i documenti.

Attività iniziali

Per iniziare, seguire l'esercitazione creare la prima estensione .

Uso delle finestre degli strumenti

Questa guida è progettata per coprire gli scenari utente principali quando si lavora con Le finestre degli strumenti:

• Creare una finestra degli strumenti
• Aggiungere contenuto a una finestra degli strumenti
• Creare un comando per visualizzare una finestra degli strumenti
• Controllare la visibilità di una finestra degli strumenti

Creare una finestra degli strumenti

La creazione di una finestra degli strumenti con il nuovo modello di estendibilità è semplice quanto estendere la classe ToolWindow di base e decorare la classe con l'attributo VisualStudioContribution.

[VisualStudioContribution]
public class MyToolWindow : ToolWindow

Attributo ToolWindow

La ToolWindow classe astratta richiede l'implementazione della ToolWindowConfiguration configurazione, che ha alcune proprietà da acquisire familiarità con:

Parametro	Type	Obbligatorio	Descrizione	Valore predefinito
Posizionamento	ToolWindowPlacement	No	Percorso in Visual Studio in cui deve essere aperta la prima volta la finestra degli strumenti. ToolWindowPlacement.DockedTo consente di ancorare la finestra degli strumenti a un GUID corrispondente a un VECCHIO ID finestra degli strumenti di stile VSIX. Vedere altre informazioni su ToolWindowPlacement.	ToolWindowPlacement.Floating
DockDirection	Ancora	No	Direzione relativa alla posizione in cui deve essere ancorata la finestra degli strumenti alla prima apertura. Vedi Dock.	Dock.None
AllowAutoCreation	Bool	No	Specifica se la finestra degli strumenti può essere creata automaticamente. Se si imposta su false, le finestre degli strumenti aperte quando Visual Studio viene chiuso non verranno ripristinate automaticamente quando Visual Studio viene aperto di nuovo.	true

Esempio

[VisualStudioContribution]
public class MyToolWindow : ToolWindow
{
    public MyToolWindow(VisualStudioExtensibility extensibility)
        : base(extensibility)
    {
        this.Title = "My Tool Window";
    }

    public override ToolWindowConfiguration ToolWindowConfiguration => new()
    {
        Placement = ToolWindowPlacement.Floating,
        DockDirection = Dock.Right,
        AllowAutoCreation = true,
    };

    public override Task<IRemoteUserControl> GetContentAsync(CancellationToken cancellationToken)
    {
        // Create and return a RemoteUserControl
    }
}

Aggiungere contenuto a una finestra degli strumenti

Poiché le estensioni in VisualStudio.Extensibility potrebbero essere out-of-process dall'IDE, non è possibile usare direttamente WPF come livello di presentazione per il contenuto in Finestre degli strumenti. L'aggiunta di contenuto a una finestra degli strumenti richiede invece la creazione di un controllo RemoteUserControl e il modello di dati corrispondente per tale controllo. Anche se di seguito sono riportati alcuni semplici esempi, è consigliabile leggere la documentazione dell'interfaccia utente remota quando si aggiunge il contenuto della finestra degli strumenti.

[VisualStudioContribution]
public class MyToolWindow : ToolWindow
{
    public MyToolWindow(VisualStudioExtensibility extensibility)
        : base(extensibility)
    {
        this.Title = "My Tool Window";
    }

    public override ToolWindowConfiguration ToolWindowConfiguration => new()
    {
        Placement = ToolWindowPlacement.DocumentWell,
    };

    public override async Task InitializeAsync(CancellationToken cancellationToken)
    {
        // Do any work here that is needed before creating the control.
    }

    public override Task<IRemoteUserControl> GetContentAsync(CancellationToken cancellationToken)
    {
        return Task.FromResult<IRemoteUserControl>(new MyToolWindowControl());
    }
}

MyToolWindowControl.cs: (nome file di esempio e deve avere lo stesso nome del file del modello di dati)

internal class MyToolWindowControl : RemoteUserControl
{
    public MyToolWindowControl()
        : base(dataContext: null)
    {
    }
}

MyToolWindowControl.xaml (nome file di esempio e deve avere lo stesso nome della classe che deriva da RemoteUserControl)

<DataTemplate xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
              xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
              xmlns:vs="http://schemas.microsoft.com/visualstudio/extensibility/2022/xaml">
    <Label></Label>
</DataTemplate>

per altre informazioni sulla creazione di un oggetto RemoteUserControl, vedere Interfaccia utente remota.

Creare un comando per visualizzare una finestra degli strumenti

Un meccanismo comune per visualizzare una finestra degli strumenti consiste nell'aggiungere un comando che, quando richiamato, mostra la finestra degli strumenti chiamando ShellExtensibility.ShowToolWindowAsync().

ShowToolWindowAsync() ha un parametro booleano, activate:

• Quando true, la finestra degli strumenti sarà visibile sia nell'IDE che nello stato attivo.
• Quando false, la finestra degli strumenti sarà visibile nell'IDE, ma potrebbe essere visibile solo come scheda in un gruppo di schede se sono attive altre finestre degli strumenti.

Esempio

[VisualStudioContribution]
public class MyToolWindowCommand : Command
{
    public MyToolWindowCommand(VisualStudioExtensibility extensibility)
        : base(extensibility)
    {
    }
    
    public override CommandConfiguration CommandConfiguration => new("My Tool Window")
    {
        Placements = new[] { CommandPlacement.KnownPlacements.ToolsMenu },
        Icon = new(ImageMoniker.KnownValues.ToolWindow, IconSettings.IconAndText),
    };

    public override async Task ExecuteCommandAsync(IClientContext context, CancellationToken cancellationToken)
    {
        await this.Extensibility.Shell().ShowToolWindowAsync<MyToolWindow>(activate: true, cancellationToken);
    }
}

Per altre informazioni sulla creazione e sull'uso dei comandi, vedere la documentazione sui comandi.

Controllare la visibilità di una finestra degli strumenti

Un altro modo per controllare la visibilità di una finestra degli strumenti, oltre a usare i comandi, consiste nell'usare vincoli di attivazione basati su regole. In questo modo le finestre degli strumenti vengono aperte automaticamente quando vengono soddisfatte determinate condizioni e nascoste di nuovo quando tali condizioni non sono più applicabili.

ToolWindowVisibleWhenAttribute

L'attributo VisibleWhen ha alcuni parametri da acquisire familiarità con:

Parametro	Type	Obbligatorio	Descrizione
Expression	String	Sì	Stringa di espressione booleana che, quando true, indica che il contesto è attivo e verrà visualizzata la finestra degli strumenti.
TermNames	String[]	Sì	Nomi dei termini usati nell'espressione.
TermValues	String[]	Sì	Valori di ogni termine. I valori del termine devono trovarsi nello stesso ordine della matrice di nomi di termini.

Esempio

// The tool window will be shown if the active document is a .cs file, and
// will be hidden if the active document is any any other type of file.
public override ToolWindowConfiguration ToolWindowConfiguration => new()
{
    VisibleWhen = ActivationConstraint.ClientContext(ClientContextKey.Shell.ActiveSelectionFileName, @"\.cs$"),
};

Per altre informazioni sui valori validi dei termini, vedere Vincoli di attivazione basati su regole.

Passaggi successivi

Assicurarsi di leggere il funzionamento dell'interfaccia utente remota nel framework VisualStudio.Extensibility.

Il contenuto della finestra degli strumenti viene creato usando WPF, quindi fare riferimento alla documentazione WPF per indicazioni.

Per un esempio completo di creazione di un'estensione con una finestra degli strumenti, vedi l'esempio toolWindow .