Build Excel Automation Add-in in C#, C++, VB.NET
Excel user-defined functions (UDF) in Visual Studio .NET

Add-in Express™
for Microsoft® Office and .net

Add-in Express Home > Add-in Express for Office and .NET > Online Guide > Excel Automation add-ins

Excel Automation add-ins

Add-in Express allows creating Automation add-ins for Excel 2010, 2007, 2003 and 2002 (XP). The sample below demonstrates how you create an Excel automation add-in providing a sample user-defined function. The source code of the project - both VB.NET and C# versions - can be downloaded here; the download is labeled Add-in Express for Office and .NET sample projects.

A bit of theory

Excel user-defined functions (UDFs) are used to build custom functions in Excel for the end user to use them in formulas. This definition underlines the main restriction of an UDF: it should return a result that can be used in a formula - not an object of any given type but a number, a string, or an error value (Booleans and dates are essentially numbers). When used in an array formula, the UDF should return a properly dimensioned array of values of the types above. Excel shows the value returned by the function in the cell where the user calls the function.

There are two Excel UDF types: Excel Automation add-in and Excel XLL add-in. They differ in several ways described in What Excel UDF Type to Choose?

Per-user Excel UDFs

An Excel UDF is a per-user thing that requires registering in HKCU. In other words, a UDF cannot be registered for all users on the machine. Instead, it must be registered for every user separately.

Step 1. Creating a COM add-in project

Make sure that you have administrative permissions before running Visual Studio. Also, if you have Windows Vista, Windows 7, or Windows 2008, run Visual Studio via Run as Administrator.

In Visual Studio, open the New Project dialog and navigate to the Extensibility folder.

Choose Add-in Express COM Add-in and click OK.

This starts the COM Add-in project wizard.

The wizard allows choosing your programming language and specifying the oldest Office version your add-in needs to support.

Choosing a particular Office version will add corresponding interop assemblies to the project. Later on, in case you need to support an older or a newer Office version, you will be able to replace interop assemblies and reference them in your project. If you are in doubt, choose Microsoft Office 2002 as the minimum supported Office version (because Excel Automation add-ins are supported in Excel 2002 and higher). If you need background information, see Choosing interop assemblies.

Choose your programming language and the minimum Office version that you want to support and click Next.

The wizard allows creating add-in projects targeting several Office applications; you select Excel.

For the settings shown on the screenshot above, the project wizard will do the following:

• copy the corresponding version of Excel interop assembly to the Interops folder of your project folder
• add an assembly reference to the project
• add a COM add-in module to the project
• set up the SupportedApp property of the add-in module.

Select Excel as the Office application your add-in will support and click Next.

If you don't know anything about strong names or don't have a special strong name key file, choose Generate new. If you are in doubt, choose Generate new. If, later on, you need to use a specific strong name key file, you will be able to specify its name on the Signing tab of your project properties; you are required to unregister your add-in project before using another strong name.

Choose Generate new or specify an existing .snk file and click Next.

The project wizard creates and opens a new solution in the Visual Studio IDE.

The solution contains an only project, the COM add-in project.

Step 2. Adding a COM Excel Add-in module

Open the Add New Item dialog for the COM add-in project and navigate to Excel below Add-in Express Items. In order to add Excel user-defined functions to the COM add-in, you choose the COM Excel Add-in Module in the Add New Item dialog.

Choose COM Excel Add-in Module and click OK. This adds the ExcelAddinModule1.vb (or ExcelAddinModule1.cs) file to the COM add-in project.

Step 3. Writing a user-defined function

In Solution Explorer, right-click ExcelAddinModule.vb (or ExcelAddinModule.cs) and choose View Code in the context menu.

Add a new public function to the class and write the code below:

 			  
Imports Excel = Microsoft.Office.Interop.Excel
...
Public Function MyFunc(ByVal Range As Object) As Object
   MyFunc = CType(Range, Excel.Range).Value * 1000
End Function

Step 4. Running the add-in

Choose Register Add-in Express Project in the Build menu, restart Excel, and check if your add-in works.

If you use an Express edition of Visual Studio, the Register Add-in Express Project item is located in the context menu of the COM add-in module's designer surface.

You can find your Excel add-in in the Add-ins dialog:

• in Excel 2000-2003, see Tools | Add-ins
• in Excel 2007, see Office Button | Excel Options | Add-ins | Manage "Excel add-ins" | Go
• in Excel 2010, see File | Options | Add-ins | Manage "Excel add-ins" | Go.

Step 5. Debugging the Excel Automation add-in

To debug your add-in, specify Excel as the Start Program in the Project Options window and run the project.

Step 6. Deploying the add-in

The table below provides links to step-by-step instructions for deploying Excel Automation add-ins. Find background information in Deploying Office extensions.

What's next?

Here you can download the project described above, both VB.NET and C# versions; the download link is labeled Add-in Express for Office and .NET sample projects.

You may want to check the following sections under Add-in Express tips and notes:

• Development - typical misunderstandings, useful tips and a must-read section Releasing COM Objects.
• Excel UDFs - many useful articles on developing Excel user-defined functions including What Excel UDF type to choose?

If you develop a combination of Excel extensions, please check HowTo: Create a COM add-in, XLL UDF and RTD server in one assembly.

Back to Add-in Express for Office and .NET homepage