4 API References

Need to dope in what exceptions are thrown where I say we throw one, and need to add more details about argument checking and exceptions we throw.

4.1 ScriptRuntime Class

This class is the starting point for hosting. For Level One scenarios, you just create ScriptScopes, use Globals, and use ExecuteFile. For Level Two scenarios, you can get to ScriptEngines and so on.

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.

ScriptRuntime has a single constructor and two convenience factory methods. You can create multiple instances of a ScriptRuntime in a single AppDomain. For information on configuring a ScriptRuntime for what languages it allows, global settings, language settings, etc., see ScriptRuntimeSetup.

4.1.1 Class Summary

public class ScriptRuntime : MarshalByRefObject
    public ScriptRuntime(ScriptRuntimeSetup setup)
    public static ScriptRuntime CreateFromConfiguration()
    public static ScriptRuntime 
        CreateRemote(AppDomain domain, ScriptRuntimeSetup setup)
    public ScriptScope ExecuteFile(string path)
    public ScriptScope Globals { get; set;}
    public ScriptScope CreateScope()
    public ScriptScope CreateScope(IDynamicMetaObjectProvider storage)
	
    public ScriptEngine GetEngine(string languageId)
    public ScriptEngine GetEngineByFileExtension(string extension)
    public string[] GetRegisteredFileExtensions()
    public string[] GetRegisteredLanguageIdentifiers()
    public void LoadAssembly(Assembly assm)
    public ObjectOperations Operations { get; }
    public ObjectOperations CreateOperations() 
    public ScriptRuntimeSetup Setup { get; }
    public ScriptHost Host { get; }
    public ScriptIO IO { get; }
    public void Shutdown()
  

4.1.2 Constructor

The constructor requires a ScriptRuntimeSetup, which gives the host full control of the languages allowed in the ScriptRuntime, their options, and the global runtime options.

This method ensures the list of languages in the setup object has no duplicate elements based on the LanguageSetup.TypeName property (just comparing them as strings at this point). Later, when engines fault in, the DLR also ensures that none of the assembly-qualified types actually identify the same type.

This method ensures the list of languages in the setup have no conflicting LangaugeSetup.Names elements or Language.FileExtensions elements.

After calling this method, modifying the ScriptRuntimeSetup object throws an exception.

Signature:

public ScriptRuntime(ScriptRuntimeSetup setup)
  

4.1.3 Create\* Methods

These factory methods construct and return ScriptRuntimes. They primarily are for convenience and discoverability via editors that complete members on types.

CreateFromConfiguration is just a convenience for:

new ScriptRuntime(ScriptRuntimeSetup.ReadConfiguration())
  

CreateRemote creates the ScriptRuntime in the specified domain, instantiates the ScriptRuntimeSetup.HostType in that domain, and returns the ScriptRuntime. Any arguments specified in ScriptRuntimeSetup.HostArguments must derive from MBRO or serialize across app domain boundaries. The same holds for any values in ScriptRuntimeSetup.Options and any LanguageSetup.Options.

Signatures:

public static ScriptRuntime CreateFromConfiguration()
public static ScriptRuntime 
    CreateRemote(AppDomain domain, ScriptRuntimeSetup setup)
  

4.1.4 ExecuteFile Method

This method executes the source identified in the path argument and returns the new ScriptScope in which the source executed. This method calls on the ScriptRuntime.Host to get the PlatformAdaptationLayer and then calls on it to resolve and open the path. ExecuteFile determines the language engine to use from the path's extension and the ScriptRuntime's configuration, comparing extensions case-insensitively.

This convenience method exists for Level 1 hosting scenarios where the path is likely an absolute pathname or a filename that naturally resolves with standard .NET BCL file open calls.

Signature:

public ScriptScope ExecuteFile(string path)
  

Each time this method is called it create a fresh ScriptScope in which to run the source. Calling Engine.GetScope returns the last ScriptScope created for repeated invocations of ExecuteFile on the same path.

This method adds variable name bindings within the ScriptRuntime.Globals object as appropriate for the language. Dynamic language code can then access and drill into objects bound to those names. For example, the IronPython loader adds the base file name to the ScriptRuntime.Globals as a Python module, and when IronPython is importing names, it looks in ScriptRuntime.Globals to find names to import. IronRuby's loader adds constants and modules to the ScriptRuntime.Globals object. DLR JScript adds all globals there.

In Globals, each language decides its own semantics for name conflicts, but the expected model is last-writer-wins. Languages do have the ability to add names to Globals so that only code executing in that language can see the global names. In this case, other languages would not have the ability to clobber the name bindings. For example, Python might do this for its special built-in modules. However, most names should be added so that all languages can see the bindings and interoperate with the objects bound to the names.

4.1.5 UseFile Method

This method executes the source identified in the path argument and returns the new ScriptScope in which the source executed. If the identified file was already executed, this method does NOT execute the file again, but instead the method just returns the ScriptScope. The path must have a language file extension registered with the ScriptRuntime. UseFile affects ScriptRuntime.Globals the same way ExecuteFile does.

This method is like ExecuteFile except in two ways. ExecuteFile always executes the file each time you call it, but UseFile executes the file at most once. UseFile resolves the path argument against the language engines search paths to find the file, but ExecuteFile just calls .NET open functions to find the file.

Essentially, this method finds the engine for the file extension and calls GetScope on the results of joining the path argument with each of the items in the engine's search paths. If it finds no scope, then it calls ExecuteFile on the first existing file found by joining the argument path with the items in the engine's search paths.

This convenience method exists for Level 1 hosting scenarios where the host wants to load a file of script code in the same manner a language would (for example, Python's import statement or Ruby's require function).

Signature:

public ScriptScope UseFile(string path)
  

4.1.6 Globals Property

This property returns the "global object" or name bindings of the ScriptRuntime as a ScriptScope. You can set the globals scope, which you might do if you created a ScriptScope with an IDynamicMetaObjectProvider so that your host could late bind names. The easiest way to provide an IDynamicMetaObjectProvider is to use ExpandObject or derive from DynamicObject.

Signature:

public ScriptScope Globals { get; set; }
  

4.1.7 CreateScope Method

This method returns a new ScriptScope.

Signatures:

public ScriptScope CreateScope()
public ScriptScope CreateScope(IDynamicMetaObjectProvider storage)
  

The storage parameter lets you supply the dictionary of the scope so that you can provide late bound values for some name lookups. If storage is null, this method throws an ArgumentNullException.

4.1.8 GetEngine Method

This method returns the one engine associated with this ScriptRuntime that matches the languageId argument, compared case-insensitively. This loads the engine and initializes it if needed.

Signature:

public ScriptEngine GetEngine(string languageId)
  

If languageId is null, or it does not map to an engine in the ScriptRuntime's configuration, then this method throws an exception.

4.1.9 GetEngineByFileExtension Method

This method takes a file extension and returns the one engine associated with this ScriptRuntime that matches the extension argument. This strips one leading period if extension starts with a period.

This loads the engine and initializes it if needed. The file extension associations are determined by the ScriptRuntime configuration (see configuration section above). This method compares extensions case-insensitively.

Signature:

public ScriptEngine GetEngineByFileExtension(string extension)
  

If extension is null, or it does not map to an engine in the ScriptRuntime's configuration, then this method throws an exception.

4.1.10 GetEngineByMimeType Method

~~This method takes a MIME type and returns the one engine associated with this ScriptRuntime that matches the argument.~~

~~This loads the engine and initializes it if needed. The MIME type associations are determined by the ScriptRuntime configuration (see configuration section above).~~

~~Signature:~~

public ScriptEngine GetEngineByMimeType(string mimetype);
  

~~If mimetype is null, or it does not map to an engine in the ScriptRuntime's configuration, then this method throws an exception.~~

4.1.11 GetRegisteredFileExtensions Method

This method returns an array of strings (without periods) where each element is a registered file extension for this ScriptRuntime. Each file extension maps to a language engine based on the ScriptRuntime configuration (see configuration section above). If there are none, this returns an empty array.

Signature:

public string[] GetRegisteredFileExtensions()
  

4.1.12 GetRegisteredLanguageIdentifiers Method

