How Do I Create a Custom Windward Function for the .NET Report Engine?

The .NET Report Engine (the Engine) ships with many functions, however, you may find from time to time you require a function customized to your needs that does not exist in our library. The Engine allows you to define your own custom macro functions to expand the Windward reporting functionality.

In this article we'll work step by step through a Catapult .NET Report Engine custom function example. We'll create a function "LOG(n)", which returns the common logarithm of its argument n.

Requirements

All that's required is the .NET Report Engine.

Create the Custom Function

Navigate to: https://github.com/windward-studios/Windward-Samples and download the code samples as a zip.

Once the zip is downloaded, extract the zip.  Then, under C# Samples > Specialized, there will be a project called CustomFunctions.  Open that folder and open the WindwardCustomFunctions.sln with Visual Studio.

In the Visual Studio Solution Explorer, select the file WindwardCustomFunctions.cs.

Paste this code after the last class MULTIPLYALL:

[FunctionDescription("Returns the common logarithm of the inputted parameter")]
public static double LOG(
[ParameterDescription("Take the common logarithm of this inputted number")] double num) 
//Note the use of [ParameterDescription(string)] which allows for custom tip information in AutoTag.
{
    return System.Math.Log10(num); //Returns the logarithm of the parameter.
}

Finally, click on Build, then select Rebuild Solution.

A notification in the Output pane indicates the build was successful. The build produced a DLL called WindwardCustomFunctions.dll.

To find the new WindwardCustomFunctions.dll file, in Solution Explorer right-click on the project, then select Open Folder in File Explorer.

In File Explorer navigate to WindwardCustomFunctions\bin\Debug\, and there is your new WindwardCustomFunctions.dll. Note this location for the custom function installation steps below.

Install the Custom Function

Installing this new custom function depends on an option you chose during the .NET Report Engine installation. If you chose to install your DLLs into the Global Assembly Cache (GAC) – the installation default – you must register your new DLL in the Global Assembly Cache. If you did not chose this option, you must copy your new DLL to the .NET Report Engine and Report Designer installation directories. Choose the option that applies to you below, and follow those instructions.

.NET Report Engine DLLs Were Installed Into the GAC

  • Open a Visual Studio Command Prompt as administrator (Right-click on Start -> Visual Studio  2015 -> Developer Command Prompt for VS2015 and select "Run as administrator". This will vary depending on your Visual Studio version.).
  • Navigate to the directory where your WindwardCustomFunctions.dll file is located (as shown above): “cd C:\Users\%USERNAME%\Documents\Windward DotNet Engine Samples\CS\Specialized\CustomFunctions\WindwardCustomFunctions\bin\Debug"
  • Add your new WindwardCustomFunctions.dll file to the GAC by typing: “gacutil /i WindwardCustomFunctions.dll” 

.NET Report Engine DLLs Were NOT Installed into the GAC

  1. In File Explorer navigate to the directory where your WindwardCustomFunctions.dll file is located (as shown above): "C:\Users\%USERNAME%\Documents\Windward DotNet Engine Samples\CS\Specialized\CustomFunctions\WindwardCustomFunctions\bin\Debug."
  2. Copy the file WindwardCustomFunctions.dll.
  3. Navigate to the install directory of the .NET Engine, by default: "C:\Program Files (x86)\Windward Studios\Windward .NET Engine."
  4. Open the directory dll\.
  5. Delete the current WindwardCustomFunctions.dll file.
  6. Paste your new file in its place.
  7. Also, if you also have Report Designer installed, navigate to the Report Designer installation directory, by default (for 64-bit): "C:\Program Files\Windward Studios\AutoTag" or "C:\Program Files\Windward Studios\Windward".
  8. Delete the WindwardCustomFunctions.dll file, if present.
  9. Paste your new file in its place.

Set Path to the Custom Functions DLL

Starting In Version 21 also follow these steps

Once you have pasted in the WindwardCustomFunctions.dll file:

  1. Go to your Designer install location (i.e. C:\Program Files\Windward Studios\Windward)
  2.  If the file AutoTag.dll.config file doesn't exist, create it, otherwise open the file.
    1. Here is a reference for the structure of the config file: https://ohana.windwardstudios.com/m/76878/l/976702-report-designer-office-edition-configuration-file-reference
  3. Under the <WindwardReports> section of the config file, add the following line with a full path to your WindwardCustomFunctions.dll file, and save the config file.

<add key="function.files" value="C:\path\to\file\WindwardCustomFunctions.dll"/> 


Test the Installation in Report Designer

First, let's create an Out Tag:

  • Close all open windows of Microsoft Office.
  • Open Microsoft Word.
  • Connect to a data source.
  • Insert an Out Tag

Now, 

  1. Select the Out Tag.
  2. Click on the Equation button in the AutoTag Manager tab.
  3. Choose "Custom" from the "Select a category:" pulldown menu.
  4. You should see the new function LOG() in the "Select a function:" select list.