Misconceptions about the JavaScript Engine Switcher version 2.X

[Taritsyn]

This is not an error, but an open appeal to React.NET's users.

Misconceptions about the JavaScript Engine Switcher version 2.X

Over the past six months, I often had to communicate with ReactJS.NET's users about errors, that occur due the JavaScript Engine Switcher. In 80 percent of cases, these were not errors, but just wrong usage of the library, which caused by misconceptions about how it works. In this post I will consider most part of these misconceptions.

MSIE

For correct working of the JavaScriptEngineSwitcher.Msie is enough, that the Internet Explorer is installed on a computer.

At the moment, most of the JS libraries are written in ECMAScript 5 (React is also one of them). Full support of the ECMAScript 5 standard are appeared only in the Internet Explorer 9, when was released a new JavaScript engine - Chakra.

If you run the ReactJS.NET with the JavaScriptEngineSwitcher.Msie on a computer on which installed the Internet Explorer 8 or below, then you will get an error like this:

Object doesn't support this property or method

Therefore, you should always use the JavaScriptEngineSwitcher.Msie only on computers on which installed the Internet Explorer 9+ or Microsoft Edge. Ideally, same version of browser should be installed on the development computer and production server.

If you do not have the opportunity to install a modern version of browser on the server, then start using the JavaScriptEngineSwitcher.ChakraCore.

V8

1. JavaScriptEngineSwitcher.V8 require msvcp120.dll and msvcr120.dll assemblies from the Visual C++ Redistributable Packages for Visual Studio 2013.

   Since version 2.2.0 the JavaScriptEngineSwitcher.V8's native assemblies require msvcp140.dll assembly from the Visual C++ Redistributable for Visual Studio 2015.

2. JavaScriptEngineSwitcher.V8 package no longer contains native assemblies, so in addition to it, you need to install the ClearScript.V8 package.

   Indeed, since version 2.1.0, JavaScriptEngineSwitcher.V8 package does not contain native assemblies for Windows, but these assemblies have not gone anywhere, and were moved to separate packages: JavaScriptEngineSwitcher.V8.Native.win-x86 and JavaScriptEngineSwitcher.V8.Native.win-x64. Therefore, you do not need to install the ClearScript.V8 package, which has no relation to the JavaScript Engine Switcher. In general, usage of the ClearScript.V8 package together with the JavaScriptEngineSwitcher.V8 is causing errors.

3. After installation of the JavaScriptEngineSwitcher.V8.Native.* packages, native assemblies need to be manually copied to the application directory, because this is recommended by the authors of the ClearScript.

   After installation of the packages don't need to do any additional actions, this is the main advantage of the JavaScriptEngineSwitcher.V8. Installation of native assemblies is performed by using the following tools:

   1. For .NET 4.X applications and ASP.NET 4.X web applications are used a MSBuild scripts (for example, JavaScriptEngineSwitcher.V8.Native.win-x64.props).
   2. For ASP.NET 4.X web sites are used a PowerShell scripts (for example, Install.ps1 and Uninstall.ps1).
   3. For .NET Core applications and ASP.NET Core web applications are used a mechanism based on the runtimes directories and RIDs.

   In .NET 4.X versions of the JavaScriptEngineSwitcher.V8 a native assemblies are loaded from non-standard directories. In this case, native assemblies are located in the x86 and x64 subdirectories of bin\[Debug|Release] directory (for web applications and sites just the bin directory).

4. For 64-bit Windows is enough to install only the JavaScriptEngineSwitcher.V8.Native.win-x64 package.

   .NET applications, ASP.NET web applications and sites in 64-bit Windows can run not only in 64-bit processes, but also in 32-bit processes. For correct working of the JavaScriptEngineSwitcher.V8 in 32-bit process need to install the JavaScriptEngineSwitcher.V8.Native.win-x86 package. If you do not know in which process will run your application or web site, then install both packages.

ChakraCore

1. JavaScriptEngineSwitcher.ChakraCore for Windows require assemblies msvcp120.dll and msvcr120.dll from the Visual C++ Redistributable Packages for Visual Studio 2013.

   Since version 2.1.0 the JavaScriptEngineSwitcher.ChakraCore's native assemblies require msvcp140.dll assembly from the Visual C++ Redistributable for Visual Studio 2015.

