Contained Languages

  • Article

Note

This article applies to Visual Studio 2015. 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

Contained languages are languages that are contained by other languages. For example, HTML in ASP.NET pages may contain Visual C# or Visual Basic scripts. A dual-language architecture is required for the .aspx file editor to provide IntelliSense, colorization, and other editing features for both the HTML and the scripting language.

Implementation

The most important interface you need to implement for contained languages is the IVsContainedLanguage interface. This interface is implemented by any language that can be hosted inside a primary language. It gives access to the language service’s colorizer, text view filter, and primary language service ID. The IVsContainedLanguageFactory enables you to create an IVsContainedLanguage interface. The following steps show you how to implement a contained language:

  1. Use QueryService() to get the language service ID and the interface ID of the IVsContainedLanguageFactory.

  2. Call the GetLanguage method to create an IVsContainedLanguage interface. Pass an IVsHierarchy interface, one or more item IDs and an IVsTextBufferCoordinator interface.

  3. The IVsTextBufferCoordinator interface, which is the text buffer coordinator object, provides the basic services that are required to map locations in a primary file into the secondary language’s buffer.

    For example, in a single .aspx file, the primary file includes the ASP, HTML and all the code that is contained. However, the secondary buffer, includes just the contained code, together with any class definitions, to make the secondary buffer a valid code file. The buffer coordinator handles the work of coordinating edits from one buffer to the other.

  4. The SetSpanMappings method, which is the primary language, tells the buffer coordinator what text within its buffer is mapped to corresponding text in the secondary buffer.

    The language passes in an array of the NewSpanMapping structure, which currently only includes a primary and a secondary span.

  5. The MapPrimaryToSecondarySpan method and the MapSecondaryToPrimarySpan method provide the mapping from primary to secondary buffer and vice versa.