Estendendo o Visual Studio para MacExtending Visual Studio for Mac

O Visual Studio para Mac consiste em um conjunto de módulos chamado Pacotes de Extensão.Visual Studio for Mac consists of a set of modules called Extension Packages. Você pode usar pacotes de extensão para introduzir novos recursos ao Visual Studio para Mac, tal como suporte a um idioma adicional ou um novo modelo de projeto.You can use Extension Packages to introduce new functionality to Visual Studio for Mac, such as support for an additional language or a new Project template.

Pacotes de extensão são baseados nos pontos de extensão de outros pacotes de extensão.Extension packages build from the extension points of other extension packages. Pontos de extensão são espaços reservados para as áreas que podem ser expandidas, como um menu ou a lista de comandos do IDE.Extension points are placeholders for areas that can be expanded upon, such as a menu or the list of IDE Commands. Um pacote de extensão pode ser baseado em um ponto de extensão com o registro de um nó de dados estruturados chamados de extensão, como um novo item de menu ou um novo comando.An extension package can build from an extension point by registering a node of structured data called an extension, such as a new menu item or a new Command. Cada ponto de extensão aceita certos tipos de extensões, como um Comando, Painel ou FileTemplate.Each extension point accepts certain types of extensions, such as a Command, Pad, or FileTemplate. Um módulo que contém pontos de extensão é chamado de host de suplemento, pois ele pode ser estendido por outros pacotes de extensão.A module that contains extension points is called an add-in host, as it can be extended by other extension packages.

Para personalizar o Visual Studio para Mac, você pode criar um pacote de extensão baseado em pontos de extensão contidos em hosts de suplementos dentro de bibliotecas pré-existentes no Visual Studio para Mac, conforme ilustrado pelo diagrama a seguir:To customize Visual Studio for Mac, you can create an extension package that builds from extension points contained in add-in hosts within pre-existing libraries in Visual Studio for Mac, as illustrated by the following diagram:

Arquitetura de suplemento

Para que um pacote de extensão se baseie no Visual Studio para Mac, ele deve ter extensões baseadas em pontos de extensão pré-existentes dentro do IDE do Visual Studio para Mac.In order for an extension package to build from Visual Studio for Mac, it must have extensions that build from pre-existing extension points within the Visual Studio for Mac IDE. Quando um pacote de extensão depende de um ponto de extensão definido em um host de suplemento, ele deve ter uma dependência no pacote de extensão em questão.When an extension package relies on an extension point defined in an add-in host, it is said to have a dependency on that extension package.

A vantagem desse design modular é que o Visual Studio para Mac é extensível – há muitos pontos de extensão que podem servir de base com pacotes de extensão personalizados.The benefit of this modular design is that Visual Studio for Mac is extensible -- there are many extension points that can be built upon with custom extension packages. Exemplos de pacotes de extensão atuais incluem suporte para C# e F#, ferramentas de depuração e modelos de projeto.Examples of current extension packages include support for C# and F#, debugger tools, and Project templates.

Note

Observação: se você tiver um projeto do Criador de Suplementos que foi criado antes do Criador de Suplementos 1.2, será necessário migrar seu projeto, conforme descrito nas etapas indicadas aqui.Note: If you have an Add-in Maker project that was created before Add-in Maker 1.2, you need to migrate your project as outlined in the steps here.

Esta seção examina os diferentes arquivos gerados pelo Criador de Suplementos os dados exigidos por uma extensão de comando.This section looks at the different files generated by the Add-in Maker and the data a command extension requires.

Arquivos de atributoAttribute files

Pacotes de extensão armazenam metadados sobre seu nome, versão, dependências e outras informações em atributos C#.Extension packages store metadata about their name, version, dependencies, and other information in C# attributes. O Criador de Suplementos cria dois arquivos, AddinInfo.cs e AssemblyInfo.cs, para armazenar e organizar essas informações.The Add-in Maker creates two files, AddinInfo.cs and AssemblyInfo.cs to store and organize this information. Pacotes de extensão devem ter uma ID exclusiva e o namespace especificado em seus atributos Addin:Extension packages must have a unique id and namespace specified in their Addin attribute:

[assembly:Addin (
   "DateInserter",
   Namespace = "DateInserter",
   Version = "1.0"
)]

Pacotes de extensão também devem declarar dependências nos pacotes de extensão que possuem os pontos de extensão aos quais eles se conectam.Extension packages must also declare dependencies on the extension packages that own the extension points they plug into. Esses são referenciadas automaticamente no tempo de build.These are automatically referenced at build time.

