Excel add-in functions typically do not have a fixed return type, since they can often return error values. Methods in other programming environments should have fixed return types, and should throw an exception if an error occurs.

By using the ReturnType attribute of the Function element, a developer can enforce this behavior. If the add-in function returns the expected return type, it will be converted and returned to the caller of the wrapper function. If the return type is an error value, or a string containing an error message, then an exception of type XllWrapperException will be thrown.

CopyXML

<Function ExportedName="COEFF.EXPAND" 
          ReturnType="double"/>

If there are any special string return values that you wish to treat as errors, use the ErrorPrefix element:

CopyXML

<Function ExportedName="Code2Name">
    <ErrorPrefixes>
        <ErrorPrefix>Not found</ErrorPrefix>
        <ErrorPrefix>#ERROR</ErrorPrefix>
    </ErrorPrefixes>
</Function>

Names

The name and namespace of the wrapper classes can be controlled with the Client element.

CopyXML

<Client Type="COM"
        Namespace="MyCompany.Analytics"
        Class="Materials"
        ... />

The name of a wrapper function and of its arguments can be controlled using the WrappedName attribute.

CopyXML

<Function ExportedName="COEFF.EXPAND" WrappedName="CoefficientOfExpansion">
  <Argument Name="X" WrappedName="xCoord"/>
</Function>

Signature

The types of each argument can be overridden using the Argument element's IsDate or Type attributes.

CopyXML

<Function ExportedName="DateMatrix" ReturnType="DateTime[,]">
  <Argument Name="Dates" IsDate="1"/>
</Function>

Client element

The Client element defines a single wrapper class that will be generated.

An instruction file normally contains two Client elements, one with type VBA - for use in Visual Basic for Applications - and other with type COM - for use with all other COM and .NET clients.

The developer can change the class name of the wrapper class, and also the namespace.

Guids (globally unique identifiers) are supplied when the information file is created, and should not usually be changed afterwards.

See also Client element in the schema reference.

Function element

The Function element contains instructions for wrapping a single add-in function. These instructions will enrich or override the data in the model file. Some of the attributes of the function element are summarized below.

The element can also contain any number of Argument elements and, optionally, an ErrorPrefixes element.

Attribute	Required	Description	Examples
ExportedName	Required	The name of the function , as it appears in the model file.	NORMSINV2
Wrap	Optional	One of: Always, Never, Default. Controls whether the specified function will be wrapped. If omitted, Default will be assumed.	Always Never Default
ReturnType	Optional	The expected return type of the add-in function. This should be a C# scalar type or array type.	string double[] int[,]
WrappedName	Optional	The name of the function as it will appear in the wrapper method.	NormsInv2

See also Function element in the schema reference.

Argument element

An Argument element is an optional element which controls the wrapping of a single named argument. These instructions will enrich or override the data in the model file. Some of the attributes of the argument element are summarized below.

Attribute	Required	Description	Example(s)
Name	Required	The name of the argument as it appears in the Name attribute of the XlArgument element in the model file.	X
IsDate	Optional	One of: 0, 1. If 1, then the argument will be treated as a date (or an array of dates). In the wrapper class, the argument's type will be DateTime (or DateTime[] or DateTime[,] for an array). If 0 or omitted, then the argument's type will be treated normally.	0 1
WrappedName	Optional	The name of the function as it will appear in the wrapper method.	nItemCount
Type	Optional	The argument type, as it will appear in the C# wrapper function. Only the following basic types are supported: bool, DateTime, double, int, string, object. The type may be a scalar (e.g. int), a vector (e.g. int[]) or a matrix (e.g. int[,]). An argument that accepts a vector or matrix of mixed types should use object[] or object[,] respectively. An argument that accepts a variety of different input types should use object.	string double[] int[,]

See also Argument element in the schema reference.

Other Resources