Choosing Compiler Engine

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:	partial
Review/update status:	pending

---

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).
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 tro the compiled code level by enabling caching (disabled by default):}

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

----- / / -----

... in progress ...