Udostępnij za pośrednictwem

ExpansionFunction Class

  • Artykuł

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.10.0 (in Microsoft.VisualStudio.Package.LanguageService.10.0.dll)
  Microsoft.VisualStudio.Package.LanguageService (in Microsoft.VisualStudio.Package.LanguageService.dll)
  Microsoft.VisualStudio.Package.LanguageService.9.0 (in Microsoft.VisualStudio.Package.LanguageService.9.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
Public method ExpansionFunction Initializes a new instance of the ExpansionFunction class.

Top

Properties

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

Top

Methods

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

See Also

Reference

Microsoft.VisualStudio.Package Namespace