Extender Visual Studio para MacExtending Visual Studio for Mac

Visual Studio para Mac consta de un conjunto de módulos denominados paquetes de extensión.Visual Studio for Mac consists of a set of modules called Extension Packages. Puede usar los paquetes de extensión para incluir una nueva función en Visual Studio para Mac, como la compatibilidad con un idioma adicional o una nueva plantilla de proyecto.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.

Los paquetes de extensión se compilan desde los puntos de extensión de otros paquetes de extensión.Extension packages build from the extension points of other extension packages. Los puntos de extensión son marcadores de posición para las áreas que se pueden expandir, por ejemplo, un menú o la lista de comandos del IDE.Extension points are placeholders for areas that can be expanded upon, such as a menu or the list of IDE Commands. Puede compilar un paquete de extensión desde un punto de extensión. Para ello, registre un nodo de datos estructurados denominados extensiones, como un nuevo elemento de menú o un comando nuevo.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 punto de extensión acepta ciertos tipos de extensiones, como Command, Pad o FileTemplate.Each extension point accepts certain types of extensions, such as a Command, Pad, or FileTemplate. Un módulo que contiene puntos de extensión se denomina host de complemento, ya que lo pueden extender otros paquetes de extensión.A module that contains extension points is called an add-in host, as it can be extended by other extension packages.

Para personalizar Visual Studio para Mac, puede crear un paquete de extensión que se compile desde los puntos de extensión contenidos en hosts de complemento en las bibliotecas preexistentes de Visual Studio para Mac, como se muestra en el diagrama siguiente: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:

Arquitectura de complementos

Para que un paquete de extensión se compile desde Visual Studio para Mac, debe tener extensiones que se compilen desde puntos de extensión preexistentes en el IDE de 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. Cuando un paquete de extensión se basa en un punto de extensión definido en un host de complemento, se dice que tiene una dependencia en dicho paquete de extensión.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.

La ventaja de este diseño modular es que Visual Studio para Mac es extensible, ya que hay muchos puntos de extensión desde los que se puede compilar con paquetes de extensión 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. Entre los ejemplos de paquetes de extensión actuales se incluyen la compatibilidad con C# y F#, las herramientas del depurador y las plantillas de proyecto.Examples of current extension packages include support for C# and F#, debugger tools, and Project templates.

Nota

Nota: Si tiene un proyecto de Add-in Maker creado antes de Add-in Maker 1.2, debe migrar el proyecto siguiendo los pasos que se describen aquí.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.

En esta sección se examinan los diferentes archivos que genera Add-in Maker y los datos que requiere una extensión de comando.This section looks at the different files generated by the Add-in Maker and the data a command extension requires.

Archivos de atributosAttribute files

Los paquetes de extensión almacenan metadatos sobre el nombre, la versión, las dependencias y otra información en atributos de C#.Extension packages store metadata about their name, version, dependencies, and other information in C# attributes. Add-in Maker crea dos archivos, AddinInfo.cs y AssemblyInfo.cs, para almacenar y organizar esta información.The Add-in Maker creates two files, AddinInfo.cs and AssemblyInfo.cs to store and organize this information. Los paquetes de extensión deben tener un identificador y un espacio de nombres únicos especificados en el atributo Addin:Extension packages must have a unique id and namespace specified in their Addin attribute:

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

Los paquetes de extensión también deben declarar las dependencias en los paquetes de extensión que poseen los puntos de extensión a los que se conectan.Extension packages must also declare dependencies on the extension packages that own the extension points they plug into. Se hace referencia a estos automáticamente en tiempo de compilación.These are automatically referenced at build time.

Además, se pueden agregar referencias adicionales a través del nodo de referencias de complemento en el panel de solución del proyecto, como se muestra en la imagen siguiente: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:

Captura de pantalla de insertar fecha

También se agregan sus atributos assembly:AddinDependency correspondientes en tiempo de compilación.They also have their corresponding assembly:AddinDependency attributes added at build time. Una vez que se han colocado los metadatos y las declaraciones de dependencias, puede centrarse en los bloques de creación fundamentales del paquete de extensión.Once the metadata and dependency declarations are in place, you can focus on the essential building blocks of the extension package.

Extensiones y puntos de extensiónExtensions and extension points

Un punto de extensión es un marcador de posición que define una estructura de datos (un tipo), mientras que una extensión define los datos que se ajustan a una estructura especificada por un punto de extensión específico.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. Los puntos de extensión especifican qué tipo de extensión pueden aceptar en su declaración.Extension points specify what type of extension they can accept in their declaration. Las extensiones se declaran mediante nombres de tipo o rutas de acceso de extensión.Extensions are declared using type names or extension paths. Vea la referencia sobre los puntos de extensión para obtener una explicación más detallada sobre cómo crear el punto de extensión que necesita.See the Extension Point reference for a more in-depth explanation on how to create the extension point that you need.

La arquitectura de extensión/punto de extensión garantiza que el desarrollo de Visual Studio para Mac sea rápido y modular.The extension/extension point architecture keeps the development of Visual Studio for Mac fast and modular.

Extensiones de comandoCommand Extensions

Las extensiones de comando son extensiones que apuntan a los métodos a los que se llama cada vez que se ejecutan.Command Extensions are extensions that point to methods that are called every time it is executed.

Las extensiones de comando se definen mediante la adición de entradas al punto de extensión /MonoDevelop/Ide/Commands.Command Extensions are defined by adding entries to the /MonoDevelop/Ide/Commands extension point. Hemos definido nuestra extensión en Manifest.addin.xml con el código siguiente: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>

