Introduction

Important Links

Getting Started

External Links

• Excel development beyond VBA
• Why Excel-DNA?
• How does Excel-DNA work?
• Excel-DNA Hello World function
• Writing an Excel-DNA function using an IDE
• Excel-DNA and the Excel object model

• Simon Murphy - xlls with Excel-DNA
• Ed Parcell - Numerical analysis in Excel using C# with Excel-DNA and AlgLib
• Mathias Brandewinder - Mutant Excel with .NET and Excel-DNA
• Mathias Brandewinder - Supercharge Excel functions with Excel-DNA and .NET parallelism
• Mike Woodhouse - A third way: DNA?
• Patrick O'Beirne - From VBA to VB.NET using Excel-DNA
• Doctor Torsten - Bring Excel 2010 to Speed: Remote UDFs with Excel 2010 and HPC Server 2008 R2
• Luca Bolognese - A trading/portfolio management Excel Add-in based on the books by Ralph Vince
• Supermab's series of blog posts introducing Excel-DNA to Japan (in Japanese)
• Joao Morais - WCF client sample
• Chris Spicer - Excel-DNA function list
• teramonagi - Using R from Excel using Excel-DNA (Also check out the F# R type provider.)

• Dodoni.net is a free/open-source library for quantitative finance and numerical computing.
• EQ Finance - Analytics library for derivatives pricing and risk management
• Technoscience UK has some interesting add-ins to mirror Excel data between PCs.
• Niels Bosma - SEOTools add-in (free, but not open source)
• DC Storm made a little wrapper add-in for the .NET UrlEncode and UrlDecode functions
• compute!box! allows real-time interchange of data between spreadsheets (via Azure Service Bus).

Related Projects

• NetOffice is a set of version-independent assemblies to allow Office integration through the COM automation interface. The NetOffice libraries can be used from an Excel-DNA add-in to ease version-independent Excel add-in development, and ease compatibility with VBA.
• Visual Studio Tools for Office (VSTO) is Microsoft's preferred plan for integrating .NET with Office. It is mainly aimed at making it easy for Visual Studio developers to create solutions integrated with the Office applications. In contrast, Excel-DNA is (eventually) aimed at Excel end-users, as a compelling replacement for VBA, completely independent of Visual Studio.
• Add-in Express is a commercial alternative to VSTO for users with Visual Studio. It support making add-ins for the various Office products, not just Excel, and has helpful wizards and graphics designers.
• Jens Thiel's ManagedXll is an established, commercial product to easily create .xll libraries in .NET. If ManagedXll were free, Excel-DNA would not exist.
• For making Excel Add-Ins in Python, have a look at PyXLL.
• There are a number of C/C++ libraries and tools that make creating .xlls easier than using the Excel SDK directly:
  • I initially used the XLW open-source library.
  • The XLL+ toolkit is a highly regarded commercial option.
  • Keith Lewis has some modern C++ libraries for making .xlls, available on CodePlex at http://xll.codeplex.com/.

Performance

Formal Support Agreements

Donations

Getting Started with ExcelDna

Do this first:

• The .NET Framework 2.0 Runtime or a later version must be installed. The .NET Framework Version 2.0 Redistributable Package is available from Microsoft.
• Get the most recent release of ExcelDna: Download Excel-DNA version 0.29, unzip in a convenient directory.
• Macro security in Excel must not be 'Very High' or 'High' (if set to Medium -- it will prompt whether to enable each macro library). To use the .NET macros you will have to 'Enable' at the prompt.

1. Create a user-defined function in Visual Basic

• Make a copy of ExcelDna.xll in a convenient directory, calling the copy Test1.xll.
• Create a new text file, called Test1.dna (the same prefix as the .xll file), with contents:

<DnaLibrary><![CDATA[

        Public Module MyFunctions


            Function AddThem(x, y)
                AddThem = x + y
            End Function


        End Module
    ]]></DnaLibrary>

• Load Test1.xll in Excel (either File->Open or Tools->Add-Ins and Browse...).
• You should be prompted whether to Enable Macros, click Enable.
• Enter =AddThem(4,2) into a cell - you should get 6. (Under some localized versions of Excel the parameters are separated by a ';', so you'd say =AddThem(4; 2) instead).
• There should also be an entry for AddThem in the function wizard, under the category Test1.

• If you are not prompted to Enable Macros and nothing else happens, your security level is probably on High. Set it to Medium.
• If you get a message indicating the .Net 2.0 runtime could not be loaded, you might not have the .NET Framework 2.0 installed. Install it.
• If Excel crashes with an unhandled exception, an access violation or some other horrible error, either during loading or when running the function, please let me know. This shouldn't happen, and I would like to know if it does.
• If a window appears with the title 'ExcelDna Error Display' then there were some errors trying to compile the code in the .dna file. Check that you have put the right code into the .dna file.
• If Excel prompts for Enabling Macros, and then the function does not work and does not appear in the function wizard, you might not have the right filename for the .dna file. The prefix should be the same as the .xll file and it should be in the same directory.
• Excel is only able to load add-ins, including .xll add-ins, if VBA is installed. (This is under the Office Shared Tools option when installing Office.) Check that VBA is installed by pressing Alt+F11 to open the VBA editor. If it does not open, add VBA to your Office installation.
• Otherwise, if something goes wrong, let me know, or post on the discussion list.

2. Creating a user-defined function in C#

<DnaLibraryLanguage="CS"><![CDATA[

        using ExcelDna.Integration;
	
                public class MyFunctions
                {
                        [ExcelFunction(Description="Joins a string to a number", Category="My functions")]
                        public static string JoinThem(string str, double val)
                        {
                                return str + val;
                        }
                }
    ]]></DnaLibrary>

• Reload the .xll, either from File->Open or in Tools->Add-Ins.
• Check with the formula =JoinThem("abc", 123)
• If the first example worked, this one should too.

3. Making the functions from a compiled library available

• Create a file called TestLib.cs containing the following code:

using ExcelDna.Integration;
			
publicclass MyFunctions
{
        [ExcelFunction(Description="Multiplies two numbers", Category="Useful functions")]
        publicstaticdouble MultiplyThem(double x, double y)
        {
                return x * y;
        }
}

• You need to reference the ExcelDna.Integration.dll assembly (the ExcelFunction attribute is defined there). Copy the file ExcelDna.Integration.dll next to your source file, or reference it in your project. You need not redistribute this file - a copy is embedded as a resource in the redistributable .xll
• Compile TestLib.cs to TestLib.dll: from the command-line: c:\windows\microsoft.net\framework\v2.0.50727\csc.exe /target:library /reference:ExcelDna.Integration.dll TestLib.cs
• Modify Test1.dna to contain:

<DnaLibrary><ExternalLibraryPath="TestLib.dll"/></DnaLibrary>

• Reload the .xll and check =MultiplyThem(2,3) (or =MultiplyThem(2; 3) on some versions).
• If you are compiling your assembly to target .NET 4, you need to tell Excel-DNA to load the right version of the CLR:

<DnaLibraryRuntimeVersion="v4.0"><ExternalLibraryPath="TestLib.dll"/></DnaLibrary>

let MakeTwo x = 2 

public int MakeTwo<T>(T input) = { return 2; }

let MakeTwo (x : float) = 2 

let AddString x y = x.ToString() + y.ToString()

let AddString (x:obj) (y:obj) = x.ToString() + y.ToString()

let Add x y = x + y 

let Add (x:float) (y:float) = x + y 

Getting started

Reference

• .dna Configuration File describes the configuration file.
• Excel-DNA Packing Tool The packing utility allow you to pack your add-in into a single .xll file for easy distribution.
• Installing your add-in and running generally.
• Integrating with VBA
• Performing Asynchronous Work
• Optional Parameters and Default Values
• Keyboard Shortcut
• Using the Excel COM Automation Interfaces
• Excel C API
• Ribbon Customization and various ribbon links.
• Debugging Notes
• COM Server Support
• Reference - other Fragments
• Some notes on FSharp Type Inference

Experimental Features

• Asynchronous Functions
• Reactive Extensions for Excel

Helpful Snippets

• Returning 1-D Arrays

Main Non-Wiki

• In the download: Distribution\GettingStarted.txt -- step by step for simple UDF.
• In the download: Distribution\Samples\*.dna
• In the download: Distribution\Excel-DNA - Step-by-step C# add-in.doc (for Visual Studio).
• http://groups.google.com/group/exceldna -- A lot of good posts here.
• http://www.excel-dna.net New main portal page, but docs and downloads are in Codeplex.

Support

Asynchronous Functions

Usage

• You have to call ExcelAsyncUtil.Initialize() in your AutoOpen:

    public class AsyncTestAddIn : IExcelAddIn
    {
        public void AutoOpen()
        {
            ExcelAsyncUtil.Initialize();
            ExcelIntegration.RegisterUnhandledExceptionHandler(
                ex => "!!! EXCEPTION: " + ex.ToString());
        }

        public void AutoClose()
        {
        }
    }

• Your async UDF then calls AsyncUtil.Run like this:

        public static object SleepAsync(string ms)
        {
            return ExcelAsyncUtil.Run("SleepAsync", ms, delegate
            {
                Debug.Print("{1:HH:mm:ss.fff} Sleeping for {0} ms", ms, DateTime.Now);
                Thread.Sleep(int.Parse(ms));
                Debug.Print("{1:HH:mm:ss.fff} Done sleeping {0} ms", ms, DateTime.Now);
                return "Woke Up at " + DateTime.Now.ToString("1:HH:mm:ss.fff");
            });
        }

• string functionName - identifies this async function.
• object parameters - identifies the set of parameters the function is being called with. Can be a single object (e.g. a string) or an object[] array of parameters.
• ExcelFunc function - a delegate that will be evaluated asynchronously.

More Samples

        public static object DownloadAsync(string url)
        {
            // Don't do anything else here - might run at unexpected times...
            return ExcelAsyncUtil.Run("DownloadAsync", url,
                delegate { return Download(url); });
        }

        public static object WebSnippetAsync(string url, string regex)
        {
            // Don't do anything else here - might run at unexpected times...
            return ExcelAsyncUtil.Run("WebSnippetAsync", new object[] {url, regex},
                delegate
                {
                    string result = Download(url);
                    string match = Regex.Match((result as string), regex,          
                        RegexOptions.Singleline).Groups[1].Value;

                    match = Regex.Replace(match, "\r", " ");
                    match = Regex.Replace(match, "\n", " ");
                    match = Regex.Replace(match, "\t", " ");
                    return match;
                });
        }

        static string Download(string url)
        {
            return new WebClient().DownloadString(url);
        }

Imports System.Runtime.CompilerServices
Imports ExcelDna.Integration

Public Module RxExcel

    <Extension()>
    Public Function ToExcelObservable(Of T)(observable As IObservable(Of T)) As IExcelObservable
        Return New ExcelObservable(Of T)(observable)
    End Function

    Public Function Observe(Of T)(functionName As String, parameters As Object, observableSource As Func(Of IObservable(Of T))) As Object
        Return ExcelAsyncUtil.Observe(functionName, parameters, Function() observableSource().ToExcelObservable())
    End Function
End Module

Public Class ExcelObservable(Of T)
    Implements IExcelObservable

    ReadOnly _observable As IObservable(Of T)

    Public Sub New(observable As IObservable(Of T))
        _observable = observable
    End Sub

    Public Function Subscribe(observer As IExcelObserver) As IDisposable _
        Implements IExcelObservable.Subscribe
        Return _observable.Subscribe(Sub(value) observer.OnNext(value), Sub(ex) observer.OnError(ex), Sub() observer.OnCompleted())
    End Function
End Class

Reactive Extensions for Excel

• You have to call ExcelAsyncUtil.Initialize() in your AutoOpen for any of the Rx stuff to work.

    public class AsyncTestAddIn : IExcelAddIn
    {
        public void AutoOpen()
        {
            // This call is required for the async function and Rx support.
            ExcelAsyncUtil.Initialize();

            // This is optional - allows a custom return value for Exceptions
            // By default exceptions just return #VALUE
            ExcelIntegration.RegisterUnhandledExceptionHandler(ex => "!!! EXCEPTION: " + ex.ToString());
        }

        public void AutoClose()
        {
        }
    }

• I created an adapter class – called RxExcel but I see it is still in the RxAdapter.cs file - to map the .NET 4 Rx types to the Excel-DNA fake types. The idea would be that any add-in doing Rx stuff would just include the RxExcel file.

using System;

namespace ExcelDna.Integration.RxExcel
{
    public static class RxExcel
    {
        public static IExcelObservable ToExcelObservable<T>(this IObservable<T> observable)
        {
            return new ExcelObservable<T>(observable);
        }

        public static object Observe<T>(string functionName, object parameters, Func<IObservable<T>> observableSource)
        {
            return ExcelAsyncUtil.Observe(functionName, parameters, () => observableSource().ToExcelObservable());
        }
    }

    public class ExcelObservable<T> : IExcelObservable
    {
        readonly IObservable<T> _observable;

        public ExcelObservable(IObservable<T> observable)
        {
            _observable = observable;
        }

        public IDisposable Subscribe(IExcelObserver observer)
        {
            return _observable.Subscribe(value => observer.OnNext(value), observer.OnError, observer.OnCompleted);
        }
    }
}

• UDFs that hook up Observables then look like this:

        // Publishes a single value after the interval elapses.
        public static object rxTimerWaitInterval(int intervalSeconds)
        {
            return RxExcel.Observe("rxTimerWaitInterval", intervalSeconds,
            () => Observable.Timer(TimeSpan.FromSeconds(intervalSeconds)));
        }

Some more examples:

using System;
using System.Collections.Generic;
using System.Linq;
using System.Reactive.Linq;
using ExcelDna.Integration;
using ExcelDna.Integration.RxExcel;

namespace AsyncFunctions
{
    public class RxTest
    {
        // Just returns a single value and completes the sequence.
        public static object rxReturn(object value)
        {
            return RxExcel.Observe("rxReturn", value, 
                () => Observable.Return(value));
        }

        // We don't currently distinguish between Empty and Never.
        // Empty is a sequence that immediately completes without pushing a value.
        // So we return #N/A (the pre-Value 'Not Available' return state), 
        // and then never have anything else to return when the sequence completes.
        // CONSIDER: Should we rather transition to an empty string if we comlete without seeing a value?
        public static object rxEmpty()
        {
            return RxExcel.Observe("rxEmpty", null,
                () => Observable.Empty<string>());
        }

        // Never just doesn't return anything, so our functions stays in the #N/A pre-value return state.
        // This seems fine.
        public static object rxNever()
        {
            return RxExcel.Observe("rxNever", null,
                () => Observable.Never<string>());
        }

        // By default, all exceptions are just returned as #VALUE, consistent with the rest of Excel-DNA.
        // If an UnhandledExceptionHandler is registered via Integration.RegisterUnhandledExceptionHandler, 
        // then the result of that handler will be returned by this function.
        public static object rxThrow()
        {
            return RxExcel.Observe("rxThrow", null,
                () => Observable.Throw<string>(new Exception()));
        }

        // Note that the System.Timers.Timer used here will raise it's Elapsed events from a ThreadPool thread.
        // This is fine - the RxExcel RTD server does all the cross-thread marshaling.
        public static object rxCreateTimer(int intervalSeconds)
        {
            return RxExcel.Observe("rxCreateTimer", intervalSeconds,
            () => Observable.Create<string>(
                observer =>
                {
                    var timer = new System.Timers.Timer();
                    timer.Interval = intervalSeconds * 1000;
                    timer.Elapsed += (s, e) => observer.OnNext("Tick at" + DateTime.Now.ToString("HH:mm:ss.fff"));
                    timer.Start();
                    return timer;
                }));
        }

        // Excel will not update for every value in the sequence - just as often as the ThrottleInreval allows.
        // Observable.Interval might generate many values we ignore.
        public static object rxInterval(int intervalSeconds)
        {
            return RxExcel.Observe("rxInterval", intervalSeconds,
            () => Observable.Interval(TimeSpan.FromSeconds(intervalSeconds)));
        }

        // Publishes a single value after the interval elapses.
        public static object rxTimerWaitInterval(int intervalSeconds)
        {
            return RxExcel.Observe("rxTimerWaitInterval", intervalSeconds,
            () => Observable.Timer(TimeSpan.FromSeconds(intervalSeconds)));
        }

        // Publishes a single value at the given time.
        public static object rxTimerWaitUntil(DateTime timeUntil)
        {
            return RxExcel.Observe("rxTimerWaitUntil", timeUntil,
            () => Observable.Timer(timeUntil));
        }

        // A custom sequence returning squares every 5 seconds, up to 20 * 20.
        // Not Observing 'Per Caller' ensures we share a sequnce if using the function in different cells
        public static object rxCreateValues()
        {
            return RxExcel.Observe("rxCreateValuesShared", null,
            () => Observable.Generate(
                    1,
                    i => i <= 20,
                    i => i + 1,
                    i => i * i,
                    i => TimeSpan.FromSeconds(5)));
        }

        // A custom sequence returning squares every intervalSeconds seconds, up to 10 * 10.
        // Observe 'Per Caller' by sending the caller is one of the 'parameters' into RxExcel.Observe. 
        // This ensures we get different sequences if using the function in different cells
        public static object rxCreateValuesPerCaller(int intervalSeconds)
        {
            object caller = XlCall.Excel(XlCall.xlfCaller);

            return RxExcel.Observe("rxCreateValues", new[] {intervalSeconds, caller},
            () => Observable.Generate(
                    1,
                    i => i <= 10,
                    i => i + 1,
                    i => i * i,
                    i => TimeSpan.FromSeconds(5)));
        }

        // Some experiments returning arrays ... not really useful yet.
        public static object rxCreateArrays()
        {
            return RxExcel.Observe("rxCreateArrays", null,
            () => Observable.Generate(
                    new List<object> {1,2,3},
                    lst => true,
                    lst => { lst.Add((int)lst[lst.Count-1] + 1); return lst;},
                    lst => Transpose(lst.ToArray()),
                    lst => TimeSpan.FromSeconds(2)));
        }

        static object[,] Transpose(object[] array)
        {
            object[,] result = new object[array.Length, 1];
            for (int i = 0; i < array.Length; i++)
            {
                result[i,0] = array[i];
            }
            return result;
        }
    }
}

Getting started

Reference

• .dna Configuration File describes the configuration file.
• Excel-DNA Packing Tool The packing utility allow you to pack your add-in into a single .xll file for easy distribution.
• Installing your add-in and running generally.
• Integrating with VBA
• Performing Asynchronous Work
• Optional Parameters and Default Values
• Keyboard Shortcut
• Using the Excel COM Automation Interfaces
• Excel C API
• Ribbon Customization and various ribbon links.
• Debugging Notes
• COM Server Support
• Some notes on FSharp Type Inference
• Asynchronous Functions
• Asynchronous Functions with Tasks example in VB.NET.
• Reactive Extensions for Excel
• Reference - various other Fragments

Helpful Snippets

• Returning 1-D Arrays

Main Non-Wiki

• In the download: Distribution\GettingStarted.txt -- step by step for simple UDF.
• In the download: Distribution\Samples\*.dna
• In the download: Distribution\Excel-DNA - Step-by-step C# add-in.doc (for Visual Studio).
• http://groups.google.com/group/exceldna -- A lot of good posts here.
• http://www.excel-dna.net New main portal page, but docs and downloads are in Codeplex.

Support

    public static DateTime asyncFormatCaller()
    {
        object caller = XlCall.Excel(XlCall.xlfCaller);
        ExcelAsyncUtil.QueueAsMacro(
            delegate
            {
                if (caller is ExcelReference)
                {
                    // Set the formatting of the function caller
                    using (new ExcelSelectionHelper((ExcelReference)caller))
                    {
                        XlCall.Excel(XlCall.xlcFormatNumber, "h:mm:ss");
                    }
                }
            });

        return DateTime.Now;
    }

    // RIIA helper class to set and restore Excel selections
    public class ExcelSelectionHelper : XlCall, IDisposable
    {
        object oldSelectionOnActiveSheet;
        object oldActiveCell;
        object oldSelectionOnRefSheet;

        public ExcelSelectionHelper(ExcelReference refToSelect)
        {
            oldSelectionOnActiveSheet = Excel(xlfSelection);
            oldActiveCell = Excel(xlfActiveCell);

            // Remember old selection and select the first cell of the target
            string refSheet = (string)Excel(xlSheetNm, refToSelect);
            Excel(xlcWorkbookSelect, new object[] { refSheet });
            oldSelectionOnRefSheet = Excel(xlfSelection);
            Excel(xlcFormulaGoto, refToSelect);
        }

        public void Dispose()
        {
            Excel(xlcSelect, oldSelectionOnRefSheet);
            Excel(xlcFormulaGoto, oldSelectionOnActiveSheet, oldActiveCell);
        }
    }

Getting started

Reference

• .dna Configuration File describes the configuration file.
• Excel-DNA Packing Tool The packing utility allow you to pack your add-in into a single .xll file for easy distribution.
• Installing your add-in and running generally.
• Integrating with VBA
• Performing Asynchronous Work
• Optional Parameters and Default Values
• Keyboard Shortcut
• Using the Excel COM Automation Interfaces
• Excel C API
• Ribbon Customization and various ribbon links.
• Debugging Notes
• COM Server Support
• Some notes on FSharp Type Inference
• Asynchronous Functions
• Asynchronous Functions with Tasks example in VB.NET.
• Reactive Extensions for Excel
• Reference - various other Fragments

Helpful Snippets

• Returning 1-D Arrays
• Async macro example - formatting the calling cell from a UDF

Main Non-Wiki

• In the download: Distribution\GettingStarted.txt -- step by step for simple UDF.
• In the download: Distribution\Samples\*.dna
• In the download: Distribution\Excel-DNA - Step-by-step C# add-in.doc (for Visual Studio).
• http://groups.google.com/group/exceldna -- A lot of good posts here.
• http://www.excel-dna.net New main portal page, but docs and downloads are in Codeplex.

Support

    public static DateTime asyncFormatCaller()
    {
        object caller = XlCall.Excel(XlCall.xlfCaller);
        ExcelAsyncUtil.QueueAsMacro(
            delegate
            {
                if (caller is ExcelReference)
                {
                    // Set the formatting of the function caller
                    using (new ExcelSelectionHelper((ExcelReference)caller))
                    {
                        XlCall.Excel(XlCall.xlcFormatNumber, "h:mm:ss");
                    }
                }
            });

        return DateTime.Now;
    }

    // RIIA helper to deal with Excel selections
    public class ExcelSelectionHelper : XlCall, IDisposable
    {
        object oldScreenUpdating;
        object oldSelectionOnActiveSheet;
        object oldActiveCellOnActiveSheet;

        object oldSelectionOnRefSheet;
        object oldActiveCellOnRefSheet;

        public ExcelSelectionHelper(ExcelReference refToSelect)
        {
            oldScreenUpdating = Excel(xlfGetWorkspace, 40);
            Excel(xlcEcho, false);

            // Remember old selection state on the active sheet
            oldSelectionOnActiveSheet = Excel(xlfSelection);
            oldActiveCellOnActiveSheet = Excel(xlfActiveCell);

            // Switch to the sheet we want to select
            string refSheet = (string)Excel(xlSheetNm, refToSelect);
            Excel(xlcWorkbookSelect, new object[] { refSheet });

            // record selection and active cell on the sheet we want to select
            oldSelectionOnRefSheet = Excel(xlfSelection);
            oldActiveCellOnRefSheet = Excel(xlfActiveCell);

            // make the selection
            Excel(xlcFormulaGoto, refToSelect);
        }

        public void Dispose()
        {
            Excel(xlcSelect, oldSelectionOnRefSheet, oldActiveCellOnRefSheet);

            string oldActiveSheet = (string)Excel(xlSheetNm, oldSelectionOnActiveSheet);
            Excel(xlcWorkbookSelect, new object[] { oldActiveSheet });

            Excel(xlcSelect, oldSelectionOnActiveSheet, oldActiveCellOnActiveSheet);

            Excel(xlcEcho, oldScreenUpdating);
        }
    }

    public static DateTime asyncFormatCaller()
    {
        object caller = XlCall.Excel(XlCall.xlfCaller);
        if (caller is ExcelReference)
        {
            ExcelAsyncUtil.QueueAsMacro(
                delegate
                {
                      // Set the desired selection, then apply formatting
                      using (new ExcelSelectionHelper((ExcelReference)caller))
                      {
                          XlCall.Excel(XlCall.xlcFormatNumber, "h:mm:ss");
                      }
                }
            });

        return DateTime.Now;
    }

    // RIIA helper to deal with Excel selections
    public class ExcelSelectionHelper : XlCall, IDisposable
    {
        object oldScreenUpdating;
        object oldSelectionOnActiveSheet;
        object oldActiveCellOnActiveSheet;

        object oldSelectionOnRefSheet;
        object oldActiveCellOnRefSheet;

        public ExcelSelectionHelper(ExcelReference refToSelect)
        {
            oldScreenUpdating = Excel(xlfGetWorkspace, 40);
            Excel(xlcEcho, false);

            // Remember old selection state on the active sheet
            oldSelectionOnActiveSheet = Excel(xlfSelection);
            oldActiveCellOnActiveSheet = Excel(xlfActiveCell);

            // Switch to the sheet we want to select
            string refSheet = (string)Excel(xlSheetNm, refToSelect);
            Excel(xlcWorkbookSelect, new object[] { refSheet });

            // record selection and active cell on the sheet we want to select
            oldSelectionOnRefSheet = Excel(xlfSelection);
            oldActiveCellOnRefSheet = Excel(xlfActiveCell);

            // make the selection
            Excel(xlcFormulaGoto, refToSelect);
        }

        public void Dispose()
        {
            Excel(xlcSelect, oldSelectionOnRefSheet, oldActiveCellOnRefSheet);

            string oldActiveSheet = (string)Excel(xlSheetNm, oldSelectionOnActiveSheet);
            Excel(xlcWorkbookSelect, new object[] { oldActiveSheet });

            Excel(xlcSelect, oldSelectionOnActiveSheet, oldActiveCellOnActiveSheet);

            Excel(xlcEcho, oldScreenUpdating);
        }
    }

    public static DateTime asyncFormatCaller()
    {
        object caller = XlCall.Excel(XlCall.xlfCaller);
        if (caller is ExcelReference)
        {
            ExcelAsyncUtil.QueueAsMacro(
                delegate
                {
                      // Set the desired selection, then apply formatting
                      using (new ExcelSelectionHelper((ExcelReference)caller))
                      {
                          XlCall.Excel(XlCall.xlcFormatNumber, "h:mm:ss");
                      }
                }
            });
        }
        return DateTime.Now;
    }

    // Helper class to deal with Excel selections in 'using' style
    public class ExcelSelectionHelper : XlCall, IDisposable
    {
        object oldScreenUpdating;
        object oldSelectionOnActiveSheet;
        object oldActiveCellOnActiveSheet;

        object oldSelectionOnRefSheet;
        object oldActiveCellOnRefSheet;

        public ExcelSelectionHelper(ExcelReference refToSelect)
        {
            oldScreenUpdating = Excel(xlfGetWorkspace, 40);
            Excel(xlcEcho, false);

            // Remember old selection state on the active sheet
            oldSelectionOnActiveSheet = Excel(xlfSelection);
            oldActiveCellOnActiveSheet = Excel(xlfActiveCell);

            // Switch to the sheet we want to select
            string refSheet = (string)Excel(xlSheetNm, refToSelect);
            Excel(xlcWorkbookSelect, new object[] { refSheet });

            // record selection and active cell on the sheet we want to select
            oldSelectionOnRefSheet = Excel(xlfSelection);
            oldActiveCellOnRefSheet = Excel(xlfActiveCell);

            // make the selection
            Excel(xlcFormulaGoto, refToSelect);
        }

        public void Dispose()
        {
            Excel(xlcSelect, oldSelectionOnRefSheet, oldActiveCellOnRefSheet);

            string oldActiveSheet = (string)Excel(xlSheetNm, oldSelectionOnActiveSheet);
            Excel(xlcWorkbookSelect, new object[] { oldActiveSheet });

            Excel(xlcSelect, oldSelectionOnActiveSheet, oldActiveCellOnActiveSheet);

            Excel(xlcEcho, oldScreenUpdating);
        }
    }

    public static DateTime asyncFormatCaller()
    {
        object caller = XlCall.Excel(XlCall.xlfCaller);
        if (caller is ExcelReference)
        {
            ExcelAsyncUtil.QueueAsMacro(
                delegate
                {
                      // Set the desired selection, then apply formatting
                      using (new ExcelSelectionHelper((ExcelReference)caller))
                      {
                          XlCall.Excel(XlCall.xlcFormatNumber, "h:mm:ss");
                      }
                }
            });
        }
        return DateTime.Now;
    }

    // Helper class to deal with Excel selections in 'using' style
    public class ExcelSelectionHelper : XlCall, IDisposable
    {
        object oldScreenUpdating;
        object oldSelectionOnActiveSheet;
        object oldActiveCellOnActiveSheet;

        object oldSelectionOnRefSheet;
        object oldActiveCellOnRefSheet;

        public ExcelSelectionHelper(ExcelReference refToSelect)
        {
            oldScreenUpdating = Excel(xlfGetWorkspace, 40);
            Excel(xlcEcho, false);

            // Remember old selection state on the active sheet
            oldSelectionOnActiveSheet = Excel(xlfSelection);
            oldActiveCellOnActiveSheet = Excel(xlfActiveCell);

            // Switch to the sheet we want to select
            string refSheet = (string)Excel(xlSheetNm, refToSelect);
            Excel(xlcWorkbookSelect, new object[] { refSheet });

            // record selection and active cell on the sheet we want to select
            oldSelectionOnRefSheet = Excel(xlfSelection);
            oldActiveCellOnRefSheet = Excel(xlfActiveCell);

            // make the selection
            Excel(xlcFormulaGoto, refToSelect);
        }

        public void Dispose()
        {
            Excel(xlcSelect, oldSelectionOnRefSheet, oldActiveCellOnRefSheet);

            string oldActiveSheet = (string)Excel(xlSheetNm, oldSelectionOnActiveSheet);
            Excel(xlcWorkbookSelect, new object[] { oldActiveSheet });

            Excel(xlcSelect, oldSelectionOnActiveSheet, oldActiveCellOnActiveSheet);

            Excel(xlcEcho, oldScreenUpdating);
        }
    }

