LanguageService Class

Article
08/16/2014

This is the base class for a language service that supplies language features including syntax highlighting, brace matching, auto-completion, IntelliSense support, and code snippet expansion.

This API is not CLS-compliant.

Inheritance Hierarchy

System.Object
Microsoft.VisualStudio.Package.LanguageService

Namespace: Microsoft.VisualStudio.Package
Assemblies:   Microsoft.VisualStudio.Package.LanguageService.9.0 (in Microsoft.VisualStudio.Package.LanguageService.9.0.dll)
  Microsoft.VisualStudio.Package.LanguageService.10.0 (in Microsoft.VisualStudio.Package.LanguageService.10.0.dll)
  Microsoft.VisualStudio.Package.LanguageService.11.0 (in Microsoft.VisualStudio.Package.LanguageService.11.0.dll)
  Microsoft.VisualStudio.Package.LanguageService (in Microsoft.VisualStudio.Package.LanguageService.dll)

Syntax

'Declaration
<CLSCompliantAttribute(False)> _
<ComVisibleAttribute(True)> _
Public MustInherit Class LanguageService _
    Implements IDisposable, IVsLanguageInfo, IVsLanguageDebugInfo, IVsProvideColorableItems,  _
    IVsLanguageContextProvider, IServiceProvider, IObjectWithSite, ISynchronizeInvoke, IVsDebuggerEvents,  _
    IVsFormatFilterProvider

[CLSCompliantAttribute(false)]
[ComVisibleAttribute(true)]
public abstract class LanguageService : IDisposable, 
    IVsLanguageInfo, IVsLanguageDebugInfo, IVsProvideColorableItems, IVsLanguageContextProvider, IServiceProvider, 
    IObjectWithSite, ISynchronizeInvoke, IVsDebuggerEvents, IVsFormatFilterProvider

[CLSCompliantAttribute(false)]
[ComVisibleAttribute(true)]
public ref class LanguageService abstract : IDisposable, 
    IVsLanguageInfo, IVsLanguageDebugInfo, IVsProvideColorableItems, IVsLanguageContextProvider, IServiceProvider, 
    IObjectWithSite, ISynchronizeInvoke, IVsDebuggerEvents, IVsFormatFilterProvider

[<AbstractClass>]
[<CLSCompliantAttribute(false)>]
[<ComVisibleAttribute(true)>]
type LanguageService =  
    class 
        interface IDisposable 
        interface IVsLanguageInfo 
        interface IVsLanguageDebugInfo 
        interface IVsProvideColorableItems 
        interface IVsLanguageContextProvider 
        interface IServiceProvider 
        interface IObjectWithSite 
        interface ISynchronizeInvoke 
        interface IVsDebuggerEvents 
        interface IVsFormatFilterProvider 
    end

public abstract class LanguageService implements IDisposable, IVsLanguageInfo, IVsLanguageDebugInfo, IVsProvideColorableItems, IVsLanguageContextProvider, IServiceProvider, IObjectWithSite, ISynchronizeInvoke, IVsDebuggerEvents, IVsFormatFilterProvider

The LanguageService type exposes the following members.

Constructors

	Name	Description
	LanguageService	Initializes a new instance of the LanguageService class.

Top

Properties

	Name	Description
	InvokeRequired	Determines if a method must be invoked across a thread boundary.
	IsActive	Determines whether the language service is connected to the current view and therefore is active.
	IsDebugging	Determines if the debugger is active.
	IsParsing	Determines if a background parse is in progress.
	LastActiveTextView	Returns the last active text view associated with this language service.
	MainThreadId	Returns the id of the thread this language service is running on.
	Name	Returns the name of the language (for example, "C++" or "HTML").
	ParseThreadIsAlive
	ParseThreadPaused
	Preferences	Provides access to the language service preferences.
	Site	Returns the service provider given to this language service.

Top

