Contained Languages

  • Article

Contained languages are languages that are contained by other languages. You may need to implement contained languages to…For example, HTML in ASP.NET Web 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 Process

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

  1. The developer implements QueryService() to query globally for the language service ID and the interface ID of the IVsContainedLanguageFactory.

  2. The developer calls the GetLanguage method to create an IVsContainedLanguage interface. The GetLanguage method that you use to create an IVsContainedLanguage method requires an IVsHierarchy interface, an item ID that consists of one or more of the VSITEMID_NIL, VSITEMID_ROOT, or VSITEMID_SELECTION fields and an IVsTextBufferCoordinator interface.

  3. The IVsTextBufferCoordinator interface, which is the text buffer coordinator object, provides the basic text mapping 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.