Introduction

Important Links

Getting Started

External Links

• Excel development beyond VBA
• Why Excel-DNA?
• How does Excel-DNA work?
• Excel-DNA Hello World function
• Writing an Excel-DNA function using an IDE
• Excel-DNA and the Excel object model

• Simon Murphy - xlls with Excel-DNA
• Ed Parcell - Numerical analysis in Excel using C# with Excel-DNA and AlgLib
• Mathias Brandewinder - Mutant Excel with .NET and Excel-DNA
• Mathias Brandewinder - Supercharge Excel functions with Excel-DNA and .NET parallelism
• Mike Woodhouse - A third way: DNA?
• Patrick O'Beirne - From VBA to VB.NET using Excel-DNA
• Doctor Torsten - Bring Excel 2010 to Speed: Remote UDFs with Excel 2010 and HPC Server 2008 R2
• Luca Bolognese - A trading/portfolio management Excel Add-in based on the books by Ralph Vince
• Supermab's series of blog posts introducing Excel-DNA to Japan (in Japanese)
• Joao Morais - WCF client sample
• Chris Spicer - Excel-DNA function list
• teramonagi - Using R from Excel using Excel-DNA (Also check out the F# R type provider.)

• Dodoni.net is a free/open-source library for quantitative finance and numerical computing.
• EQ Finance - Analytics library for derivatives pricing and risk management
• Technoscience UK has some interesting add-ins to mirror Excel data between PCs.
• Niels Bosma - SEOTools add-in (free, but not open source)
• DC Storm made a little wrapper add-in for the .NET UrlEncode and UrlDecode functions
• compute!box! allows real-time interchange of data between spreadsheets (via Azure Service Bus).

Related Projects

• NetOffice is a set of version-independent assemblies to allow Office integration through the COM automation interface. The NetOffice libraries can be used from an Excel-DNA add-in to ease version-independent Excel add-in development, and ease compatibility with VBA.
• Visual Studio Tools for Office (VSTO) is Microsoft's preferred plan for integrating .NET with Office. It is mainly aimed at making it easy for Visual Studio developers to create solutions integrated with the Office applications. In contrast, Excel-DNA is (eventually) aimed at Excel end-users, as a compelling replacement for VBA, completely independent of Visual Studio.
• Add-in Express is a commercial alternative to VSTO for users with Visual Studio. It support making add-ins for the various Office products, not just Excel, and has helpful wizards and graphics designers.
• Jens Thiel's ManagedXll is an established, commercial product to easily create .xll libraries in .NET. If ManagedXll were free, Excel-DNA would not exist.
• For making Excel Add-Ins in Python, have a look at PyXLL.
• There are a number of C/C++ libraries and tools that make creating .xlls easier than using the Excel SDK directly:
  • I initially used the XLW open-source library.
  • The XLL+ toolkit is a highly regarded commercial option.
  • Keith Lewis has some modern C++ libraries for making .xlls, available on CodePlex at http://xll.codeplex.com/.

Performance

Formal Support Agreements

Donations

Introduction

Important Links

Getting Started

External Links

• Excel development beyond VBA
• Why Excel-DNA?
• How does Excel-DNA work?
• Excel-DNA Hello World function
• Writing an Excel-DNA function using an IDE
• Excel-DNA and the Excel object model

• Simon Murphy - xlls with Excel-DNA
• Ed Parcell - Numerical analysis in Excel using C# with Excel-DNA and AlgLib
• Mathias Brandewinder - Mutant Excel with .NET and Excel-DNA
• Mathias Brandewinder - Supercharge Excel functions with Excel-DNA and .NET parallelism
• Mike Woodhouse - A third way: DNA?
• Patrick O'Beirne - From VBA to VB.NET using Excel-DNA
• Doctor Torsten - Bring Excel 2010 to Speed: Remote UDFs with Excel 2010 and HPC Server 2008 R2
• Luca Bolognese - A trading/portfolio management Excel Add-in based on the books by Ralph Vince
• Supermab's series of blog posts introducing Excel-DNA to Japan (in Japanese)
• Joao Morais - WCF client sample
• Chris Spicer - Excel-DNA function list
• teramonagi - Using R from Excel using Excel-DNA (Also check out the F# R type provider.)

• Dodoni.net is a free/open-source library for quantitative finance and numerical computing.
• EQ Finance - Analytics library for derivatives pricing and risk management
• Technoscience UK has some interesting add-ins to mirror Excel data between PCs.
• Niels Bosma - SEOTools add-in (free, but not open source)
• DC Storm made a little wrapper add-in for the .NET UrlEncode and UrlDecode functions
• compute!box! allows real-time interchange of data between spreadsheets (via Azure Service Bus).

Related Projects

• NetOffice is a set of version-independent assemblies to allow Office integration through the COM automation interface. The NetOffice libraries can be used from an Excel-DNA add-in to ease version-independent Excel add-in development, and ease compatibility with VBA.
• Visual Studio Tools for Office (VSTO) is Microsoft's preferred plan for integrating .NET with Office. It is mainly aimed at making it easy for Visual Studio developers to create solutions integrated with the Office applications. In contrast, Excel-DNA is (eventually) aimed at Excel end-users, as a compelling replacement for VBA, completely independent of Visual Studio.
• Add-in Express is a commercial alternative to VSTO for users with Visual Studio. It support making add-ins for the various Office products, not just Excel, and has helpful wizards and graphics designers.
• Jens Thiel's ManagedXll is an established, commercial product to easily create .xll libraries in .NET. If ManagedXll were free, Excel-DNA would not exist.
• For making Excel Add-Ins in Python, have a look at PyXLL.
• There are a number of C/C++ libraries and tools that make creating .xlls easier than using the Excel SDK directly:
  • I initially used the XLW open-source library.
  • The XLL+ toolkit is a highly regarded commercial option.
  • Keith Lewis has some modern C++ libraries for making .xlls, available on CodePlex at http://xll.codeplex.com/.

Performance

Formal Support Agreements

Donations

Getting Started with ExcelDna

Do this first:

• The .NET Framework 2.0 Runtime or a later version must be installed. The .NET Framework Version 2.0 Redistributable Package is available from Microsoft.
• Get the most recent release of ExcelDna: Download Excel-DNA version 0.30, unzip in a convenient directory.
• Macro security in Excel must not be 'Very High' or 'High' (setting to Medium is fine -- it will prompt whether to enable each macro library). To use the .NET macros you will have to 'Enable' at the prompt.

1. Create a user-defined function in Visual Basic

• Make a copy of ExcelDna.xll in a convenient directory, calling the copy Test1.xll.
• Create a new text file, called Test1.dna (the same prefix as the .xll file), with contents:

<DnaLibrary><![CDATA[

        Public Module MyFunctions


            Function AddThem(x, y)
                AddThem = x + y
            End Function


        End Module
    ]]></DnaLibrary>

• Load Test1.xll in Excel (either File->Open or Tools->Add-Ins and Browse...).
• You should be prompted whether to Enable Macros, click Enable.
• Enter =AddThem(4,2) into a cell - you should get 6. (Under some localized versions of Excel the parameters are separated by a ';', so you'd say =AddThem(4; 2) instead).
• There should also be an entry for AddThem in the function wizard, under the category Test1.

• If you are not prompted to Enable Macros and nothing else happens, your security level is probably on High. Set it to Medium.
• If you get a message indicating the .Net 2.0 runtime could not be loaded, you might not have the .NET Framework 2.0 installed. Install it.
• If Excel crashes with an unhandled exception, an access violation or some other horrible error, either during loading or when running the function, please let me know. This shouldn't happen, and I would like to know if it does.
• If a window appears with the title 'ExcelDna Error Display' then there were some errors trying to compile the code in the .dna file. Check that you have put the right code into the .dna file.
• If Excel prompts for Enabling Macros, and then the function does not work and does not appear in the function wizard, you might not have the right filename for the .dna file. The prefix should be the same as the .xll file and it should be in the same directory.
• Excel is only able to load add-ins, including .xll add-ins, if VBA is installed. (This is under the Office Shared Tools option when installing Office.) Check that VBA is installed by pressing Alt+F11 to open the VBA editor. If it does not open, add VBA to your Office installation.
• Otherwise, if something goes wrong, let me know, or post on the discussion list.

2. Creating a user-defined function in C#

<DnaLibraryLanguage="CS"><![CDATA[

        using ExcelDna.Integration;
	
                public class MyFunctions
                {
                        [ExcelFunction(Description="Joins a string to a number", Category="My functions")]
                        public static string JoinThem(string str, double val)
                        {
                                return str + val;
                        }
                }
    ]]></DnaLibrary>

• Reload the .xll, either from File->Open or in Tools->Add-Ins.
• Check with the formula =JoinThem("abc", 123)
• If the first example worked, this one should too.

3. Making the functions from a compiled library available

• Create a file called TestLib.cs containing the following code:

using ExcelDna.Integration;
			
publicclass MyFunctions
{
        [ExcelFunction(Description="Multiplies two numbers", Category="Useful functions")]
        publicstaticdouble MultiplyThem(double x, double y)
        {
                return x * y;
        }
}

• You need to reference the ExcelDna.Integration.dll assembly (the ExcelFunction attribute is defined there). Copy the file ExcelDna.Integration.dll next to your source file, or reference it in your project. You need not redistribute this file - a copy is embedded as a resource in the redistributable .xll
• Compile TestLib.cs to TestLib.dll: from the command-line: c:\windows\microsoft.net\framework\v2.0.50727\csc.exe /target:library /reference:ExcelDna.Integration.dll TestLib.cs
• Modify Test1.dna to contain:

<DnaLibrary><ExternalLibraryPath="TestLib.dll"/></DnaLibrary>

• Reload the .xll and check =MultiplyThem(2,3) (or =MultiplyThem(2; 3) on some versions).
• If you are compiling your assembly to target .NET 4, you need to tell Excel-DNA to load the right version of the CLR:

<DnaLibraryRuntimeVersion="v4.0"><ExternalLibraryPath="TestLib.dll"/></DnaLibrary>