ExpansionFunction Class

 

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

Namespace:   Microsoft.VisualStudio.Package
Assembly:  Microsoft.VisualStudio.Package.LanguageService.14.0 (in Microsoft.VisualStudio.Package.LanguageService.14.0.dll)

System.Object
  Microsoft.VisualStudio.Package.ExpansionFunction

[CLSCompliantAttribute(false)]
[ComVisibleAttribute(true)]
public abstract class ExpansionFunction : IVsExpansionFunction

NameDescription
System_CAPS_pubmethodExpansionFunction(ExpansionProvider)

Initializes a new instance of the ExpansionFunction class.

NameDescription
System_CAPS_pubpropertyArguments

Gets or sets the arguments to the function.

System_CAPS_pubpropertyExpansionProvider

Gets the expansion provider that owns this expansion function.

System_CAPS_pubpropertyFieldName

Gets or sets the name of the field with which this expansion function is associated.

NameDescription
System_CAPS_pubmethodEquals(Object)

(Inherited from Object.)

System_CAPS_pubmethodFieldChanged(String, Int32)

Called when a field has changed its value.

System_CAPS_protmethodFinalize()

(Inherited from Object.)

System_CAPS_pubmethodGetArgument(Int32)

Gets the specified argument.

System_CAPS_pubmethodGetCurrentValue()

Gets the current value of the expansion function as a string.

System_CAPS_pubmethodGetCurrentValue(String, Int32)

Gets the current value of the expansion function.

System_CAPS_pubmethodGetDefaultValue()

Gets the default value of the expansion function.

System_CAPS_pubmethodGetDefaultValue(String, Int32)

Gets the default value of the expansion function.

System_CAPS_pubmethodGetFieldValue(String, String)

Gets the value of the specified field.

System_CAPS_pubmethodGetFunctionType(UInt32)

Gets the type of the function; that is, what type of value the function returns.

System_CAPS_pubmethodGetHashCode()

(Inherited from Object.)

System_CAPS_pubmethodGetIntellisenseList()

Gets a list of all values the expansion function can return.

System_CAPS_pubmethodGetListCount(Int32)

Gets the number of items in the list of values for the expansion function.

System_CAPS_pubmethodGetListText(Int32, String)

Gets the value of the specified list item.

System_CAPS_pubmethodGetSelection()

Gets the span of the selected text in the current view.

System_CAPS_pubmethodGetType()

(Inherited from Object.)

System_CAPS_protmethodMemberwiseClone()

(Inherited from Object.)

System_CAPS_pubmethodReleaseFunction()

Frees any allocations your ExpansionFunction class may have made.

System_CAPS_pubmethodToString()

(Inherited from Object.)

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 for details on how an expansion function is declared.572c5549-5821-4e15-8ecd-0fa86c1c65df

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.

System_CAPS_warningWarning

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.

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;
        }
    }
}

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

Return to top
Show: