DLR Hosting and related stuff... : ScriptScope

DLR Hosting API : How to create ScriptScopes using backing symbol dictionaries to implement dynamic variable lookup

seshadripv — Sat, 16 Aug 2008 06:04:00 GMT

The factory methods used to create a ScriptScope object have overloads that take a 'IAttributeCollection' object to create the scope using the collection as a backing store. This feature is very useful and any app that needs non trivial Hosting would mostly use this feature.

The easiest way to implement the IAttributeCollection interface is to implement the CustomSymbolDictionary defined in the the Hosting API. Once this is done, all variable access by a script executing in the context of this scope will result in a call to the set or get methods that were overriden.

You can do some interesting things like chaining of scopes, inspecting variable values upon script access, value validation etc using this symbol dictionary implementation.

The following example uses a custom symbol dictionary to chain scopes to create a pseudo hierarchy.

using System;

using Microsoft.Scripting;

using Microsoft.Scripting.Hosting;

using Microsoft.Scripting.Runtime;

namespace ScopeOps {

public class ScopeHiererchy {

public static void Main() {

ScriptEngine eng = new ScriptRuntime().GetEngine("py");

ScriptScope baseScope = eng.CreateScope();

var dict = new DynamicLookupDictionary(baseScope);

//set variables in the base scope.

baseScope.SetVariable("base_int", 100);

baseScope.SetVariable("base_string", "from base");

ScriptScope useScope = eng.CreateScope(dict);

var src = eng.CreateScriptSourceFromString(

"print base_int\nprint base_string",

SourceCodeKind.Statements);

//'useScope' doesn't have the variables accessed by the script yet.

//The overriden 'get' method dynamically looks up the variable in the base scope.

src.Execute(useScope);

}

internal class DynamicLookupDictionary : CustomSymbolDictionary {

private ScriptScope _baseScope;

public DynamicLookupDictionary(ScriptScope baseScope):base() {

_baseScope = baseScope;

}

//This method would be invoked whenever a script executing in the context of this scope

//accesses a variable

protected override bool TryGetExtraValue(SymbolId key, out object value) {

//If the variable is part of the base scope, return that value - this effectively

//creates a 'scope chain'

if (_baseScope.TryGetVariable(SymbolTable.IdToString(key), out value)) {

return true;

}

value = null;

return false;

}

public override SymbolId[] GetExtraKeys() {

return null;

}

protected override bool TrySetExtraValue(SymbolId key, object value) {

return false;

}

Quick notes on ScriptScope

seshadripv — Thu, 07 Aug 2008 05:30:00 GMT

ScriptScope is one of the key types available in the DLR Hosting API. They act as a context in which hosts execute code and record the effects of execution like changes in object values, creation of new objects etc.

Prior to any code execution, ScriptScopes can be populated with variables by hosts using methods defined in this type and these variables are then available to any code that’s executed in its context. ScriptScope also acts as a unit of isolation - it maintains state, isolates side effects from code and can be reused as a context to execute another code snippet.

The Hosting API spec describes this type in detail. The following list is a short summary of some of the key points described by the spec

This class represents a namespace essentially. Hosts can bind variable names in ScriptScopes, fetch variable values, etc. Hosts can execute code within scopes for distinct name bindings.
You create instances of ScriptScopes using the CreateScope and ExecuteFile methods on ScriptRuntime or CreateScope on ScriptEngine.

o ScriptScope scope = pythonEngine.CreateScope();

o ScriptScope scope = runtime.CreateScope();

o ScriptScope scope = runtime.ExecuteFile(@"C:\Foo.py");

If a ScriptScope were created with a default language, then members such as Execute and IncludeFile use that language's engine to perform these operations. If the ScriptScope has no default language, then these convenience methods throw an exception, and the Engine property returns null.
At runtime, the DLR manifests a ScriptScope object as a dynamic object. This means that normal object member access sees the variables stored in the scope, not the members of the static .NET ScriptScope type.
Hosts can use ScriptScopes to execute any kind of code within their namespace context. This method offers an easy and convenient way to execute a piece of script code and get a result from the execution. The variables from the execution are also bound to this ScriptScope and this lets hosts examine the state after code execution

o public object Execute(string code)

ScriptScopes has members to support operations on variables like set, edit, remove, clear etc.

o public bool ContainsVariable(string name)

o public object GetVariable(string name)

o public void SetVariable(string name, object value)

o public bool RemoveVariable(string name)

o public void ClearVariables()

In addition to the above items, the spec also contains details about each of the method defined in this type and their arguments.

4 different ways to execute IronPython code using the DLR Hosting API

seshadripv — Tue, 29 Jul 2008 06:55:00 GMT

The Hosting API offers 4 different sets of methods to execute a script. These methods provide hosts - managed application in C#, VB and other .NET languages - with powerful, convenient and versatile ways to execute scripts from the DLR languages like IronPython, IronRuby etc. ( Though the title mentions just IronPython, this post applies to others like IronRuby, ToyScript etc as well)

I have put together a short summary of these methods and the types that define them. The descriptions found here are shortened versions of the descriptions found in the Hosting API spec. Please refer to the same for more specific details about the type and the method.

The types that define these method families are ScriptRuntime, ScriptScope, ScriptSource and CompiledCode.

ScriptRuntime

This class is the starting point for hosting. ScriptRuntime represents global script state. This includes referenced assemblies, a "global object" (ScriptRuntime.Globals), "published" scopes (scopes bound to a name on Globals), available language engines, etc.

public ScriptScope ExecuteFile(string path);

This method executes the source identified in the path argument and returns the new ScriptScope in which the source executed. ExecuteFile determines the language engine to use from the path's extension and the ScriptRuntime's configuration, comparing extensions case-insensitively.

The path is an absolute pathname or a filename that naturally resolves with standard .NET BCL file open calls.

ScriptScope

This class represents a namespace essentially. Hosts can bind variable names in ScriptScopes, fetch variable values, etc. Hosts can execute code within scopes for distinct name bindings.

public object Execute(string code);

public T Execute<T>(string code);

These methods return objects that result from executing code in the string argument.

ScriptSource

ScriptSource represents source code and offers a variety of ways to execute or compile the source. You can get ScriptSources from factory methods on ScriptEngine, and ScriptSources are tied to the engine that created them.

public object Execute(ScriptScope scope);

public ObjectHandle ExecuteAndWrap(ScriptScope scope);

public T Execute<T>(ScriptScope scope);

public int ExecuteProgram();

These methods execute the source code and return the result. All but one method executes the code in the specified ScriptScope.

CompiledCode

CompiledCode represents code that has been compiled to execute repeatedly without having to compile it each time, and it represents the default ScriptScope the code runs in. You can also execute the code in any ScriptScope if you need it to execute in a clean scope each time, or you want to accumulate side effects from the code in another scope.

public object Execute() { }

public object Execute(ScriptScope scope) { }

public ObjectHandle ExecuteAndWrap() { }

public ObjectHandle ExecuteAndWrap(ScriptScope scope) { }

public T Execute<T>() { }

public T Execute<T>(ScriptScope scope) { }

Unlike the ScriptSource’s execute methods, these do not compile the code again.

A few of these methods can be found in the samples from the earlier blog posts. For more details and documentation about these methods and types please refer to the Hosting API spec.