ExpansionFunction Class

Article
07/12/2014

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

This API is not CLS-compliant.

Inheritance Hierarchy

System.Object
Microsoft.VisualStudio.Package.ExpansionFunction

Namespace: Microsoft.VisualStudio.Package
Assemblies:   Microsoft.VisualStudio.Package.LanguageService.9.0 (in Microsoft.VisualStudio.Package.LanguageService.9.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)
  Microsoft.VisualStudio.Package.LanguageService.10.0 (in Microsoft.VisualStudio.Package.LanguageService.10.0.dll)

Syntax

'Declaration
<ComVisibleAttribute(True)> _
<CLSCompliantAttribute(False)> _
Public MustInherit Class ExpansionFunction _
    Implements IVsExpansionFunction

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

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

[<AbstractClass>]
[<ComVisibleAttribute(true)>]
[<CLSCompliantAttribute(false)>]
type ExpansionFunction =  
    class 
        interface IVsExpansionFunction 
    end

public abstract class ExpansionFunction implements IVsExpansionFunction

The ExpansionFunction type exposes the following members.

Constructors

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

Top

Properties

	Name	Description
	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.

Top

Methods

	Name	Description
	Equals	Determines whether the specified object is equal to the current object. (Inherited from Object.)
	FieldChanged	Called when a field has changed its value.
	Finalize	Allows an object to try to free resources and perform other cleanup operations before it is reclaimed by garbage collection. (Inherited from Object.)
	GetArgument	Gets the specified argument.
	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	Gets the value of the specified field.
	GetFunctionType	Gets the type of the function; that is, what type of value the function returns.
	GetHashCode	Serves as a hash function for a particular type. (Inherited from Object.)
	GetIntellisenseList	Gets a list of all values the expansion function can return.
	GetListCount	Gets the number of items in the list of values for the expansion function.
	GetListText	Gets the value of the specified list item.
	GetSelection	Gets the span of the selected text in the current view.
	GetType	Gets the Type of the current instance. (Inherited from Object.)
	MemberwiseClone	Creates a shallow copy of the current Object. (Inherited from Object.)
	ReleaseFunction	Frees any allocations your ExpansionFunction class may have made.
	ToString	Returns a string that represents the current object. (Inherited from Object.)

Top

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

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.

Share via