Поделиться через

Вклады и конфигурации

  • Статья

Вы можете предоставлять компоненты расширений в Visual Studio, производные от определенных базовых классов, и их можно настроить, определив определенные свойства и используя различные атрибуты.

Вклады Visual Studio

Цель расширения Visual Studio — добавление новых функций в Visual Studio. Это достигается путем расширения одного из многих классов, таких как Command, ToolWindowили ExtensionPart и применение атрибута VisualStudioContribution.

В этой статье рассматривается расширение Command Parenting для объяснения основных понятий участия в создании и настройки компонентов расширения.

Каждое расширение VisualStudio.Extensibility должно внести по крайней мере один класс Extension:

namespace CommandParentingSample;

[VisualStudioContribution]
public class CommandParentingSampleExtension : Extension
{
    /// <inheritdoc/>
    protected override void InitializeServices(IServiceCollection serviceCollection)
    {
        base.InitializeServices(serviceCollection);
    }
}

Класс Extension является первым созданным классом расширения и позволяет добавлять ваши собственные сервисы в IServiceCollection для использования во внедрении зависимостей .

Пример родительского управления командами вносит другой класс, Command, в Visual Studio:

[VisualStudioContribution]
internal class SampleCommand : Command
{
    public SampleCommand()
    {
    }
    ...

При расширении базового класса, предоставленного пакетом SDK для VisualStudio.Extensibility, можно знать, следует ли использовать атрибут VisualStudioContribution, проверяя, реализует ли базовый класс IVisualStudioContributionClass (как Extension, так и Command).

Классы расширений Visual Studio — это отложенно создаваемые одиночные экземпляры: создается только один экземпляр, и его создание откладывается до тех пор, пока Visual Studio не потребуется взаимодействовать с ним (например, когда пользователем впервые вызывается Command).

Инфраструктура VisualStudio.Extensibility также позволяет получать службы через внедрение зависимостей в качестве параметров конструктора классов компонентов Visual Studio (см. Внедрение зависимостей в расширениях VisualStudio.Extensibility), включая любую службу, которую вы добавили в IServiceCollection в методе InitializeServices класса Extension.

Visual Studio часто требует, чтобы уникальный идентификатор был связан с вкладами. В большинстве случаев инфраструктура VisualStudio.Extensibility использует полное имя класса вклада Visual Studio в качестве идентификатора вклада. Например, идентификатор вышеуказанного класса Extension будет CommandParentingSample.CommandParentingSampleExtension. Вам может потребоваться тщательно выбрать имя типа и пространство имен классов вкладов Visual Studio, так как они могут отображаться в журналах и сообщениях об ошибках Visual Studio.

Настройка компонентов Visual Studio

Большинство классов вкладов Visual Studio требуют или разрешают настройку. Например, для абстрактного класса Command требуется реализация свойства CommandConfiguration, указывающего по крайней мере отображаемое имя команды и, при необходимости, другие свойства, такие как его размещение.

[VisualStudioContribution]
internal class SampleCommand : Command
{
    /// <inheritdoc />
    public override CommandConfiguration CommandConfiguration => new("%CommandParentingSample.SampleCommand.DisplayName%")
    {
        Placements = new[]
        {
            // File in project context menu
            CommandPlacement.VsctParent(new Guid("{d309f791-903f-11d0-9efc-00a0c911004f}"), id: 1072, priority: 0),

            // Project context menu
            CommandPlacement.VsctParent(new Guid("{d309f791-903f-11d0-9efc-00a0c911004f}"), id:  1026, priority: 0),

            // Solution context menu
            CommandPlacement.VsctParent(new Guid("{d309f791-903f-11d0-9efc-00a0c911004f}"), id:  1043, priority: 0),
        },
    };
    ...

CommandConfiguration является константой времени компиляции , которая означает, что его значение вычисляется при построении расширения и включается в манифест расширения (extension.json). Visual Studio может считывать манифест расширения без загрузки самого расширения, что позволяет повысить производительность.

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

При оценке константы sampleCommand.CommandConfiguration возникла проблема. Ссылки на определяемые пользователем нестатические элементы не поддерживаются при оценке значений константы во время компиляции.

Как правило, расширение не должно ссылаться на констант времени компиляции свойства конфигурации во время выполнения.

Вы можете легко определить свойства конфигурации, являющиеся константами времени компиляции, , так как их определение имеет атрибут CompileTimeEvaluation.

public abstract class Command : ExecutableCommandHandler, IVisualStudioContributionClass
{
    ...
    /// <summary>
    /// Gets the configuration for this command. The value of this property is evaluated at compile time
    /// when building the Visual Studio extension.
    /// </summary>
    [CompileTimeEvaluation]
    public abstract CommandConfiguration CommandConfiguration { get; }
    ...

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

Свойства автономной конфигурации

Как описано выше, классы вкладов Visual Studio определяют одинтонный класс, который обычно предоставляет один или несколько констант времени компиляции свойства конфигурации. Значения свойств конфигурации сохраняются в виде метаданных расширения.

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

Свойства вклада Visual Studio можно поместить в любой класс.

Пример родительского команды определяет панель инструментов, объявляя статичное свойство типа ToolbarConfiguration и помечая его как VisualStudioContribution.

namespace CommandParentingSample;

internal static class ExtensionCommandConfiguration
{
    [VisualStudioContribution]
    public static ToolbarConfiguration ToolBar => new("%CommandParentingSample.ToolBar.DisplayName%")
    {
        Children = new[]
        {
            ToolbarChild.Command<SampleCommand>(),
        },
    };
}

Свойства вклада Visual Studio также константы времени компиляции и имеют те же ограничения, которые обсуждались ранее.

Свойство вклада Visual Studio также может ссылаться на другое свойство конфигурации. Например:

public static class MenuConfigurations
{
    [VisualStudioContribution]
    public static CommandGroupConfiguration MyCommandGroup => new(GroupPlacement.KnownPlacements.ExtensionsMenu)
    {
        Children = new GroupChild[]
        {
            GroupChild.Menu(MyMenu),
        },
    };

    [VisualStudioContribution]
    public static MenuConfiguration MyMenu => new("%MyMenu.DisplayName%")
    {
        Children = new[]
        {
            MenuChild.Command<MyCommand>(),
        },
    };
    ...

Типы, предназначенные для определения свойств расширений Visual Studio, реализуют интерфейс IVisualStudioContributionProperty и отмечены атрибутом CompileTimeEvaluation, чтобы задокументировать, что их значения оцениваются при сборке расширения.

[CompileTimeEvaluation]
public sealed class DocumentTypeConfiguration : IVisualStudioContributionProperty ...

Рекомендации не ссылаться на константу времени компиляции и свойства конфигурации во время выполнения также применяются к свойствам добавления Visual Studio.

Если для свойства вклада Visual Studio требуется уникальный идентификатор, его полное имя (содержащее полное имя типа и имя свойства) используется инфраструктурой VisualStudio.Extensibility в качестве идентификатора. Например, уникальный идентификатор конфигурации панели инструментов, описанной здесь, будет CommandParentingSample.ExtensionCommandConfiguration.ToolbarConfiguration.

Связанное содержимое