Welcome to ClearScript!
ClearScript is a library that allows you to add scripting to your .NET applications. It supportsand out of the box and in theory can work with other engines.
Now that an VI below.is available, you can simply add it to your project and skip to Section
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:
<remove assembly="ClearScriptV8-64" />
<remove assembly="ClearScriptV8-32" />
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.
The provided project and solution files support Visual Studio bin\[Debug|Release].and . They produce architecture-neutral managed libraries that target .NET Framework 4.5. ClearScript does not support older environments. The output directory is
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 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 Programs → Programs 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 protection → Virus & threat protection settings.
c. Switch Real-time protection off.
7. Open a 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 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 in HTML and Compiled HTML (.CHM) formats. If you'd like to rebuild these files, use with the provided project files (ClearScript\doc\[Web]Reference.shfbproj).
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:
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.
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:
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 2017
1. Install and launch .
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:
"name": "Attach to ClearScript V8 on port 9222",
c. You can specify additional configurations for different hosts, port numbers, and other options. See for more information.
d. Click File → Save.
3. Enable script debugging in your application by invoking the 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 .
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 Debug → Start Debugging.
Note: You can also attach Visual Studio to your application for simultaneous debugging of script, managed, and native code.
We’d like to thank:
2. for generously providing the service.