This method returns an array of strings where each element is a registered language identifier for this ScriptRuntime. Each language identifier maps to a language engine based on the ScriptRuntime configuration (see configuration section above). Typically all registered file extensions are also language identifiers. If there are no language identifiers, this returns an empty array.

Signature:

public string[] GetRegisteredLanguageIdentifiers()
  

4.1.13 LoadAssembly Method

This method calls on language engines to inform them of DLLs whose namespaces and types should be available to code the engines execute. Language engines can make the names available however they see fit. They may resolved free identifiers first to ScriptRuntime.Globals and then to names provided by loaded DLLs. They may make the names available to ‘using', ‘import', or ‘require' expressions. They may add names to ScriptRuntime.Globals that are bound to dynamic objects for accessing sub namespaces and types by drilling in from root namespaces stored in Globals.

By default, the DLR seeds the ScriptRuntime with Mscorlib and System assemblies. You can avoid this by setting the ScriptRuntimeSetup option "NoDefaultReferences" to true. When new language engines load, the ScriptRuntime passes the list of loaded assemblies.

Signature:

public void LoadAssembly(Assembly assm)
  

The following is the old behavior that was cut in lieu of the more flexible, langauge-specific support above (kept here should it come back before adding these APIs to .NET):

walks the assembly's namespaces and adds name bindings in ScriptRuntime.Globals to represent namespaces available in the assembly. Each top-level namespace name becomes a name in Globals, bound to a dynamic object representing the namespace. Within each top-level namespace object, the DLR binds names to dynamic objects representing each sub namespace or type.

There is a bug today that instead of dynamic objects representing namespaces and types, the DLR stores NamespaceTrackers and TypeTrackers, which only implement IAttributesCollection. We are considering cutting these types, perhaps even leaving all reflection with dynamic objects to the langauge. See the Sympl language example for what it does. Production-quality languages may want something as sophisticated as the tracker objects, which IronPython will continue to use from an IronPython DLL.

~~By default, the DLR seeds the ScriptRuntime with Mscorlib and System assemblies. You can avoid this by setting the ScriptRuntimeSetup option "NoDefaultReferences" to true.~~

When this method encounters the same fully namespace-qualified type name, it merges names together objects representing the namespaces. If you called LoadAssembly on two different assemblies, each contributing to System.Foo.Bar namespace, then all names within System.Foo.Bar from both assemblies will be present in the resulting object representing Bar.

4.1.14 Operations Property

Likely cutting this from the hosting APIs soon. We've shifted our thinking away from having a language-invariant static helper since it can't do very much without baking in language choices, like implicit conversions and whatnot just to invoke objects.

This property returns a default, language-neutral ObjectOperations. ObjectOperations lets you perform various operations on objects. When the objects do not provide their own behaviors for performing the operations, this ObjectOperations uses general .NET semantics. Because there are many situations when general .NET semantics are insufficient due to dynamic objects often not using straight .NET BCL types, this ObjectOperations will throw exceptions when one produced by a ScriptEngine would succeed.

Because an ObjectOperations object caches rules for the types of objects and operations it processes, using the default ObjectOperations for many objects could degrade the caching benefits. Eventually the cache for some operations could degrade to a point where ObjectOperations stops caching and does a full search for an implementation of the requested operation for the given objects. For simple hosting situations, this is sufficient behavior.

See CreateOperations for alternatives.

Signature:

public ObjectOperations Operations { get; }
  

4.1.15 CreateOperations Methods

These methods return a new ObjectOperations object. See the Operations property for why you might want to call this and for limitations of ObjectOperations provided by a ScriptRuntime instead of one obtained from a ScriptEngine.

There currently is little guidance on how to choose when to create new ObjectOperations objects. However, there is a simple heuristic. If you were to perform some operations over and over on the same few types of objects, it would be advantageous to create an ObjectOperations just for use with those few cases. If you perform different operations with many types of objects just once or twice, you can use the default instance provided by the ObjectOperations property.

Signature:

public ObjectOperations CreateOperations() 
  

4.1.16 Setup Property

This property returns a read-only ScriptRuntimeSetup object describing the configuration information used to create the ScriptRuntime.

Signature:

public ScriptRuntimeSetup Setup { get; }
  

4.1.17 Host Property

This property returns the ScriptHost associated with the ScriptRuntime. This is not settable because the ScriptRuntime must create the host from a supplied type to support remote ScriptRuntime creation. Setting it would also be bizarre because it would be similar to changing the owner of the ScriptRuntime.

Signature:

public ScriptHost Host { get; }
  

4.1.18 IO Property

This property returns the ScriptIO associated with the ScriptRuntime. The ScriptIO lets you control the standard input and output streams for code executing in the ScriptRuntime.

Signature:

public ScriptIO IO { get; }
  

4.1.19 Shutdown Method

This method announces to the language engines that are loaded that the host is done using the ScriptRuntime. Languages that have a shutdown hook or mechanism for code to release system resources on shutdown will invoke their shutdown protocols.

There are no other guarantees from this method. For example, It is undefined when code executing (possibly on other threads) will stop running. Also, any calls on the ScriptRuntime, hosting API objects associated with the runtime, or dynamic objects extracted from the runtime have undefined behavior.

Signature:

public void Shutdown()
  

4.2 ScriptScope Class

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.

ScriptScopes also have some convenience members and an optional language affinity. Scopes use the language to look up names and convert values. If the ScriptScope has no default language, then these convenience methods throw an exception, and the Engine property returns null.

Hosts can store ScriptScopes as the values of names on ScriptRuntime.Globals or in other scopes. When dynamic language code encounters a ScriptScope as an object, the DLR manifests the scope as a dynamic object. This means that normal object member access sees the variables stored in the ScriptScope first. Languages executing code that is doing the object member access get a chance to find members if the members are not variables in the ScriptScope. The language might bind to the .NET static type members documented here. They might detect the .NET type is ScriptScope and throw a missing member exception, use meta-programming hooks to give dynamic language code a chance to produce the member, or return sentinel objects according to the language's semantics.

Hosts can use ScriptScopes (regardless of whether they have a language affinity) to execute any kind of code within their namespace context. ScriptEngine methods that execute code take a ScriptScope argument. There are parallel methods on engines for getting and setting variables so that hosts can request a name lookup with any specific language's semantics in any ScriptScope.

You create instances of ScriptScopes using the CreateScope and ExecuteFile methods on ScriptRuntimes or CreateScope on ScriptEngine.

Note, members that take or return ObjectHandles are not present on Silverlight.

4.2.1 Class Summary

