Building, Integrating, and Deploying ClearScript

    I. Introduction

Welcome to ClearScript!

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.

ClearScript 5 adds support for the V8 high-performance open-source JavaScript engine. It allows you to use V8 with the same managed API and host integration features as JScript and VBScript. V8 provides better performance, however, and is more suitable for multi-threaded applications and asynchronous server-side scripting.

 II. ClearScript NuGet package

Now that an official ClearScript NuGet package is available, you can simply add it to your project and skip to Section VI below.

Important: If you’re adding the ClearScript NuGet package to an ASP.NET project, you must exclude ClearScript’s mixed-mode assemblies from ASP.NET compilation. To do so, merge the following into your Web.config files:

<system.web>

  <compilation>

    <assemblies>

      <remove assembly="ClearScriptV8-64" />

      <remove assembly="ClearScriptV8-32" />

    </assemblies>

  </compilation>

</system.web>

III. Building ClearScript

The ClearScript source code is hosted in a Git repository. If you’re installing Git for the first time, select the options Use Git from the Windows Command Prompt and Checkout Windows-style, commit Unix-style line endings. If you already have Git installed, use git-config to ensure that the core.autocrlf variable is set to true.

Use git-clone to download the ClearScript source code into a convenient directory.

The provided project and solution files support Visual Studio 2015 and 2017. They produce architecture-neutral managed libraries that target .NET Framework 4.5. ClearScript does not support older environments. The output directory is bin\[Debug|Release].

There are two ways to build ClearScript – with and without V8 support. If you don't need V8 support, simply build the ClearScript.NoV8 solution using Visual Studio. Note that this solution does not include test projects.

In order to build full ClearScript with V8 support, you must first acquire, build, and import V8:

1.       Note: This procedure and the V8Update script are provided for your convenience. ClearScript does not include V8 source code, nor does it come with any third-party software required to download and build V8. Rights to V8 and its dependencies are provided by their respective rights holders.

2.       Important: Ensure that the path to your ClearScript root directory does not contain spaces or non-ASCII characters.

3.       Important: The V8 build now requires Visual Studio 2017 and a 64-bit operating system. Your Visual Studio installation must include the .NET desktop development and Desktop development with C++ workloads. Once built, ClearScript can still be deployed in a 32-bit environment.

4.       Recommended: To avoid V8 build issues, we recommend that you install the latest version of the Windows 10 SDK and uninstall all earlier versions.

5.       Important: Your Windows SDK installation must include the Debugging Tools for Windows feature. Here’s how to add it to your installation:

a.       Launch Control Panel and click ProgramsPrograms and Features.

b.       Right-click your Windows SDK version and select Change.

c.       Click Next, check Debugging Tools for Windows, and click Change.

6.       Important: The V8Update script downloads executables that Windows Defender may incorrectly identify as containers of malware. To prevent this from interfering with your build, ensure that real-time malware protection is turned off while the script is running:

a.       Launch Windows Defender Security Center.

b.       Navigate to Virus & threat protectionVirus & threat protection settings.

c.       Switch Real-time protection off.

7.       Open a Visual Studio 2017 developer command prompt and run the V8Update script from your ClearScript root directory:

C:\ClearScript> V8Update [/N] [Debug|Release] [Latest|Tested|<Revision>]

This script downloads the V8 source code and its dependencies, builds 32-bit and 64-bit V8 shared libraries, and imports the results into ClearScript. It requires approximately 6GB of additional disk space and does not perform any permanent software installation on your machine.

The optional /N flag causes V8Update to reuse previously downloaded files if possible. It's useful for switching between Debug and Release versions of V8 and for testing local V8 modifications.

Specifying Debug or Release is optional; the default is Release. The selected V8 variant will then be used for all ClearScript configurations.

By default, V8Update builds a V8 revision that has been tested with the current version of ClearScript. If you'd like to use a specific revision instead, place the desired branch name, commit ID, or tag on the V8Update command line. Browse here to view V8's revision history.

