XLL+ Class Library (7.0)

Preparing to import

To create a set of wrapper functions for a .NET assembly, there are 4 steps required:

  1. Create an XLL+ project that supports CLR.
  2. Add a reference to the assembly, in your project.
  3. Use the Imported Assemblies Window to mark the assembly for instance.
  4. Use the Import Editor to select which methods and properties will be exported as XLL Add-in Functions.

Create a project

When you create your XLL+ project you should make sure that it includes Common Language Runtime support, by ticking the appropriate check-box. See AppWizard - CLR Option for details.

It is also often a good idea to create a directory for the solution, with each project in a sub-directory. You can do this by putting a check against "Create directory for solution" in Visual Studio's "New Project" dialog.

Adding a reference

If you have the source code for the .NET assembly, it is often a good idea to add the assembly's project to the current solution. In Solution Explorer, select the Solution node (the root), right-click it, and click on "Add", then "Existing Project".

To add the reference, select the project node for your add-in in Solution Explorer, right-click it, and select "Properties". In the Project Property Pages, select the page "Common Properties/References". Click the "Add New Reference..." button and the Add Reference dialog will appear. (Be prepared, on occasion, for a very long wait.)

Note that on Visual Studio 2015 and 2017, where there is no "Common Properties/References" node in the Project Properties, you should instead use the Solution Explorer window: select the "References" node under the project node, and right-click it, then select the "Add Reference..." command.

If you have added the .NET assembly as a project (as described above), then go to the Projects tab, select the .NET assembly project and press "OK". If you are just adding a reference to the DLL, then go to the Browse tab, navigate to the DLL, and press "OK".

.NET Runtime target framework

By default, XLL+ projects are created without a specific target framework version of .NET. Later versions of Visual Studio, again by default, will use .NET runtime 4.0 as a target if no target is specified.

If your .NET assembly targets a higher version of .NET, then you must either lower the target version of your .NET assembly or raise the target version of your XLL+ C++ project.

To lower the target version in the .NET assembly project, use the Application page of the C# project's properties, and set the Target framework to be .NET Framework 4. This will make the .NET project compatible with the XLL+ C++ project.

Alternatively, you can change the C++ project to use .NET Framework 4.5 or above as its target framework. Close the project in Visual Studio, or unload it, and directly edit the project file [ProjectName].vcxproj. Locate the element <PropertyGroup Label="Globals"> and insert the desired target framework, e.g.: <TargetFrameworkVersion>v4.5.2</TargetFrameworkVersion> See How to: Modify the Target Framework and Platform Toolset for details.

Project references

There are three major advantages in adding a .NET assembly to your solution as a project rather than just a reference.

Documentation File

If you added an assembly reference, and your .NET assembly has a documentation file, try to make sure that it is available in the same directory as the assembly's dll file. Then the .NET Import Wizard will be able to find it automatically, and will add some of its contents to the XLL, as help text.

If you added a project reference, then make sure that at least one of the configurations of the referenced .NET project (usually the Debug build) is set up to create a documentation file. In the "Project Properties" page, select the "Build" tab, and put a check against "XML documentation file" in the "Output" section near the end of the page.

Build the project

Build the project, and make sure that the imported assembly - along with its documentation file - has been successfully built.

You are now ready to import the assembly.

Next: Imported Assemblies Window >>