Using Editor Templates to Create Extensions

You can use templates that are included in the Visual Studio SDK to create basic editor extensions that add classifiers, adornments, and margins to the editor.

Prerequisites

To use editor extension templates, you must install the Visual Studio SDK.

Note

For more information about the Visual Studio SDK, see Extending Visual Studio Overview. To find out how to download the Visual Studio SDK, see Visual Studio Extensibility Developer Center on the MSDN Web site.

Creating a Classifier Extension

The Editor Classifier template creates an editor classifier that colors the appropriate text (in this case, everything) in any text file.

To create a classifier extension by using the Editor Classifier template

1. On the File menu, point to New and then click New Project. In the New Project dialog box, expand Visual C# or Visual Basic and then click Extensibility. In the Templates pane, select Editor Classifier. In the Name box, type TestClassifier. Click OK.

   The TestClassifier project is opened.

2. Open the source.extension.vsixmanifest file and edit it as follows:

   • Product Name: TestClassifier

   • Author: Fabrikam

   • Version: 1.0

   • Description: This is a test classifier extension.

   Do not change the ID. It is generated automatically.

3. The Content header specifies the kind of content in this project (Project Template Directory, Item Template Directory, Template Wizard, VSPackage, MEF Component, or Custom Extension Type). One project can contain one or more kinds of content, for example, a VSPackage and a MEF Component. This extension is a MEF Component, and the content is defined in TestClassifier.

4. There are three code files, as follows:

   • TestClassifierType contains the OrdinaryClassificationType class.

   • TestClassifierFormat contains the OrdinaryFormat class.

   • TestClassifier contains the OrdinaryClassifier class and the OrdinaryClassifierProvider class.

5. The OrdinaryClassificationType class exports the ClassificationTypeDefinition, and defines the text that is to be formatted (in this case, all text). This class is exported together with the NameAttribute, which is used to identify this classifier. For more information about classifications, see the "Extending Classification Types and Classification Formats" section of Editor Extension Points.

6. The OrdinaryFormat class inherits from the ClassificationFormatDefinition, and defines the visual effects that the formatting will produce, in this case, a BlueViolet font color and a Underline. This class must be exported as an EditorFormatDefinition type. You can specify whether the formatting is visible to the user by using UserVisibleAttribute, and you can specify the order in which the format is applied to the text by using OrderAttribute.

7. The OrdinaryClassifier class implements the GetClassificationSpans method that identifies the text that is to be classified by using the "ordinary" classifier (in this case, all text).

8. The OrdinaryClassifierProvider class inherits from IClassifierProvider, and implements the GetClassifier method, which instantiates the classifier. This class is exported together with the ContentTypeAttribute, which specifies the kind of content (text, code, or so on) to which this classifier applies. It also takes the TextViewRoleAttribute, which specifies the kind of text view, which can be any of the values of PredefinedTextViewRoles.

9. When you build this solution, copies of the assembly and the manifest are put in the experimental directory.

10. When you run this project in the debugger, a second instance of Visual Studio is instantiated. If you open a text file, all the text is displayed as underlined against a violet background.

Creating a Text-Relative Adornment Extension

The Editor Text Adornment template creates a text-relative adornment that decorates all instances of the text character 'a' by using a box that has a red outline and a blue background. It is text-relative because the box always overlays the 'a' characters, even when they are moved or reformatted.

To create a text adornment extension by using the Editor Text Adornment template

1. On the File menu, point to New and then click New Project. In the New Project dialog box, expand Visual C# or Visual Basic and then click Extensibility. In the Templates pane, select Editor Text Adornment. In the Name box, type TestTextAdornment. Click OK.

   The TestTextAdornment project is opened.

2. Open the source.extension.vsixmanifest file and edit it as follows:

   • Product Name: TestTextAdornment

   • Author: Fabrikam

   • Version: 1.0

   • Description: This is a test text-relative adornment extension.

   Do not change the ID. It is generated automatically.

3. The Content header specifies the kind of content in this project. This extension is a MEF Component, and the content is defined in TestTextAdornment.

4. There are two code files, as follows:

   • TestTextAdornment contains the ScarletCharacter class.

   • TestTextAdornmentFactory contains the EditorAdornmentFactory class.

