Skip to content

Home

Jump to bottom
Matthias Klaey edited this page Oct 26, 2021 · 39 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

CS-Script

CS-Script platform is used worldwide for extending the applications functionality with scripting and as a general purpose scripting environment. It is used by both enthusiasts and by professional programmers. It found its way to nonprofit organizations (e.g. educational institutes) as well as to commercial organizations. These are just a few examples: MediaPortal, FlashDevelop, K2 API, SF.net ("WinTin"), BonSAI, AyaNova (service management software)...

In 15 April 2014 (10 years after the first public release) CS-Script has been re-released under MIT license and since then its source code is hosted on GitHub. At the time of creating this repository CS-Script has been downloaded ~270,000 times world wide. And more than 1,000,000 (at Jul 2017) via Notepad++ plugin manager.

At this site you will find:

How to use CS-Script resources

  • This very website (GitHub Wiki) is the best place to search for the latest documentation. Particularly regarding the hosted script execution as it is the most dynamic and actively changing part of the CS-Script interface/functionality. This is where you can find the most concise information about the mainstream features of CS-Script. It is also the place where you can ask the questions, make feature requests and report defects.

  • The all released packages (including NuGet) contain CSScriptLib.chm file, which is an offline documentation for the CSScriptLib.dll assembly. This is the assembly that you need to uses if you need to host CS-Script engine in your application. While it is a true API (not user manual) documentation, it is full of code samples that can be extremely useful during the development. This documentation is a SandCastle compiled version of the API XML documentation (CSCSriptLib.xml). Thus, it is also immediately and fully available via your IDE like VSCode or Visual Studio.

  • The easiest way to access the most versatile form of documentation for CS-Script CLI is the help output of the script engine itself (cscs.exe or css.exe). Just execute it with the -? or -help argument and it will print the whole help document.

  • It is recommended (but not required) that you use an IDE when working with CS-Script.

    • Windows Just run the script with -vs argument and it will open Visual Studio and load the complete script project created on-fly: css -vs script.cs

    • Linux/Windows 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. Alternatively, you can open the file in VSCode with its own CLI command: code .\script.cs.

Overview

The documentation is an excellent starting point for exploring CS-Script features. But if you want just to dive in then jump to the How-to guide.

CS-Script comes in two forms: CLI for stand alone execution and a class library for hosting script engine in applications. Thank .NET 5 transparent runtime target model both CLI and hosting script engine support script execution on both .NET Core and .NET Framework runtimes.

CLI can be installed from Choco (or Releases). See Deployment section below). Nuget package (class library) from https://www.nuget.org.

Hosting samples can be found here.

CS-Script CLI

Documentation: CLI, CLI User-guide

CLI (cscs.exe or css) delivers Python inspired user experience when you can import (include) multiple scripts, reference assemblies and NuGet packages.

Create a script (e.g. console app):

css -new:console my_script.cs

run the script:

css my_script.cs

The script itself is a plain-vanilla C#. It uses only a handful of custom directives ('//css_*') that are encoded as C# comments so the script can still be used with non-scripting tools (e.g. IDEs). This is a sample of the script that imports another script, references an assembly and a NuGet package:

//css_inc web_api_host.cs
//css_ref media_server.dll
//css_nuget Newtonsoft.Json

using System;

WebApi.SimpleHost(args)
      .StartAsConosle("http://localhost:8080");

You can access CS-Script specific syntax help topics via CLI:

css -syntax

Hosting CS-Script engine

Documentation: Hosted Script Execution, Samples

CS-Script can be hosted by any CLR application. The best way to bring scripting in your application is to add the corresponding NuGet package to your .NET project:

Install-Package CS-Script

After that you can execute either scripts with a complete class definitions:

ICalc calc = CSScript.Evaluator
                     .LoadCode<ICalc>(@"using System;
                                        public class Script : ICalc
                                        {
                                            public int Sum(int a, int b)
                                            {
                                                return a+b;
                                            }
                                        }");

int result = calc.Sum(1, 2);

Or scripts with simple code fragments:

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

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

How to build

Source code includes src\1.build-binaries.cmd, which builds all CS-Script binaries.

It also includes VS2019 solution for building script engine executable and the class library assemblies to allow more convenient debugging, troubleshooting.

Deployment

CLI

Ubuntu (terminal)

repo=https://github.com/oleg-shilo/cs-script.core/releases/download/v2.0.0.0/; file=cs-script_2.0-0.deb; rm $file; wget $repo$file; sudo dpkg -i $file

Windows (choco)

choco install cs-script

Read more on Chocolatey and how to enable it on your version of windows here: https://chocolatey.org/

Manual Just unpack the corresponding 7z file from Releases page and start using the script engine executable cscs.

If you prefer you can build a shim exe css for an easy launch of the script engine process:

cscs -self-exe

The same shim/symbolic link is created if you are installing the CS-Script as a package.

NuGet Package (class library)

You can host script engine in any .NET application.

You can use Visual Studio console application project and NuGet package as the starting point.

PM> Install-Package CS-Script

The hosting samples can be found here: https://github.com/oleg-shilo/cs-script/blob/master/src/CSScriptLib/src/CSScriptLib/samples.cs

Pages

Clone this wiki locally