Getting Started with Scripting Integrator

Requirements: Scripting Integrator

Introduction

Scripting Integrator is a powerful pair of fully-embeddable scripting components that enable developers to extend applications with support for custom scripting through JavaScript and PowerShell.

This article goes through the basic functionality of the Scripting Integrator components. Before continuing, it is recommended to download Scripting Integrator in order to follow along with this tutorial.

Contents

  1. Setup
  2. Executing Scripts
  3. Integrating Custom Functions and Variables

Setup

This section details the additional libraries that are used by the components, and are necessary for execution of scripts.

JavaScript Setup

All editions of Scripting Integrator require a JavaScript engine. In all languages the actual engine must be present and accessible at runtime.

Several engine libraries are shipped with the product in the lib folder. The engines do not need to be included in your project, but must be present at runtime in order to be loaded.

.NET Engines

The component supports two different JavaScript engines: The V8 JavaScript engine from Google and the Jurassic engine. Possible values for this property are:

  • NSILP_JavaScript.v8.dll (default)
  • NSILP_JavaScript.Jurrasic.dll (.NET Edition Only)

If the V8 JavaScript engine is used the two dlls NSILP_JavaScript.v8.x86.dll and NSILP_JavaScript.v8.x64.dll are also relevant. The NSILP_JavaScript.v8.dll is a managed library which will call the appropriate native library (NSILP_JavaScript.v8.x86.dll or NSILP_JavaScript.v8.x64.dll). The application's target architecture determines which native dll will be needed at runtime. When distributing an application, both NSILP_JavaScript.v8.dll and NSILP_JavaScript.v8.x86.dll or NSILP_JavaScript.v8.x64.dll should be deployed as well.

It is safe to deploy both NSILP_JavaScript.v8.x86.dll and NSILP_JavaScript.v8.x64.dll. The appropriate native library will be loaded at runtime.

Java Engines

The component supports the Rhino JavaScript engine. Possible values for this property are:

  • NSILP_JavaScript.jar (default)

Windows Engines

This section applies to all languages that are not .NET or Java. The component supports the V8 JavaScript engine from Google. This is provided in both 32 bit and 64 bit versions. The following files are present in the lib and lib64 directories respectively:

  • NSILP_JavaScript.v8.x86.dll
  • NSILP_JavaScript.v8.x64.dll

At runtime the component will load the appropriate library depending on the target architecture of the application.

To specify a JavaScript engine, set the Engine property of the JavaScript component to the path of the preferred engine. For instance:

//specify the JavaScript engine
javascript1.Engine = scriptingIntegratorDirectory + "\\lib\\NSILP_JavaScript.v8.dll";

Interface Libraries (.NET and Java)

In .NET and Java the component uses a common interface which acts as a bridge between the component itself and the actual engine. The component will make calls to the interface library which will in turn make calls to the selected engine. Every project must include the interface library, as well as the selected engine library.

The interface library is a separate file:

  • nsoftware.InScript.Interface.dll
  • inscript.interface.jar

This file must be included in your project. Editions other than .NET or Java do not require the interface library.

PowerShell Setup

.NET: The .NET edition of Scripting Integrator does not require any additional dependencies to run.

Other Editions: For all other editions a separate library is required to execute PowerShell scripts. The NSILP_PowerShell.x86.dll and the NSILP_PowerShell.64.dll files are present in the lib and lib64 folders respectively. Depending on the target platform of your project (32 bit or 64 bit) one of the above dlls must be available at runtime.

The PowerShell component does not require programmatically specifying an engine.

Executing Scripts

Both the JavaScript component and PowerShell component can read scripts from a file or from a string. If formatted as a string, scripts should be passed as a parameter to the Eval method. If the script is stored in a file, the path should be passed as a parameter to the EvalFile method. When a script is successfully executed, the Eval or EvalFile method will return a string containing the output of the script. For example:

