How to upgrade applications to version 2.X

In order to install the packages of the JavaScript Engine Switcher version 2.X you need to upgrade the NuGet Package Manager to version 2.8.6 or higher.

Breaking changes

The main breaking change of the JavaScript Engine Switcher version 2.X was refusal from the usage Web.config and App.config files for configuring of the core and other modules. Now during configuration instead of the declarative approach (using the configuration file) is used in the imperative approach (using the program code).

Therefore, when upgrading the JavaScript Engine Switcher to version 2.X always need to do 2 things:

1. Uninstall a JavaScriptEngineSwitcher.ConfigurationIntelliSense package, because it has become useless.
2. After upgrade of old packages, you must remove the jsEngineSwitcher configuration section group and its declaration from the Web.config and App.config files:

<?xml version="1.0" encoding="utf-8"?>
<configuration>
    <configSections>
        …
        <sectionGroup name="jsEngineSwitcher">
            …
        </sectionGroup>
        …
    </configSections>
    …
    <jsEngineSwitcher xmlns="http://tempuri.org/JavaScriptEngineSwitcher.Configuration.xsd">
        …
    </jsEngineSwitcher>
    …
</configuration>

Next, consider the changes in each package.

Core

Was renamed the following members of JsEngineSwitcher class:

• Current property -> Instance
• CreateJsEngineInstance method -> CreateEngine
• CreateDefaultJsEngineInstance method -> CreateDefaultEngine

JsRuntimeErrorHelpers class was renamed to JsErrorHelpers class.

In IJsEngine interface was added SupportsGarbageCollection property and CollectGarbage method. Since not all JS engines support garbage collection, then before calling of CollectGarbage method should always check the value of SupportsGarbageCollection property:

if (engine.SupportsGarbageCollection)
{
    engine.CollectGarbage();
}

Since version 2.4.0 in IJsEngine interface was added overloaded versions of the Evaluate, Evaluate<T> and Execute methods, which take the document name as second parameter.

MSIE

MsieConfiguration class was replaced by MsieSettings class.

V8

V8Configuration class was replaced by V8Settings class.

Changed type of DebugPort configuration property from int to ushort.

Since version 2.1.0 native assemblies have been moved to separate packages: JavaScriptEngineSwitcher.V8.Native.win-x86 and JavaScriptEngineSwitcher.V8.Native.win-x64.

Jurassic

JurassicConfiguration class was replaced by JurassicSettings class.

Jint

JintConfiguration class was replaced by JintSettings class.

ChakraCore

Since version 2.1.0 native assemblies for Windows have been moved to separate packages: JavaScriptEngineSwitcher.ChakraCore.Native.win-x86 and JavaScriptEngineSwitcher.ChakraCore.Native.win-x64.

Specificity of configuration

The rejection of the declarative approach was due to the following reasons:

1. Microsoft for several years, uses an imperative approach for configuration of individual parts of ASP.NET (for example, Web API or Web Optimization Framework).
2. ASP.NET Core has only limited support of Web.config files (mainly for integration with IIS).

Now for registration of JS engines uses the following properties of JsEngineSwitcher class:

Property name	Data type	Default value	Description
DefaultEngineName	String	Empty string	Name of default JS engine
EngineFactories	JsEngineFactoryCollection	Empty сollection	Collection of JS engine factories

The table shows, that the EngineFactories property is empty by default, i.e. is not registered any JS engine. In version 1.X JS engines were registered automatically during installation of corresponding NuGet packages (by using transformations of configuration files). In version 2.X registration of JS engines you need to make manually.

Registration of JS engines should be done only once, and before to call of the CreateEngine and CreateDefaultEngine methods of JsEngineSwitcher class. In general, configuration of the JavaScript Engine Switcher is as follows:

JsEngineSwitcher engineSwitcher = JsEngineSwitcher.Instance;
engineSwitcher.EngineFactories.Add(new ChakraCoreJsEngineFactory());
engineSwitcher.EngineFactories.Add(new JintJsEngineFactory());
engineSwitcher.EngineFactories.Add(new JurassicJsEngineFactory());
engineSwitcher.EngineFactories.Add(new MsieJsEngineFactory(new MsieSettings
{
    UseEcmaScript5Polyfill = true,
    UseJson2Library = true
}));
engineSwitcher.EngineFactories.Add(new V8JsEngineFactory());

engineSwitcher.DefaultEngineName = "ChakraCoreJsEngine";

This code can be simplified by using extension methods and constants:

JsEngineSwitcher engineSwitcher = JsEngineSwitcher.Instance;
engineSwitcher.EngineFactories
    .AddChakraCore()
    .AddJint()
    .AddJurassic()
    .AddMsie(new MsieSettings
    {
        UseEcmaScript5Polyfill = true,
        UseJson2Library = true
    })
    .AddV8()
    ;

engineSwitcher.DefaultEngineName = ChakraCoreJsEngine.EngineName;

Next, consider examples of the JavaScript Engine Switcher configuration in ASP.NET applications.

ASP.NET 4.X

Configuring of the JavaScript Engine Switcher in many ways resembles configuration of the Microsoft ASP.NET Web Optimization Framework.