5. The ScarletCharacter class provides the user interface (UI) features of the adornment in its constructor and handles the LayoutChanged event by finding all the occurrences of the character 'a' in the IWpfTextView and adding the ScarletCharacter adornment.

6. The EditorAdornmentFactory class inherits from IWpfTextViewCreationListener and implements the TextViewCreated method by instantiating the adornment. This class also declares the AdornmentLayerDefinition that corresponds to the ScarletCharacter adornment, and exports it together with the NameAttribute, OrderAttribute, and TextViewRoleAttribute.

7. When you build this solution, copies of the assembly and the manifest are put in the experimental directory.

8. When you run this project in the debugger, a second instance of Visual Studio is instantiated. If you open a text file, all the 'a' characters in the text are displayed as outlined in red against a blue background.

Creating a Viewport-Relative Adornment Extension

The Editor Viewport Adornment template creates a viewport-relative adornment that adds a violet box that has a red outline to the top-right corner of the viewport.

Note

The viewport is the area of the text view that is currently displayed.

To create a viewport adornment extension by using the Editor Viewport Adornment template

1. On the File menu, point to New and then click New Project. In the New Project dialog box, expand Visual C# or Visual Basic and then click Extensibility. In the Templates pane, select Editor Viewport Adornment. In the Name box, type TestViewportAdornment. Click OK.

   The TestViewportAdornment project is opened.

2. Open the source.extension.vsixmanifest file and edit it as follows:

   • Product Name: TestViewportAdornment

   • Author: Fabrikam

   • Version: 1.0

   • Description: This is a test viewport-relative adornment extension.

   Do not change the ID. It is generated automatically.

3. The Content header specifies the kind of content in this project. This extension is a MEF Component, and the content is defined in TestViewportAdornment.

4. There are two code files, as follows:

   • TestViewportAdornment contains the PurpleCornerBox class

   • TestViewportAdornmentFactory contains the AdornmentFactory class

5. The PurpleCornerBox class provides the UI features of the adornment in its constructor and handles the ViewportHeightChanged and ViewportWidthChanged events by deleting and re-adding the adornment at the top-right corner of the viewport.

6. The AdornmentFactory class inherits from IWpfTextViewCreationListener, and implements the TextViewCreated method by instantiating the adornment. This class also declares the AdornmentLayerDefinition that corresponds to the PurpleCornerBox adornment, and exports it together with the NameAttribute, OrderAttribute, and TextViewRoleAttribute.

7. When you build this solution, copies of the assembly and the manifest are put in the experimental directory.

8. When you run this project in the debugger, a second instance of Visual Studio is instantiated. If you open a text file, a violet box that has a red outline is displayed in the top-right corner of the viewport.

Creating a Margin Extension

The Editor Margin template creates a green margin that appears together with the words "Hello world!" below the horizontal scrollbar.

To create a margin extension by using the Editor Margin template

1. On the File menu, point to New and then click New Project. In the New Project dialog box, expand Visual C# or Visual Basic and then click Extensibility. In the Templates pane, select Editor Margin. In the Name box, type TestMargin. Click OK.

   The TestMargin project is opened.

2. Open the source.extension.vsixmanifest file and edit it as follows:

   • Product Name: TestMargin

   • Author: Fabrikam

   • Version: 1.0

   • Description: This is a test margin extension.

   Do not change the ID. It is generated automatically.

3. The Content header specifies the kind of content in this project. This extension is a MEF Component, and the content is defined in TestMargin.

4. There are two code files, as follows:

   • TestMargin contains the GreenMargin class.

   • TestMarginFactory contains the MarginFactory class.

5. The GreenMargin class inherits from Canvas and implements IWpfTextViewMargin. It provides the UI features of the margin in its constructor.

6. The MarginFactory class implements IWpfTextViewMarginProvider, and its implementation of the CreateMargin method instantiates the margin. This class is exported together with the NameAttribute, OrderAttribute, MarginContainerAttribute, ContentTypeAttribute, and TextViewRoleAttribute.

7. When you build this solution, copies of the assembly and the manifest are put in the experimental directory.

8. When you run this project in the debugger, a second instance of Visual Studio is instantiated. If you open a text file, a green margin that has the words "Hello world!" is displayed below the horizontal scrollbar.

See Also

Concepts

Editor Extension Points