Getting started with Excel-DNA
==============================

Do this first:
--------------

* The .NET 2.0 runtime must be installed (or .NET 4 with additional settings).
The .NET Framework Version 2.0 Redistributable Package is available from Microsoft here:
http://www.microsoft.com/downloads/details.aspx?FamilyID=0856eacb-4362-4b0d-8edd-aab15c5e04f5&DisplayLang=en

* Macros 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 RuntimeVersion="v2.0" Language="VB">
	<![CDATA[
	
		Public Module MyFunctions

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

		End Module
		
	]]>
	</DnaLibrary>

* (To target .NET 4 or .NET 4.5, use RuntimeVersion="v4.0" instead.)	
* 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.
* There should also be an entry for AddThem in the function wizard, under the category Test1.

Troubleshooting
---------------
* 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 that the .xll file is not recognized (and even opening it as text), you might not have the .NET Framework 2.0 installed. Install it. Otherwise Excel is using .Net version 1.1 by default. To change this, refer back to the prerequisites section.
* 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 form appears with the title 'ExcelDna Compilation Errors' 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.
* Otherwise, if something goes wrong, let me know or post to the Google group noted below.

2. Creating a user-defined function in C#
-----------------------------------------
* Change the contents of Test1.dna to:

<DnaLibrary RuntimeVersion="v2.0" Language="CS">
	<![CDATA[
	
	  using ExcelDna.Integration;
	
		public class MyFunctions
		{
			[ExcelFunction(Description="Joins a string to a number", Category="Useful 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
---------------------------------------------------------
Excel-DNA can also load any compiled .NET library. Public static functions with a compatible signature are exported to Excel.

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

	using ExcelDna.Integration;
	
	public class SomeClass
	{

	    [ExcelFunction(Description="Multiplies two numbers", Category="Useful functions")]
	    public static double MultiplyThem(double v1, double v2)
	    {
        	return v1 * v2;
	    }
	}


* 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>
		<ExternalLibrary Path="TestLib.dll" />
	</DnaLibrary>

* Reload the .xll and check =MultiplyThem(2,3)
* To support .NET 4 assemblies, add a RuntimeVersion="v4.0" attribute to the DnaLibrary tag:

	<DnaLibrary RuntimeVersion="v4.0">
		<ExternalLibrary Path="TestLib.dll" />
	</DnaLibrary>

4. Create an add-in using Visual Studio and the Excel-DNA NuGet package
-----------------------------------------------------------------------
Excel-DNA is also available as a NuGet package. Create a new "Class Library" project (in C#, Visual Basic or F#) and install the "ExcelDna.AddIn" package.
The project will be configured as an Excel add-in, with additional information and instructions in the Readme.txt file that is displayed.
 
5. Additional samples
---------------------
Included in the distribution are various samples in the Distribution\Samples directory. Each sample is a .dna file which can be loaded by putting a renamed copy of ExcelDna.xll in the same directory, where <TheName>.dna must be matched by <TheName>.xll.

6. Getting Support
------------------
The Excel-DNA Google group at https://groups.google.com/forum/#!forum/exceldna is the primary support forum. All questions are welcome.
Formal support agreements for corporate users are also available - see http://excel-dna.net/support/ for details.
 
