How Do I Create a Custom Windward Function for the RESTful Report Engine?
The RESTful 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 custom function example that you can download from here. We'll create a function "LOG(n)", which returns the common logarithm of its argument n.
Starting in Version 21, auto-loading of WindwardCustomFunctions.dll is no longer available you will have to manually activate WindwardCustomFunctions.dll by following the updated instructions below
Custom functions are not supported in templates uploaded to Windward Hub
Create the Custom Function
Unzip CSCustomFunctionWalkthrough.zip then open the WindwardCustomFunctions.sln in 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 for RESTful Engine
- In File Explorer navigate to the directory where your WindwardCustomFunctions.dll file is located (as shown above): "%USERPROFILE%\Downloads\CSCustomFunctionWalkthrough\WindwardCustomFunctions\bin\Debug"
- Copy the file WindwardCustomFunctions.dll.
- Next navigate to the install directory of the RESTful Engine, by default: "C:\inetpub\wwwroot\RESTfulEngine\bin."
- Paste your WindwardCustomFunctions.dll into this directory.
Starting In Version 21 also follow these steps - Open C:\inetpub\wwwroot\RESTfulEngine\web.config
- Add the following under the <WindwardReports> in your "web.config" file
<add key="function.files" value="C:\inetpub\wwwroot\RESTfulEngine\bin\WindwardCustomFunctions.dll"/>
- Save the "web.config" file
Install the Custom Function for the Designer
Installing this new custom function for the Designer depends on an option you chose during the Designer 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 choose this option, you must copy your new DLL to the Report Designer installation directory. Choose the option that applies to you below, and follow those instructions.
Designer 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”
- In file explorer navigate to your navigate to the directory where your WindwardCustomFunctions.dll file is located
- Copy the file WindwardCustomFunctions.dll.
- 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
- Delete the WindwardCustomFunctions.dll file, if present.
- Paste your new WindwardCustomFunctions.dll file in its place.
Starting In Version 21 also follow these steps - Open the "AutoTag2013.dll.config" located in "C:\Program Files\Windward Studios\AutoTag" or "C:\Program Files\Windward Studios\Windward" and add the following string under <WindwardReports>
<add key="function.files" value="C:\Program Files\Windward Studios\Windward\WindwardCustomFunctions.dll"/>
- Save the "AutoTag2013.dll.config" file.
Designer DLLs Were NOT Installed into the GAC
- In File Explorer navigate to the directory where your WindwardCustomFunctions.dll file is located (as shown above): "%USERPROFILE%\Downloads\CSCustomFunctionWalkthrough\WindwardCustomFunctions\bin\Debug"
- Copy the file WindwardCustomFunctions.dll.
- 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".
- Delete the WindwardCustomFunctions.dll file, if present.
- Paste your new WindwardCustomFunctions.dll file in its place.
Starting In Version 21 also follow these steps - Open the "AutoTag2013.dll.config" located in "C:\Program Files\Windward Studios\AutoTag" or "C:\Program Files\Windward Studios\Windward" and add the following string under <WindwardReports>
<add key="function.files" value="C:\Program Files\Windward Studios\Windward\WindwardCustomFunctions.dll"/>
- Save the "AutoTag2013.dll.config" file.
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,
- Select the Out Tag.
- Click on the Equation button in the AutoTag Manager tab.
- Choose "Custom" from the "Select a category:" pulldown menu.
- You should see the new function LOG() in the "Select a function:" select list.