Além disso, referências adicionais podem ser adicionadas por meio do nó de referência Suplemento no Painel de Soluções do projeto, conforme ilustrado pela imagem a seguir:Furthermore, additional references can be added via the Add-in reference node in the solution pad for the project, as depicted by the following image:

Inserir captura de tela de data

Eles também têm seus atributos assembly:AddinDependency correspondentes adicionados no tempo de build.They also have their corresponding assembly:AddinDependency attributes added at build time. Depois que os metadados e as declarações de dependência estão em vigor, você pode se concentrar nos blocos de construção essenciais do pacote de extensão.Once the metadata and dependency declarations are in place, you can focus on the essential building blocks of the extension package.

Extensões e pontos de extensãoExtensions and extension points

Um ponto de extensão é um espaço reservado que define uma estrutura de dados (um tipo), enquanto uma extensão define dados que correspondem a uma estrutura especificada por um determinado ponto de extensão.An extension point is a placeholder that defines a data structure (a type), while an extension defines data that conforms to a structure specified by a specific extension point. Os pontos de extensão especificam o tipo de extensão que pode ser aceito em sua declaração.Extension points specify what type of extension they can accept in their declaration. As extensões são declaradas usando nomes de tipos ou caminhos de extensão.Extensions are declared using type names or extension paths. Consulte a Referência de ponto de extensão para ver uma explicação mais aprofundada sobre como criar o ponto de extensão que você precisa.See the Extension Point reference for a more in-depth explanation on how to create the extension point that you need.

A arquitetura de extensão/ponto de extensão mantém o desenvolvimento do Visual Studio para Mac modular e rápida.The extension/extension point architecture keeps the development of Visual Studio for Mac fast and modular.

Extensões de comandoCommand Extensions

As Extensões de Comando são extensões que apontam para métodos que são chamados toda vez que eles são executados.Command Extensions are extensions that point to methods that are called every time it is executed.

As extensões de comando são definidas ao adicionar entradas ao ponto de extensão /MonoDevelop/Ide/Commands.Command Extensions are defined by adding entries to the /MonoDevelop/Ide/Commands extension point. Definimos nossa extensão em Manifest.addin.xml com o código a seguir:We defined our extension in Manifest.addin.xml with the following code:

<Extension path="/MonoDevelop/Ide/Commands/Edit">
 <command id="DateInserter.DateInserterCommands.InsertDate"
           _label="Insert Date"
           _description="Insert the current date"
           defaulthandler="DateInserter.InsertDateHandler" />
</Extension>

O nó de extensão contém um atributo de caminho que especifica o ponto de extensão de conexão, nesse caso /MonoDevelop/Ide/Commands/Edit.The extension node contains a path attribute that specifies the extension point that it is plugging into, in this case /MonoDevelop/Ide/Commands/Edit. Além disso, ele atua como um nó pai para o Comando.Additionally, it acts as a parent node to the Command. O nó Comando tem os seguintes atributos:The Command node has the following attributes:

  • id – Especifica o identificador para esse Comando.id - Specifies the identifier for this Command. Identificadores de comando devem ser declarados como membros de enumeração e são usados para conectar os Comandos aos CommandItems.Command Identifiers must be declared as enumeration members, and are used to connect Commands to CommandItems.
  • _label – O texto a ser mostrado nos menus._label - The text to be shown in menus.
  • _description –O texto a ser mostrado como uma dica de ferramenta para os botões da barra de ferramentas._description - The text to be shown as a tooltip for toolbar buttons.
  • defaultHandler – Especifica a classe CommandHandler que habilita o ComandodefaultHandler - Specifies the CommandHandler class that powers the Command

Uma Extensão CommandItem que se conecta ao ponto de extensão /MonoDevelop/Ide/MainMenu/Edit é demonstrado no seguinte trecho de código:A CommandItem extension that plugs into the /MonoDevelop/Ide/MainMenu/Edit extension point is demonstrated in the following code snippet:

<Extension path="/MonoDevelop/Ide/MainMenu/Edit">
  <commanditem id="DateInserter.DateInserterCommands.InsertDate" />
</Extension>

Um CommandItem posiciona um Comando especificado em seu atributo id em um menu.A CommandItem places a Command specified in its id attribute into a menu. Este CommandItem está estendendo o ponto de extensão /MonoDevelop/Ide/MainMenu/Edit, o que faz com que o rótulo do comando apareça no Menu Editar.This CommandItem is extending the /MonoDevelop/Ide/MainMenu/Edit extension point, which makes the Command's label appear in the Edit Menu. Observe que a id no CommandItem corresponde à ID do nó do Comando, InsertDate.Note that the id in the CommandItem corresponds to the id of the Command node, InsertDate. Se você remover o CommandItem, a opção Inserir Data desaparecerá do Menu Editar.If you were to remove the CommandItem, the Insert Date option would disappear from the Edit Menu.