public class ScriptScope : MarshalByRefObject {
    public object GetVariable(string name)
    public ObjectHandle GetVariableHandle(string name)
    public bool RemoveVariable(string name)
    public void SetVariable(string name, object value)
    public void SetVariable(string name, ObjectHandle handle)
    public bool TryGetVariable(string name, out object value)
    public bool TryGetVariableHandle(string name, 
                                       out ObjectHandle handle)
    public T GetVariable<T>(string name)
    public bool TryGetVariable<T>(string name, out T value)
    public bool ContainsVariable(string name)
    public IEnumerable<string> GetVariableNames()
    public IEnumerable<KeyValuePair<string, object>> GetItems()
    public ScriptEngine Engine { get;}
  

4.2.2 GetVariable\* Methods

These methods fetch the value of a variable stored in the scope.

If there is no engine associated with the scope (see ScriptRuntime.CreateScope), then the name lookup is a case-sensitive, literal lookup of the name in the scope's dictionary. If there is a default engine, then the name lookup uses that language's semantics.

Signatures:

public object GetVariable(string name)
public ObjectHandle GetVariableHandle(string name)
public T GetVariable<T>(string name)
  

GetVariableHandle is useful when the ScriptScope is remote so that you get back an ObjectHandle referring to the value.

GetVariable<T> uses language-specific (based on the default language in the Engine property) conversions. These may be implicit only, or include explicit conversions too. This method throws a NotSupportedException if the engine cannot perform the requested type conversion. If there is no associated engine, this method essentially just casts to T, which could throw an ArgumentException.

If you need an explicit conversion to T, you can use scope.Engine.Operations.ExplicitConvertTo<T>.

4.2.3 SetVariable Methods

These methods assign a value to a variable in the scope, overwriting any previous value.

If there is no engine associated with the scope (see ScriptRuntime.CreateScope), then the name mapping is a case-sensitive, literal mapping of the name in the scope's dictionary. If there is a default engine, then the name lookup uses that language's semantics.

Signatures:

public void SetVariable(string name, object value)
public void SetVariable(string name, ObjectHandle handle)
  

4.2.4 TryGetVariable\* Methods

These methods fetch the value of a variable stored in the scope and return a Boolean indicating success of the lookup. When the method's result is false, then it assigns null to value.

Signatures:

public bool TryGetVariable(string name, out object value)
public bool TryGetVariableHandle(string name, 
                                   out ObjectHandle handle)
public bool TryGetVariable<T>(string name, out T value)
  

TryGetVariableHandle is useful when the ScriptScope is remote so that you get back an ObjectHandle referring to the value.

TryGetVariable<T> uses language-specific (based on the default language in the Engine property) conversions. These may be implicit only, or include explicit conversions too. It throws a NotSupportedException if the engine cannot perform the requested type conversion. If there is no associated engine, this method uses standard .NET conversion, which could throw an ArgumentException.

If you need an explicit conversion to T, you can use scope.Engine.Operations.TryExplicitConvertTo<T>.

4.2.5 ContainsVariable Method

This method returns whether the variable is exists in this scope and has a value.

If there is no engine associated with the scope (see ScriptRuntime.CreateScope), then the name lookup is a literal lookup of the name in the scope's dictionary. Therefore, it is case-sensitive for example. If there is a default engine, then the name lookup uses that language's semantics.

Signature:

public bool ContainsVariable(string name)
  

4.2.6 GetVariableNames Method

This method returns an enumeration of strings, one string for each variable name in this scope. If there are no names, then it returns an empty array. Modifying the array has no impact on the ScriptScope. This method returns a new instance for the result of each call.

Signature:

public IEnumerable<string> GetVariableNames()
  

4.2.7 GetItems Method

This method returns an IEnumerable of variable name/value pairs, one for each variable name in this scope. If there are no names, then the enumeration is empty. Modifying the array has no impact on the ScriptScope. This method returns a new instance for the result of each call, and modifying the scope while using the enumeration has undefined behavior.

Signature:

public IEnumerable<KeyValuePair<string, object>> GetItems ()
  

4.2.8 RemoveVariable Method

This method removes the variable name and returns whether the variable existed and had a value in the scope when you called this method.

Some languages may refuse to remove some variables. If the scope has an associated language that has variables that cannot be removed, and name identifies such a variable, it is undefined what happens. Languages vary on whether this is a no-op or exceptional.

Signature:

public bool RemoveVariable(string name)
  

4.2.9 Engine Property

This property returns the engine associated with this scope. If the scope was created without a language affinity, then this property returns null.

Signature:

public ScriptEngine Engine { get;}
  

4.3 ScriptEngine Class

ScriptEngines represent a language implementation in the DLR, and they are the work horse for intermediate and advanced hosting scenarios. ScriptEngines offer various ways to execute code and create ScriptScopes and ScriptSources. ScriptSources offer methods for executing code in various ways from different kinds of sources. ScriptEngines offer the more common or convenience methods for executing code.

There is only one instance of a ScriptEngine for a given language in a given ScriptRuntime. You get to engines with ScriptRuntime's methods or the Engine property of ScriptScope.

Note, members that take or return ObjectHandles are not present on Silverlight.

4.3.1 Class Summary

public class ScriptEngine : MarshalByRefObject {
    internal ScriptEngine()
    public ScriptRuntime Runtime { get; }
    public string LanguageDisplayName { get; }
    public string[] GetRegisteredIdentifiers()
    public string[] GetRegisteredExtensions()
    public object Execute(string expression)
    public object Execute(string expression, ScriptScope scope)
    public T Execute<T>(string code)
    public T Execute<T>(string expression, ScriptScope scope)
    public ObjectHandle ExecuteAndWrap(string expression)
    public ObjectHandle ExecuteAndWrap(string expression, 
                                       ScriptScope scope)
    public ScriptScope ExecuteFile(string path)
    public ScriptScope ExecuteFile(string path, ScriptScope scope) 
    public ScriptScope GetScope(string path)
    public ObjectOperations Operations { get; }
    public ObjectOperations CreateOperations() 
    public ObjectOperations CreateOperations(ScriptScope Scope) 
    public ScriptSource CreateScriptSourceFromString
        (string expression) 
    public ScriptSource CreateScriptSourceFromString
        (string expression, string path) 
    public ScriptSource CreateScriptSourceFromString
        (string code, SourceCodeKind kind) 
    public ScriptSource CreateScriptSourceFromString
        (string code, string path, SourceCodeKind kind) 
    public ScriptSource CreateScriptSourceFromFile(string path) 
    public ScriptSource CreateScriptSourceFromFile
        (string path, System.Text.Encoding encoding) 
    public ScriptSource CreateScriptSourceFromFile
        (string path, System.Text.Encoding encoding, 
         SourceCodeKind kind) 
    public ScriptSource CreateScriptSource
        (StreamContentProvider contentProvider, string path)
    public ScriptSource CreateScriptSource
       (StreamContentProvider contentProvider, string path, 
        System.Text.Encoding encoding)
    public ScriptSource CreateScriptSource
        (StreamContentProvider contentProvider, string path, 
         System.Text.Encoding encoding, SourceCodeKind kind)
    public ScriptSource CreateScriptSource
        (TextContentProvider contentProvider, string path, 
         SourceCodeKind kind)
    public ScriptSource CreateScriptSource(CodeObject content)
    public ScriptSource CreateScriptSource(CodeObject content, 
                                           string path)
    public ScriptSource CreateScriptSource(CodeObject content,
                                           SourceCodeKind kind)
    public ScriptSource CreateScriptSource
                        (System.CodeDom.CodeObject code,
                         string path, SourceCodeKind kind)
    public ScriptScope CreateScope()
    public ScriptScope CreateScope(IDynamicMetaObjectProvider globals)
    public ServiceType GetService<ServiceType>(params object[] args) 
                                  where ServiceType : class
    public LanguageSetup Setup { get; }
    public CompilerOptions GetCompilerOptions() 
    public CompilerOptions GetCompilerOptions(ScriptScope scope) 
    public ICollection<string> GetSourceSearchPaths() 
    public void SetSearchPaths (ICollection<string> paths)
    public System.Version LanguageVersion { get; }
  

4.3.2 Runtime Property

This property returns the ScriptRuntime for the context in which this engine executes.

Signature:

public ScriptRuntime Runtime { get; }
  

4.3.3 LanguageDisplayName Property

This property returns a display name for the engine or language that is suitable for UI.

Signature:

public string LanguageDisplayName { get; }
  

4.3.4 GetRegistered\* Methods

These methods return unique identifiers for this engine and file extensions that map to this engine and its language. This information comes from configuration data passed to ScriptRuntime.Create.

Modifying the results of these methods has no effect on configuration of this engine.

Signatures:

public string[] GetRegisteredIdentifiers()
public string[] GetRegisteredExtensions()
  

4.3.5 Execute\* Methods

These methods execute the strings as expressions and return a result in various ways. There are complementary overloads that take a ScriptScope. The overloads that do not take scopes create a new scope for each execution. These methods throw the scope away and use it for side effects only, returning the result in the same way the complementary overload does.

Execute<T> returns the result as the specified type, using the engine's Operations.ConvertTo<T> method. If this method cannot convert to the specified type, then it throws a NotSupportedException.

ExecuteAndWrap returns an ObjectHandle for use when the engine and/or scope are remote.

Signatures:

public object Execute(string expression)
public object Execute(string expression, ScriptScope scope)
public T Execute<T>(string expression)
public T Execute<T>(string expression, ScriptScope scope)
public ObjectHandle ExecuteAndWrap(string expression)
public ObjectHandle ExecuteAndWrap(string expression, 
                                   ScriptScope scope)
  

4.3.6 ExecuteFile Methods

These methods execute the strings the contents of files and return the scope in which the string executed. The overload that does not take a ScriptScope creates a new one each time it is called.

Signatures:

public ScriptScope ExecuteFile(string path)
public ScriptScope ExecuteFile(string path, ScriptScope scope) 
  

4.3.7 GetScope Method

This method returns the ScriptScope in which the specified path/source executed. This method works in conjunction with LoadFile and language implementer APIs for loading dynamic language libraries (see LoadFile's side note). The path argument needs to match a ScriptSource's Path property because it is the key to finding the ScriptScope. Hosts need to make sure they create ScriptSources (see ScriptHost as well as methods on ScriptEngine) with their Path properties set appropriately (for example, resolving relative paths to canonical full pathnames, FileInfo.FullPath for standard .NET resolved paths).

GetScope is primarily useful for tools that need to map files to their execution scopes when the tool did not create the scope. For example, an editor and interpreter tool might execute a file, Foo, that imports or requires a file, Bar. The editor end user might later open the Bar and want to execute expressions in its context. The tool would need to find Bar's ScriptScope for setting the appropriate context in its interpreter window. This method helps with this scenario.

Languages may return null. For example, Ruby's require expression executes a file's contents in the calling scope. Since Ruby does not have a distinct scope in which the file executed in this case, they return null for such files.

Signature:

public ScriptScope GetScope(string path)
  

4.3.8 Operations Property

This property returns a default ObjectOperations for the engine. ObjectOperations lets you perform various operations on objects. Because an ObjectOperations object caches rules for the types of objects and operations it processes, using the default ObjectOperations for many objects could degrade the caching benefits. Eventually the cache for some operations could degrade to a point where ObjectOperations stops caching and does a full search for an implementation of the requested operation for the given objects. For simple hosting situations, this is sufficient behavior.

See CreateOperations for alternatives.

Signature:

public ObjectOperations Operations { get; }
  

4.3.9 CreateOperations Methods

These methods return a new ObjectOperations object. See the Operations property for why you might want to call this.

Signature:

public ObjectOperations CreateOperations() 
public ObjectOperations CreateOperations(ScriptScope Scope) 
  

The overload that takes a ScriptScope supports pretty advanced or subtle scenarios. It allows you to get an ObjectOperations that uses the execution context built up in a ScriptScope. For example, the engine affiliated with the scope could be IronPython, and you could execute code that did an "import clr" or "from __future__ import true_division". These change execution behaviors within that ScriptScope. If you obtained objects from that scope or executing expressions in that scope, you may want to operate on those objects with the same execution behaviors; however, you generally do not need to worry about these subtleties for typical object interactions.

4.3.10 CreateScriptSourceFromString Methods

These methods return ScriptSource objects from string contents. These are factory methods for creating ScriptSources with this language binding.

The default SourceCodeKind is AutoDetect.

The ScriptSource's Path property defaults to null. When path is non-null, if executing the resulting ScriptSource would create a ScriptScope, then path should map to the ScriptScope via GetScope.

Signatures:

public ScriptSource CreateScriptSourceFromString
    (string expression) 
public ScriptSource CreateScriptSourceFromString
    (string expression, string path) 
public ScriptSource CreateScriptSourceFromString
    (string code, SourceCodeKind kind) 
public ScriptSource CreateScriptSourceFromString
    (string code, string path, SourceCodeKind kind) 
  

4.3.11 CreateScriptSourceFromFile Methods

These methods return ScriptSource objects from file contents. These are factory methods for creating ScriptSources with this language binding. The path's extension does NOT have to be registered or valid for the engine. This method does NOT go through the PlatformAdaptationLayer to open the file; it goes directly to the file system via .NET.

The default SourceCodeKind is File.

The ScriptSource's Path property will be the path argument, which needs to be in some canonical form according to the host if the host is using GetScope to find the source's execution context later.

Creating the ScriptSource does not open the file. Any exceptions that will be thrown on opening or reading the file happen when you use the ScriptSource to execute or compile the source.

The encoding defaults to the platform encoding.

Signatures:

public ScriptSource CreateScriptSourceFromFile(string path) 
public ScriptSource CreateScriptSourceFromFile
    (string path, System.Text.Encoding encoding) 
public ScriptSource CreateScriptSourceFromFile
    (string path, System.Text.Encoding encoding, 
     SourceCodeKind kind) 
  

4.3.12 CreateScriptSource Methods

These methods returns a ScriptSource based on a CodeDom object or content providers. This is a factory method for creating a ScriptSources with this language binding.

public ScriptSource CreateScriptSource
    (StreamContentProvider contentProvider, string path)
public ScriptSource CreateScriptSource
   (StreamContentProvider contentProvider, string path, 
    System.Text.Encoding encoding)
public ScriptSource CreateScriptSource
    (StreamContentProvider contentProvider, string path, 
     System.Text.Encoding encoding, SourceCodeKind kind)
public ScriptSource CreateScriptSource
    (TextContentProvider contentProvider, string path, 
     SourceCodeKind kind)
public ScriptSource CreateScriptSource
                    (System.CodeDom.CodeObject code,
                     string path, SourceCodeKind kind)
public ScriptSource CreateScriptSource(CodeObject content)
public ScriptSource CreateScriptSource(CodeObject content, 
                                       string path)
public ScriptSource CreateScriptSource(CodeObject content,
                                       SourceCodeKind kind)
public ScriptSource CreateScriptSource
                    (System.CodeDom.CodeObject code,
                     string path, SourceCodeKind kind)
  

The method taking a TextContentProvider lets you supply input from Unicode strings or stream readers. This could be useful for implementing a TextReader over internal host data structures, such as an editor's text representation.

The method taking a StreamContentProvider lets you supply binary (sequence of bytes) stream input. This is useful when opening files that may contain language-specific encodings that are marked in the first few bytes of the file's contents. There is a default StreamContentProvider used internally if you call CreateScriptSourceFromFile. The encoding defaults to the platform encoding if the language doesn't recognize some other encoding (for example, one marked in the file's first few bytes).

The method taking a System.CodeDom.CodeObject, and the expected CodeDom support is extremely minimal for syntax-independent expression of semantics. Languages may do more, but hosts should only expect CodeMemberMethod support, and only sub nodes consisting of the following:

CodeSnippetStatement
CodeSnippetExpression
CodePrimitiveExpression
CodeMethodInvokeExpression
CodeExpressionStatement (for holding MethodInvoke)

This support exists primarily for ASP.NET pages that contain snippets of DLR languages, and these requirements were very limited. When the CodeObject argument does not match this specification, you will get a type cast error, but if the language supports more options, you could get different errors per engine.

The path argument in all cases is a unique ID that the host may use to retrieve the scope in which the source executes via Engine.GetScope.

4.3.13 CreateScope Method

This method returns a new ScriptScope with this engine as the default language for the scope.

Signatures:

public ScriptScope CreateScope()
public ScriptScope CreateScope(IDynamicMetaObjectProvider globals)
  

The globals parameter lets you supply the dictionary of the scope so that you can provide late bound values for some name lookups. The easiest way to supply your own dictionary is to use ExpandoObject or derive from DynamicObject .

4.3.14 GetService Method

This method returns a language-specific service. It provides a point of extensibility for a language implementation to offer more functionality than the standard engine members discussed here. If the specified service is not available, this returns null.

Signature:

public ServiceType GetService<ServiceType>(params object[] args) 
                              where ServiceType : class
  

The following are services expected to be supported:

`ExceptionOperations`	This duplicates some members of Exception and can return a string in the style of this engine's language to describe the exception argument.
`TokenCategorizer`	This is for building tools that want to scan languages and get token info, such as colorization categories. This type will change and be spec'ed external to this document eventually, see the section below for this type.
`OptionsParser`	This can parse a command shell (cmd.exe) style command line string. Hosts that are trying to be an interactive console or incorporate standard command line switches of a language's console can get the engine's command line parser. This is a place holder for DLR v2. Its design will definitely change. We have a big open issue to redesign language and DLR support for building interactive UI, interpreters, tools, etc., with some common support around command lines and consoles.
`CommandLine`	is a helper object for parsing and processing interactive console input, maintaining a history of input, etc. This is a place holder for DLR v2. Its design will definitely change. We have a big open issue to redesign language and DLR support for building interactive UI, interpreters, tools, etc., with some common support around command lines and consoles.
`ScriptConsole`	This is a helper object for the UI of an interpreter, how output is displayed and how we get input. If the language does not implement a ScriptConsole, there is a default Console object they can return. This is a place holder for DLR v2. Its design will definitely change. We have a big open issue to redesign language and DLR support for building interactive UI, interpreters, tools, etc., with some common support around command lines and consoles. Need to distinguish this and CommandLine.

4.3.15 Setup Property

This property returns a read-only LanguageSetup describing the configuration used to instantiate this engine.

Signature:

public LanguageSetup Setup { get; }
  

4.3.16 GetCompilerOptions Method

This method returns the compiler options object for the engine's language. The overload that takes a ScriptScope returns options that represent any accrued imperative options state from the scope (for example, "from futures import truedivision" in python). To operate on the options before passing them to ScriptSource.Compile, for example, you may need to cast the result to the documented subtype of CompilerOptions for the language you're manipulating.

If scope is null, this throws an ArgumentNullException.

Signatures:

public CompilerOptions GetCompilerOptions() 
public CompilerOptions GetCompilerOptions(ScriptScope scope) 
  

CompilerOptions type will likely change by the time the DLR Hosting APIs move into the .NET libraries, possibly becoming Dictionary<str,obj>.

4.3.17 GetSearchPaths Method

This method returns the search paths used by the engine for loading files when a script wants to import or require another file of code. These are also the paths used by ScriptRuntime.UseFile.

These paths do not affect ScriptRuntime.ExecuteFile. The ScriptHost's PlatformAdaptationLayer (or the default's direct use of .NET file APIs) controls partial file name resolution for ExecuteFile.

Signature:

public ICollection<string> GetSearchPaths () 
  

4.3.18 SetSearchPaths Method

This method sets the search paths used by the engine for loading files when a script wants to import or require another file of code. Setting these paths affects ScriptRuntime.UseFile.

These paths do not affect ScriptRuntime.ExecuteFile. The ScriptHost's PlatformAdaptationLayer (or the default's direct use of .NET file APIs) controls partial file name resolution for ExecuteFile.

Signature:

public void SetSearchPaths (ICollection<string> paths)
  

4.3.19 LanguageVersion Property

This property returns the language's version.

Signature:

public System.Version LanguageVersion { get; }
  

4.4 ScriptSource Class

ScriptSource represents source code and offer 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. The associated engine provides the execution and compilation semantics for the source.

ScriptSources have properties that direct the parsing of and report aspects of the source. For example, the source could be marked as being an expression or a statement, for language that need to distinguish expressions and statements semantically for how to parse them. The code could be marked as being interactive, which means the language's parser should handle standard interpreter affordances the language might support (for example, Python's "_" variable or VB's "?" syntax).

ScriptSources also have a Path property. This is mostly useful for those marked as being a file. The Path is the key for engines recognizing ScriptSources they have seen before so that they do not repeatedly load files when load-once semantics should apply (see ScriptEngine.LoadFile). The Path also helps the engine find the ScriptScope the file executed in (see ScriptEngine.GetScope), which is useful for some tool host scenarios. The host defines what a canonical representation of a path is. The host needs to set the path to the same string when it intends for ScriptSources to match for the purposes of the above functions on ScriptEngine.

You can create ScriptSource objects with factory methods on ScriptEngine.

Note, members that take or return ObjectHandles are not present on Silverlight.

4.4.1 Class Summary

public sealed class ScriptSource : MarshalByRefObject {
  internal ScriptSource()
  public string Path { get; }
  public SourceCodeKind Kind { get;}
  public ScriptCodeParseResult GetCodeProperties () 
  public ScriptCodeParseResult GetCodeProperties 
                               (CompilerOptions options) 
  public ScriptEngine Engine { get; }
  public CompiledCode Compile()
  public CompiledCode Compile(ErrorListener sink)
  public CompiledCode Compile(CompilerOptions options)
  public CompiledCode Compile(CompilerOptions options, 
                              ErrorListener sink)
  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)
  public int ExecuteProgram()
  public ScriptCodeReader GetReader() 
  public Encoding DetectEncoding() 
  // line/file mapping:
  public string GetCode() 
  public string GetCodeLine(int line) 
  public string[] GetCodeLines(int start, int count) 
  public SourceSpan MapLine(SourceSpan span) 
  public SourceLocation MapLine(SourceLocation loc) 
  public int MapLine(int line) 
  public string MapLineToFile(int line) 
  

4.4.2 Path Property

This property returns the identifier for this script source. In many cases the Path doesn't matter. It is mostly useful for file ScriptSources. The Path is the key for engines to recognize ScriptSources they have seen before so that they do not repeatedly load files when load-once semantics should apply. The Path also helps the engine find the ScriptScope the file executed in, which is useful for some tool host scenarios (see ScriptEngine.GetScope).

The Path is null if not set explicitly on construction. The path has the value the ScriptSource was created with. In the case of relative file paths, for example, the DLR does not convert them to absolute or canonical representations.

Signature:

public string Path { get; }
  

4.4.3 Kind Property

This property returns the kind of source this ScriptSource represents. This property is a hint to the ScriptEngine how to parse the code ScriptSource (as an expression, statement, whole file, etc.).

If you're unsure, File can be used to direct the language to generally parse the code. For languages that are expression-based, they should interpret Statement as Expression.

Signature:

public SourceCodeKind Kind { get;}
  

4.4.4 GetCodeProperties Methods

This method returns the properties of the code to support tools. The values indicate the state of parsing the source relative to completeness, or whether the source is complete enough to execute.

Signature:

public ScriptCodeParseResult GetCodeProperties () 
public ScriptCodeParseResult GetCodeProperties 
                             (CompilerOptions options) 
  

CompilerOptions type will likely change by the time the DLR Hosting APIs move into the .NET libraries, possibly becoming Dictionary<str,obj>.

4.4.5 Engine Property

This property returns the language engine associated with this ScriptSource. There is always a language tied to the source for convenience. Also, we do not think it is useful to support having a piece of code that could perhaps be parsed by multiple languages.

Signature:

public ScriptEngine Engine { get; }
  

4.4.6 Compile Methods

These methods compile the source and return a CompileCode object that can be executed repeatedly in its default scope or in other scopes without having to recompile the code.

Each call to Compile returns a new CompiledCode object. Each call to Compile always calls on its content provider to get sources, and the default file content provider always re-opens the file and reads its contents.

Signatures

