Home

Oleg Shilo edited this page Jan 9, 2017 · 18 revisions

CS-Script

Currently it 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 by this site (CodePlex Git). At the time of creating this repository at CodePlex (first OS hosting) CS-Script has been downloaded 239,477 times world wide. And at the time of the first GitHub release the CodePlex downloads have reached 28,239.

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 in-depth online documentation for the standalone execution is the most accurate and historically complete capture of the CS-Script evolution. Note that this documentation covers some topics that are no longer active/relevant (e.g. COM/ActiveX) or represent a pure-research effort (e.g. pre-execution script). This documentation is included in the offline form in the CS-Script downloadables as Script.chm file.

  • The all released packages (including NuGet) contain CSScriptLibrary.chm file, which is an offline documentation for the CSSCriptLibrary.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 (CSCSriptLibrary.xml). Thus it is also immediately and fully available via your IDE like Notepad++ or Visual Studio.

  • The easiest to access and the most vercitile form of documentation for CS-Script standalone execution is the help output of the script engine itself (cscs.exe). Just execute it with the -? or -help argument and it will print the whole help document. If csws.exe is used on Windows it will display the help file in the system default text viewer. You can also access individual help topics like syntax (CS-Script C# directives) and individual commands/arguments.

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

    • Windows
      • CS-Script C# intellisense plugin for Notepad++
      • CS-Script Tools Visual Studion extension.
      • CS-Script Windows Explorer shell extensions that allows starting the execution, editing and debugging with a single right-click on the file script file in the explorer.
    • Linux/Windows
      • Sublime Text 3 plugin. This plugin delivers true intellisense experience and it is very similar to the CS-Script plugin for Notepad++. This plugin is still under development.

Overview

This documentation will provide a complete overview of CS-Script functionality but few code snippets below can give you a quick idea what CS-Script is about:

dynamic script = CSScript.Evaluator
                         .LoadCode(@"using System.Windows.Forms;
                                     public class Script
                                     {
                                         public void SayHello(string greeting)
                                         {
                                             MessageBox.Show(""Greeting: ""+ greeting);
                                         }
                                     }");
script.SayHello("Hello World!");
var sqr = await CSScript.Evaluator
                        .CreateDelegateAsync(@"int Sqr(int a)
                                               {
                                                   return a * a;
                                               }");
OutputPanel.Print(sqr(3));
var sum = CSScript.Evaluator
                  .CreateDelegateRemotely<int>(@"int Sum(int a, int b)
                                                 {
                                                     return a+b;
                                                 }");

int result = sum(15, 3);

sum.UnloadOwnerDomain();
var SayHello = CSScript.LoadMethod(
                        @"using System.Windows.Forms;
                          public static void SayHello(string greeting)
                          {
                              MessageBoxSayHello(greeting);
                              ConsoleSayHello(greeting);
                          }
                          static void MessageBoxSayHello(string greeting)
                          {
                              MessageBox.Show(greeting);
                          }
                          static void ConsoleSayHello(string greeting)
                          {
                              Console.WriteLine(greeting);
                          }")
                         .GetStaticMethod("SayHello" , typeof(string)); 
SayHello("Hello again!");

CS-Script can execute script files without an additional hosting solution. Just from the command prompt:

C:\> cscs ss_host.cs

Where ss_host.cs is a script for hosting ServiceStack REST server:

//css_npp asadmin;
//css_inc ServiceStack.cs;
using System;
using ServiceStack;

public class Host : ConsoleHost
{
    static void Main()
    {
        new Host().Init()
                  .Start("http://*:8080/");

        Console.WriteLine(@"AppHost listening on http://localhost:8080/
                            sample: http://localhost:8080/hello/John");
        Console.ReadKey();
    }
}

[Route("/hello/{Name}")]
public class Hello
{
    public string Name { get; set; }
}

public class StatusService : Service
{
    public object Get(Hello request)
    {
        return new
        {
            Message = $"Hello {request.Name}!",
            Timestamp = DateTime.Now.ToString()
        };
    }
}

You can also use take an advantage of CS-Script dedicated fully featured IDE (Intellisense, execution, debugging, packaging) built on top of Notepad++.

How to build binaries
Source code includes \Build\build.cmd, which builds all CS-Script binaries.

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

How to install CS-Script on Windows
You can download the package from the Downloads page and deploy the package content manually (the procedure is described at the end of this section). Alternatively you can use Chocolatey, which is a preferred way of installing.

Chocolatey is the repository for the Windows software packages. Chocolatey NuGet is a Machine Package Manager, somewhat like apt-get, but built with Windows in mind. It is also the source repository of the OneGet package manager of Windows 10.

CS-Script can be installed with the following command:

C:\> choco install cs-script

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

Note, by default support for C# 6.0 is disabled. Instructions on how to enable it can be found here: C#6.0 support

How to host script engine in the application

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

PM> Install-Package CS-Script

After installing the package the VS project will include the scripting.cs file containing the samples for all supported hosting scenarios.

Manual installation

Using Chocolatey is a preferred delivery machanizm for CS-Script. The reason is simple. It allows avoiding manual downloading which can lead to silent sneaky disabling of the downloaded content by latest Windows security features. Though you may still have your reasons for the manual installation.

The first step is to download the package and extract the binaries. Be careful there is a huge chance that Windows will silently lock your package and its extracted content preventing it from running. The simplest way to avoid it is to use 7Zip client.

After that you can continue by executing css_config.exe, which does the install.

Well it's is not truly an "install". CS-Script only needs a few environment variables to be set and a config file created. Even if this is not done it will not prevent you from using CS-Script. The absence of the config file will trigger the use of the defaults and not having envars may not necessarily affect your experience. Thus if for whatever reason you cannot/don't want to execute css_config you can do the rest of install manually as well:

  1. Add <cs-script> directory (folder with cscs.exe) into your system PATH
  2. Add CSSCRIPT_DIR envvar with value "<cs-script>"

That is it.

If you still want to use config file then you can create it (\css_config..xml) and use the default content from here: https://github.com/oleg-shilo/cs-script/blob/master/Source/css_config.default.xml