AuthoringSink Class

Definition

Namespace:

Microsoft.VisualStudio.Package

Assembly:

Microsoft.VisualStudio.Package.LanguageService.15.0.dll

Package:

Microsoft.VisualStudio.Package.LanguageService.15.0 v17.12.40392

Important

This API is not CLS-compliant.

AuthoringSink is used to gather information from the parser to help in the following:

• error reporting
• matching braces (ctrl-])
• intellisense: Member Selection, CompleteWord, QuickInfo, MethodTips
• management of the autos window in the debugger
• breakpoint validation

public ref class AuthoringSink

[Windows::Foundation::Metadata::WebHostHidden]
class AuthoringSink

public class AuthoringSink

type AuthoringSink = class

Public Class AuthoringSink

Inheritance

Object

AuthoringSink

Remarks

An instantiation of this class is used extensively by the parser to remember various language elements that help with the following features:

• Error reporting.

• Brace matching.

• IntelliSense Member Selection, Complete Word, Quick Info, and Method Tips.

• Hidden regions.

• Management of contents of the Autos window in the debugger.

• Breakpoint validation.

The base class has support for all but the last two features.

Errors

The base class uses an internal ArrayList called errors to contain the errors found during parsing. This list is displayed at the end of a full parsing operation by converting each error message into a task list item by calling CreateErrorTaskItem and adding it the Error List task window. These errors are also shown in the source file itself as squiggly lines under the code that is in error. This is handled automatically by the MPF classes. The AuthoringSink class constructor takes a parameter that specifies the maximum number of errors that can be retained by the class.

Brace Matching

The base class uses an internal ArrayList called Braces to contain matching pairs of language elements (such as "{" and "}") as well as matching triples (such as "for()", "{", and "}"). A base class called BraceMatch is used for matching pairs while a derived class called TripleMatch adds information for a third language element. Calling the MatchPair and MatchTriple methods is done only when the reason for parsing is to match braces (see the BraceMatching property for details on the exact reasons). See the Example section of MatchPairfor a description of the BraceMatch class and see the Example section of MatchTriplefor a description of the TripleMatch class.

IntelliSense

IntelliSense has at least four distinct modes that can be supported by the language service. These are:

1. Member Selection: This option provides a list of members for the current scope, typically supplied after the user types a particular character. For example, if the user has entered a variable name followed by a "." then a member list for the type of that variable is displayed for selection.

2. Complete Word: This option presents a list of possible completions for a word being entered by the user.

3. Quick Info: This option presents information about an identifier. This is triggered either by the user holding the mouse cursor over the identifier or by positioning the edit caret on an identifier and selecting Quick Info from the IntelliSense menu.

4. Method Tip: This option presents parameter information to help the user while entering a method and its parameters. A tool tip is displayed showing one of possible several overloaded forms of the method along with the parameters. As the user enters each parameter, the tool tip is updated to show the parameter being typed.

All of these modes are supported by the methods StartName and QualifyName and the internal lists MethodCalls, Names, and SourceLocations. MethodCalls is used to track method signatures as they are parsed. Names and SourceLocations are used to track the method parameters while parsing a method parameter list. Note that for each name in the Names list, there is a corresponding TextSpan object in the SourceLocations list.

Hidden Regions

Hidden regions are sections of code that can optionally be hidden from view by the user. These regions are typically used as part of support for outlining where each method and class can be collapsed into a single line, making the overall class structure clearer. Some languages support specific hidden regions through special keywords. For example, C# uses #region/#endregion to bracket a region that the user normally wants hidden. A hidden region is indicated by a TextSpan object that is wrapped in a NewHiddenRegion object that in turn is stored in an internal array called hiddenRegions. Hidden regions are added by calling AddHiddenRegion.

Autos

While debugging, the Autos window can show all local variables and parameters available in a particular scope of a stack frame. The language service can support these variables by locating them during parsing. This allows the Autos window to be dynamically updated while editing during debugging. The base class AuthoringSink does not support autos so you have to derive a class from the AuthoringSink class and implement the AutoExpression method yourself.

Breakpoint Validation

When a breakpoint is placed, the location of the breakpoint is not validated until debugging actually starts and the debug engine has been loaded. If your language service supports identifying valid sections of code where a breakpoint can be placed, then this information can be used to validate the placement of breakpoints without loading the debug engine. Note that the debug engine is always the final judge when validating breakpoint locations but the language service can provide fast feedback to the user. The base class AuthoringSink does not support breakpoint validation so you have to derive a class from the AuthoringSink class and implement the CodeSpan method yourself.

Notes to Inheritors