    public CompiledCode Compile()
    public CompiledCode Compile(ErrorListener sink)
    public CompiledCode Compile(CompilerOptions options)
    public CompiledCode Compile(CompilerOptions options, 
                                ErrorListener sink)
  

If any arguments are null, these throw ArgumentNullExceptions.

If you supply an error listener, and there were errors, these methods return null. Otherwise, it leaves any raised exceptions unhandled.

These methods do not take a ScriptScope to compile against. That would prevent compilation from choosing optimized scope implementations. You can always execute compiled code against any scope (see Execute* methods).

CompilerOptions type will likely change by the time the DLR Hosting APIs move into the .NET libraries, possibly becoming Dictionary<str,obj>.

4.4.7 Execute\* Methods

These methods execute the source code and return a result in various ways. There are complementary overloads that take a ScriptScope and those that do not. The overloads with no arguments create a new scope for each execution. These methods throw the scope away and use it for side effects only, returning the result in the same way the complementary overload does.

These methods always execute the ScriptSource. Even when the source is a file, and the associated engine's language has an execute-at-most-once mechanism, these methods always execute the source contents.

Each call to Execute always calls on its content provider to get sources, and the default file content provider always re-opens the file and reads its contents.

Signatures:

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)
public int ExecuteProgram()
  

Execute returns an object that is the resulting value of running the code. When the ScriptSource is a file or statement, the language decides what is an appropriate value to return. Some languages return the value produced by the last expression or statement, but languages that are not expression based may return null.

ExecuteAndWrap returns an ObjectHandle for use when the engine and/or scope are remote.

Execute<T> returns the result as the specified type, using the associated engine's Operations.ConvertTo<T> method. If this method cannot convert to the specified type, then it throws an exception.

ExecuteProgram runs the source as though it were launched from an OS command shell and returns a process exit code indicating the success or error condition of executing the code. Each time this method is called it creates a fresh ScriptScope in which to run the source, and if you were to use ScriptEngine.GetScope, you'd get whatever last ScriptScope the engine created for the source.

4.4.8 GetReader Method

This method returns a derived type of TextReader that is bound to this ScriptSource. Every time you call this method you get a new ScriptCodeReader reset to beginning parsing state, and no two instances interfere with each other.

Signature:

public ScriptCodeReader GetReader() 
  

4.4.9 DetectEncoding Method

This method returns the encoding for the source. The language associated with the source has the chance to read the beginning of the file if it has any special handling for encodings based on the first few bytes of the file. This method could return an encoding different than what the source was created with.

Signature:

public Encoding DetectEncoding() 
  

4.4.10 GetCode Method

This method returns all the source code contents as a string. The result may share storage with the string passed to create the ScriptSource.

Each call to GetCode always calls on its content provider to get sources, and the default file content provider always re-opens the file and reads its contents.

Signature:

public string GetCode() 
  

4.4.11 GetCodeLine\* Methods

These methods return a string (or strings) for the line (or lines) indexed. Count is one-based. The count argument can be greater than the number of lines. The start argument cannot be zero or negative.

The line and count arguments can cause indexing to go beyond the end of the source. GetCodeLine returns null in that case. GetCodeLines returns strings only for existing lines and does not throw an exception or include nulls in the array. If start is beyond the end, the result is an empty array.

Signatures:

public string GetCodeLine(int line) 
public string[] GetCodeLines(int start, int count) 
  

4.4.12 MapLine Methods

These methods map physical line numbers to virtual line numbers for reporting errors or other information to users. These are useful for languages that support line number directives for their parsers and error reporting.

Signatures:

public SourceSpan MapLine(SourceSpan span) 
public SourceLocation MapLine(SourceLocation loc) 
public int MapLine(int line) 
  

4.4.13 MapLineToFile Method

This method maps a physical line number to a .NET CLR pdb or file with symbol information in it. The result is an absolute path or relative path that resolves in a standard .NET way to the appropriate file.

Signature:

public string MapLineToFile(int line) 
  

4.5 CompiledCode Class

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. The default scope may have optimized variable storage and lookup for the code. You can always 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.

You can get CompiledCode from Compile methods on ScriptSource. CompiledCode objects have an internal reference to the engine that produced them. Because they have a default scope in which to execute, and the use for CompiledCode objects is to execute them, they have several execute methods.

Note, members that take or return ObjectHandles are not present on Silverlight.

4.5.1 Class Summary

public class CompiledCode : MarshalByRefObject {
    internal CompiledCode()
    public ScriptScope DefaultScope { get; }
    public ScriptEngine Engine { get; }
    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) 
  

4.5.2 DefaultScope Property

This property returns the default ScriptScope in which the code executes. This allows you to extract variable values after executing the code or insert variable bindings before executing the code.

Signature:

public ScriptScope DefaultScope { get; }
  

4.5.3 Engine Property

This property returns the engine that produced the compiled code.

Signature:

public ScriptEngine Engine { get; }
  

4.5.4 Execute\* Methods

These methods execute the compiled code in a variety of ways. Half of the overloads do the same thing as their complement, one executes in the default scope while the other takes a ScriptScope in which to execute the code. If invoked on null, this throws an ArgumentNullException.

Signatures:

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) 
  

