CLI Script Execution

Overview

Script stand-alone execution is the most mature and stable part of CS-Script feature set. Thus, the major documentation has been written quite some time ago and while it may currently have some referencing discrepancies (e.g. VS2012 instead of VS2015) it is still an accurate primary source of CS-Script knowledge. This Wiki article, on the other hand, is the most concise and concentrated description of the relevant content and in the vast majority of the cases, it will be fully sufficient for the majority of the readers. In all other cases (e.g. older versions of CS-Script) please refer to the legacy Online documentation.

CS-Script allows direct single-step execution of files containing ECMA-compliant C# code. Canonical Hello World script:

using System;
Console.WriteLine("Hello World!");

The script engine executable comes in three forms:

• cscs.dll - Console application assembly. Available on both Windows and Linux.
• css - Native executable. It simply launches the script engine assembly (cscs.dll) without the need to invoke .NET launcher:

  css --version
  

  instead of

  dotnet /usr/local/bin/cs-script/cscs.dll --version
  

• csws.dll - Windows application assembly (available only on Windows). It is a script engine compiled as a Windows application assembly (as opposed to console application). You may want to use it when executing the scripts that run as a Windows application without a console window attached. csws.dll is only available on Windows.

The simplest way to execute the C# script is to run the script engine (css) and pass the script file as a parameter.

css script.cs

Any OS that has CS-Script installed can run C# scripts. The minimal distribution file set is the script file itself. Of course, if the script depends on the third-party library or other scripts then they also need to be deployed on the target system.

Optionally it may convert the script into a self-sufficient single executable with

PS C:\Users\user> css -e test.cs
Created: C:\Users\user\test.exe

Features

From the start, CS-Script was heavily influenced by Python and the developer experiences it delivers. Thus, it tries to match the most useful Python features (apart from the Python syntax). Here are some highlights of the CS-Script features.

• Scripts are written in plain vanilla CLS-compliant C#. Though classless scripts (top-level statements) are also supported.
• Remarkable execution speed matching performance of compiled managed applications.
• 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 namespaces ('usings').
• Automatic resolving (downloading and referencing) NuGet packages.
• Building a self-sufficient executable from the script.
• Possibility to plug in external compiling services for supporting alternative script syntax (e.g. VB, C++)
• Scripts can be executed on Windows, Linux and MacOS (.NET5 needs to be present).
• Full integration with Windows, Visual Studio, VSCode, Notepad++ (CS-Script plugin for Notepad++ brings true IntelliSense to the 'peoples editor'), Sublime Text 3

CS-Script directives

CS-Script relies on so-called 'script directives' for implementing some features. These directives are the C# comments that do not obstruct standard C# compilers and yet provide user-defined instructions for the script engine.

Simple WebAPI server top-level statement script:

//css_include webapi;     - include webapi.cs script
//css_include my_dto.cs;  - include DTO definitions script
//css_nuget NLog;         - reference NLog assembly
using System;
using WebApi;

WebApi.SimpleHost
      .StartAsConosle("http://localhost:8080",
      . . .

The complete set of the directives as well as the details about the complete scripting syntax can be found here: https://github.com/oleg-shilo/cs-script/wiki/Script-Syntax

Editing scripts

The scripts can be edited with any suitable text editor. Though if want to take advantage of IntelliSense you may prefer Visual Studio or VSCode with CS-Script extensions.

You can also use Notepad++ or Sublime Text 3 with CS-Script extensions. While these editors do not have debugging tools they are still very capable and will be an adequate choice for most of the cases.

VSCode is arguable is the most versatile editor out of all. It is a true IDE and it is available on all OSs.

CS-Script has two built-in commands for easy loading scripts in Visual Studio and VSCode

Though in many cases you may be better off with just Notepad++. You will need to enable C# IntelliSense plugin from the plugin manager. This plugin was developed specifically to allow VS-like experience when dealing with C# scripts and any C# code. The plugin comes with its own CS-Script package and allows true C# IntelliSense assisted editing.