El nodo de extensión contiene un atributo de ruta de acceso que especifica el punto de extensión al que se conecta, en este 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. Además, actúa como nodo primario para el comando.Additionally, it acts as a parent node to the Command. El nodo de comando tiene los atributos siguientes:The Command node has the following attributes:

  • id: especifica el identificador de este comando.id - Specifies the identifier for this Command. Los identificadores de comando deben declararse como miembros de enumeración y se usan para conectar Commands a CommandItems.Command Identifiers must be declared as enumeration members, and are used to connect Commands to CommandItems.
  • _label: texto que se mostrará en los menús._label - The text to be shown in menus.
  • _description: texto que se mostrará como una información sobre herramientas para los botones de la barra de herramientas._description - The text to be shown as a tooltip for toolbar buttons.
  • defaultHandler: especifica la clase CommandHandler que activa el comando.defaultHandler - Specifies the CommandHandler class that powers the Command

En el siguiente fragmento de código se muestra una extensión de CommandItem que se conecta al punto de extensión /MonoDevelop/Ide/MainMenu/Edit: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>

CommandItem coloca un comando especificado en su atributo id en un menú.A CommandItem places a Command specified in its id attribute into a menu. Dicho CommandItem extiende el punto de extensión /MonoDevelop/Ide/MainMenu/Edit, lo que hace que la etiqueta del comando aparezca en el menú Edición.This CommandItem is extending the /MonoDevelop/Ide/MainMenu/Edit extension point, which makes the Command's label appear in the Edit Menu. Tenga en cuenta que el valor de id de CommandItem se corresponde con el identificador del nodo de comandos, InsertDate.Note that the id in the CommandItem corresponds to the id of the Command node, InsertDate. Si quita CommandItem, la opción Insertar fecha desaparecerá del menú Edición.If you were to remove the CommandItem, the Insert Date option would disappear from the Edit Menu.

Controladores de comandosCommand Handlers

InsertDateHandler es una extensión de la clase CommandHandler.The InsertDateHandler is an extension of the CommandHandler class. Reemplaza dos métodos, Update y Run.It overrides two methods, Update and Run. El método Update se consulta cada vez que un comando se muestra en un menú o se ejecuta mediante enlaces de teclado.The Update method is queried whenever a Command is shown in a menu or executed via key bindings. Al cambiar el objeto de información, puede deshabilitar el comando o convertirlo en invisible, rellenar comandos de matriz, etc.By changing the info object, you can disable the Command or make it invisible, populate array commands, and more. El método Update deshabilita el comando si no encuentra un objeto Document activo con un objeto TextEditor en el que insertar 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;
}

Solo necesita invalidar el método Update cuando tiene una lógica especial para habilitar u ocultar el comando.You only need to override the Update method when you have special logic for enabling or hiding the Command. El método Run se ejecuta cada vez que un usuario ejecuta un comando, lo que en este caso se produce cuando un usuario selecciona el comando en el menú Edición.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. Este método inserta la fecha y hora en el símbolo de inserción en el 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 el tipo Command como un miembro de enumeración en DateInserterCommands:Declare the Command type as an enumeration member within DateInserterCommands:

public enum DateInserterCommands
{
  InsertDate,
}

Esto enlaza Command y CommandItem y, cuando en el menú Edición se selecciona CommandItem, este llama a Command.This ties together the Command and CommandItem - the CommandItem calls the Command when the CommandItem is selected from the Edit Menu.

API del IDEIDE APIs

Para obtener información sobre el ámbito de las áreas disponibles para el desarrollo, vea Extension Tree Reference (Referencia del árbol de extensión) y API Overview (Introducción a la API).For information on the scope of areas that are available for development, see the Extension Tree Reference and the API Overview. Al compilar paquetes de extensión avanzados, vea también los artículos para desarrolladores.When building advanced extension packages, also refer to Developer Articles. A continuación se muestra una lista parcial de las áreas que se pueden personalizar:Below is a partial list of areas for customization:

  • PanelesPads
  • Esquemas de enlace del tecladoKey Binding Schemes
  • DirectivasPolicies
  • Formateadores de códigoCode formatters
  • Formatos de archivos de proyectoProject file formats
  • Paneles de preferenciasPreferences panels
  • Paneles de opcionesOptions Panels
  • Protocolos del depuradorDebugger Protocols
  • Visualizadores del depuradorDebugger visualizers
  • Diseños del área de trabajoWorkspace layouts
  • Nodos de árbol del panel de solucionesSolution pad tree nodes
  • Márgenes del editor de código fuenteSource editor margins
  • Motores de prueba unitariaUnit test engines
  • Generadores de códigoCode generators
  • Fragmentos de códigoCode snippets
  • Versiones de .NET Framework de destinoTarget frameworks
  • Tiempo de ejecución de destinoTarget runtime
  • Back-end de VCSVCS back-ends
  • RefactorizaciónRefactoring
  • Controladores de ejecuciónExecution handlers
  • Resalte de sintaxisSyntax highlighting

Información adicionalAdditional Information

Nota

Actualmente estamos trabajando para mejorar los escenarios de extensibilidad de Visual Studio para Mac.We are currently working on improving the extensibility scenarios for Visual Studio for Mac. Si está creando extensiones y necesita más información o ayuda, o si quiere proporcionar comentarios, rellene el formulario Visual Studio for Mac Extension Authoring (Creación de extensiones de 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.