ExecuteAndWrap returns an ObjectHandle for use when the engine and/or scope are remote.

Execute<T> returns the result as the specified type, using the engine's Operations.ConvertTo<T> method. If this method cannot convert to the specified type, then it throws an exception.

4.6 ObjectOperations Class

This utility class provides operations on objects. The operations work on objects emanating from a ScriptRuntime or straight up .NET static objects. The behaviors of this class are language-specific, depending on which language owns the instance you're using.

You get ObjectOperations objects from ScriptEngines. The operations have a language-specific behavior determined by the engine from which you got the ObjectOperations object. For example, calling GetMember on most objects to get the "__dict__" member using an ObjectOperations obtained from an IronPython ScriptEngine will return the object's dictionary of members. However, using an ObjectOperations obtained from an IronRuby engine, would raise a member missing exception.

The reason ObjectOperations is a utility class that is not static is that the instances provide a context of caching for performing the operations. If you were to perform several operations over and over on the same few objects, it would be advantageous to create a special ObjectOperations just for use with those few objects. If you perform different operations with many objects just once or twice, you can use the default instance provided by the ScriptEngine.

Half of the methods do the same thing as their complement, one works with objects of type Object while the other works with ObjectHandles. We need the overloads for clear method selection and to allow for an ObjectHandle to be treated as Object should that be interesting.

