Создание окон инструментов Visual Studio

Окна инструментов — это способ добавления сложного пользовательского интерфейса и взаимодействия в Visual Studio. Обычно они предоставляют удобный способ взаимодействия с различными API и функциями. Например, окно инструментов обозревателя решений предоставляет представление на основе дерева текущего проекта или решения или папки и предоставляет простые жесты для открытия, переименования и создания файлов.

Окна инструментов являются одним экземпляром, что означает, что одновременно можно открыть только один экземпляр окна инструментов. При закрытии окна инструментов в интегрированной среде разработки оно просто скрывается визуально, но не полностью закрывается и не удаляется, как документы.

Начало работы

Чтобы приступить к работе, выполните действия, описанные в руководстве создайте своё первое расширение.

Работа с Окнами инструментов

Это руководство предназначено для освещения ключевых пользовательских сценариев при работе с Окнами инструментов.

• Создание окна инструментов
• Добавление содержимого в окно инструментов
• Создание команды для отображения окна инструментов
• Управление видимостью окна инструментов

Создание окна инструментов

Создание окна инструментов с новой моделью расширяемости так же просто, как расширение базового класса и украшение класса ToolWindow атрибутом VisualStudioContribution.

[VisualStudioContribution]
public class MyToolWindow : ToolWindow

Атрибут ToolWindow

Абстрактный ToolWindow класс требует реализации конфигурации ToolWindowConfiguration , которая имеет несколько свойств, с которыми вы должны ознакомиться:

Параметр	Тип	Обязательно	Описание	Значение по умолчанию
размещение	Размещение окон инструментов	нет	Расположение в Visual Studio, в котором окно инструмента должно быть открыто при первом открытии. ToolWindowPlacement.DockedTo позволяет прикрепить окно инструмента к ИДЕНТИФИКАТОРу GUID, соответствующему старому идентификатору окна инструментов в стиле VSIX. Дополнительные сведения о ToolWindowPlacement.	РасположениеОкнаИнструмента.Плавающее
DockDirection	Док	нет	Направление относительно того места, где окно инструмента должно быть закреплено при первом открытии. См. Док.	Dock.None
AllowAutoCreation	Булев	нет	Указывает, можно ли автоматически создать окно инструментов. Установка этого параметра на значение false означает, что окна инструментов, открытые при закрытии Visual Studio, не восстанавливаются автоматически при повторном открытии Visual Studio.	true

Пример

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

Добавление содержимого в окно инструментов

Поскольку расширения в VisualStudio.Extensibility могут работать вне процесса IDE, мы не можем напрямую использовать WPF (Windows Presentation Foundation) в качестве слоя презентации для содержимого в окнах инструментов. Вместо этого для добавления содержимого в окно инструментов требуется создать RemoteUserControl и соответствующий шаблон данных для этого элемента управления. Хотя ниже приведены некоторые простые примеры, мы рекомендуем ознакомиться с документацией по удаленному пользовательскому интерфейсу при добавлении содержимого окна инструментов.

[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: (это пример имени файла и должен иметь то же имя, что и файл шаблона данных).

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

MyToolWindowControl.xaml: (это пример имени файла и должен иметь то же имя, что и класс, производный от 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>

Дополнительные сведения о создании пользовательского интерфейса см. в разделе RemoteUserControl пользовательский интерфейс".

Создание команды для отображения окна инструментов

Распространенный механизм отображения окна инструментов заключается в добавлении команды , которая при вызове отображает окно средства путем вызова ShellExtensibility.ShowToolWindowAsync().

ShowToolWindowAsync() имеет логический параметр, activate:

• Если trueокно инструмента отображается как в интегрированной среде разработки, так и в заданном фокусе.
• Когда false окно инструментов видно в интегрированной среде разработки, оно может отображаться только как вкладка в группе вкладок, если другие окна инструментов активны.

Пример

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

Дополнительные сведения о создании и использовании команд см. в документации по командам .

Управление видимостью окна инструментов

Другим способом управления видимостью окна инструментов, помимо использования команд, является использование ограничений активации на основе правил. Эти ограничения позволяют окнам инструментов автоматически открываться при выполнении определенных условий и снова скрываться, когда эти условия больше не применимы.

АтрибутВидимостиОкнаИнструментовКогда

Атрибут VisibleWhen имеет несколько параметров, с которыми вы должны ознакомиться:

Параметр	Тип	Обязательно	Описание
Выражение	Струна	Да	Логическое выражение, которое при значении true означает, что контекст активен и окно инструментов отображается.
ИменаТерминов	String[]	Да	Имена терминов, используемых в выражении.
Значениятерминов	String[]	Да	Значения каждого термина. Значения терминов должны находиться в том же порядке, что и массив имен терминов.

Пример

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

Дополнительные сведения о допустимых значениях терминов см. в разделе ограничения активации на основе правил.

Добавление панели инструментов в окно инструментов

Панель инструментов можно добавить в окно инструментов. Сначала определите панель инструментов, как описано в документации по меню и панелям инструментов:

[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`
    ],
};

Затем наведите ссылку на панель инструментов из конфигурации окна инструментов:

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

Дальнейшие шаги

Обязательно ознакомьтесь с тем, как работает удаленный пользовательский интерфейс в платформе VisualStudio.Extensibility.

Содержимое окна инструментов создается с помощью WPF, поэтому ознакомьтесь с документацией по WPF .

Полный пример создания расширения с помощью окна инструментов см. в примере ToolWindow .