Script hosting guideline

Script hosting can be as simple as a single line call or it can be a more complex solution, requiring design, deployment and code maintenance considerations. In most cases a success would depend on how correctly the hosting model was chosen.

"Isolated execution" is straightforward and does not really require any special consideration.

However the "type sharing" model can lead to some run-time and code maintenance problems if not implemented correctly. The greatest benefit can be achieved when using interfaces as the types to be passed between the host and the script. Because they enforce good implementation/interface separation.

The script-assembly loading approach is not as critical as it seams. Whereas the remote loading obviously is the most flexible model it gives a little advantage, but requires all types, which are crossing AppDomain boundaries to be either sterilizable or descendant of MarshalByRefObject.

Use the following as a general guideline:

Use interfaces when you can and remote loading when you need to.

Samples\Hosting\HostingWithInterfaces folder contains example of script hosting with using interfaces. This is an example of a balanced usage of scripting. It uses local loading and allows unrestricted data exchange between the script and the host using an ordinary C# coding technique.

There is also another advantage of using interfaces. By using interfaces you can avoid using less-friendly coding techniques (pure reflection) in the implementation of the host application. The following code sample demonstrates the technique:

Host: interface definition code

public interface IWordProcessor
{
    void CreateDocument();
    void CloseDocument();
    void OpenDocument(string file);
    void SaveDocument(string file);
}

Script: interface implementation code

public class WordProcessor: IWordProcessor
{
    public void CreateDocument() { ... }
    public void CloseDocument() { ... }
    public void OpenDocument(string file) { ... }
    public void SaveDocument(string file) { ... }
}

Host: script usage code

AsmHelper helper = new AsmHelper(CSScript.Load("script.cs", null, true));

//the only reflection based call
IWordProcessor proc = (IWordProcessor)helper.CreateObject("WordProcessor");

//no reflection, just direct calls
proc.CreateDocument();
proc.SaveDocument("MyDocument.cs");

Interface Alignment

In version 2.3.3 CS-Script introduces new script hosting model Interface Alignment, which is an attractive alternative to the interface inheritance while loading/accessing scripts through interfaces.

This model allows manipulation with the the script by "aligning" it to the appropriate interface (DuckTyping). Important aspect of this approach is that the script execution is completely typesafe (as with any script accessed through an interface) but even more importantly the script does not have to implement the interface being used by the host application.

In a way Interface Alignment is a forcible typecasting: typecast to interface is possible as long as the object has all methods defined in the interface .

This promising technique allows high level of decoupling between the host and the script business logic without any type safety compromise.

The core implementation of the Interface Alignment is based on the ObjectCaster by Ruben Hakopian, which is a subject of this Copyright.

Example of the Interface Alighnment:

using CSScriptLibrary;

public interface IScript
{
    void Hello(string greeting);
}

class Host
{
    static void Main()
    {
        var script = CSScript.Load("HelloScript.cs")
                             .CreateInstance("Script")
                             .AlignToInterface<IScript>();

        script.Hello("Hi there...");
    }
}

HelloScript.cs

using System;

public class Script
{
public void Hello(string griting)
{
Console.WriteLine(greeting);
}

void SomeOtherMethod()
{
...
}
}

If you need to align remote object (TransparentProxy) created in the different AppDomain you need to use AsmHelper to do actual alignment and in the appropriate AppDomain context (see <cs-script>\Samples\Hosting\InterfaceAlignment samples):

//Note using helper.CreateAndAlignToInterface<IScript>("Script") is also acceptable
using (var helper = new AsmHelper(CSScript.CompileCode(code), null, false))
{
IScript script = helper.CreateAndAlignToInterface<IScript>("*");

script.Hello("Hi there...");
}

Script hosting considerations

As almost with any other programming task script hosting can be a simple maintainable solution or it can lead to bloated unstable system, which is hard to maintain or test. As usual it all depends on design and implementation decisions. Decisions, which are easier to make if you consider the following hosting aspects.

How to invoke script methods?
Strictly speaking you do not need any special framework to exercice script methods. The script assembly is (the primary output of the script engine) is an ordinary assembly and you can use Reflection to work with it as you would with any other assembly. But the problem is that reflection based code is harder to read and maintain. AsmHelper is a CS-Script class, which significantly simplifies working with dynamically loaded assemblies. You can find various invocation samples in cs-script\Samples\Hosting\MethodSignatures.cs.