You obtain ObjectOperation objects from ScriptEngines' Operations property and CreateOperations method.

Note, members that take or return ObjectHandles are not present on Silverlight.

4.6.1 Class Summary

public sealed class ObjectOperations : MarshalByRefObject {
    public ScriptEngine Engine { get; }
    public ObjectHandle Add(ObjectHandle self, ObjectHandle other)
    public Object Add(Object self, Object other)
    public Object BitwiseAnd(Object self, Object other)
    public ObjectHandle BitwiseAnd(ObjectHandle self,
                                   ObjectHandle other)
    public ObjectHandle BitwiseOr(ObjectHandle self,
                                  ObjectHandle other)
    public Object BitwiseOr(Object self, Object other)
    public Boolean ContainsMember(ObjectHandle obj, String name)
    public Boolean ContainsMember(Object obj, String name,
                                  Boolean ignoreCase)
    public Boolean ContainsMember(Object obj, String name)
    public T ConvertTo<T>(Object obj)
    public ObjectHandle ConvertTo<T>(ObjectHandle obj)
    public Object ConvertTo(Object obj, Type type)
    public ObjectHandle ConvertTo(ObjectHandle obj, Type type)
    public ObjectHandle CreateInstance(ObjectHandle obj,
                                      params ObjectHandle[] parameters)
    public ObjectHandle CreateInstance(ObjectHandle obj,
                                       params Object[] parameters)
    public Object CreateInstance(Object obj,
                                 params Object[] parameters)
    public Object Divide(Object self, Object other)
    public ObjectHandle Divide(ObjectHandle self,
                               ObjectHandle other)
    public Object DoOperation(ExpressionType operation,
                              Object target)
    public TResult DoOperation<TTarget, TResult>
       (ExpressionType operation, TTarget target)
    public Object DoOperation
       (ExpressionType operation, Object target, Object other)
    public TResult DoOperation<TTarget, TOther, TResult>
       (ExpressionType operation, TTarget target, TOther other)
    public Object DoOperation(ExpressionType op,
                              ObjectHandle target)
    public ObjectHandle DoOperation
       (ExpressionType op, ObjectHandle target, ObjectHandle other)
    public Boolean Equal(Object self, Object other)
    public Boolean Equal(ObjectHandle self, ObjectHandle other)
    public Object ExclusiveOr(Object self, Object other)
    public ObjectHandle ExclusiveOr(ObjectHandle self,
                                    ObjectHandle other)
    public T ExplicitConvertTo<T>(Object obj)
    public Object ExplicitConvertTo(Object obj, Type type)
    public ObjectHandle ExplicitConvertTo(ObjectHandle obj, Type type)
    public ObjectHandle ExplicitConvertTo<T>(ObjectHandle obj)
    public T ImplicitConvertTo<T>(Object obj)
    public Object ImplicitConvertTo(Object obj, Type type)
    public ObjectHandle ImplicitConvertTo(ObjectHandle obj, Type type)
    public ObjectHandle ImplicitConvertTo<T>(ObjectHandle obj)
    public String Format(Object obj)
    public String Format(ObjectHandle obj)
    public IList<System.String> GetCallSignatures(ObjectHandle obj)
    public IList<System.String> GetCallSignatures(Object obj)
    public String GetDocumentation(Object obj)
    public String GetDocumentation(ObjectHandle obj)
    public T GetMember<T>(ObjectHandle obj, String name)
    public T GetMember<T>(Object obj, String name, Boolean ignoreCase)
    public Object GetMember(Object obj, String name)
    public Object GetMember(Object obj, String name,
                            Boolean ignoreCase)
    public ObjectHandle GetMember(ObjectHandle obj, String name)
    public T GetMember<T>(Object obj, String name)
    public IList<System.String> GetMemberNames(ObjectHandle obj)
    public IList<System.String> GetMemberNames(Object obj)
    public Boolean GreaterThan(Object self, Object other)
    public Boolean GreaterThan(ObjectHandle self, ObjectHandle other)
    public Boolean GreaterThanOrEqual(Object self, Object other)
    public Boolean GreaterThanOrEqual(ObjectHandle self,
                                      ObjectHandle other)
    public ObjectHandle Invoke(ObjectHandle obj,
                               params ObjectHandle[] parameters)
    public ObjectHandle Invoke(ObjectHandle obj,
                               params Object[] parameters)
    public Object Invoke(Object obj, params Object[] parameters)
    public Object InvokeMember(Object obj, String memberName,
                               params Object[] parameters)
    public Boolean IsCallable(Object obj)
    public Boolean IsCallable(ObjectHandle obj)
    public ObjectHandle LeftShift(ObjectHandle self,
                                  ObjectHandle other)
    public Object LeftShift(Object self, Object other)
    public Boolean LessThan(Object self, Object other)
    public Boolean LessThan(ObjectHandle self, ObjectHandle other)
    public Boolean LessThanOrEqual(ObjectHandle self,
                                   ObjectHandle other)
    public Boolean LessThanOrEqual(Object self, Object other)
    public ObjectHandle Modulo(ObjectHandle self, ObjectHandle other)
    public Object Modulo(Object self, Object other)
    public ObjectHandle Multiply(ObjectHandle self, ObjectHandle other)
    public Object Multiply(Object self, Object other)
    public Boolean NotEqual(Object self, Object other)
    public Boolean NotEqual(ObjectHandle self, ObjectHandle other)
    public Object Power(Object self, Object other)
    public ObjectHandle Power(ObjectHandle self, ObjectHandle other)
    public Boolean RemoveMember(Object obj, String name)
    public Boolean RemoveMember(ObjectHandle obj, String name)
    public Boolean RemoveMember(Object obj, String name,
                                Boolean ignoreCase)
    public ObjectHandle RightShift(ObjectHandle self,
                                   ObjectHandle other)
    public Object RightShift(Object self, Object other)
    public void SetMember(Object obj, String name, Object value,
                          Boolean ignoreCase)
    public void SetMember(ObjectHandle obj, String name,
                          ObjectHandle value)
    public void SetMember<T>(Object obj, String name, T value,
                             Boolean ignoreCase)
    public void SetMember<T>(Object obj, String name, T value)
    public void SetMember<T>(ObjectHandle obj, String name, T value)
    public void SetMember(Object obj, String name, Object value)
    public ObjectHandle Subtract(ObjectHandle self, ObjectHandle other)
    public Object Subtract(Object self, Object other)
    public Boolean TryConvertTo<T>(ObjectHandle obj,
                                   out ObjectHandle result)
    public Boolean TryConvertTo(Object obj, Type type,
                                out Object result)
    public Boolean TryConvertTo<T>(Object obj, out T result)
    public Boolean TryConvertTo(ObjectHandle obj, Type type,
                                out ObjectHandle result)
    public Boolean TryExplicitConvertTo<T>(Object obj, out T result)
    public Boolean TryExplicitConvertTo<T>(ObjectHandle obj,
                                           out ObjectHandle result)
    public Boolean TryExplicitConvertTo(ObjectHandle obj, Type type,
                                        out ObjectHandle result)
    public Boolean TryExplicitConvertTo(Object obj, Type type,
                                        out Object result)
    public Boolean TryImplicitConvertTo<T>(Object obj, out T result)
    public Boolean TryImplicitConvertTo<T>(ObjectHandle obj,
                                           out ObjectHandle result)
    public Boolean TryImplicitConvertTo(ObjectHandle obj, Type type,
                                        out ObjectHandle result)
    public Boolean TryImplicitConvertTo(Object obj, Type type,
                                        out Object result)
    public Boolean TryGetMember(Object obj, String name,
                                Boolean ignoreCase, out Object value)
    public Boolean TryGetMember(ObjectHandle obj, String name,
                                out ObjectHandle value)
    public Boolean TryGetMember(Object obj, String name,
                                out Object value)
    public T Unwrap<T>(ObjectHandle obj)
  

4.6.2 Engine Property

This property returns the engine bound to this ObjectOperations. The engine binding provides the language context or semantics applied to each requested operation.

Signature:

public ScriptEngine Engine { get; }
  

4.6.3 IsCallable Methods

These methods returns whether the object is callable. Languages should return delegates when fetching the value of variables or executing expressions that result in callable objects. However, sometimes you'll get objects that are callable, but they are not wrapped in a delegate. Note, even if this method returns true, a call may fail due to incorrect number of arguments or incorrect types of arguments.

Signatures:

public bool IsCallable(object obj)
public bool IsCallable(ObjectHandle obj)
  

4.6.4 Invoke Methods

These methods invoke objects that are callable. In general you should not need to call these methods. Languages should return delegates when fetching the value of variables or executing expressions that result in callable objects. However, sometimes you'll get objects that are callable, but they are not wrapped in a delegate. If you're calling an object multiple times, you can use ConvertTo to get a strongly typed delegate that you can call more efficiently. You'll also need to use Invoke for objects that are remote.

If any obj arguments are null, then these throw an ArgumentNullException.

Signatures:

public ObjectHandle Invoke(ObjectHandle obj,
                           params ObjectHandle[] parameters)
public ObjectHandle Invoke(ObjectHandle obj,
                           params Object[] parameters)
public Object Invoke(Object obj, params Object[] parameters)
  

4.6.5 InvokeMember Method

This method invokes callable members from objects.

If the obj argument is null, then this throws an ArgumentNullException.

Signatures:

public Object InvokeMember(Object obj, String memberName,
                           params Object[] parameters)
  

4.6.6 CreateInstance Methods

These methods create objects when the input object can be instantiated.

If any obj arguments are null, then these throw an ArgumentNullException.

Signatures:

public ObjectHandle CreateInstance(ObjectHandle obj,
                                  params ObjectHandle[] parameters)
public ObjectHandle CreateInstance(ObjectHandle obj,
                                   params Object[] parameters)
public Object CreateInstance(Object obj,
                             params Object[] parameters)
  

4.6.7 GetMember\* Methods

These methods return a named member of an object.

The generic overloads do not modify obj to convert to the requested type. If they cannot perform the requested conversion to the concrete type, then they throw a NotSupportedException. You can use Unwrap<T> after ConvertTo<T> on ObjectHandle to get a local T for the result. The generic overloads use language-specific conversions (based on the default language in the Engine property), like ConvertTo<T>.

If the specified member does not exist, or if it is write-only, then these throw exceptions.

Signatures:

public T GetMember<T>(ObjectHandle obj, String name)
public T GetMember<T>(Object obj, String name, Boolean ignoreCase)
public Object GetMember(Object obj, String name)
public Object GetMember(Object obj, String name,
                        Boolean ignoreCase)
public ObjectHandle GetMember(ObjectHandle obj, String name)
public T GetMember<T>(Object obj, String name)
  

4.6.8 TryGetMember Methods

These methods try to get a named member of an object. They return whether name was a member of obj and set the out value to name's value. If the name was not a member of obj, then this method sets value to null.

If obj or name is null, then these throw an ArgumentNullException.

Signatures:

public Boolean TryGetMember(Object obj, String name,
                            Boolean ignoreCase, out Object value)
public Boolean TryGetMember(ObjectHandle obj, String name,
                            out ObjectHandle value)
public Boolean TryGetMember(Object obj, String name,
                            out Object value)
  

4.6.9 ContainsMember Methods

These methods return whether the name is a member of obj.

Signatures:

public Boolean ContainsMember(ObjectHandle obj, String name)
public Boolean ContainsMember(Object obj, String name,
                              Boolean ignoreCase)
public Boolean ContainsMember(Object obj, String name)
  

4.6.10 RemoveMember Methods

These methods remove name from obj so that it is no longer a member of obj. If the object or the language binding of this ObjectOperations allows read-only or non-removable members, and name identifies such a member, then it is undefined what happens. Languages vary on whether this is a no-op or exceptional.

If any arguments are null, then these throw an ArgumentNullException.

Signatures:

public Boolean RemoveMember(Object obj, String name)
public Boolean RemoveMember(ObjectHandle obj, String name)
public Boolean RemoveMember(Object obj, String name,
                            Boolean ignoreCase)
  

4.6.11 SetMember Methods

These members set the value of a named member of an object. There are generic overloads that can be used to avoid boxing values and casting of strongly typed members.

If the object or the language binding of this ObjectOperations supports read-only members, and name identifies such a member, then these methods throw a NotSupportedException.

If any arguments are null, then these throw an ArgumentNullException.

Signatures:

public void SetMember(Object obj, String name, Object value,
                      Boolean ignoreCase)
public void SetMember(ObjectHandle obj, String name,
                      ObjectHandle value)
public void SetMember<T>(Object obj, String name, T value,
                         Boolean ignoreCase)
public void SetMember<T>(Object obj, String name, T value)
public void SetMember<T>(ObjectHandle obj, String name, T value)
public void SetMember(Object obj, String name, Object value)
  

4.6.12 ConvertTo\* Methods

These methods convert an object to the requested type using language-specific (based on the default language in the Engine property) conversions. These may be implicit only, or include explicit conversion too. The conversions do not modify obj. Obj may be returned if it is already the requested type. You can use Unwrap<T> after ConvertTo<T> on ObjectHandle to get a local T for the result.

If any of the arguments is null, then these throw an ArgumentNullException.

If these methods cannot perform the requested conversion, then they throw a NotSupportedException.

Signatures:

public T ConvertTo<T>(Object obj)
public ObjectHandle ConvertTo<T>(ObjectHandle obj)
public Object ConvertTo(Object obj, Type type)
public ObjectHandle ConvertTo(ObjectHandle obj, Type type)
  

4.6.13 TryConvertTo\* Methods

These methods try to convert an object to the requested type language-specific (based on the default language in the Engine property) conversions. These may be implicit only, or include explicit conversion too. The conversions do not modify obj. They return whether they could perform the conversion and set the out result parameter. If the methods could not perform the conversion, then they set result to null.

You can use Unwrap<T> after calling overloads on ObjectHandle to get a local T for the result.

If they cannot perform the conversion to the requested type, then they throw a NotSupportedException.

If obj is null, then these throw an ArgumentNullException.

Signatures:

public Boolean TryConvertTo<T>(ObjectHandle obj,
                               out ObjectHandle result)
public Boolean TryConvertTo(Object obj, Type type,
                            out Object result)
public Boolean TryConvertTo<T>(Object obj, out T result)
public Boolean TryConvertTo(ObjectHandle obj, Type type,
                            out ObjectHandle result)
  

4.6.14 ExplicitConvertTo\* Methods

These methods convert an object to the requested type using explicit conversions, which may be lossy. Otherwise these methods are the same as the ConvertTo* methods.

public T ExplicitConvertTo<T>(Object obj)
public Object ExplicitConvertTo(Object obj, Type type)
public ObjectHandle ExplicitConvertTo(ObjectHandle obj, Type type)
public ObjectHandle ExplicitConvertTo<T>(ObjectHandle obj)
  

4.6.15 TryExplicitConvertTo\* Methods

These methods try to convert an object to the request type using explicit conversions, which may be lossy. Otherwise these methods are the same as TryConvertTo* methods.

public Boolean TryExplicitConvertTo<T>(Object obj, out T result)
public Boolean TryExplicitConvertTo<T>(ObjectHandle obj,
                                       out ObjectHandle result)
public Boolean TryExplicitConvertTo(ObjectHandle obj, Type type,
                                    out ObjectHandle result)
public Boolean TryExplicitConvertTo(Object obj, Type type,
                                    out Object result)
  

4.6.16 ImplicitConvertTo\* Methods

These methods convert an object to the requested type using implicit conversions, which may be lossy. Otherwise these methods are the same as the ConvertTo* methods.

public T ImplicitConvertTo<T>(Object obj)
public Object ImplicitConvertTo(Object obj, Type type)
public ObjectHandle ImplicitConvertTo(ObjectHandle obj, Type type)
public ObjectHandle ImplicitConvertTo<T>(ObjectHandle obj)
  

4.6.17 TryimplicitConvertTo\* Methods

These methods try to convert an object to the request type using implicit conversions, which may be lossy. Otherwise these methods are the same as TryConvertTo* methods.

public Boolean TryImplicitConvertTo<T>(Object obj, out T result)
public Boolean TryImplicitConvertTo<T>(ObjectHandle obj,
                                       out ObjectHandle result)
public Boolean TryImplicitConvertTo(ObjectHandle obj, Type type,
                                    out ObjectHandle result)
public Boolean TryImplicitConvertTo(Object obj, Type type,
                                    out Object result)
  

4.6.18 Unwrap\<T\> Method

This method unwraps the remote object reference, converting it to the specified type before returning it. If this method cannot perform the requested conversion to the concrete type, then it throws a NotSupportedException. If the requested T does not serialize back to the calling app domain, the CLR throws an exception.

Signature:

public T Unwrap<T>(ObjectHandle obj) 
  

4.6.19 Format Methods

These methods return a string representation of obj that is parse-able by the language. ConvertTo operations that request a string return a display string for the object that is not necessarily parse-able as input for evaluation.

Signatures:

public string Format(object obj) 
public string Format(ObjectHandle obj) 
  

4.6.20 GetMemberNames Methods

These methods return an array of all the member names that obj has explicitly, determined by the language associated with this ObjectOperations. Computed or late bound member names may not be in the result.

Signatures:

public IList<string> GetMemberNames(object obj) 
public IList<string> GetMemberNames(ObjectHandle obj) 
  

4.6.21 GetDocumentation Methods

These methods return the documentation for obj. When obj is a static .NET object, this returns xml documentation comment information associated with the DLL containing obj's type. If there is no available documentation for the object, these return the empty string. Some languages do not have documentation hooks for objects, in which case they return the empty string.

Signatures:

public string GetDocumentation(object obj)
public string GetDocumentation(ObjectHandle obj)
  

4.6.22 GetCallSignatures Methods

These methods return arrays of stings, each one describing a call signature that obj supports. If the object is not callable, these throw a NotSupportedException.

Signatures:

public IList<string> GetCallSignatures(object obj)
public IList<string> GetCallSignatures(ObjectHandle obj)
  

4.6.23 DoOperation\* Methods

These methods perform the specified unary and binary operations on the supplied target and other objects, returning the results. If the specified operator cannot be performed on the object or objects supplied, then these throw an exception. See the Expression Tree spec for information on the expected semantics of the operators.

The Hosting APIs share the ExpressionType enum with Expression Trees and the dynamic object interop protocol to specify what operation to perform. Most values overlap making a distinct enum just another concept to learn, but this enum contains values for operations used in Expression Trees that do not make sense when passed to this method (for example, Block, Try, and Throw). These methods pass the operation to the language that created the ObjectOperations object, and the language handles the ExpressionType as it sees fit. For example, IronPython only supports the following ExpressionType values:

Add	Subtract	SubtractAssign
And	AddAssign	Equal
Divide	AndAssign	GreaterThan
ExclusiveOr	DivideAssign	GreaterThanOrEqual
Modulo	ExclusiveOrAssign	LessThan
Multiply	MultiplyAssign	LessThanOrEqual
Or	OrAssign	NotEqual
Power	PowerAssign
RightShift	RightShfitAssign
LeftShift	LeftShiftAssign

Signatures:

public Object DoOperation(ExpressionType operation,
                          Object target)
public TResult DoOperation<TTarget, TResult>
   (ExpressionType operation, TTarget target)
public Object DoOperation
   (ExpressionType operation, Object target, Object other)
public TResult DoOperation<TTarget, TOther, TResult>
   (ExpressionType operation, TTarget target, TOther other)
public Object DoOperation(ExpressionType op,
                          ObjectHandle target)
public ObjectHandle DoOperation
   (ExpressionType op, ObjectHandle target, ObjectHandle other)
  