Methods

	Name	Description
	AbortBackgroundParse
	AddCodeWindowManager	Adds a code window manager to the language service.
	BeginInvoke	Invokes a method on another thread.
	BeginParse	Starts a parse operation on a background thread.
	CanStopThread
	CreateCodeWindowManager	Instantiates a CodeWindowManager class.
	CreateDocumentProperties	Instantiates a DocumentProperties class.
	CreateDropDownHelper	Instantiates a TypeAndMemberDropdownBars class.
	CreateExpansionFunction	Instantiates an ExpansionFunction class.
	CreateExpansionProvider	Instantiates an ExpansionProvider class.
	CreateParseRequest	Creates a request to satisfy the given reason for parsing that is then passed on to the parser.
	CreateSource	Instantiates a Source class.
	CreateViewFilter	Instantiates a ViewFilter class.
	CurFileExtensionFormat	Returns the index into the file extension list that matches the extension of the specified file name.
	DispatchCommand(Guid, UInt32, IntPtr, IntPtr)	Called to execute the specified command.
	DispatchCommand(Guid, UInt32, UInt32, IntPtr, IntPtr)
	Dispose	Called when the language service object is being destroyed.
	EndInvoke	Retrieves the result of an asynchronous call started by LanguageService.BeginInvoke.
	Equals	Determines whether the specified object is equal to the current object. (Inherited from Object.)
	Finalize	Allows an object to try to free resources and perform other cleanup operations before it is reclaimed by garbage collection. (Inherited from Object.)
	GetCodeWindowManager	Instantiates a CodeWindowManager class.
	GetCodeWindowManagerForSource	Returns the CodeWindowManager object associated with the specified Source object.
	GetCodeWindowManagerForView	Returns the CodeWindowManager associated with the specified IVsTextView object.
	GetColorableItem	Returns the requested IVsColorableItem object.
	GetColorizer(IVsTextLines)	Iinstantiates a Colorizer class.
	GetColorizer(IVsTextLines, IVsColorizer%)	Returns the colorizer associated with a Source object that contains the given IVsTextLines object.
	GetFileExtensions	Returns a string containing the file extensions associated with this language.
	GetFormatFilterList	Returns a list of file extension filters suitable for a Save As dialog box.
	GetHashCode	Serves as a hash function for a particular type. (Inherited from Object.)
	GetImageList	Returns an image list containing glyphs associated with the language service.
	GetItemCount	Returns the number of custom colorable items supported by the language service.
	GetIVsDebugger	Returns an IVsDebugger object representing the currently available debugger in order to listen for debugger events.
	GetIVsTextMacroHelperIfRecordingOn	Returns an IVsTextMacroHelper object if macro recording is turned on.
	GetLanguageID	Returns the language GUID of the language service.
	GetLanguageName	Returns the name of the language this language service handles.
	GetLanguagePreferences	Returns a LanguagePreferences object for this language service.
	GetLanguageServiceGuid	Returns the GUID of the language service.
	GetLocationOfName	Obsolete method that always returns E_NOTIMPL.
	GetNameOfLocation	Returns the name of the enclosing element that contains the given position.
	GetOrCreateSource
	GetParseResult	Gets the result of the parse operation.
	GetPrimaryViewForSource
	GetProximityExpressions	Returns a list of expressions to be evaluated and shown in the Autos window, for a given span of lines.
	GetScanner	Returns a single instantiation of a parser.
	GetService	Returns a service object that can be cast to a specific interface.
	GetSite	Returns an unmarshaled pointer to a requested interface.
	GetSource(IVsTextLines)	Returns an existing Source object that contains the specified buffer of source.
	GetSource(IVsTextView)	Returns an existing Source object that contains the source file shown in the specified text view.
	GetSource(String)	Returns an existing Source object given a file name.
	GetSources	Returns a collection of Source objects maintained by the language service.
	GetType	Gets the Type of the current instance. (Inherited from Object.)
	Initialize	Called to initialize the language service.
	Invoke	Called to invoke a task specified by the given delegate.
	IsMacroRecordingOn	Called to determine if macro recording is turned on.
	IsMappedLocation	Called to determine if the specified location in the given source file references code in another file.
	IsSourceOpen	Determines whether or not the source file is open.
	MemberwiseClone	Creates a shallow copy of the current Object. (Inherited from Object.)
	OnActiveViewChanged	Called when the current view has changed to a different view.
	OnCaretMoved	Called when the caret has moved.
	OnChangesCommitted	Called when changes generated by an auto-complete or code snippet expansion operation is committed to the buffer.
	OnCloseSource	Called to close the specified Source object.
	OnIdle	Called when no other events need to be handled.
	OnModeChange	Called whenever the debug mode has changed while debugging.
	OnParseAborted
	OnParseComplete	Called when a background parse has been completed.
	OpenDocument	Opens the specified file.
	ParseSource	Parses the source based on the specified ParseRequest object.
	QueryInvalidEncoding	Determines if the specified source format is valid or not.
	QueryService	Returns the request interface from the specified service.
	QueryWaitForAutoOutliningCallback
	RemoveCodeWindowManager	Called when the view associated with the specified CodeWindowManager is closed.
	ResolveName	Returns a list of method names that match the given name modified by the specified flags.
	ScrollToEnd(IVsTextView)	Updates the specified view to show the end of the source file.
	ScrollToEnd(IVsWindowFrame)	Updates the view in the specified window frame to show the end of the source file.
	SetSite	Called to set or site the service provider for this language service.
	SetUserContextDirty	Marks the user context as dirty in the specified source buffer.
	SynchronizeDropdowns	Called to update a drop-down bar based on the current caret position.
	ToString	Returns a string that represents the current object. (Inherited from Object.)
	UpdateLanguageContext	Updates the current user help context in a selected region of the given source.
	ValidateBreakpointLocation	Called to determine if the given location can have a breakpoint applied to it.