You are now ready to build the full ClearScript solution using Visual Studio 2015 or 2017.

Note: The first time you open the solution, Visual Studio may prompt you to upgrade one or more projects to the latest platform toolset or .NET Framework. We recommend that you select Cancel or Don't Upgrade. If you encounter issues building ClearScript’s unmanaged projects (ClearScriptV8-32 and ClearScriptV8-64), ensure that their Windows SDK Version properties are set to an installed version of the Windows SDK.

Optional: The ClearScript repository includes the ClearScript Library Reference in HTML and Compiled HTML (.CHM) formats. If you'd like to rebuild these files, use Sandcastle Help File Builder with the provided project files (ClearScript\doc\[Web]Reference.shfbproj).

IV. Building strong-named ClearScript assemblies (optional)

ClearScript now includes optional support for building strong-named assemblies. Use the following one-time procedure to enable this feature:

1.       If the ClearScript solution is open in Visual Studio, close it.

2.       Generate a cryptographic key pair in your ClearScript root directory:

C:\ClearScript> sn -k ClearScript.snk

3.       Open the ClearScript solution in Visual Studio.

4.       Click Build Transform All T4 Templates.

5.       Rebuild the solution.

Once you've performed these steps, the ClearScript assemblies you build will have strong names.

  V. Integrating and deploying ClearScript with your application

Once you've built ClearScript, here's how to add it to your application:

1.       Right-click your project in Visual Studio and select Add Reference.

2.       In the Reference Manager window, click Browse and locate your ClearScript output directory (see above). Select ClearScript.dll, click Add, and then click OK to exit Reference Manager.

3.       Important: If you're using V8, you must also copy the following files from your ClearScript output directory to your application's directory:

ClearScriptV8-32.dll

ClearScriptV8-64.dll

v8-base-ia32.dll

v8-base-x64.dll

v8-ia32.dll

v8-x64.dll

For ASP.NET projects, we recommend that you add these assemblies as content files at the root of your web application and set their Copy to Output Directory properties to Do not copy.

4.       Important: If Visual Studio is not installed on your deployment machine, you must install 32-bit and 64-bit Visual C++ Redistributable packages:

Visual C++ Redistributable for Visual Studio 2015

Visual C++ Redistributable for Visual Studio 2017 [x64] [x86]

VI. Debugging with ClearScript and V8

V8 does not support standard Windows script debugging. Instead, it implements its own WebSocket-based debugging protocol. A convenient way to debug JavaScript code running in V8 is to use the Visual Studio Code IDE:

1.       Install and launch Visual Studio Code.

2.       Set up one or more ClearScript V8 debug configurations:

a.       Click File Preferences Settings to open your User Settings file.

b.       Add the following section to the file:

"launch": {

    "version": "0.2.0",

    "configurations": [

        {

            "name": "Attach to ClearScript V8 on port 9222",

            "type": "node",

            "request": "attach",

            "protocol": "inspector",

            "address": "localhost",

            "port": 9222

        }

    ]

}

c.       You can specify additional configurations for different hosts, port numbers, and other options. See here for more information.

d.       Click FileSave.

3.       Enable script debugging in your application by invoking the V8ScriptEngine constructor with V8ScriptEngineFlags.EnableDebugging and a TCP port number that matches one of your debug configurations. The default port number is 9222.

4.       If you’d like to debug your application remotely, you must also do the following:

a.       Construct your script engine with the additional flag V8ScriptEngineFlags.EnableRemoteDebugging.

b.       Important: If necessary, configure your firewall to allow incoming connections to your TCP port.

5.       Attach the Visual Studio Code debugger to your application:

a.       Click View Debug to bring up the Debug view.

b.       Select the appropriate debug configuration at the top of the Debug Side Bar.

c.       Click DebugStart Debugging.

Note: You can also attach Visual Studio to your application for simultaneous debugging of script, managed, and native code.

VII. Acknowledgments

We’d like to thank:

1.       The V8 team.

2.       Kenneth Reitz for generously providing the Httpbin service.