If your language service supports expressions in the Autos window or validating breakpoints in a span of code, you need derive a class from the AuthoringSink class and override the appropriate methods (AutoExpression(TextSpan) and CodeSpan). Then override the CreateAuthoringSink(ParseReason, Int32, Int32) method in the Source class to instantiate your version of the AuthoringSink class. The AuthoringSink class is instantiated every time a parse operation is called for.

Notes to Callers

This class is accessed in several places in the Source class in order to handle brace matching, IntelliSense, and error reporting.

Tip: When implementing your class derived from AuthoringScope, add a field to your class to store the AuthoringSink object created for the ParseRequest object. This way, your AuthoringScope object can access all the information stored in the AuthoringSink object.

Constructors

AuthoringSink(ParseReason, Int32, Int32, Int32)

Initializes the AuthoringSink class.

Properties

BraceMatching	Use this property to find if your parser should call MatchPair or MatchTriple
Column	Gets the column the parsing started on.
FindNames	Use this property to find if your parser should call StartName or QualifyName
FoundMatchingBrace	Tracks if a matching pair of braces was added to the internal list.
HiddenRegions	Use this property to find if your parser should call AddHiddenRegion
Line	Returns the line the parsing operation started on.
MethodParameters	Use this property to find if your parser should call StartParameters, NextParameter or EndParameters
ProcessHiddenRegions	Determines whether or not hidden regions should be updated or not based on the calls to AddHiddenRegion. Default is false.
Reason	Returns the reason the parse operation was started.

Methods

AddError(String, String, TextSpan, Severity, TaskCategory)	Add an error message. This method also filters out duplicates so you only see the unique errors in the error list window.
AddHiddenRegion(NewHiddenRegion)	AddHiddenRegion calls this for you, you can call it directly or override it to modify the default behavior.
AddHiddenRegion(TextSpan, String)	Add a hidden region to the internal list.
AddHiddenRegion(TextSpan)	This is in support of outlining.
AutoExpression(TextSpan)	AutoExpression is in support of IVsLanguageDebugInfo.GetProximityExpressions. It is called for each expression that might be interesting for a user in the "Auto Debugging" window. All names that are set using StartName and QualifyName are already automatically added to the "Auto" window! This means that AutoExpression is rarely used.
CodeSpan(TextSpan)	CodeSpan is in support of IVsLanguageDebugInfo.ValidateBreakpointLocation. It is called for each region that contains "executable" code. This is used to validate breakpoints. Comments are automatically taken care of based on TokenInfo returned from scanner. Normally this method is called when a procedure is started/ended.
EndParameters(TextSpan)	EndParameter is called on the end of the paramters, ie. ")".
MatchMultiple(TextSpan[], Int32)	Matching multiples are used to highlight in bold a completed statement. For example a language can define a construct like if ... elif ... elif ... else ... endif A priority can also be given so that multiple overlapping pairs can be prioritized for brace matching. The matching pair with the highest priority (largest integer value) wins.
MatchPair(TextSpan, TextSpan, Int32)	Whenever a matching pair is parsed, e.g. '{' and '}', this method is called with the text span of both the left and right item. The information is used when a user types "ctrl-]" in VS to find a matching brace and when auto-highlight matching braces is enabled. A priority can also be given so that multiple overlapping pairs can be prioritized for brace matching. The matching pair with the highest priority (largest integer value) wins.
MatchTriple(TextSpan, TextSpan, TextSpan, Int32)	Matching tripples are used to highlight in bold a completed statement. For example when you type the closing brace on a foreach statement VS highlights in bold the statement that was closed. The first two source contexts are the beginning and ending of the statement that opens the block (for example, the span of the "foreach(...){" and the third source context is the closing brace for the block (e.g., the "}"). A priority can also be given so that multiple overlapping pairs can be prioritized for brace matching. The matching pair with the highest priority (largest integer value) wins.
NextParameter(TextSpan)	NextParameter is called after StartParameters on the start of each new parameter, ie. ",".
QualifyName(TextSpan, TextSpan, String)	QualifyName is called for each qualification with both the text span of the selector (e.g. ".") and the text span of the name ("WriteLine").
StartName(TextSpan, String)	In support of Member Selection, CompleteWord, QuickInfo, MethodTip, and Autos, the StartName and QualifyName methods are called. StartName is called for each identifier that is parsed (e.g. "Console")
StartParameters(TextSpan)	The StartParameters, Parameter and EndParameter methods are called in support of method tip intellisense (ECMD_PARAMINFO). [StartParameters] is called when the parameters of a method are started, ie. "(". [Parameter] is called on the start of a new parameter, ie. ",". [EndParameter] is called on the end of the paramters, ie. ")".