How to upgrade applications to version 3.X

Breaking changes

Core

IJsEngineSwitcher interface

Now you can implement your own version of the JsEngineSwitcher class. To do this, you must create a class, that implements the IJsEngineSwitcher interface and assign an instance of this class to the Current property (this property should be used instead of the Instance property) of JsEngineSwitcher class:

JsEngineSwitcher.Current = new MyJsEngineSwitcher();

Because of appearance of this feature, you need to make changes in the source code of your applications: change the type of variables, parameters or properties from JsEngineSwitcher to IJsEngineSwitcher.

Reorganization of exceptions

During reorganization of exceptions, the following changes were made:

1. Format of the error messages was unified.
2. Created a new exception classes: JsCompilationException, JsEngineException, JsFatalException, JsInterruptedException, JsTimeoutException and JsUsageException. These exceptions are responsible for handling errors, some of which were previously handled by the JsRuntimeException class.
3. In the JsException class was added two new properties: Category and Description.
4. From the JsRuntimeException class was removed one property - ErrorCode.
5. In the JsRuntimeException class was added three new properties: Type, DocumentName and CallStack.
6. JsEngineLoadException class now is inherited from the JsEngineException class.
7. Removed a EmptyValueException class.
8. Format method of the JsErrorHelpers class was renamed to the GenerateErrorDetails.

Now exception hierarchy looks like this:

• JsException
  • JsEngineException
    • JsEngineLoadException
  • JsFatalException
  • JsScriptException
    • JsCompilationException
    • JsRuntimeException
      • JsInterruptedException
      • JsTimeoutException
  • JsUsageException
• JsEngineNotFoundException

Script interruption

In IJsEngine interface was added SupportsScriptInterruption property and Interrupt method. Since not all JS engines support ability to interrupt execution of the script, then before calling of Interrupt method should always check the value of SupportsScriptInterruption property:

if (engine.SupportsScriptInterruption)
{
	engine.Interrupt();
}

After calling of the Interrupt method, execution of scripts ends with an error, therefore you should catch the JsInterruptedException exception.

V8

Microsoft ClearScript.V8 and JavaScriptEngineSwitcher.V8 now requires .NET Framework 4.5+ and the Microsoft Visual C++ Redistributable for Visual Studio 2017.

MaxExecutableSize configuration property became obsolete.

Jint

Timeout configuration property has been replaced by the TimeoutInterval property (default TimeSpan.Zero).

ChakraCore

Now the ChakraCore for Windows requires the Microsoft Visual C++ Redistributable for Visual Studio 2017.