Walkthrough: Creating a Legacy Language Service

Article
11/04/2016

Applies to: Visual Studio Visual Studio for Mac

Note

This article applies to Visual Studio 2017. If you're looking for the latest Visual Studio documentation, see Visual Studio documentation. We recommend upgrading to the latest version of Visual Studio. Download it here

Using the managed package framework (MPF) language classes to implement a language service in Visual C# is straightforward. You need a VSPackage to host the language service, the language service itself, and a parser for your language.

Prerequisites

To follow this walkthrough, you must install the Visual Studio SDK. For more information, see Visual Studio SDK.

Locations for the Visual Studio Package Project Template

The Visual Studio Package Project Template can be found in three different template locations in the New Project dialog box:

Under Visual Basic Extensibility. The default language of the project is Visual Basic.
Under C# Extensibility. The default language of the project is C#.
Under Other Project Types Extensibility. The default language of the project is C++.

Create a VSPackage

Create a new VSPackage with the Visual Studio Package project template.

If you are adding a language service to an existing VSPackage, skip the following steps and go directly to the "Create the Language Service Class" procedure.
Enter MyLanguagePackage for the name of the project and click OK.

You can use whatever name you want. These procedures detailed here assume MyLanguagePackage as the name.
Select Visual C# as the language and the option to generate a new key file. Click Next.
Enter the appropriate company and package information. Click Next.
Select Menu Command. Click Next.

If you do not intend to support code snippets, you can just click Finish and ignore the next step.
Enter Insert Snippet as the Command Name and cmdidInsertSnippet for the Command ID. Click Finish.

The Command Name and Command ID can be whatever you want, these are just examples.

Create the Language Service Class

In Solution Explorer, right-click on the MyLanguagePackage project, choose Add, Reference, and then choose the Add New Reference button.
In the Add Reference dialog box, select Microsoft.VisualStudio.Package.LanguageService in the .NET tab and click OK.

This needs to be done only once for the language package project.
In Solution Explorer, right-click on the VSPackage project and select Add, Class.
Make sure Class is selected in the templates list.
Enter MyLanguageService.cs for the name of the class file and click Add.

You can use whatever name you want. These procedures detailed here assume MyLanguageService as the name.

In the MyLanguageService.cs file, add the following using directives.

using Microsoft.VisualStudio;
using Microsoft.VisualStudio.Package;
using Microsoft.VisualStudio.TextManager.Interop;
using Microsoft.VisualStudio.OLE.Interop;

Imports Microsoft.VisualStudio
Imports Microsoft.VisualStudio.Package
Imports Microsoft.VisualStudio.TextManager.Interop
Imports Microsoft.VisualStudio.OLE.Interop

Modify the MyLanguageService class to derive from the LanguageService class:

class MyLanguageService : LanguageService

Friend Class MyLanguageService
    Inherits LanguageService

Position the cursor on "LanguageService" and from the Edit, IntelliSense menu, select Implement Abstract Class. This adds the minimum necessary methods to implement a language service class.
Implement the abstract methods as described in Implementing a Legacy Language Service.

Register the Language Service

Open the MyLanguagePackagePackage.cs file and add the following using directives:

Imports Microsoft.VisualStudio
Imports Microsoft.VisualStudio.Package
Imports Microsoft.VisualStudio.TextManager.Interop

using Microsoft.VisualStudio;
using Microsoft.VisualStudio.Package;
using Microsoft.VisualStudio.TextManager.Interop;

Register your language service class as described in Registering a Legacy Language Service. This includes the ProvideXX attributes and "Proffering the Language Service" sections. Use MyLanguageService where this topic uses TestLanguageService.

The Parser and Scanner

Implement a parser and scanner for your language as described in Legacy Language Service Parser and Scanner.

How you implement your parser and scanner is entirely up to you and is beyond the scope of this topic.

Language Service Features

To implement each feature in the language service, you typically derive a class from the appropriate MPF language service class, implement any abstract methods as necessary, and override the appropriate methods. What classes you create and/or derive from is dependent on the features you intend to support. These features are discussed in detail in Legacy Language Service Features. The following procedure is the general approach to deriving a class from the MPF classes.

Deriving From an MPF Class

In Solution Explorer, right-click on the VSPackage project and select Add, Class.
Make sure Class is selected in the templates list.

Enter a suitable name for the class file and click Add.

In the new class file, add the following using directives.

using Microsoft.VisualStudio;
using Microsoft.VisualStudio.Package;
using Microsoft.VisualStudio.TextManager.Interop;
using Microsoft.VisualStudio.OLE.Interop;

Imports Microsoft.VisualStudio
Imports Microsoft.VisualStudio.Package
Imports Microsoft.VisualStudio.TextManager.Interop
Imports Microsoft.VisualStudio.OLE.Interop

Modify the class to derive from the desired MPF class.

Add a class constructor that takes at least the same parameters as the base class's constructor and pass the constructor parameters on to the base class constructor.

For example, the constructor for a class derived from the Source class might look like the following:

namespace MyLanguagePackage
{
    class MySource : Source
    {
        public MySource(LanguageService service,
                        IVsTextLines textLines,
                        Colorizer colorizer)
            : base(service, textLines, colorizer)
        {
        }
    }
}

Namespace MyLanguagePackage
    Friend Class MySource
        Inherits Source
        Public Sub New(ByVal service As LanguageService, ByVal textLines As IVsTextLines,
                       ByVal colorizer As Colorizer)
            MyBase.New(service, textLines, colorizer)
        End Sub
    End Class
End Namespace

From the Edit, IntelliSense menu, select Implement Abstract Class if the base class has any abstract methods that must be implemented.
Otherwise, position the caret inside the class and enter the method to be overridden.

For example, type public override to see a list of all methods that can be overridden in that class.

Share via