ExpansionFunction Class

Definition

Namespace:

Microsoft.VisualStudio.Package

Assembly:

Microsoft.VisualStudio.Package.LanguageService.15.0.dll

Package:

Microsoft.VisualStudio.Package.LanguageService.15.0 v17.11.40262

Important

This API is not CLS-compliant.

Provides support for expansion functions in code snippets for a language service.

public ref class ExpansionFunction abstract : Microsoft::VisualStudio::TextManager::Interop::IVsExpansionFunction

[Windows::Foundation::Metadata::WebHostHidden]
class ExpansionFunction abstract : Microsoft::VisualStudio::TextManager::Interop::IVsExpansionFunction

[System.Runtime.InteropServices.ComVisible(true)]
public abstract class ExpansionFunction : Microsoft.VisualStudio.TextManager.Interop.IVsExpansionFunction

[<System.Runtime.InteropServices.ComVisible(true)>]
type ExpansionFunction = class
    interface IVsExpansionFunction

Public MustInherit Class ExpansionFunction
Implements IVsExpansionFunction

Inheritance

Object

ExpansionFunction

Attributes

ComVisibleAttribute

Implements

IVsExpansionFunction

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="http://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;  
        }  
    }  
}  

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(ExpansionProvider, String) 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(ExpansionProvider, String) method, allowing you to instantiate one of several different versions of your ExpansionFunction class, one for each expansion function.

Notes to Callers

This method is created in the CreateExpansionFunction(ExpansionProvider, String) method of the LanguageService class. The CreateExpansionFunction(ExpansionProvider, String) method is called from GetExpansionFunction(IXMLDOMNode, String, IVsExpansionFunction) 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(IVsTextView, String, String, TextSpan, Boolean), InsertSpecificExpansion(IVsTextView, XmlElement, TextSpan, String), or DisplayExpansionBrowser(IVsTextView, String, String[], Boolean, String[], Boolean) methods in the ExpansionProvider class.

Constructors

ExpansionFunction(ExpansionProvider)

Initializes a new instance of the ExpansionFunction class.

Properties

Arguments	Gets or sets the arguments to the function.
ExpansionProvider	Gets the expansion provider that owns this expansion function.
FieldName	Gets or sets the name of the field with which this expansion function is associated.

Methods

FieldChanged(String, Int32)	Called when a field has changed its value.
GetArgument(Int32)	Gets the value of the specified argument, resolving any fields referenced in the argument. In the substitution, "$$" is replaced with "$" and any floating '$' signs are left unchanged, for example "$US 23.45" is returned as is. Only if the two dollar signs enclose a string of letters or digits is this considered a field name (e.g. "$foo123$"). If the field is not found then the unresolved string "$foo" is returned.
GetCurrentValue()	Gets the current value of the expansion function as a string.
GetCurrentValue(String, Int32)	Gets the current value of the expansion function.
GetDefaultValue()	Gets the default value of the expansion function.
GetDefaultValue(String, Int32)	Gets the default value of the expansion function.
GetFieldValue(String, String)	Gets the value of the specified field.
GetFunctionType(UInt32)	Gets the type of the function; that is, what type of value the function returns.
GetIntellisenseList()	Override this method if you want intellisense drop support on a list of possible values.
GetListCount(Int32)	Gets the number of items in the list of values for the expansion function.
GetListText(Int32, String)	Gets the value of the specified list item.
GetSelection()	Gets the span of the selected text in the current view.
ReleaseFunction()	Frees any allocations your ExpansionFunction class may have made.