Skip to content
Oleg Shilo edited this page Jan 5, 2022 · 39 revisions

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)...

On 15 April 2014 (10 years after the first public release) CS-Script was re-released under MIT license and since then its source code is hosted on GitHub. At the time of creating this repository CS-Script had 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. You can also use the project GitHub project page to 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 use 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 VSCode 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

The documentation map below will give you an idea about the structure of the wiki resources so you can find the required information the most efficient way:

  • Home: an overview
  • Overview

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 more focused pages for CLI and hosted script execution.

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 Chocolatey (or Releases). Nuget package (class library) from https://www.nuget.org. See Deployment section below for details.

Hosting samples can be found here.

CS-Script CLI

Detailed 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:

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. After that, you can execute either script with a complete class definition or scripts with simple code fragments like a method body.

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.