In ASP.NET MVC and Web Forms applications configuring of the JavaScript Engine Switcher maked in App_Start/JsEngineSwitcherConfig.cs file:

using JavaScriptEngineSwitcher.ChakraCore;
using JavaScriptEngineSwitcher.Core;
using JavaScriptEngineSwitcher.Jint;
using JavaScriptEngineSwitcher.Jurassic;
using JavaScriptEngineSwitcher.Msie;
using JavaScriptEngineSwitcher.V8;

namespace JavaScriptEngineSwitcher.Sample.AspNet4.Mvc4
{
    public class JsEngineSwitcherConfig
    {
        public static void Configure(JsEngineSwitcher engineSwitcher)
        {
            engineSwitcher.EngineFactories
                .AddChakraCore()
                .AddJint()
                .AddJurassic()
                .AddMsie(new MsieSettings
                {
                    UseEcmaScript5Polyfill = true,
                    UseJson2Library = true
                })
                .AddV8()
                ;

            engineSwitcher.DefaultEngineName = ChakraCoreJsEngine.EngineName;
        }
    }
}

In order for these configuration settings to take effect, you must also add the JsEngineSwitcherConfig.Configure method call in the Global.asax file:

using System.Web;
…
using System.Web.Routing;

using JavaScriptEngineSwitcher.Core;

namespace JavaScriptEngineSwitcher.Sample.AspNet4.Mvc4
{
    public class MvcApplication : HttpApplication
    {
        protected void Application_Start()
        {
            …
            RouteConfig.RegisterRoutes(RouteTable.Routes);
            JsEngineSwitcherConfig.Configure(JsEngineSwitcher.Instance);
            …
        }
    }
}

In ASP.NET Web Pages sites instead of the App_Start/JsEngineSwitcherConfig.cs and Global.asax files is used only one file - _AppStart.cshtml:

…
@using JavaScriptEngineSwitcher.ChakraCore
@using JavaScriptEngineSwitcher.Core
@using JavaScriptEngineSwitcher.Jint
@using JavaScriptEngineSwitcher.Jurassic
@using JavaScriptEngineSwitcher.Msie
@using JavaScriptEngineSwitcher.V8

@{
    …
    #region JavaScript Engine Switcher configuration

    JsEngineSwitcher engineSwitcher = JsEngineSwitcher.Instance;
    engineSwitcher.EngineFactories
        .AddChakraCore()
        .AddJint()
        .AddJurassic()
        .AddMsie(new MsieSettings
        {
            UseEcmaScript5Polyfill = true,
            UseJson2Library = true
        })
        .AddV8()
        ;

    engineSwitcher.DefaultEngineName = ChakraCoreJsEngine.EngineName;

    #endregion
    …
}

ASP.NET Core

In ASP.NET Core applications configuring of the JavaScript Engine Switcher maked in the Startup.cs file:

…
using Microsoft.AspNetCore.Mvc;
…
using Microsoft.Extensions.DependencyInjection;
…

using JavaScriptEngineSwitcher.ChakraCore;
using JavaScriptEngineSwitcher.Extensions.MsDependencyInjection;
using JavaScriptEngineSwitcher.Jint;
using JavaScriptEngineSwitcher.Jurassic;
using JavaScriptEngineSwitcher.Msie;
using JavaScriptEngineSwitcher.Sample.Logic.Services;
using JavaScriptEngineSwitcher.V8;
…

namespace JavaScriptEngineSwitcher.Sample.AspNetCore1Full.Mvc1
{
    public class Startup
    {
        …
        // This method gets called by the runtime.
        // Use this method to add services to the container.
        public void ConfigureServices(IServiceCollection services)
        {
            …
            // Add JavaScriptEngineSwitcher services to the services container.
            services.AddJsEngineSwitcher(options =>
                options.DefaultEngineName = ChakraCoreJsEngine.EngineName
            )
                .AddChakraCore()
                .AddJint()
                .AddJurassic()
                .AddMsie(options => {
                    options.UseEcmaScript5Polyfill = true;
                    options.UseJson2Library = true;
                })
                .AddV8()
                ;

            // Add framework services.
            services.AddMvc();
            …
        }
        …
    }
}

^{* - This example is valid only for web application created by the “ASP.NET Core Web Application (.NET Framework)” template. If you create a web application based on the “ASP.NET Core Web Application (.NET Core)” template, then you will have only four JS engines: JavaScriptEngineSwitcher.ChakraCore, JavaScriptEngineSwitcher.Msie (only works in JsRT modes), JavaScriptEngineSwitcher.Jint and JavaScriptEngineSwitcher.Vroom.}

First of all, you need to install the JavaScriptEngineSwitcher.Extensions.MsDependencyInjection package, that contains definition of the AddJsEngineSwitcher extension method. AddJsEngineSwitcher method adds a instance of the JsEngineSwitcher class to the services container in the form of singleton and returns value of the EngineFactories property. It should also be noted, that for configuration of instance of the JsEngineSwitcher class and individual JS engines do not use the Microsoft.Extensions.Options (it behavior is just simulated).