An information file contains instructions for the
CWGENCLS utility.
When you create a new XLL Wrapper project, an information file is created for you,
and is added to the project.
For full details see the Schema reference.
This topic contains the following sections.
Purpose of an information file
An information file allows the developer to fine-tune the signature and behavior of a wrapped
add-in function.
Return type and Error handling
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>
Example of an information file
A simple example of an information file is shown below.
CopyXML
<?xml version="1.0" encoding="utf-8"?>
<XllWrapper Name="MyAddin">
<Clients>
<Client Type="COM"
Namespace="MyNamespace"
Class=" MyAddin"
ClassGuid="51922C8E-F57D-485F-91AD-7B6FB01E046B"
Interface="IMyAddin"
InterfaceGuid="F665828B-9914-41E5-9B74-42505F67A88D"/>
<Client Type="VBA"
Namespace="MyNamespace"
Class="MyAddinVba"
ClassGuid="14636546-A5DE-40F9-B02B-1847BC47C9E5"
Interface="IMyAddinVba"
InterfaceGuid="7CBD1C10-C089-4D34-8BC4-633B729C49C1"/>
</Clients>
<Functions>
<Function ExportedName="MyAddin_VersionInfo"
Wrap="Always"
ReturnType="string[,]"/>
</Functions>
</XllWrapper>
Content
- 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.
See Also