Assembly assembly = CSScript.LoadCode(
            @"using System;
              public class Calculator
              {
                    static public int Add(int a, int b)
                    {
                       return a + b;
                    }
              }");

AsmHelper calc = new AsmHelper(assembly);
int sum = calc.Invoke("Calculator.Add", 1, 2); //sum == 3;

AsmHelper implements Dispatch invokation pattern by resolving user specified method names into actual method runtime type information. An alternative approach is to generate dynamic delegate for each method you are going to execute and work with these delegates instead of AsmHelper directly.

...
AsmHelper calc = new AsmHelper(assembly);
var Add = calc.GetMethodInvoker("Calculator.Add", 0, 0);

//pass null because Calculator.Add is a static method otherwise pass class instance
int sum = Add(null, 1, 2); //sum == 3;

Note: that you can use wild card for method names (e.g. "*.Add").

AsmHelper also has specialized method emitters GetStaticMethod() and GetMethod(), which return delegate for static or instance method, thus you do not need to pass instance value:

Assembly assembly = CSScript.LoadCode(
            @"using System;
              public class Calculator
              {
                    static public int Add(int a, int b)
                    {
                       return a + b;
                    }
              }");

var Add = new AsmHelper(assembly).GetStaticMethod();
int sum = Add(1, 2);

In the example above GetStaticMethod() is used without any parameters, what is an equivalent of GetStaticMethod("*.*"). Meaning any method of any type from the specified assembly.

Another alternative is to use interfaces (see previous section code sample). When using interfaces a simple typecasting automatically maps entire set of class methods and properties into runtime object.

How important performance is?
AsmHelper operates through Reflection (MethodInfo) and this is the reason why if you have to invoke some script methods multiple times you will pay some performance penalties. The work around this is to avoid using Reflection and rather work with interfaces or delegates emitted by AsmHelper (see sections above).

Interfaces and emitted delegates are about 100 faster than Reflection You can find detailed information about ways of improving performance in cs-script\Samples\Hosting\performance.cs sample (TestMethodDelegates() method).

How type safe your code is?
Dispatch pattern for method invocation is (Reflection) is error prone as it cannot be checked at by compiler. Thus if you want to achieve stronger typed code you need to use either dynamic (emitted) delegates or better yet to use interfaces. See cs-script\Samples\Hosting\TypeSafety.cs for samples.

How readable your code is?
Code readability (and maintainability in general) is something the you should invest in generously. Usage of extension methods is one of the possibilities for code improvements. CS-Script class library comes with a few extension methods which allow to minimize code footprint for script hosting routines. In the code samples below Assembly class extended with GetStaticMethod and CreateObject method extensions, which allow in the presented context completely avoid usage of AsmHelper.

var SayHello = CSScript.LoadMethod(
@"public static void SayHello(string greeting)
                           {
                             Console.WriteLine(greeting);
                             }")
                             .GetStaticMethod();

SayHello("Hello World!");

"How much" scripting do you need?
The default scripting unit is a C# module containing type definition(s). However it is possible to have a script which defines just a single method with no class (classless).

Assembly assembly = CSScript.LoadCode(
            @"static public void PrintSum(int a, int b)
              {
                 Console.WriteLine(a + b);
              }");

var PrintSum = new AsmHelper(assembly).GetStaticMethod();

PrintSum(1, 2);

Note that you can have multiple methods implementations in the classless script code. You can also specify namespaces at the beginning of the code:

See cs-script\Samples\Hosting\Classless.cs sample for details.

Assembly and Script Probing scenarios

When implementing particular hosting scenario you may get into the situation when your host, script and script dependencies required to be located in different places. Such requirement sometimes is hard to meet and it is a common issue for dynamic assembly loading.

It is important to recognize that a part from the dealing with the common assembly probing problems developers also have to face script probing issues.

assembly probing - the way how CLR locates assemblies.
script probing - the way how CS-Script engine locates scripts.

Also it is worth to mention that script execution consist of two logical stages and they are affected by the probing problems in different degree:

Script compilation - involves assembly and script probing
Compiled script (assembly) execution - involves assembly probing only

Fortunately CS-Script can assist with solving all probing problems. In general, the way of solving the assembly probing problems is to nominate probing directories (search directories) before executing the script. This can be done globally for all scripts or on the script by script base. An alternative approach is to use Simplified Hosting Model. In most of the cases Simplified Hosting Model would be sufficient to handle all possible script probing problems, however in some rare cases you may need to set probing directories by yourself.

Simplified Hosting Model probing directories

The simplest way to solve probing problems is to use Simplified Hosting Model. The main advantage of this approach is that CS-Script engine automatically includes directories of all loaded assemblies of the host application (including the application assembly itself) into the list of searchable directories. And because Simplified Hosting Model is enabled by default in most of the cases you do not have to do anything special about the script probing in your code. For example if your script is located in the different directory with respect to the host application and the script is accessing the host application type(s) you do not have to express host/script dependency in any special way: the script engine will do it for you.

//Host.cs
class Host
{
    ...
    void Process()
    {
        AsmHelper helper = new AsmHelper(CSScript.Load(@"Scripts\MyScript.cs"));
        helper.Invoke("*.Process", this);
    }
}

//MyScript.cs
static public void Process(Host host)
{
......
}

Global probing directories

Another way of solving the probing problems is to nominate probing directories globally. Such approach is the simplest however it does have some limitations.

The first line of the code below adds Lib directory to the list of the probing directories. These directories are used for probing at compiling stage (CSScript.Load) and also at execution stage (helper.Invoke).

CSScript.GlobalSettings.AddSearchDir(Path.GetFullPath("Lib"));
CSScript.AssemblyResolvingEnabled = true;

AsmHelper helper = new AsmHelper(CSScript.Load("script.cs"));
helper.Invoke("Script.Report", "Hello!");

Note that assembly resolving at the execution stage is forced to use the same global probing directories by setting AssemblyResolvingEnabled to true. If AssemblyResolvingEnabled is false you have to set probing directories for script execution explicitly by modifying the AsmHelper's object ProbingDirs property.

CSScript.GlobalSettings.AddSearchDir(Path.GetFullPath("Lib"));

AsmHelper helper = new AsmHelper(CSScript.Load("script.cs"));
helper.ProbingDirs = CSScript.GlobalSettings.SearchDirs.Split(';');
helper.Invoke("Script.Report", "Hello!");

Using GlobalSettings is convenient but it will not work with the remote script execution. Remote execution model implies that the script assembly after execution is unloaded. In order to do this the script assembly is executed in a different AppDomain thus even if GlobalSettings.SearchDirs is set it's value will be different in the actual execution domain. The following code will produce the error if script.cs uses any assembly form the Lib directory.

CSScript.GlobalSettings.AddSearchDir(Path.GetFullPath("Lib"));
CSScript.AssemblyResolvingEnabled = true;

string asmFile = CSScript.Compile("script.cs", null, false);
using (AsmHelper helper = new AsmHelper(asmFile, "tempDomain", true))
{
helper.Invoke("Script.Report", "Hello!"); //ERROR
}

In order to fix the problem the code has to be modified as following:

CSScript.GlobalSettings.AddSearchDir(Path.GetFullPath("Lib"));

string asmFile = CSScript.Compile("script.cs", null, false);
using (AsmHelper helper = new AsmHelper(asmFile, "tempDomain", true))
{
helper.ProbingDirs = CSScript.GlobalSettings.SearchDirs.Split(';');
helper.Invoke("Script.Report", "Hello!");
}

Script specific probing directories

As an alternative to the GlobalSettings approach you may specify probing directories for particular script only. This can be accomplished by passing Settings object to the script compiler and setting the AsmHelper.ProbingDirs property.

Settings settings = new Settings();
settings.AssSearchDir(Path.GetFullPath("Lib"));

string asmFile = CSScript.CompileWithConfig("script.cs", null, false, settings, "");

AsmHelper helper = new AsmHelper(Assembly.LoadFrom(asmFile));
helper.ProbingDirs = settings.SearchDirs.Split(';');
helper.Invoke("Script.Report", "Hello!");

The code above will work with remote script execution too.

PInvoke probing directories

When using PInvoke to call unmanaged functions that are implemented in a DLL CLR searches the DLLs in the local (with respect to main application) directory and in all directories of the system PATH environment variables. CS-Script automatically adds all SearchDirs to the system PATH thus native DLL probing directories can be managed in the same way as assembly probingdirectories.

Script caching

Script caching is available durings script execution from the command-prompt (see /c switch). The same script caching mechanism is engaged while executing by the engine hosted by an other application. You can enable/disable the caching by setting the CSScript.CacheEnabled property (true by default). Practically it means that if you are executing the script from the application it will not be recompiled every time unless it is changes since the last execution.

Script Compiling Errors
If the script to be executed generated compiling it is possible now to extract the detailed information about the error. The iformation is stored in the Data dictionary of CompilerException class. This technique is also useful when it is required to distinguish compiling Errors and Warnings.

try

{

CSScript.LoadCode(code);

}

catch (CompilerException e)

{

CompilerErrorCollection errors = (CompilerErrorCollection)e.Data["Errors"];

foreach (CompilerError err in errors)

{

Console.WriteLine("{0}({1},{2}): {3} {4}: {5}",

err.FileName,

err.Line,

err.Column,

err.IsWarning ? "warning" : "error",

err.ErrorNumber,

err.ErrorText);

}

Script Hosting Guideline

Script hosting considerations

Assembly and Script Probing scenarios

See Also