Freigeben über

Erstellen von Visual Studio-Toolfenstern

Toolfenster sind eine Möglichkeit, komplexe UI und Interaktionen zu Visual Studio hinzuzufügen. Sie bieten in der Regel eine benutzerfreundliche Möglichkeit, mit verschiedenen APIs und Features zu interagieren. Das Toolfenster des Projektmappen-Explorers stellt z. B. eine strukturbasierte Ansicht des aktuellen Projekts/Projektmappenordners und einfache Gesten zum Öffnen, Umbenennen und Erstellen von Dateien bereit.

Toolfenster sind einzelinstanzig, was bedeutet, dass jeweils nur eine Instanz des Toolfensters geöffnet werden kann. Wenn ein Toolfenster in der IDE geschlossen wird, ist es optisch verborgen und nicht vollständig geschlossen und entsorgt, wie es bei Dokumenten der Fall ist.

Loslegen

Befolgen Sie zunächst das Tutorial zum Erstellen Ihrer ersten Erweiterung.

Arbeiten mit Tool-Fenstern

Dieses Handbuch wurde entwickelt, um die wichtigsten Benutzerszenarien beim Arbeiten mit Tool-Windows abzudecken:

Erstellen eines Toolfensters

Das Erstellen eines Toolfensters mit dem neuen Erweiterbarkeitsmodell ist so einfach wie das Erweitern der Basisklasse ToolWindow und das Schmücken Ihrer Klasse mit dem Attribut VisualStudioContribution.

[VisualStudioContribution]
public class MyToolWindow : ToolWindow

Attribut ToolWindow

Die ToolWindow abstrakte Klasse erfordert die Implementierung der ToolWindowConfiguration Konfiguration, die über einige Eigenschaften verfügt, mit denen Sie vertraut sein sollten:

Parameter Typ Erforderlich BESCHREIBUNG Standardwert
Platzierung ToolWindowPlacement Nein Der Speicherort in Visual Studio, an dem das Toolfenster zum ersten Mal geöffnet werden soll. ToolWindowPlacement.DockedTo bietet die Möglichkeit, das Tool-Fenster an eine GUID anzudocken, die einer alten VSIX-Style Tool-Fenster-ID entspricht. Weitere Informationen zu ToolWindowPlacement. ToolWindowPlacement.Floating
DockDirection Dockingstation Nein Die Richtung relativ zur Platzierung, an der das Tool-Fenster beim ersten Öffnen angedockt werden soll. Siehe Dock. Dock.None
AllowAutoCreation Bool Nein Gibt an, ob das Toolfenster automatisch erstellt werden kann. Das Festlegen dieses Parameters auf "false" bedeutet, dass Toolfenster, die geöffnet sind, wenn Visual Studio geschlossen wird, nicht automatisch wiederhergestellt werden, wenn Visual Studio erneut geöffnet wird. true

Beispiel

[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
    }
}

Hinzufügen von Inhalten zu einem Toolfenster

Da Erweiterungen in VisualStudio.Extensibility möglicherweise außerhalb der IDE ausgeführt werden, können wir WPF (Windows Presentation Foundation) nicht direkt als Präsentationsebene für Inhalte in Werkzeugfenstern verwenden. Stattdessen erfordert das Hinzufügen von Inhalten zu einem Toolfenster das Erstellen eines RemoteUserControl-Steuerelements und der entsprechenden Datenvorlage für dieses Steuerelement. Es gibt zwar einige einfache Beispiele unten, es wird jedoch empfohlen, die Remote-UI-Dokumentation beim Hinzufügen von Toolfensterinhalten zu lesen.

[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: (Dies ist ein Beispieldateiname und sollte denselben Namen wie die Datenvorlagendatei haben)

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

MyToolWindowControl.xaml: (Dies ist ein Beispieldateiname und sollte denselben Namen wie die Klasse aufweisen, die von RemoteUserControl abgeleitet ist)

<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>

Weitere Informationen zum Erstellen einer RemoteUserControlBenutzeroberfläche finden Sie unter Remote-UI.

Erstellen eines Befehls zum Anzeigen eines Toolfensters

Ein gängiger Mechanismus zum Anzeigen eines Toolfensters besteht darin, einen Befehl hinzuzufügen, der beim Aufrufen das Toolfenster durch Aufrufen ShellExtensibility.ShowToolWindowAsync()anzeigt.

ShowToolWindowAsync() hat einen booleschen Parameter, activate:

  • Wenn true, ist das Tool-Fenster sowohl in der IDE als auch sichtbar, wenn es den Fokus erhält.
  • Wenn false, ist das Tool-Fenster in der IDE sichtbar, aber möglicherweise nur als Registerkarte in einer Registerkartengruppe, wenn andere Tool-Fenster aktiv sind.

Beispiel

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

Weitere Informationen zum Erstellen und Verwenden von Befehlen finden Sie in den Befehlsdokumenten .

Steuern der Sichtbarkeit eines Toolfensters

Eine weitere Möglichkeit zum Steuern der Sichtbarkeit eines Toolfensters neben der Verwendung von Befehlen ist die Verwendung regelbasierter Aktivierungseinschränkungen. Diese Einschränkungen ermöglichen es Toolfenstern, sich automatisch zu öffnen, wenn bestimmte Bedingungen erfüllt sind, und wieder ausgeblendet werden, wenn diese Bedingungen nicht mehr anwendbar sind.

ToolWindowVisibleWhenAttribute

Das VisibleWhen Attribut verfügt über einige Parameter, mit denen Sie vertraut werden sollten:

Parameter Typ Erforderlich BESCHREIBUNG
Ausdruck Schnur Ja Eine boolesche Ausdruckszeichenfolge, die, wenn wahr, bedeutet, dass der Kontext aktiv ist und das Toolfenster angezeigt wird.
TermNames Zeichenfolge[] Ja Die Namen der begriffe, die im Ausdruck verwendet werden.
TermValues Zeichenfolge[] Ja Die Werte der einzelnen Begriffe. Die Begriffswerte müssen in der gleichen Reihenfolge wie das Array von Begriffsnamen angeordnet sein.

Beispiel

// 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$"),
};

Weitere Informationen zu gültigen Begriffswerten finden Sie unter Regelbasierte Aktivierungseinschränkungen.

Hinzufügen einer Symbolleiste zu einem Toolfenster

Eine Symbolleiste kann einem Toolfenster hinzugefügt werden. Definieren Sie zunächst eine Symbolleiste, wie in der Dokumentation zu Menüs und Symbolleisten beschrieben:

[VisualStudioContribution]
public static ToolbarConfiguration MyToolbar => new("%MyToolbar.DisplayName%")
{
    Children = [
        ToolbarChild.Command<MyCommand1>(), // Assuming there is a `Command` defined in the extension called `MyCommand1`
        ToolbarChild.Separator,
        ToolbarChild.Command<MyCommand2>(), // Assuming there is a `Command` defined in the extension called `MyCommand2`
    ],
};

Dann referenzieren Sie die Toolbar über die Konfiguration des Tool-Fensters:

public override ToolWindowConfiguration ToolWindowConfiguration => new()
{
    ...
    Toolbar = new(MyToolbar),
};

Nächste Schritte

Lesen Sie unbedingt, wie Remote-UI im VisualStudio.Extensibility-Framework funktioniert.

Der Toolfensterinhalt wird mit WPF erstellt. Weitere Informationen finden Sie in der WPF-Dokumentation .

Ein vollständiges Beispiel zum Erstellen einer Erweiterung mit einem Toolfenster finden Sie im ToolWindow-Beispiel .