We recommend using Visual Studio 2017

Contained Languages


The new home for Visual Studio documentation is Visual Studio 2017 Documentation on docs.microsoft.com.

The latest version of this topic can be found at Contained Languages.

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.

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, an item ID (one or more of VSITEMID_NIL, VSITEMID_ROOT, or VSITEMID_SELECTION) 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.