Top

Explicit Interface Implementations

	Name	Description
	IVsFormatFilterProvider.CurFileExtensionFormat	Returns the index into the file extension list that matches the extension of the specified file name.
	IVsFormatFilterProvider.GetFormatFilterList	Returns a list of file extension filters suitable for a Save As dialog box.
	IVsFormatFilterProvider.QueryInvalidEncoding	Determines if the specified source format is valid or not.
	IVsLanguageContextProvider.UpdateLanguageContext	Updates the current user help context given a selected region of the given source.

Top

Remarks

Visual Studio uses language services to provide support for code languages. A language service is registered with Visual Studio when the language service package is installed. Part of this registration process associates a file extension with a language service so any time a file with that extension is loaded, the language service is also loaded.

The LanguageService class is the base class for your language service. Visual Studio instantiates the VSPackage implementing your language service and calls the SetSite method on the VSPackage. In the implementation of this method, the Initialize method on the Package base class is called. Override the Initialize method to instantiate your language service. Remember to call the SetSite method on your language service after instantiation.

Notes to Implementers

Derive a class from this class to create your own language service. You must also, at the very least, implement a parser that implements the IScanner interface. All features of a language service are based on this parser.

The following methods and property are marked as abstract and must be implemented in a class derived tom the LanguageService class:

Method/Property to be Implemented	Description
GetLanguagePreferences	A method that returns a LanguagePreferences object.
GetScanner	A method that returns an IScanner object.
ParseSource	A method that parses the source.
Name	A read-only property that returns the language name

If you do not intend to support the ValidateBreakpointLocation but your language does support breakpoints, you must override the ValidateBreakpointLocation method and return a span that contains the specified line and column; otherwise, breakpoints cannot be set anywhere except line 1. You can return E_NOTIMPL to indicate that you do not otherwise support this method but the span must always be set. The example in the ValidateBreakpointLocation method shows how this can be done.

Notes to Callers

Register your language service when installing your VSPackage (this could be a package dedicated to your language service or it could be a project package that also supplies a language service). You instantiate your own language service during your package initialization. Visual Studio interacts with your language service to display code written in the language supported by your language service. See the example below for how this language registration can be done.

Examples

The following example shows how to register and initialize your language service for your package. Note: MyLanguageService is derived from the LanguageService class.

using System.ComponentModel.Design;
using Microsoft.VisualStudio.Shell;

namespace MyLanguagePackage
{
    /////////////////////////////////////////////
    // Other package registration details go here
    /////////////////////////////////////////////

    // Offer a new language service
    [ProvideServiceAttribute(typeof(MyLanguageService),
                                       ServiceName = "My Language Service")]

    // Register the language service with Visual Studio.
    // "106" is the resource ID in the satellite DLL to the localized language name.
    [ProvideLanguageServiceAttribute(typeof(MyLanguageService),"My Language",106)]

    // Associate a file extension with our language service.
    [ProvideLanguageExtensionAttribute(typeof(MyLanguageService), ".myext")]

    class MyLanguagePackage : Package
    {
        protected override void Initialize()
        {
            base.Initialize();

            IServiceContainer serviceContainer = this as IServiceContainer;
            MyLanguageService languageService = new MyLanguageService();
            languageService.SetSite(this);
            serviceContainer.AddService(typeof(MyLanguageService),
                                        languageService,
                                        true);
        }
    }
}

Thread Safety

Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.