JavaScript
// Print 'Hello World'
String script = "function sayHello(){ return 'Hello World!';} \r\n sayHello();"
Console.WriteLine(javascript1.Eval(script));
PowerShell
// Print 'Hello World'
String script = "Function Say-Hello{\r\nWrite-Output 'Hello World!'} \r\n Say-Hello";
Console.WriteLine(powershell1.Eval(script));

If the script fails to execute, the component will not throw an exception. Instead, the Error event will fire and should be handled to access information about the error. For instance:

// Error event handler delegate
javascript1.OnError += (o, e) => 
{
	Console.WriteLine("Error: " + e.Description);
};

Integrating Custom Functions and Variables

Both Scripting Integrator components can add variable or function definitions to the running context of the script. The PowerShell component can also load PowerShell Profiles for function and variable definitions.

Custom Functions

Functions can be defined by first passing the name of the function to AddFunction, then defining the function behavior in the Function event handler.

Inside the Function event handler, the Name parameter holds the name of the function being executed. The component's Parameters property can be inspected to access any parameters passed to the function in the script. When execution is complete the ReturnValue parameter of the event should be set to the value to be returned by the function. For example:

JavaScript
// Add a function, define behavior in event handler
javascript1.AddFunction("multiply");
javascript1.OnFunction += (o, e) =>
{
	if (e.Name.Equals("multiply")
	{
		int param1 = Int32.Parse(javascript1.Parameters[0].Value);
		int param2 = Int32.Parse(javascript1.Parameters[1].Value);
		int product = param1 * param2;
		e.ReturnValue = product.ToString();
	}
}
String script = "multiply(2,3);";
Console.WriteLine(javascript1.Eval(script));
PowerShell
// Add a function, define behavior in event handler
powershell1.AddFunction("Square");
powershell1.OnFunction += (o, e) =>
{
	if (e.Name.Equals("Square")
	{
		int param = Int32.Parse(powershell1.Parameters[0].Value);
		int product = param * param;
		e.ReturnValue = product.ToString();
	}
}
String script = "Square 2";
Console.WriteLine(powershell1.Eval(script));

Variables

Variables can be defined and added to the scope of the script using the AddVariable method, which takes the variable name and value as parameters. For example:

JavaScript
// Add a variable, use it in a function
javascript1.AddVariable("myNum","5");
javascript1.AddFunction("multiply");
javascript1.OnFunction += (o, e) =>
{
	if (e.Name.Equals("multiply")
	{
		int param1 = Int32.Parse(javascript1.Parameters[0].Value);
		int param2 = Int32.Parse(javascript1.Parameters[1].Value);
		int product = param1 * param2;
		e.ReturnValue = product.ToString();
	}
}
String script = "multiply(myNum,3);";
Console.WriteLine(javascript1.Eval(script));
PowerShell
// Add a variable, use it in a function
powershell.AddVariable("MyNum","5");
powershell1.AddFunction("Square");
powershell1.OnFunction += (o, e) =>
{
	if (e.Name.Equals("Square")
	{
		int param = Int32.Parse(powershell1.Parameters[0].Value);
		int product = param * param;
		e.ReturnValue = product.ToString();
	}
}
String script = "Square $MyNum";
Console.WriteLine(powershell1.Eval(script));

PowerShell Profiles

If you have a PowerShell profile with variables and functions already defined, it can be loaded with the PowerShell component by setting the LoadProfiles property to true before calling Eval or EvalFile.

powershell1.LoadProfiles = true;
powershell1.Eval(script);

The PowerShell component will look for profiles in the following locations:

  • %windir%\system32\WindowsPowerShell\v1.0\profile.ps1
  • %windir%\system32\WindowsPowerShell\v1.0\Microsoft.PowerShell_profile.ps1
  • %UserProfile%\My Documents\WindowsPowerShell\profile.ps1
  • %UserProfile%\My Documents\WindowsPowerShell\Microsoft.PowerShell_profile.ps1


We appreciate your feedback.  If you have any questions, comments, or suggestions about this article please contact our support team at kb@nsoftware.com.