help.txt

C# Script execution engine. Version 3.28.8.0.
Copyright (C) 2004-2018 Oleg Shilo.

Usage: cscs <switch 1> <switch 2> <file> [params] [//x]

<switch 1>

--help|-help|-? [command]
    Displays either generic or command specific help info.
    Reversed order of parameters for the command specific help is also acceptable. The all following argument
    combinations print the same help topic for 'cache' command:
       -help cache
       -? cache
       -cache help
       -cache ?

-e
    Compiles script into console application executable.

-ew
    Compiles script into Windows application executable.

-c[:<0|1>]
    Uses compiled file (cache file .compiled) if found (to improve performance).
       -c:1|-c  enable caching
       -c:0     disable caching (which might be enabled globally);

-ca
    Compiles script file into assembly (cache file .compiled) without execution.

-cd
    Compiles script file into assembly (.dll) without execution.

-check
    Checks script for errors without execution.

-proj
    Shows script 'project info' - script and all its dependencies.

-cache[:<ls|trim|clear>]
    Performs script cache operations.
     ls    - lists all cache items.
     trim  - removes all abandoned cache items.
     clear - removes all cache items.

-co:<options>
    Passes compiler options directly to the language compiler.
    (e.g.  -co:/d:TRACE pass /d:TRACE option to C# compiler
    or  -co:/platform:x86 to produce Win32 executable)

-s|-sample[:<C# version>]
    Prints content of sample script file.
     -s:7    - prints C# 7 sample. Otherwise it prints the default canonical 'Hello World' sample.
    (e.g. cscs -s:7 > sample.cs).

-wait[:prompt]
    Waits for user input after the execution before exiting.
    If specified the execution will proceed with exit only after any std input is received.
    Applicable for console mode only.
    prompt - if none specified 'Press any key to continue...' will be used

-ac|-autoclass[:<0|1|2|out>]
    
    This argument has the same effect as the script directive '//css_autoclass' placed in directly in the code.
     -ac     - enables auto-class decoration (which might be disabled globally).
     -ac:0   - disables auto-class decoration (which might be enabled globally).
     -ac:1   - same as '-ac'
     -ac:out - prints auto-class decoration for a given script file. The argument must be followed by the path to
               script file.
     
    Automatically generates 'static entry point' class if the script doesn't define any.
     
    See '//css_autoclass' directive for details. Or find the full documentation on GitHub: 
    https://github.com/oleg-shilo/cs-script/wiki/CLI---User-Guide#command-auto-class

---------
<switch 2>

-dbg|-d
    Forces compiler to include debug information.

-l[:<0|1>]
    'local'- makes the script directory a 'current directory' (enabled by default).
     -l:1   the process current directory is assigned to the script directory (default);
     -l:0   the process current directory is not adjusted in any way;

-v|-ver|--version
    Prints CS-Script version information.

-inmem[:<0|1>]
    Loads compiled script in memory before execution.
    This mode allows preventing locking the compiled script file. Can be beneficial for fine concurrency control as it
    allows changing and executing the scripts that are already loaded (being executed). This mode is incompatible with
    the scripting scenarios that require script assembly to be file based (e.g. advanced Reflection).
     -inmem:1   enable caching (which might be disabled globally);
     -inmem:0   disable caching (which might be enabled globally);

-dbgprint[:<0:1>]
    Controls whether to enable Python-like print methods (e.g. dbg.print(DateTime.Now)).
    This setting allows controlling dynamic inclusion of the embedded dbg.cs script containing implementation of
    Python-like print methods `dbg.print` and derived extension methods object.print() and object.dup(). While
    `dbg.print` is extremely useful it can and lead to some referencing challenges when the script being executed is
    referencing assemblies compiled with `dbg.print` already included. The simplest way o solve this problem is disable
    the `dbg.cs` inclusion.
     -dbgprint:1   enable `dbg.cs` inclusion; Same as `-dbgprint`;
     -dbgprint:0   disable `dbg.cs` inclusion;

-verbose
    Prints runtime information during the script execution.
    (applicable for console clients only)

-stop
    Stops all running instances of Roslyn sever (VBCSCompiler.exe).
    (applicable for .NET/Windows only)

-tc
    Trace compiler input produced by CS-Script code provider CSSRoslynProvider.dll.
    It's useful when troubleshooting custom compilers (e.g. Roslyn on Linux).

-config[:<option>]
    Performs various CS-Script config operations
     -config:none               - ignores config file (uses default settings)
     -config:create             - creates config file with default settings
     -config:default            - prints default config file
     -config:<raw|xml>          - prints current config file content
     -config[:ls]               - lists/prints current config values
     -config:get:name           - prints current config value
     -config:set:name=value     - sets current config value
     -config:set:name=add:value - updates the current config value content by appending the specified value.
     -config:set:name=del:value - updates the current config value content by removing all occurrences of the specified
                                  value.
     -config:set:roslyn         - enables Roslyn integration via configuration (C#7 support)
     -config:<file>             - uses custom config file
     
    Note: The property name in -config:set and -config:set is case insensitive and can also contain '_' as a token
    separator that is ignored during property lookup.
    (e.g. cscs -config:none sample.cs
          cscs -config:default > css_VB.xml
          cscs -config:set:inmem=true
          cscs -config:set:DefaultArguments=add:-ac
          cscs -config:set:default_arguments=del:-ac
          cscs -config:c:\cs-script\css_VB.xml sample.vb)

-out[:<file>]
    Forces the script to be compiled into a specific location.
    Used only for very fine hosting tuning.
    (e.g. cscs -out:%temp%\%pid%\sample.dll sample.cs

-sconfig[:<file>|none]
    Uses custom config file as a .NET app.config.
    This option might be useful for running scripts, which usually cannot be executed without custom configuration file
    (e.g. WCF, Remoting).
    By default CS-Script expects script config file name to be <script_name>.cs.config or <script_name>.exe.config.
    However if <file> value is specified the it is used as a config file. 
    (e.g. if -sconfig:myApp.config is used the expected config file name is myApp.config)

-r:<assembly 1>,<assembly N>
    Uses explicitly referenced assembly.
    It is required only for rare cases when namespace cannot be resolved into assembly.
    (e.g. cscs /r:myLib.dll myScript.cs).

-dir:<directory 1>,<directory N>
    Adds path(s) to the assembly probing directory list.
    You can use a reserved word 'show' as a directory name to print the configured probing directories.
    (e.g. cscs -dir:C:\MyLibraries myScript.cs; cscs -dir:show).

-precompiler[:<file 1>,<file N>]
    Specifies custom precompiler. This can be either script or assembly file.
    Alias - pc[:<file 1>,<file N>]
    If no file(s) specified prints the code template for the custom precompiler. The spacial value 'print' has the same
    effect (e.g. cscs -pc:print).
    There is a special reserved word 'nodefault' to be used as a file name. It instructs script engine to prevent
    loading any built-in precompilers like the one for removing shebang before the execution.
    (see http://www.csscript.net/help/precompilers.html)

-pvdr|-provider:<file>
    Location of the alternative/custom code provider assembly.
    Alias - pvdr:<file>
    If set it forces script engine to use an alternative code compiler.
     
    C#7 support is implemented via Roslyn based provider: '-pvdr:CSSRoslynProvider.dll'.If the switch is not specified
    CSSRoslynProvider.dll file will be use as a code provider if it is found in the same folder where the script engine
    is. Automatic CSSRoslynProvider.dll loading can be disabled with special 'none' argument: -pvdr:none.
    (see http://www.csscript.net/help/non_cs_compilers.html)

-nuget[:<package|purge>]
    Installs new or updates existing NuGet package.
    This command allows light management of the NuGet packages in the CS-Script local package repository
    (%PROGRAMDATA%\CS-Script\nuget).
    The tasks are limited to installing, updating and listing the local packages.
     
     -nuget           - prints the list of all root packages in the repository
     -nuget:<package> - downloads and installs the latest version of the package(s). 
                        Wild cards can be used to update multiple packages. For example '-nuget:ServiceStack*' will
                        update all already installed ServiceStack packages.
                        You can also use the index of the package instead of its full name.
     
    Installing packages this way is an alternative to have '//css_nuget -force ...' directive in the script code as it
    may be more convenient for the user to update packages manually instead of having them updated on every script
    execution/recompilation.

-syntax
    Prints documentation for CS-Script specific C# syntax.

-commands|-cmd
    Prints list of supported commands (arguments).

---------
file
    Specifies name of a script file to be run.

params
    Specifies optional parameters for a script file to be run.

//x
    Launch debugger just before starting the script.



**************************************
Script specific syntax
**************************************
Engine directives:
 
 - //css_include <file>;
 - //css_reference <file>;
 - //css_nuget [-noref] [-force[:delay]] [-ver:<version>] [-ng:<nuget arguments>] package0[,package1]..[,packageN];
 - //css_args arg0[ arg1]..[ argN];
 - //css_searchdir <directory>;
 - //css_autoclass [style]
 - //css_precompiler <file 1>,<file 2>;
 - //css_resource <file>[, <out_file>];
 - //css_import <file>[, preserve_main][, rename_namespace(<oldName>, <newName>)];
 - //css_co <options>;
 - //css_ignore_namespace <namespace>;
 - //css_prescript file([arg0][,arg1]..[,argN])[ignore];
 - //css_postscript file([arg0][,arg1]..[,argN])[ignore];
 
------------------------------------
//css_include <file>;
 
Alias - //css_inc
file - name of a script file to be included at compile-time.
 
This directive is used to include one script into another one. It is a logical equivalent of '#include' in C++. This
directive is a full but more convenient equivalent of //css_import <file>, preserve_main;
 
If a relative file path is specified with a single-dot prefix it will be automatically converted into the absolute path
with respect to the location of the file containing the directive being resolved. Otherwise it will be resolved with
respect to the process current directory.
 
If for whatever reason it is preferred to always resolve path expression with respect to the parent script location you
can configure the script engine to do it with the following command:
 
   cscs -config:set: ResolveRelativeFromParentScriptLocation = true
 
Note if you use wildcard in the imported script name (e.g. *_build.cs) the directive will only import from the first
probing directory where the matching file(s) is found. Be careful with the wide wildcard as '*.cs' as they may lead to
unpredictable behavior. For example they may match everything from the very first probing directory, which is typically
a current directory. Using more specific wildcards is arguably more practical (e.g. 'utils/*.cs', '*Helper.cs',
'./*.cs')
------------------------------------
//css_reference <file>;
 
Alias - //css_ref
file - name of the assembly file to be loaded at run-time.
This directive is used to reference assemblies required at run time.
The assembly must be in GAC, the same folder with the script file or in the 'Script Library' folders (see 'CS-Script
settings').
------------------------------------
 
//css_nuget [-noref] [-force[:delay]] [-ver:<version>] [-ng:<nuget arguments>] package0[,package1]..[,packageN];
 
Downloads/Installs the NuGet package. It also automatically references the downloaded package assemblies.
Note: The directive switches need to be in the order as above.
 
By default the package is not downloaded again if it was already downloaded.
If no version is specified then the highest downloaded version (if any) will be used.
Referencing the downloaded packages can only handle simple dependency scenarios when all downloaded assemblies are to
be referenced.
You should use '-noref' switch and reference assemblies manually for all other cases. For example multiple assemblies
with the same file name that target different CLRs (e.g. v3.5 vs v4.0) in the same package.
Switches:
 -noref         - switch for individual packages if automatic referencing isn't desired. 
                  You can use 'css_nuget' environment variable for further referencing package content (e.g. //css_dir
                  %css_nuget%\WixSharp\**)
 -force[:delay] - switch to force individual packages downloading even when they were already downloaded.
                  You can optionally specify delay for the next forced downloading by number of seconds since last
                  download.
                  '-force:3600' will delay it for one hour. This option is useful for preventing frequent download
                  interruptions during active script development.
 -ver:<version> - switch to download/reference a specific package version.
 -ng:<args>     - switch to pass NuGet arguments for every individual package.
 
Example: //css_nuget cs-script;
         //css_nuget -ver:4.1.2 NLog
         //css_nuget -ver:"4.1.1-rc1" -ng:"-Pre -NoCache" NLog
 
This directive will install CS-Script NuGet package.
(see http://www.csscript.net/help/script_nugets.html)
------------------------------------
//css_args arg0[ arg1]..[ argN];
 
Embedded script arguments. The both script and engine arguments are allowed except "/noconfig" engine command switch.
Example: //css_args -dbg -inmem;
This directive will always force script engine to execute the script in debug mode.
------------------------------------
//css_searchdir <directory>;
 
Alias - //css_dir
directory - name of the directory to be used for script and assembly probing at run-time.
 
This directive is used to extend set of search directories (script and assembly probing).
The directory name can be a wildcard based expression.In such a case all directories matching the pattern will be this
case all directories will be probed.
The special case when the path ends with '**' is reserved to indicate 'sub directories' case. Examples:
    //css_dir packages\ServiceStack*.1.0.21\lib\net40
    //css_dir packages\**
------------------------------------
//css_autoclass [style]
 
Alias - //css_ac
Automatically generates 'static entry point' class if the script doesn't define any.
 
    //css_ac
    using System;
 
    void Main()
    {
        Console.WriteLine("Hello World!");
    }
 
Using an alternative 'instance entry point' is even more convenient (and reliable).
The acceptable 'instance entry point' signatures are:
 
    void main()
    void main(string[] args)
    int main()
    int main(string[] args)
 
The convention for the classless (auto-class) code structure is as follows:
 - set of 'using' statements - classless 'main'  - user code  - optional //css_ac_end directive - optional user code
that is not a subject of auto-class decoration(see
https://github.com/oleg-shilo/cs-script/wiki/CLI---User-Guide#command-auto-class)
 
A special case of auto-class use case is a free style C# code that has no entry point 'main' at all:
 
    
 
Since it's problematic to reliable auto-detect free style auto-classes, they must be defined with the special parameter
'freestyle' after the '//css_ac' directive
 
By default CS-Script decorates the script by adding a class declaration statement to the start of the script routine
and a class closing bracket to the end. This may have an unintended effect as any class declared in the script becomes
a 'nested class'. While it is acceptable for practically all use-cases it may be undesired for just a few scenarios.
For example, any class containing method extensions must be a top level static class, what conflicts with the
auto-class decoration algorithm.
 
An additional '//css_autoclass_end' ('//css_ac_end') directive can be used to solve this problem.
 
It's nothing else but a marker indicating the end of the code that needs to be decorated as (wrapped into) an
auto-class.
This directive allows defining top level static classes in the class-less scripts, which is required for implementing
extension methods.
 
 //css_ac
 using System;
 
 void main()
 {
     ...
 }
 
 //css_ac_end
 
 static class Extensions
 {
     static public string Convert(this string text)
     {
         ...
     }
 }
------------------------------------
//css_precompiler <file 1>,<file 2>;
 
Alias - //css_pc
file - name of the script or assembly file implementing precompiler.
 
This directive is used to specify the CS-Script precompilers to be loaded and exercised against script at run time just
before compiling it. Precompilers are typically used to alter the script coder before the execution. Thus CS-Script
uses built-in precompiler to decorate classless scripts executed with -autoclass switch.
(see http://www.csscript.net/help/precompilers.html
------------------------------------
//css_resource <file>[, <out_file>];
 
Alias - //css_res
file     - name of the compiled resource file (.resources) to be used with the script.
           Alternatively it can be the name of the XML resource file (.resx) that will be compiled on-fly.
out_file - Optional name of the compiled resource file (.resources) to be generated form the .resx input.If not
           supplied then the compiled file will have the same name as the input file but the file extension '.resx'
           changed to '.resources'.
 
This directive is used to reference resource file for script.
 Example: //css_res Scripting.Form1.resources;
          //css_res Resources1.resx;
          //css_res Form1.resx, Scripting.Form1.resources;
------------------------------------
//css_import <file>[, preserve_main][, rename_namespace(<oldName>, <newName>)];
 
Alias - //css_imp
There are also another two aliases //css_include and //css_inc. They are equivalents of //css_import <file>,
preserve_main
If $this (or $this.name) is specified as part of <file> it will be replaced at execution time with the main script full
name (or file name only).
 
file            - name of a script file to be imported at compile-time.
<preserve_main> - do not rename 'static Main'
oldName         - name of a namespace to be renamed during importing
newName         - new name of a namespace to be renamed during importing
 
This directive is used to inject one script into another at compile time. Thus code from one script can be exercised in
another one.'Rename' clause can appear in the directive multiple times.
------------------------------------
//css_co <options>;
 
options - options string.
 
This directive is used to pass compiler options string directly to the language specific CLR compiler.
 Example: //css_co /d:TRACE pass /d:TRACE option to C# compiler
          //css_co /platform:x86 to produce Win32 executable
------------------------------------
//css_ignore_namespace <namespace>;
 
Alias - //css_ignore_ns
namespace - name of the namespace. Use '*' to completely disable namespace resolution
 
This directive is used to prevent CS-Script from resolving the referenced namespace into assembly.
------------------------------------
//css_prescript file([arg0][,arg1]..[,argN])[ignore];
//css_postscript file([arg0][,arg1]..[,argN])[ignore];
 
Aliases - //css_pre and //css_post
file    - script file (extension is optional)
arg0..N - script string arguments
ignore  - continue execution of the main script in case of error
 
These directives are used to execute secondary pre- and post-execution scripts.
If $this (or $this.name) is specified as arg0..N it will be replaced at execution time with the main script full name
(or file name only).
You may find that in many cases precompilers (//css_pc and -pc) are a more powerful and flexible alternative to the
pre-execution script.
------------------------------------
//css_host [-version:<CLR_Version>] [-platform:<CPU>]
 
CLR_Version - version of CLR the script should be execute on (e.g. //css_host /version:v3.5)
CPU - indicates which platforms the script should be run on: x86, Itanium, x64, or anycpu.
Sample: //css_host /version:v2.0 /platform:x86;
 
Note this directive only supported on Windows due to the fact that on Linux the x86/x64 hosting implemented via runtime
launcher 'mono'.
 
These directive is used to execute script from a surrogate host process. The script engine application (cscs.exe or
csws.exe) launches the script
execution as a separate process of the specified CLR version and CPU architecture.
------------------------------------
 
Note the script engine always sets the following environment variables:
 'pid'                     - host processId (e.g. Environment.GetEnvironmentVariable("pid")
 'CSScriptRuntime'         - script engine version
 'CSScriptRuntimeLocation' - script engine location
 'cscs_exe_dir'            - script engine directory
 'EntryScript'             - location of the entry script
 'EntryScriptAssembly'     - location of the compiled script assembly
 'location:<assm_hash>'    - location of the compiled script assembly.
 
This variable is particularly useful as it allows finding the compiled assembly file from the inside of the script
code. Even when the script loaded in-memory (InMemoryAssembly setting) but not from the original file. (e.g. var
location = Environment.GetEnvironmentVariable("location:" + Assembly.GetExecutingAssembly().GetHashCode()); 
 
Note that by default setting of 'location:<assm_hash>' is disabled. You can enable it by calling 
'CSScript.EnableScriptLocationReflection = true'.
 
The following is the optional set of environment variables that the script engine uses to improve the user experience:
 
 'CSS_NUGET' 
      location of the NuGet packages scripts can load/reference
 
 'CSSCRIPT_DIR'
      script engine location. Used by the engine to locate dependencies (e.g. resgen.exe). Typically this variable is
      during the CS-Script installation.
 
 'CSSCRIPT_CONSOLE_ENCODING_OVERWRITE'
      script engine output encoding if the one from the css_confix.xml needs to be overwritten.
 
 'CSSCRIPT_INC'
      a system wide include directory for the all frequently used user scripts.
---------
During the script execution CS-Script always injects a little object inspector class 'dbg'. This class contains static
printing methods that mimic Python's 'print()'. It is particularly useful for object inspection in the absence of a
proper debugger.
 
Examples:
  dbg.print("Now:", DateTime.Now)        - prints concatenated objects.
  dbg.print(DateTime.Now)                - prints object and values of its properties.
  dbg.printf("Now: {0}", DateTime.Now)   - formats and prints object and values of its fields and properties.
---------
 
Any directive has to be written as a single line in order to have no impact on compiling by CLI compliant compiler.It
also must be placed before any namespace or class declaration.
 
---------
Example:
 
 //css_include web_api_host.cs;
 //css_reference media_server.dll;
 //css_nuget Newtonsoft.Json;
 
 using System;
 using static dbg;
 
 class MediaServer
 {
     static void Main(string[] args)
     {
         print(args);
 
         WebApi.SimpleHost(args)
               .StartAsConosle("http://localhost:8080");
   }
 }
 
Or shorter form:
 
 //css_autoclass
 //css_inc web_api_host.cs
 //css_ref media_server.dll
 //css_nuget Newtonsoft.Json
 
 using System;
 
 void main(string[] args)
 {
     print(args);
 
     WebApi.SimpleHost(args)
           .StartAsConosle("http://localhost:8080");
 }
 
---------
 Project Website: https://github.com/oleg-shilo/cs-script