Skip to content

CLI Script Execution

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

Script stand-alone execution is the most mature and stable part of CS-Script feature set. Thus, the major online 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 wast 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 Documentation online.

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

using System;

class Script
{
    static public void Main(string[] args)
    {
        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
  • Note, On Windows you can use csws.dll, which is a script engine Windows application assembly. You may want to use it when executing the scripts that run as a Windows application without console attached.

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

Installing CS-Script

Installing dependencies

CS-Script requires .NET 5 or higher: https://dotnet.microsoft.com/download/dotnet. CS-Script relies on .NET tools (compilers) when it executes scrips. Meaning that you will need to ensure a complete .NET suite (that includes SDK) is installed.

Interestingly enough you can us CS-Script on the system that only has .NET Runtime installed but no SDK (.NET tools). This is because one of the supported engines, Roslyn, does not require any extra tools. Though it does have some limitations.

Installing CS-Script engine

The simplest way to start using CS-Script is to install it from Chocolatey, which is a repository for the Windows software packages. Chocolatey it is a Windows version of Linux apt-get. CS-Script can be installed with the following command:

C:\> choco install cs-script

If you want to install CS-Script on Linux (e.g. Ubuntu) you can use Debian package included in every release.

You can copy the terminal command for the specific release from the release page. Below is the example of the command for installing CS-Script version 4.1.0.0.

repo=https://github.com/oleg-shilo/cs-script/releases/download/v4.1.0.0/; file=cs-script_4.1-0.deb; rm $file; wget $repo$file; sudo dpkg -i $file

Deploying C# scripts

Any OS that have 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, the it tries to match the most useful Python features (apart from the Python syntax). Here are some highlight 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",
                      server =>
                      {
                          Console.WriteLine("Press Enter to quit.");
                          Console.WriteLine("---------------------");
                          server.Configuration.OutputRouts(Console.WriteLine);
                          Console.WriteLine("---------------------");
                          Console.ReadLine();
                      });

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

CS-Script CLI

A complete documentation for the CLI command can be found here.

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 as well as the execution and debugging. image

Pages

Clone this wiki locally