Manipuladores de comandosCommand Handlers

O InsertDateHandler é uma extensão da classe CommandHandler.The InsertDateHandler is an extension of the CommandHandler class. Ele substitui dois métodos, Update e Run.It overrides two methods, Update and Run. O método Update é consultado sempre que um comando é mostrado em um menu ou executado por meio de associações de chave.The Update method is queried whenever a Command is shown in a menu or executed via key bindings. Alterando o objeto de informações, é possível desabilitar o Comando ou torná-lo invisível, popular comandos de matriz e muito mais.By changing the info object, you can disable the Command or make it invisible, populate array commands, and more. Esse método Update desabilita o comando se ele não encontrar um Documento ativo com um TextEditor para inserção de texto:This Update method disables the command if it can't find an active Document with a TextEditor to insert text into:

protected override void Update (CommandInfo info)
{
    info.Enabled = IdeApp.Workbench.ActiveDocument?.Editor != null;
}

Será necessário substituir o método Update somente se você tiver uma lógica especial para habilitar ou ocultar o Comando.You only need to override the Update method when you have special logic for enabling or hiding the Command. O método Run é executado sempre que um usuário executar um Comando, que nesse caso ocorre quando um usuário seleciona o Comando no Menu Editar.The Run method executes whenever a user executes a Command, which in this case occurs when a user selects the Command from the Edit Menu. Esse método insere a data e a hora na posição do cursor no editor de texto:This method inserts the date and time at the caret in the text editor:

protected override void Run ()
{
  var editor = IdeApp.Workbench.ActiveDocument.Editor;
  var date = DateTime.Now.ToString ();
  editor.InsertAtCaret (date);
}

Declare o tipo de Comando como um membro de enumeração em DateInserterCommands:Declare the Command type as an enumeration member within DateInserterCommands:

public enum DateInserterCommands
{
  InsertDate,
}

Isso vincula o Comando e o CommandItem – o CommandItem chama o Comando quando o CommandItem é selecionado no Menu Editar.This ties together the Command and CommandItem - the CommandItem calls the Command when the CommandItem is selected from the Edit Menu.

APIs de IDEIDE APIs

Para ver informações sobre o escopo das áreas que estão disponíveis para o desenvolvimento, consulte a Referência de árvore de extensões e Visão geral da API.For information on the scope of areas that are available for development, see the Extension Tree Reference and the API Overview. Ao criar pacotes de extensão avançados, consulte também Artigos do desenvolvedor.When building advanced extension packages, also refer to Developer Articles. Veja abaixo uma lista parcial das áreas de personalização:Below is a partial list of areas for customization:

  • PainéisPads
  • Esquemas de associação de teclasKey Binding Schemes
  • PolíticasPolicies
  • Formatadores de códigoCode formatters
  • Formatos de arquivo de projetoProject file formats
  • Painéis de preferênciasPreferences panels
  • Painéis de opçõesOptions Panels
  • Protocolos do depuradorDebugger Protocols
  • Visualizadores do depuradorDebugger visualizers
  • Layouts de espaço de trabalhoWorkspace layouts
  • Nós de árvore do painel de soluçõesSolution pad tree nodes
  • Margens do editor de código-fonteSource editor margins
  • Mecanismos de teste de unidadeUnit test engines
  • Geradores de códigoCode generators
  • Trechos de códigoCode snippets
  • Frameworks de destinoTarget frameworks
  • Tempo de execução de destinoTarget runtime
  • Back-ends de VCSVCS back-ends
  • RefatoraçãoRefactoring
  • Manipuladores de execuçãoExecution handlers
  • Realce de sintaxeSyntax highlighting

Informações adicionaisAdditional Information

Note

Estamos trabalhando para melhorar os cenários de extensibilidade do Visual Studio para Mac.We are currently working on improving the extensibility scenarios for Visual Studio for Mac. Se você estiver criando extensões e precisa de ajuda ou informações adicionais, ou deseja fornecer comentários, preencha o formulário Visual Studio for Mac Extension Authoring (Criação de extensão do Visual Studio para Mac).If you are creating extensions and need additional help or information, or would like to provide feedback, please fill in the Visual Studio for Mac Extension Authoring form.