Skip to content

Choosing Compiler Engine

Jump to bottom
oleg.shilo edited this page Oct 6, 2021 · 36 revisions
Since porting CS-Script on .NET 5 the documentation is still in the process of being refined and cleared from the legacy content.
Thus it may contain some minor inaccuracies until both statuses below are set to full and complete or this disclaimer is removed.
.NET 5 accuracy status: full
Review/update status: completed

Compiler technology overview

CS-Script is not a true interpreter like Python nor compiler like C++. CS-Script is a hybrid script engine that uses .NET stock compilers to compile scripts on-fly and deliver true scripting experience without loosing type safety and performance of the compiled execution.

Thus CS-Script is heavily dependant on the .NET compiling tools. These tools were always available starting from the very first release of NET. As well as the corresponding API CodeDom. And this is exactly what CS-Script was using in the early versions.

Despite the common belief Roslyn is not the first release of compiler-as-service of .NET CodeDom is. Though it is first implementation that delivers complete in-process hosting. Interestingly enough Mono has released its own version of compiler-as-service even before Roslyn but now it is obsolete.

Prior .MET 5 release CS-Script allowed the users to select any desired compiling engine supported by .NET Framework: CodeDom, Mono or Roslyn (see this overview).

But with the release of .NET 5 which is effectively .NET Core all other compilers became completely obsolete so the only available engine out of box was Roslyn. However even Roslyn was not well suited for comprehensive scripting since it has a few serious practical limitations. That's why the first release of CS-Script for .NET 5 used dotnet.exe as an out-of-process compiler-as-service compiling engine.

This engine is the most versatile engine that can be. It is capable of running scripts implementing WPF, ASP.NET, WinForms and any app type that .NET supports.

However... it is slow and it is only available with .NET 5 SDK. Meaning that in order to run scripts having .NET 5 runtime installed is not enough and you need to deploy .NET SDK as well.

Thus in order to overcome these limitations and after the initial feedback from users, CS-Script v4.0.3 was extended with support for extra new compiling engines: in-process Roslyn and csc.exe compiling services.

Configuring compiling engine

CS-Script CLI

When using CS-Script CLI css.exe you can choose your desired compiling engine (dotnet, csc, roslyn) either per-script execution or system-wide.

Per-execution

From command line:

css -engine:csc <script file>
or
css -ng:csc <script file>

From script code:

//css_engine roslyn
or
//css_ng roslyn

Global

css -config:set:DefaultCompilerEngine=dotnet

The default engine is dotnet for Windows and csc for all other OS.

Hosting CS-Script (CSScriptLib.dll)

When hosting CS-Script CSScriptLib.dll you have a choose the desired compiling engines: EvaluatorEngine.Roslyn and EvaluatorEngine.CodeDom. Note, the CodeDom is mapped internally to the out-of-process csc.exe compiler and Roslyn (default) to mapped internally to the in-process Roslyn compiling service.

Per-evaluator instance

dynamic script = CSScript.RoslynEvaluator
                         .LoadMethod(@"public int add(int a, int b)
                                    {
                                        return a+b;
                                    }");

Per-process instance

CSScript.EvaluatorConfig.Engine = EvaluatorEngine.CodeDom;
. . .
dynamic script = CSScript.Evaluator
                         .LoadMethod(@"public int add(int a, int b)
                                    {
                                        return a+b;
                                    }");

Compiler technology comparison

This section is contains the detailed analysis of the aspects of compiler engine selection. But a very concise summary of the comparative analysis in the table below.

CS-Script CLI

Features dotnet csc roslyn
Performance
(first execution)1 		poor excellent2 very good3
Performance
("next" execution)4 		perfect perfect perfect
Need SDK installed yes yes no
Namespace declarations allowed yes yes no
WPF yes no yes
WinForms yes yes yes
Support for NuGet packages full full no
Support for multi-file scripts full full partial5

1 - The execution of the script that was just created or modified.
 2 - The csc.exe based compiling service needs to be running. It is started automatically if it is not already running. Service runs on socket port 17001 (can be overwritten via environment variable CSS_BUILDSERVER_CSC_PORT)
 3 - The Roslyn based compiling service needs to be running. It is started automatically if it is not already running. Service runs on socket port 17002 (can be overwritten via environment variable CSS_BUILDSERVER_ROSLYN_PORT)
 4 - Any execution that is not "first execution" while CS-Script caching is enabled (see CLI -c). It's enabled by default.
 5 - Roslyn API does not allow multi module scripting thus CS-Script merges multiple script into a single script. This can potentially lead to C# syntax errors (e.g. namespaces collisions).

Hosting CS-Script (CSScriptLib.dll)

Features EvaluatorEngine.CodeDom EvaluatorEngine.Roslyn
Performance1 very good excellent
Namespace declarations allowed yes no
Need SDK installed yes no

1 - If your scripting scenario involves executing the same script(s) again and again you can improve performance up to the level of the compiled assembly by enabling caching. Caching is disabled by default. 

CSScript.Evaluator
        .With(eval => eval.IsCachingEnabled = true)
        .LoadMethod(<script code>);

Pros and Cons

DotNet

Pros

  • It is the most flexible engine. It is tunneling the script compilation to the .NET builder dotnet.exe meaning that the script can be defined the same way as any application typ supported by .NET 5 and higher (e.g.5). It can even be a WPF application implemented as a script.

Cons

  • Slow to start up. Caching solves the problem but if your script is frequently changed the the startup penalty will be paid every time you change something in your script.
  • Requires .NET 5 SDK to be installed on the target system.

csc / CodeDom

Pros

  • It is quite flexible as as it is tunneling the script compilation to the C# compiler csc.exe.
  • It is very fast to load. Note: Requires csc out-of-process compiling service running. It starts on the first execution of a scripts and remains active till the OS restarts. It is CS-Script own equivalent of VBCSCompiler.exe (hot-start csc.exe launcher) that was available in .NET Framework but sadly is broken in .NET5.

Cons

  • Cannot compile XAML (WPF scripts).
  • Requires .NET 5 SDK to be installed on the target system.

Roslyn

Pros

  • It is the only engine that does not require SDK installed. .NET 5 runtime is fully sufficient to run the scripts.
  • It is very fast to load. Note: Requires roslyn out-of-process compiling service running. It starts on the first execution of a scripts and remains active till the OS restarts. It is conceptually similar to VBCSCompiler.exe as it simply ensures hot-start launching cscs.exe (another instance of CS-Script process) that uses Roslyn compiler to compile the scripts into assemblies.

Cons

  • Cannot reference Nuget packages.
  • Requires special considerations when importing other scripts into the master script as they are simply merged together. This may lead to the collisions of the using <namespace>; statements.
  • Declaring namespaces is prohibited by the underlying Roslyn compiler.

Pages

Clone this wiki locally