Hinweis
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, sich anzumelden oder das Verzeichnis zu wechseln.
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, das Verzeichnis zu wechseln.
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
- Hinzufügen von Inhalten zu einem Toolfenster
- Erstellen eines Befehls zum Anzeigen eines Toolfensters
- Steuern der Sichtbarkeit eines Toolfensters
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 RemoteUserControl
Benutzeroberflä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 .