Tworzenie okien narzędzi programu Visual Studio

Okna narzędzi to sposób dodawania złożonego interfejsu użytkownika i interakcji do programu Visual Studio. Zazwyczaj zapewniają one przyjazny dla użytkownika sposób interakcji z różnymi interfejsami API i funkcjami. Na przykład okno narzędzia Eksplorator rozwiązań zawiera widok drzewa bieżącego projektu/rozwiązania/folderu i udostępnia proste gesty otwierania, zmieniania nazw i tworzenia plików.

Okna narzędzi są pojedynczym wystąpieniem, co oznacza, że jednocześnie można otworzyć tylko jedno wystąpienie okna narzędzi. Gdy okno narzędzia jest zamknięte w środowisku IDE, jest widoczne tylko ukryte, zamiast w pełni zamykać i usuwać podobne dokumenty.

Rozpocznij

Aby rozpocząć pracę, postępuj zgodnie z samouczkiem dotyczącym tworzenia pierwszego rozszerzenia .

Praca z systemem Windows narzędzi

Ten przewodnik jest przeznaczony do obsługi najważniejszych scenariuszy użytkownika podczas pracy z systemem Windows narzędzi:

• Tworzenie okna narzędzi
• Dodawanie zawartości do okna narzędzi
• Tworzenie polecenia w celu wyświetlenia okna narzędzia
• Kontrolowanie widoczności okna narzędzi

Tworzenie okna narzędzi

Tworzenie okna narzędzi przy użyciu nowego modelu rozszerzalności jest tak proste, jak rozszerzanie klasy bazowej i adorowanie klasy ToolWindow za pomocą atrybutu VisualStudioContribution.

[VisualStudioContribution]
public class MyToolWindow : ToolWindow

ToolWindow, atrybut

Klasa abstrakcyjna ToolWindow wymaga implementacji ToolWindowConfiguration konfiguracji, która ma kilka właściwości, które należy znać:

Parametr	Type	Wymagania	opis	Wartość domyślna
Umieszczenie	ToolWindowPlacement	Nie.	Lokalizacja w programie Visual Studio, w której okno narzędzi powinno być otwierane po raz pierwszy. ToolWindowPlacement.DockedTo umożliwia zadokowanie okna narzędzi do identyfikatora GUID zgodnego ze starym identyfikatorem okna narzędzi w stylu VSIX. Zobacz więcej na temat narzędziaWindowPlacement.	ToolWindowPlacement.Floating
DockDirection	Dock	Nie.	Kierunek względem położenia, w którym okno narzędzia powinno być zadokowane po otwarciu po raz pierwszy. Zobacz Dock.	Dock.None
AllowAutoCreation	Bool	Nie.	Określa, czy okno narzędzi można utworzyć automatycznie. Ustawienie wartości false oznacza, że okna narzędzi otwarte po zamknięciu programu Visual Studio nie zostaną automatycznie przywrócone po ponownym otwarciu programu Visual Studio.	true

Przykład

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

Dodawanie zawartości do okna narzędzi

Ponieważ rozszerzenia w programie VisualStudio.Extensibility mogą być poza procesem ze środowiska IDE, nie możemy bezpośrednio używać platformy WPF jako warstwy prezentacji dla zawartości w oknach narzędzi. Zamiast tego dodanie zawartości do okna narzędzi wymaga utworzenia kontrolki RemoteUserControl i odpowiedniego szablonu danych dla tej kontrolki. Chociaż poniżej przedstawiono kilka prostych przykładów, zalecamy przeczytanie dokumentacji interfejsu użytkownika zdalnego podczas dodawania zawartości okna narzędzi.

[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: (jest to przykładowa nazwa pliku i powinna mieć taką samą nazwę jak plik szablonu danych)

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

MyToolWindowControl.xaml (jest to przykładowa nazwa pliku i powinna mieć taką samą nazwę jak klasa pochodząca z 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>

Aby uzyskać więcej informacji na temat tworzenia obiektu RemoteUserControl, zobacz Interfejs użytkownika zdalnego.

Tworzenie polecenia w celu wyświetlenia okna narzędzia

Typowym mechanizmem wyświetlania okna narzędzi jest dodanie polecenia , które po wywołaniu pokazuje okno narzędzia przez wywołanie metody ShellExtensibility.ShowToolWindowAsync().

ShowToolWindowAsync() ma parametr logiczny, activate:

• Gdy trueokno narzędzia będzie widoczne zarówno w środowisku IDE , jak i fokus.
• Gdy falseokno narzędzia będzie widoczne w środowisku IDE, ale może być widoczne tylko jako karta w grupie kart, jeśli inne okna narzędzi są aktywne.

Przykład

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

Zobacz dokumentację poleceń , aby dowiedzieć się więcej na temat tworzenia poleceń i używania ich.

Kontrolowanie widoczności okna narzędzi

Innym sposobem kontrolowania widoczności okna narzędzi, oprócz używania poleceń, jest użycie ograniczeń aktywacji opartych na regułach. Dzięki temu okna narzędzi mogą być automatycznie otwierane po spełnieniu określonych warunków i ponownie ukryte, gdy te warunki nie będą już stosowane.

ToolWindowVisibleWhenAttribute

Atrybut VisibleWhen ma kilka parametrów, które należy znać:

Parametr	Type	Wymagania	opis
Expression	String	Tak	Ciąg wyrażenia logicznego, który po wartości true oznacza, że kontekst jest aktywny, a zostanie wyświetlone okno narzędzia.
Nazwy terminów	Ciąg[]	Tak	Nazwy terminów używanych w wyrażeniu.
TermValues	Ciąg[]	Tak	Wartości każdego terminu. Wartości terminów muszą być w tej samej kolejności co tablica nazw terminów.

Przykład

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

Aby uzyskać więcej informacji na temat prawidłowych wartości terminów, zobacz Ograniczenia aktywacji oparte na regułach.

Następne kroki

Pamiętaj, aby dowiedzieć się, jak działa zdalny interfejs użytkownika w strukturze VisualStudio.Extensibility.

Zawartość okna narzędzi jest tworzona przy użyciu platformy WPF, dlatego zapoznaj się z dokumentacją platformy WPF, aby uzyskać wskazówki.

Zobacz przykład ToolWindow, aby zapoznać się z pełnym przykładem tworzenia rozszerzenia za pomocą okna narzędzi.