CS Script Overview
This top-level Wiki documentation in most of the cases is fully sufficient for the development with CS-Script. It reflects the current state of CS-Script and all most recent API changes. Though in some cases (e.g. legacy topics) you may find useful to consult the online documentation on the CS-Script Home Page. The online help content can also be downloaded form Releases page.
Further reading:
When you start exploring CS-Script you will probably quickly notice that it is quite different comparing to other scripting solutions. The immediate candidates for comparison are Mono and Roslyn. Both of these solutions are very similar. They concentrate mostly on hosting the script engine and executing small pieces of code. Their documentation offers plenty of samples of executing simple statements like '1+2' or 'Console.WriteLine("Hello")'. It all makes an impression that these script engines were designed for a single objective - providing a hosting solution for execution of user specified C# fragments (e.g. REPL or work flow engine). The usual consideration scope of these solutions is often no larger then a single C# statement. Thus they offer no solution for:
- Executing a complete C# module (C# file).
- Executing C# file as an external process (e.g. from command-prompt).
- Linking multiple inter-dependent C# files at runtime and executing them as a single unit.
- Convenient way of referencing dependency assemblies.
- Debugging scripts.
- A 14 years old (since 2002) problem of memory leaking with every single C# statement executed in the current AppDomain.
- ...
Both Roslyn and Mono are fully capable of being used to build a derived solutions addressing the challenges listed above but they don't deal with them directly.
CS-Script is different as its objective is to provide a platform for executing scripts of any level of complexity and dependency as well as extending the applications with the functionality as rich as .NET can facilitate. In a way CS-Script to C# syntax is what Python platform to Python syntax.
CS-Script does answer the all scripting challenges including REPL and IDE. But what even more important CS-Script provides one unified interface (API) that normalizes all three major C# compiling technologies CodeDom, Roslyn and Mono. Thus while letting developers to have a single scripting codebase CS-Script makes the choice of a concrete compiling technology (e.g. Mono vs Roslyn) a simple matter of the configuration. For the complete comparative overview of the compiling technologies see the dedicated Script Hosting page.
CS-Script is one of the most mature C# scripting frameworks available today. CS-Script first public release is dated back to 2004. At that time .NET ecosystem didn't provide any scripting solution. What is even more intriguing is the fact that at that time Microsoft consistently refused any call for such a solution. It insisted that there is no need for scripting as it has no place in .NET domain. Thus CS-Script was a pioneering effort to bring scripting experience to the developers when .NET vendor failed to do so. The main idea of CS-Script is to allow "plain vanilla" C# code execution from both command-prompt and form any CLR application hosting the script engine.
Things have changed since then. Today Microsoft is behind the ongoing Roslyn effort - their own compiler-as-service solution. Mono also has their compiler-as-service (Mono.CSharp) released around 2010. Though CS-Script remains one of the best choices of scripting platform due to the unorthodox conceptual approaches and unique features not found in other solutions.
What makes CS-Script almost unique is the comprehensive approach to scripting as a software development technique that has various applications (beyond just simple "eval"). CS-Script was hugely influenced by Python. In fact many CS-Scrip features was 'borrowed' from Python: referencing external scripts and assemblies, caching, converting scripts into self-sufficient executables. Thus having Python in mind CS-Script provided the answer for both standalone (script file) execution by the script engine executable and hosted script (file or in-memory text) execution by the script engine hosted by the user application.
For the hosted script execution CS-Script provides one unified interface, which allows switching between underlying compiling services (Mono, Roslyn and CodeDom) without the need to change the hosting code.
CSScript.EvaluatorConfig.Engine = EvaluatorEngine.Roslyn;
//EvaluatorEngine.Mono;
//EvaluatorEngine.CodeDom;
var sqr = CSScript.Evaluator
.CreateDelegate(@"int Sqr(int a)
{
return a * a;
}");
var r = sqr(3);Additional documentation
The simplest way to execute the C# script is to run the script engine executable (css.exe) and pass the script file as a parameter. The script file is a file containing an ordinary ECMA-compliant C# code. CS-Script currently targets Microsoft implementation of CLR (.NET 2.0/3.0/3.5/4.0/4.5) with full support on Mono. CS-Script is implements script caching that ensures that the script file is never compiler unless it has change since the first execution or it is the first execution. This in turn allows a remarkable performance for the script execution, which is identical to the performance of the fully compiled assembly. Thus CS-Script implements JIT compilation but not within the scope of the code fragments (e.g. .NET JIT compilation) but within the scope of whole script file.
Some of the important features of CS-Script are:
- Including (referencing) dependency scripts from the main script
- Referencing external assemblies from the script
- Automatic referencing external assemblies based on analyses of the script imported namaspaces ('usings')
- Automatic resolving (downloading and referencing) NuGet packages
- Possibility to plug in external compiling services for supporting alternative script syntax (e.g. VB, C++)
- Scripts can be executed on Windows, Linux and OS X (last two will require Mono)
- Full integration with Windows, Visual Studio and Notepad++ (CS-Script extension for Notepad++ brings true Intellisense to the 'peoples editor')
- ...
You can find all the details about the stand alone script execution in the online documentation.
The default CS-Script distribution includes various components that make scripting a comfortable experience and yet it in may cases a single script engine file is sufficient for the scripting execution.
The most convenient way of installing CS-Script is to get it from Chocolaty (Windows equivalent of Linux apt-get)
NOTE: Due to the fact that C# 6.0 compiler (Roslyn) is a beta product it is not enabled by default. The full C# 6.0 support overview can be found here: .NET 4.6 Support.
Additional documentation
CS-Script can be hosted by any CLR application. The easiest way to do this is to add it as a NuGet package. CS-Script allows executing entire script files or C# code fragments. The very original implementation of hosted script execution was based on CodeDom API, which is available in all distributions of .NET and Mono. Thus it combines low dependency and ultimate portability.
Later CS-Script support alternative (compiler-as-service) compiling services has been added:
- End of 2012 CS-Script v3.5: Mono Evaluator (Mono.CSharp.dll v.4.0.0.0)
- End of 2015 CS-Script v3.10: Roslyn Compilers Beta release v1.2.0-beta-20151211-01
It is entirely up to developer to decide which compiling engine to use. The choice can be dictated by performance, deployment and maintainability considerations but not the convenience of the hosting API. This is because CS-Script encapsulates all three supported C# compilers into a single unified interface CSScript.Evaluator. Thus changing the compiling engine becomes a merely configuration exercise.
The evaluator allow executing either code fragments or entire class(es) definitions. Script can automatically access host types without any restrictions except types visibility (public vs. private). Scripted objects can be accessed dynamically (via 'dynamic') or statically via interface inheritance or duck-typing or via strongly typed delegates:
Accessing the script members dynamically:
dynamic script = CSScript.Evaluator
.LoadCode(@"using System;
public class Script
{
public int Sum(int a, int b)
{
return a+b;
}
}");
int result = script.Sum(1, 2);Loading strongly typed delegate:
var product = CSScript.Evaluator
.LoadDelegate<Func<int, int, int>>(
@"int Product(int a, int b)
{
return a * b;
}");
int result = product(3, 2);Interface alignment (duck-typing). Note that class Script doesn't inherit from ICalc. Instead the script engine wraps the script object into dynamically generated proxy of ICals type:
public interface ICalc
{
int Sum(int a, int b);
}
...
ICalc script = CSScript.Evaluator
.LoadCode<ICalc>(@"using System;
public class Script
{
public int Sum(int a, int b)
{
return a+b;
}
}");
int result = script.Sum(1, 2);While Mono and Roslyn bring some benefits in many cases CodeDom driven execution remains the most practical solution. Particularly because it is the only solution that allows script debugging. You can find all the details about the hosted script execution on this page: Hosted Script Execution.
Interactive environments are essential part of any software development platform. Majority of scripting scripting solutions come with a simple REPL included. While more complex richer IDEs are usually developed by third-parties.
A simple third-party REPL is included into CS-Script ExtensionPack (cs-script/lib/tools/CSI). However it is rather not as comprehensive as similar products available from other vendors (e.g. Mono).
Instead of developing its own REPL CS-Script makes a strong emphasis on a dedicated rich IDE. The choice of IDE instead or REPL is a recognition of the fact that the complexity of the production level scripting is by far higher then the use-case of REPL (rather 'educational' ny nature) and an industry standard IDE is a more appropriate choice.
When developing a stand alone scripts you have two IDEs to choose from:
Visual Studio
CS-Script integration with Visual studio comes in two forms.
Shell extensions
If you have CS-Script installed (e.g. with Chocolatey) you can just open any script file in visual Studio with CS-Script specific shell context menu:
The script file will not be just loaded in VS but the appropriate project infrastructure will be created on the fly. Thus you will be able to take advantage of the full power of VS and edit, execute and debug your script as any other C# code.
Visual Studio 'CS-Script Tools' extension
This extension deliveres the same experience as provided by shell extensions but without leaving Visual Sudio. See Visual Studio Gallery page for more details.
**Notepad++ **
While arguably nothing can compete with the power of Visual Studio in many cases the 'peoples editor' Notepad++ is a more attractive and practical alternative.
CS-Script products family include a powerful 'CS-Script (Intellisense)' Notepad++ plugin. While editing (with true Intellisence), executing and even debugging the scripts you can also benefit from lightning fast nature and rich functionality of Notepad++.
The plugin also offers an interesting deployment opportunities. It includes a copy of the CS-Script engine thus the only thing you need to work with CS-Script C# scripts on any Windows with .NET (v4.0{"+"}) installed is a copy of Notepad++ with this plugin enabled. The plugin also allows you to package yours scripts so they can be brought and executed on other systems without the need for CS-Script to be installed.
The plugin home page contains plenty details about the product but to put it simple "the plugin brings true VS experiences in Notepad".
Notepad++ project support:
Notepad++ Intellisense:
