CS-Script 3.20.0


Using .NET assemblies

CS-Script uses C# as a scripting language. Therefore, the scripting capabilities are largely based on the language itself. These capabilities can be extended by using external .NET assemblies (FCL or/and third-party assemblies).

It is possible to instruct the script engine to load at execution time any assembly which is referenced within the code. This can be accomplished by any of the following approaches:


Loading assembly implicitly

The assembly is loaded automatically as a result of the analysis of C# code by the script engine.

The concept of loading the referenced assemblies automatically is quite simple. The script engine analyses all namespaces referenced in the code ("using" statement) and searches "local directories" (see File Location section below) and Global Assembly Cache (GAC) for assemblies with the same name as the referenced namespace. If such assembly is found it is loaded at execution time.

The approach is based on the fact that in a real life there is a strong correlation between the assembly name and the root namespace. For example, the namespace System.Windows.Forms is implemented in the assembly System.Windows.Forms, and the namespace System.XML is implemented in the assembly System.XML . This is also applicable to the assembly file name, which is usually a DLL file with the same name as the assembly name.

Thus, if script code has a statement "using System.Windows.Forms;" the system.windows.forms.dll will be automatically loaded (resolved) form GAC at execution time. If you need to make a use of myLibrary.dll in your script and it has a namespace myLibrary just put "using myLibrary;" in your code and assembly will be resolved.

In any case  explicit assembly loading has to be used is where there is no resemblance between a namespace in the assembly and a name of the assembly file (eg. the namespace Steema is implemented in teechart.lite.dll).

Loading assembly explicitly

The assembly is loaded because of an explicit request either from the code or from the command-line.

Information on loading the assembly from the command-line can be found in the Command-line interface section.

This is the code directive to load the assembly at execution time:

//css_reference <file>;

file - name of the assembly file. Assembly names may be enclosed in double quotation marks. Non-searchable assembly names should be enclosed in double quotation marks (see explanations below). Try to avoid using the absolute path because it can create difficulties when isolating scripts for deployment.

The shorter alias directive //css_ref can be used in place of the //css_reference.

Note:

The <file> parameter can contain environement variable mask which would be expanded at runtime. The file extension in the file name is optional for non-GAC assemblies. 

If the name is enclosed to the quotation marks the engine does not search for this assembly and passes the assembly name to the compiler as it is (in this case the CLR compiler is responsible for the assembly search). This approach is used to run the scripts on MONO where all GAC (non-searchable) assemblies have to be specified explicitly from code.

File location

The assembly to be loaded must be from one of the following locations (the order indicates the assembly search priority):

Remember that you may need to escape some path characters that conflict with the //css_ delimiters. See Delimiters Escaping section.

Example

The assembly math.dll contains implementation of class Calculator (which belongs to the namespace Math). This class has the method Add(int a, int b).

The following code explicitly loads two assemblies: math.dll and system.windows.forms.dll.

//css_reference math.dll;
using
 System;
using System.Windows.Forms;

class Test 

    static public void Main( string [] args)
    {
        MessageBox.Show(Math.Calculator.Add(1,2).ToString());
    }
}


Hints And Tips

When you need to reference many assemblies (and particularly when these assemblies are commonly used) it is convenient to combine all //css_reference statements into single file containing no code and include this file into your primary script. 

The following code includes linq.includes.cs file containing references to all assemblies required for programming against LINQ:

//css_include linq.includes.cs;
using
 System;

class Test 

    static public void Main( string [] args)
    {
        ....

This is the content of the linq.includes.cs file:

//css_ref System.Core;
//css_ref System.Data.ComponentModel;
//css_ref System.Data.DataSetExtensions;
//css_ref System.Xml;
//css_ref System.Xml.Linq;

Script Library already  contains some predefined "include" scripts (e.g. linq.includes.cs, wwf.includes.cs and wpf.includes.cs).

 

See Also

Command-line interfaceCS-Script settings | Using COM (Tutorial)