chewel611 / cs-script

C# scripting platform

CS-Script

---

Please note that this repository is hosting the releases of CS-Script (v4.0.0 and higher), which target .NET 5. Meaning that both CLI and class library (Nuget package) can transparently be hosted on and interact with both .NET Framework and .NET Core runtimes (.NET 5 SDK is required to be installed).

Previous content of this repository and Wiki, which was exclusively dedicated to .NET Framework edition of CS-Script has been is has been moved to a new repository: https://github.com/oleg-shilo/cs-script.net-framework

---

CS-Script is a CLR based scripting system which uses ECMA-compliant C# as a programming language.

CS-Script is one of the most mature C# scripting solutions. It became publicly available in 2004, just two years after the first release of .NET. And it was the first comprehensive scripting platform for .NET

CS-Script supports both hosted and standalone (CLI) execution model. This makes it possible to use the script engine as a pure C# alternative for PowerShell. As well as extending .NET applications with C# scripts executed at runtime by the hosted script engine.

CS-Script allows seamlessly switching underlying compiling technology without affecting the code base. Currently supported compilers are dotnet.exe and csc.exe.

CS-Script also offers comprehensive integration with most common development tools:

• Visual Studio (built-in feature via -vs CLI argument)
• VSCode
• Sublime Text 3
• Legacy .NET Framework plugins that are yet to be ported to .NET 5:
  • Notepad++ .
  • Visual Studio

It can be run on Win and Linux. Class library for hosting the script engine is compiled for ".NET Standard" so it can be hosted by any managed application.

Over the long history of CS-Script it has been downloaded through Notepad++ x86 plugin manager alone over times (stats till July 2017).

---

Documentation disclaimer Please be aware that currently the online Documentation Wiki is being reviewed and updated. This is review/rework hs been triggered by the convergence of two CS-Script development and distribution streams for .NET Core and .NET Framework.Meaning that until this review is completed and this disclaimer is removed some of the Wiki content may not be fully accurate.

The most accurate and concise documentation is embedded in the engine executable and can be accessed via CLI "help" command:

css -help

A copy of the help content can be accessed here

---

The following section describes a few use cases just to give you the idea about the product:

CLI: Executing script from shell

CS-Script follows many elements of the Python user experience model. Thus a script can reference other scripts, .NET assemblies or even NuGet packages. It also uses Python style caching ensuring that script that was executed at least once is never compiled again unless the script code is changes. This ensures ultimate performance. Thus script execution speed of the consecutive runs matches the excution of fully compiled .NET applications.

Create a simple console script: You can script any type of application that .NET supports (e.g. WinForm, WPF, WEB API) and in two supported syntaxes: C# and VB.

cscs -new script.cs

This creates a sample script file with a sample code. Of course you can also create the script file by yourself. This is a top-level class script:

using System;

Console.WriteLine(user());

string user()
    => Environment.UserName;

Execute script file directly in cmd-prompt/linux-shell without building an executable assembly:

css .\script.cs

Note, while the script engine CLI executables is cscs.exe (on Win) and cscs (on Linux) you can use css shim that is available in both win and linux distro.

CLI: Executing script from IDE

While various IDEs can be used VSCode is arguably the simplest one. You can either load the existing script into it with css -vscode .\script.cs or create a new script within the IDE if you install the CS-Script extension:

Hosting script engine

You can host the script engine in any .NET application. The class library is distributed as a NuGet package CS-Script.

Install-Package CS-Script

The library is built against .NET Standard 2.0 so it can be hosted on any edition of runtime. However the script evaluation is done via .NET 5 tool chain so it needs to be installed on the host PC even if the application is implemented with the older framework (e.g. .NET Framework).

These are just a few samples: The complete content of samples can be found here.

public interface ICalc
{
    int Sum(int a, int b);
}
...
// you can but don't have to inherit your script class from ICalc
ICalc calc = CSScript.Evaluator
                     .LoadCode<ICalc>(@"using System;
                                        public class Script
                                        {
                                            public int Sum(int a, int b)
                                            {
                                                return a+b;
                                            }
                                        }");
int result = calc.Sum(1, 2);

dynamic script = CSScript.Evaluator
                         .LoadMethod(@"int Product(int a, int b)
                                       {
                                           return a * b;
                                       }");

int result = script.Product(3, 2);

public interface ICalc
{
    int Sum(int a, int b);
    int Div(int a, int b);
}
...
ICalc script = CSScript.Evaluator
                       .LoadMethod<ICalc>(@"public int Sum(int a, int b)
                                            {
                                                return a + b;
                                            }
                                            public int Div(int a, int b)
                                            {
                                                return a/b;
                                            }");
int result = script.Div(15, 3);

var log = CSScript.Evaluator
                  .CreateDelegate(@"void Log(string message)
                                    {
                                        Console.WriteLine(message);
                                    }");

log("Test message");