ExpansionFunction Class
Provides support for expansion functions in code snippets for a language service.
This API is not CLS-compliant.
Namespace: Microsoft.VisualStudio.Package
Assembly: Microsoft.VisualStudio.Package.LanguageService (in Microsoft.VisualStudio.Package.LanguageService.dll)
Syntax
'Declaration
<ComVisibleAttribute(True)> _
<CLSCompliantAttribute(False)> _
Public MustInherit Class ExpansionFunction _
Implements IVsExpansionFunction
'Usage
Dim instance As ExpansionFunction
[ComVisibleAttribute(true)]
[CLSCompliantAttribute(false)]
public abstract class ExpansionFunction : IVsExpansionFunction
[ComVisibleAttribute(true)]
[CLSCompliantAttribute(false)]
public ref class ExpansionFunction abstract : IVsExpansionFunction
public abstract class ExpansionFunction implements IVsExpansionFunction
Remarks
An expansion function is associated with a field in a code snippet template in order to provide a value or values for that field at the time the snippet is inserted. See Function Element (IntelliSense Code Snippets) for details on how an expansion function is declared.
Whenever a field's value needs to be displayed, the expansion function is "executed", that is, the methods on the ExpansionFunction object that represents the expansion function are called to return the appropriate value.
Notes to Implementers:
If you support expansion functions in code snippets for your language service, you must derive a class from the ExpansionFunction class and implement the GetCurrentValue method. If you want to support multiple values for a field, then you must override the GetIntellisenseList method to return a list of values. Finally, you must override the CreateExpansionFunction method in the LanguageService class and return an instance of your version of the ExpansionFunction class. Note that the name of the expansion function is passed to the CreateExpansionFunction method, allowing you to instantiate one of several different versions of your ExpansionFunction class, one for each expansion function.
Warning
An expansion function that takes arguments or needs to access other fields should not be associated with an editable field as the expansion provider might not be fully initialized by the time the expansion function is called. As a result, the expansion function is not able to obtain the value of its arguments or any other field.
A suitable default value for the field containing the expansion function should always be specified as that default value is always displayed when the code snippet is first inserted.
Notes to Callers:
This method is created in the CreateExpansionFunction method of the LanguageService class. The CreateExpansionFunction method is called from GetExpansionFunction in the ExpansionProvider class that is in turn called by Visual Studio when a code snippet has been inserted and the fields are being filled out. A code snippet is inserted by a call to the InsertNamedExpansion, InsertSpecificExpansion, or DisplayExpansionBrowser methods in the ExpansionProvider class.
Examples
This example shows a code snippet file and associated implementations of expansion functions. The code snippet has two expansion functions, one for showing a list of options, and the second for updating a non-editable field based on the value of its argument (which, in this case, is the value of an editable field).
The code snippet template file (in this case, called class.xml). Note the <Function> tags defining the expansion functions.
<?xml version="1.0" encoding="utf-8" ?>
<CodeSnippets xmlns="https://schemas.microsoft.com/VisualStudio/2005/CodeSnippet">
<CodeSnippet Format="1.0.0">
<Header>
<Title>class</Title>
<Shortcut>class</Shortcut>
<Description>Code snippet for class</Description>
<Author>Microsoft Corporation</Author>
<SnippetTypes>
<SnippetType>Expansion</SnippetType>
<SnippetType>SurroundsWith</SnippetType>
</SnippetTypes>
</Header>
<Snippet>
<Declarations>
<Literal Editable="false">
<ID>ConstructorName</ID>
<Function>GetClassName($ClassName$)</Function>
<Default>MyClass</Default>
</Literal>
<Literal>
<ID>ClassName</ID>
<ToolTip>Class name</ToolTip>
<Default>MyClass</Default>
</Literal>
<Literal>
<ID>access</ID>
<ToolTip>public, internal, private or protected</ToolTip>
<Function>EnumAccessType()</Function>
<Default>public</Default>
</Literal>
</Declarations>
<Code Language="mylanguage"><![CDATA[$access$ class $ClassName$
{
public $ConstructorName$() {
$selected$$end$
}
}]]>
</Code>
</Snippet>
</CodeSnippet>
</CodeSnippets>
This is the implementation of the expansion functions and how they are instantiated from the language service.
using Microsoft.VisualStudio.Package;
namespace MyLanguagePackage
{
//==============================================================
// The Expansion functions.
//--------------------------------------------------------------
// This expansion function returns the value of its argument.
internal class MyGetClassNameExpansionFunction : ExpansionFunction
{
public MyGetClassNameExpansionFunction(ExpansionProvider provider)
: base(provider)
{
}
public override string GetCurrentValue()
{
string argValue = null;
if (this.ExpansionProvider != null)
{
// The expansion session may not be initialized yet
// so do not try to get any arguments if the session is
// is null. In this case, the default value for the
// associated field should be the same as the field
// passed as the argument.
if (this.ExpansionProvider.ExpansionSession != null)
{
argValue = this.GetArgument(0);
}
}
return argValue;
}
}
//--------------------------------------------------------------
// This expansion function returns a list of options.
internal class MyEnumAccessTypeExpansionFunction : ExpansionFunction
{
string[] nameList = null;
public MyEnumAccessTypeExpansionFunction(ExpansionProvider provider)
: base(provider)
{
}
public override string[] GetIntellisenseList()
{
if (nameList == null)
{
nameList = new string[] {
"public",
"protected",
"private",
"internal",
};
}
return nameList;
}
public override string GetCurrentValue()
{
// Enumerations do not need to return a value.
return null;
}
}
//==============================================================
// The language service, showing how the expansion functions are
// instantiated.
//--------------------------------------------------------------
public class MyLanguageService : LanguageService
{
public override ExpansionFunction CreateExpansionFunction(ExpansionProvider provider,
string functionName)
{
ExpansionFunction function = null;
if (String.Compare(functionName, "GetClassName", true) == 0)
{
function = new MyGetClassNameExpansionFunction(provider);
}
else if (String.Compare(functionName, "EnumAccessType", true) == 0)
{
function = new MyEnumAccessTypeExpansionFunction(provider);
}
return function;
}
}
}
Inheritance Hierarchy
System.Object
Microsoft.VisualStudio.Package.ExpansionFunction
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.