2. JavaScriptEngineSwitcher.ChakraCore package no longer contains native assemblies, so in addition to it, you need to install the Microsoft.ChakraCore package.

   Indeed, since version 2.1.0, JavaScriptEngineSwitcher.ChakraCore package does not contain native assemblies for Windows, but these assemblies have not gone anywhere, and were moved to separate packages: JavaScriptEngineSwitcher.ChakraCore.Native.win-x86 and JavaScriptEngineSwitcher.ChakraCore.Native.win-x64. Therefore, you do not need to install the Microsoft.ChakraCore package, which has no relation to the JavaScript Engine Switcher.

   In addition to these two packages are also available three packages:

   • JavaScriptEngineSwitcher.ChakraCore.Native.win-arm contains the native assemblies for Windows (ARM). Only compatible with .NET Core and .NET Framework 4.5.
   • JavaScriptEngineSwitcher.ChakraCore.Native.linux-x64 contains the native assemblies for Linux (x64). Only compatible with .NET Core.
   • JavaScriptEngineSwitcher.ChakraCore.Native.osx-x64 contains the native assemblies for OS X (x64). Only compatible with .NET Core.

   If you need support for other operating systems, then you can build the ChakraCore assembly by using following instructions from official repository. Only instead of the latest version of ChakraCore's source code, you need to use a version, that is supported by the JavaScriptEngineSwitcher.ChakraCore.

3. After installation of the JavaScriptEngineSwitcher.ChakraCore.Native.* packages, native assemblies need to be manually copied to the bin directory.

   After installation of the packages don't need to do any additional actions, this is the main advantage of the JavaScriptEngineSwitcher.ChakraCore. Installation of native assemblies is performed by using the following tools:

   1. For .NET 4.X applications and ASP.NET 4.X web applications are used a MSBuild scripts (for example, JavaScriptEngineSwitcher.ChakraCore.Native.win-x64.props).
   2. For ASP.NET 4.X web sites are used a PowerShell scripts (for example, Install.ps1 and Uninstall.ps1).
   3. For .NET Core applications and ASP.NET Core web applications are used a mechanism based on the runtimes directories and RIDs.

   In .NET 4.X versions of the JavaScriptEngineSwitcher.ChakraCore for native assemblies are overrided the default search paths. In this case, native assemblies are located in the x86, x64 and arm subdirectories of bin\[Debug|Release] directory (for web applications and sites just the bin directory).

4. For 64-bit Windows is enough to install only the JavaScriptEngineSwitcher.ChakraCore.Native.win-x64 package.

   .NET applications, ASP.NET web applications and sites in 64-bit Windows can run not only in 64-bit processes, but also in 32-bit processes. For correct working of the JavaScriptEngineSwitcher.ChakraCore in 32-bit process need to install the JavaScriptEngineSwitcher.ChakraCore.Native.win-x86 package. If you do not know in which process will run your application or web site, then install both packages.

P.S.: To avoid such misconceptions in the future I recommend you to read fluently “Release Notes” sections of updated NuGet packages. In case, when problems have already occurred, read the CHANGELOG.md or “Releases” sections. Also do not forget about the documentation and issue tracker.

UPDATE 1/1/2019: Fixed a broken links and updated information about the JavaScriptEngineSwitcher.ChakraCore.Native.* packages. It is also worth noting that in the JavaScript Engine Switcher version 3.X there have been some changes. For example, JavaScriptEngineSwitcher.V8 and JavaScriptEngineSwitcher.ChakraCore for Windows now require the Microsoft Visual C++ Redistributable for Visual Studio 2017. Other changes can be found in the “How to upgrade applications to version 3.X” section of documentation.

[Daniel15]

Hey @Taritsyn, thank you so much for the detailed post! This would be good content for the https://reactjs.net/ website 😃

[theFranmcod]

The V8 package does not work with core 1.0 in VS2017.

[Taritsyn]

@a40637francisco Yes, JavaScriptEngineSwitcher.V8 and JavaScriptEngineSwitcher.Jurassic does not support .NET Core, because .NET Core not supported by the original libraries.

[gunnim]

Great read!
I'd like to ask though, is there a reason for not including both the x86 and x64 binaries with the v8 package?

[Taritsyn]

@gunnim This is done in order to allow user can choose only what he really needs.

Advantages of this approach are more obvious when working with the JavaScriptEngineSwitcher.ChakraCore module and LibSass Host for .NET library.

In addition, there is another reason.

[dustinsoftware]

Closing this mega-issue, but feel free to keep referencing it :)

[pmonty]

ClearScript.V8 is now deprecated should instead use Microsoft.ClearScript