ClearScript FAQtorial
It’s a tutorial in the form of questions and answers. It may look like a FAQ list, but it’s really a guide.
ClearScript is a library that allows you to add scripting to your .NET applications. It supports JScript and VBScript out of the box and in theory can work with other Windows Script engines.
New! ClearScript 5 supports the V8 high-performance open-source JavaScript engine. Unlike Windows Script engine instances, V8 instances have no thread affinity and are suitable for server-side asynchronous scripting.
Perhaps, but sometimes it’s fun to start something from scratch and see how far you can take it.
There are many possible reasons. Sophisticated productivity applications often support script-based customization and extension. The ability to automate an application may be desirable for testing purposes or for running complex jobs. Another goal might be to process active content that includes embedded scripts, such as web pages.
Yes, but they’re designed for a different purpose. They typically introduce numerous language extensions in order to “retarget” standard script languages for full-blown .NET development. That is not ClearScript’s goal. ClearScript focuses on adding standards-based scripting to existing .NET applications with minimal effort.
ClearScript is all about simplicity. It’s one line of code to instantiate a script engine, another to expose a host resource for scripting, and one more to execute a script. You don’t worry about implementing hosting interfaces, creating scriptable proxies, decorating class members, etc.
Because it aims to make existing applications scriptable without modification or special coding, ClearScript works hard to give script code the ability to access a long list of .NET features – constructors, methods, properties, fields, events, indexers, extension methods, nested types, output parameters, statics, generics, enums, delegates, etc. It does this without introducing special syntax or requiring script language extensions of any kind.
ClearScript also provides streamlined host-to-script support, allowing the host to invoke script functions and access script objects directly. In addition, it allows script-enabled applications to be debugged in script mode.
New! ClearScript 5 supports simultaneous debugging of script, managed, and native code for applications that use its new V8-based JavaScript engine.
You simply “new up” a class instance:
Host - C#
using Microsoft.ClearScript.V8;
…
var engine = new V8ScriptEngine();
At this point the script engine contains only its built-in objects and functions and has no access to the host application.
You make one method call to expose a host object or type:
Host - C#
using System;
…
engine.AddHostObject("uri", new Uri("http://www.example.com"));
engine.AddHostType("Console", typeof(Console));
The script engine now contains two root-level objects – a host object and a host type – that provide access to the corresponding host resources.
It can access the object’s public members directly:
Script - JavaScript
var uriQuery = uri.Query;
var uriString = uri.ToString();
It can access the type’s static members and nested types directly:
Script - JavaScript
Console.WriteLine('Downloading from {0}...', uri);
Console.Title = 'Please wait...';
Host types can also be used to invoke constructors and specify generic type arguments. There’ll be more on that later.
Use one of these methods:
Host - C#
engine.Execute("var uriQuery = uri.Query;");
var result = engine.Evaluate("Math.sqrt(Math.PI)");
Some script languages have ambiguous syntactic elements whose meaning depends on whether they’re part of a statement or an expression. For example, in VBScript a single equals sign is used for both assignment (statement) and equality testing (expression). To resolve this ambiguity the host must establish the syntactic context for script execution. Execute interprets script code in a statement context, while Evaluate treats code as an expression.
To script code, the public fields of a host object or type look exactly like properties.
ClearScript supports C#-like type inference, so you can call most generic methods just as you’d call them from C#. However, some generic methods require explicit type arguments. To call such a method from script code, place the required number of host types at the beginning of the argument list. For example, suppose the host exposes the following types:
Host – C#
using System;
using System.Linq;
…
engine.AddHostType("Int32", typeof(int));
engine.AddHostType("Enumerable", typeof(Enumerable));
Here’s how to call the Enumerable.Empty generic method from script code:
Script - JavaScript
var empty = Enumerable.Empty(Int32);
Extension methods are available if the type that implements them has been exposed. Continuing the previous example, here’s script code that calls the Enumerable.ToArray extension method:
Script - JavaScript
var numbers = Enumerable.Range(0, 10).ToArray();
Note that Enumerable.ToArray is a generic extension method whose type argument is inferred from its “this” argument. As you can see, ClearScript allows you to call it using the same convenient syntax as C#.
Yes. Here’s how to connect a host event source to a script handler function:
Script - JavaScript
var connection = Console.CancelKeyPress.connect(function (sender, args) {
Console.WriteLine('{0} pressed!', args.SpecialKey);
});
To break the connection, do this:
Script - JavaScript
connection.disconnect();
Script code cannot instantiate a host type directly. However, ClearScript provides a set of utility functions that includes this capability:
Host – C#
using System;
using Microsoft.ClearScript;
…
engine.AddHostObject("host", new HostFunctions());
engine.AddHostType("Uri", typeof(Uri));
Now you can create System.Uri class instances from script code:
Script - JavaScript
var newUri = host.newObj(Uri, 'http://www.example.com');
Note that newObj is a generic method that requires an explicit type argument. Its first argument (the type argument) is the host type to be instantiated. The rest of the arguments are passed to the constructor that matches the argument signature.
New! ClearScript 5 supports simplified instantiation syntax for JavaScript:
Script - JavaScript
var newUri = new Uri('http://www.example.com');
There’s a utility function for creating host arrays, too:
Script - JavaScript
var uriArray = host.newArr(Uri, 10);
That depends on your script language. However, if a host object implements System.Collections.IList, ClearScript exposes read/write properties with numeric names that match the object’s valid indices:
Script - JavaScript
var firstUri = uriArray[0];
uriArray[1] = firstUri;
Yes. Suppose that a dictionary is exposed for scripting:
Host – C#
using System.Collections.Generic;
…
engine.AddHostObject("dict", new Dictionary<string, Uri>());
You can use a host variable to invoke the Dictionary.TryGetValue method from script code:
Script - JavaScript
var uriVar = host.newVar(Uri);
if (dict.TryGetValue('key', uriVar.out)) {
Console.WriteLine('Found Uri value: {0}.', uriVar);
}
Host variables support two special properties in addition to out. The first is ref, which is similar to out but compatible with ref parameters. The second is value, which provides read/write access to the value stored within the variable. If you’re passing a variable into an input parameter, invoking value is unnecessary.
Yes, by creating a delegate that invokes your script function. Consider this code:
Host – C#
using System.Threading;
…
engine.AddHostType("Timer", typeof(Timer));
engine.AddHostType("TimerCallback", typeof(TimerCallback));
You can now create timers and handle their callbacks from script code:
Script - JavaScript
var callback = host.del(TimerCallback, function (state) {
Console.WriteLine('Timer fired: {0}.', state);
});
var timer = host.newObj(Timer, callback, 'foo', 5000, 5000);
In addition to del, ClearScript provides proc and func; these functions create specialized delegates compatible with System.Action and System.Func respectively.
New! ClearScript 5 supports simplified delegate creation syntax for JavaScript:
Script - JavaScript
var callback = new TimerCallback(function (state) {
Console.WriteLine('Timer fired: {0}.', state);
});
Yes. You can use a host type collection to expose all the types defined in one or more assemblies:
Host - C#
using Microsoft.ClearScript;
…
var typeCollection = new HostTypeCollection("mscorlib", "System", "System.Core");
engine.AddHostObject("clr", typeCollection);
Now all the types defined in the standard mscorlib, System, and System.Core assemblies are exposed. Host type collections are hierarchical data structures where leaf nodes represent host types and parent nodes represent namespaces:
Script - JavaScript
var guid = clr.System.Guid.NewGuid();
var today = clr.System.DayOfWeek.Friday;
Note that, unlike C# types and namespaces, the nodes of a host type collection are objects. A script can copy them to the root level for more convenient access:
Script - JavaScript
var System = clr.System;
var Guid = System.Guid;
var myGuid = Guid.NewGuid();
Such a host type can be invoked with type arguments to produce a closed generic type:
Script - JavaScript
var Dictionary = System.Collections.Generic.Dictionary;
var myDictionary = host.newObj(Dictionary(System.String, System.Int32));
myDictionary.Add('foo', 123);
Not without the host’s explicit permission:
Host – C#
using Microsoft.ClearScript;
…
engine.AddHostObject("xHost", new ExtendedHostFunctions());
By exposing an instance of ExtendedHostFunctions, the host hands over the keys to the kingdom:
Script - JavaScript
var List = xHost.type('System.Collections.Generic.List');
var DayOfWeek = xHost.type('System.DayOfWeek');
var week = xHost.newObj(List(DayOfWeek), 7);
week.Add(DayOfWeek.Sunday);
You can even import entire assemblies:
Script - JavaScript
var clr = xHost.lib('mscorlib', 'System', 'System.Core');
var Dictionary = clr.System.Collections.Generic.Dictionary;
Yes. ClearScript provides a dynamic property named Script that represents a script engine’s root-level namespace. Consider the following script:
Script - JavaScript
function myFunc(x, y, z) {
return { xValue: x, yValue: y, zValue: z };
}
After executing this script, the host can directly invoke myFunc and examine the properties of the object it returns:
Host – C#
var yValue = engine.Script.myFunc(1, 2.0, "three").yValue;
If you’re using ClearScript with JScript, VBScript, or another Windows Script engine, you can use Visual Studio to debug your application in script mode. If you’re using ClearScript’s new V8-based JavaScript engine, your best option is Visual Studio Code. Best of all is that you can attach both Visual Studio and Visual Studio Code to the same process for simultaneous debugging of script, managed, and native code. See here for the latest information about using ClearScript with V8.
Take a look at the ClearScript API reference that accompanies this FAQtorial. Also check out the ClearScriptConsole and ClearScriptBenchmarks test programs.