// Copyright (c) Microsoft Corporation. All rights reserved.

// Licensed under the MIT license.

using System;

using System.Collections;

using System.Collections.Generic;

using System.Linq;

using System.Reflection;

using System.Runtime.CompilerServices;

using Microsoft.ClearScript.Util;

namespace Microsoft.ClearScript

{

/// <summary>

/// Provides the base implementation for all script engines.

/// </summary>

public abstract class ScriptEngine : IDisposable

{

#region data

private readonly string name;

private Type accessContext;

private ScriptAccess defaultAccess;

private bool enforceAnonymousTypeAccess;

private bool exposeHostObjectStaticMembers;

private object undefinedImportValue = Undefined.Value;

private DocumentSettings documentSettings;

private readonly DocumentSettings defaultDocumentSettings = new DocumentSettings();

private static readonly IUniqueNameManager nameManager = new UniqueNameManager();

private static readonly object nullHostObjectProxy = new object();

[ThreadStatic] private static ScriptEngine currentEngine;

#endregion

#region constructors

/// <summary>

/// Initializes a new script engine instance.

/// </summary>

/// <param name="name">A name to associate with the instance. Currently this name is used only as a label in presentation contexts such as debugger user interfaces.</param>

[Obsolete("Use ScriptEngine(string name, string fileNameExtensions) instead.")]

protected ScriptEngine(string name)

: this(name, null)

{

}

/// <summary>

/// Initializes a new script engine instance with the specified list of supported file name extensions.

/// </summary>

/// <param name="name">A name to associate with the instance. Currently this name is used only as a label in presentation contexts such as debugger user interfaces.</param>

/// <param name="fileNameExtensions">A semicolon-delimited list of supported file name extensions.</param>

protected ScriptEngine(string name, string fileNameExtensions)

{

this.name = nameManager.GetUniqueName(name, GetType().GetRootName());

defaultDocumentSettings.FileNameExtensions = fileNameExtensions;

}

#endregion

#region public members

/// <summary>

/// Gets the name associated with the script engine instance.

/// </summary>

public string Name

{

get { return name; }

}

/// <summary>

/// Gets the script engine that is invoking a host member on the current thread.

/// </summary>

/// <remarks>

/// If multiple script engines are invoking host members on the current thread, this

/// property gets the one responsible for the most deeply nested invocation. If no script

/// engines are invoking host members on the current thread, this property returns

/// <c>null</c>.

/// </remarks>

public static ScriptEngine Current

{

get { return currentEngine; }

}

/// <summary>

/// Gets the script engine's recommended file name extension for script files.

/// </summary>

public abstract string FileNameExtension { get; }

/// <summary>

/// Allows script code to access non-public host resources.

/// </summary>

/// <remarks>

/// By setting this property to a type you declare that script code running in the current

/// script engine is to be treated as if it were part of that type's implementation. Doing

/// so does not expose any host resources to script code, but it affects which host

/// resources are importable and which members of exposed resources are accessible.

/// </remarks>

public Type AccessContext

{

get { return accessContext; }

set

{

accessContext = value;

OnAccessSettingsChanged();

}

}

/// <summary>

/// Gets or sets the default script access setting for all members of exposed objects.

/// </summary>

/// <remarks>

/// Use <see cref="DefaultScriptUsageAttribute"/>, <see cref="ScriptUsageAttribute"/>, or

/// their subclasses to override this property for individual types and members. Note that

/// this property has no effect on the method binding algorithm. If a script-based call is

/// bound to a method that is blocked by this property, it will be rejected even if an

/// overload exists that could receive the call.

/// </remarks>

public ScriptAccess DefaultAccess

{

get { return defaultAccess; }

set

{

defaultAccess = value;

OnAccessSettingsChanged();

}

}

/// <summary>

/// Enables or disables access restrictions for anonymous types.

/// </summary>

/// <remarks>

/// Anonymous types are

/// <see href="https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/keywords/internal">internal</see>

/// and therefore accessible only within the same assembly, but ClearScript 5.5.3 and

/// earlier permitted access to the public properties of an object even if its type was

/// internal. Newer versions strictly enforce <see cref="AccessContext"/>, but because

/// anonymous types are particularly useful for scripting, ClearScript by default continues

/// to expose their properties to external contexts. To override this behavior and enable

/// normal access restrictions for anonymous types, set this property to <c>true</c>.

/// </remarks>

public bool EnforceAnonymousTypeAccess

{

get { return enforceAnonymousTypeAccess; }

set

{

enforceAnonymousTypeAccess = value;

OnAccessSettingsChanged();

}

}

/// <summary>

/// Controls whether host objects provide access to the static members of their exposed types to script code.

/// </summary>

public bool ExposeHostObjectStaticMembers

{

get { return exposeHostObjectStaticMembers; }

set

{

exposeHostObjectStaticMembers = value;

OnAccessSettingsChanged();

}

}

/// <summary>

/// Enables or disables script code formatting.

/// </summary>

/// <remarks>

/// When this property is set to <c>true</c>, the script engine may format script code

/// before executing or compiling it. This is intended to facilitate interactive debugging.

/// The formatting operation currently includes stripping leading and trailing blank lines

/// and removing global indentation.

/// </remarks>

public bool FormatCode { get; set; }

/// <summary>

/// Controls whether script code is permitted to use reflection.

/// </summary>

/// <remarks>

/// When this property is set to <c>true</c>, script code running in the current script

/// engine is permitted to use reflection. This affects

/// <see cref="System.Object.GetType">Object.GetType()</see>,

/// <see cref="System.Exception.GetType">Exception.GetType()</see>,

/// <see cref="System.Delegate.Method">Delegate.Method</see>,

/// <see cref="HostFunctions.typeOf(object)"/> and <see cref="HostFunctions.typeOf{T}"/>.

/// By default, any attempt to invoke these members from script code results in an

/// exception.

/// </remarks>

public bool AllowReflection { get; set; }

/// <summary>

/// Enables or disables type restriction for field, property, and method return values.

/// </summary>

/// <remarks>

/// When this property is set to <c>true</c>, script code running in the current script

/// engine has access to the runtime types of all exposed host resources, which by default

/// are restricted to their declared types. The default behavior is a general requirement

/// for correct method binding, so setting this property to <c>true</c> is not recommended.

/// </remarks>

/// <seealso cref="ScriptMemberFlags.ExposeRuntimeType"/>

public bool DisableTypeRestriction { get; set; }

/// <summary>

/// Enables or disables type restriction for array and list elements retrieved by index.

/// </summary>

/// <remarks>

/// In ClearScript 5.4.4 and earlier, indexed array and list elements were exempt from type

/// restriction. ClearScript 5.4.5 introduced a breaking change to correct this, but you can

/// set this property to <c>true</c> to restore the exemption if you have older script code

/// that depends on it.

/// </remarks>

/// <seealso cref="DisableTypeRestriction"/>

public bool DisableListIndexTypeRestriction { get; set; }

/// <summary>

/// Enables or disables <c>null</c> wrapping for field, property, and method return values.

/// </summary>

/// <remarks>

/// When this property is set to <c>true</c>, all field, property, and method return values

/// are marshaled with full .NET type information even if they are <c>null</c>. Note that

/// such values will always fail equality comparison with JavaScript's

/// <c><see href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/null">null</see></c>,

/// VBScript's

/// <c><see href="https://docs.microsoft.com/en-us/previous-versions//f8tbc79x(v=vs.85)">Nothing</see></c>,

/// and other similar values. Instead, use <see cref="HostFunctions.isNull"/> or

/// <see cref="object.Equals(object, object)"/> to perform such a comparison.

/// </remarks>

/// <seealso cref="ScriptMemberFlags.WrapNullResult"/>

/// <seealso cref="HostFunctions.isNull"/>

public bool EnableNullResultWrapping { get; set; }

/// <summary>

/// Enables or disables the use of reflection-based method binding as a fallback.

/// </summary>

/// <remarks>

/// When this property is set to <c>true</c>, the script engine attempts to use

/// reflection-based method binding when the default method binding algorithm fails. This

/// approach reduces type safety, but it may be useful for running legacy scripts that rely

/// on the specific behavior of reflection-based method binding.

/// </remarks>

public bool UseReflectionBindFallback { get; set; }

/// <summary>

/// Enables or disables automatic host variable tunneling for by-reference arguments to script functions and delegates.

/// </summary>

/// <remarks>

/// When this property is set to <c>true</c>, the script engine replaces by-reference

/// arguments to script functions and delegates with host variables, allowing script code

/// to simulate output arguments if the script language does not support them natively.

/// </remarks>

/// <seealso cref="HostFunctions.newVar{T}(T)"/>

public bool EnableAutoHostVariables { get; set; }

/// <summary>

/// Gets or sets the engine's undefined import value.

/// </summary>

/// <remarks>

/// Some script languages support one or more special non-<c>null</c> values that represent

/// nonexistent, missing, unknown, or undefined data. When such a value is marshaled to the

/// host, the script engine maps it to the value of this property. The default value is

/// <see cref="Undefined.Value"/>.

/// </remarks>

public object UndefinedImportValue

{

get { return undefinedImportValue; }

set { undefinedImportValue = value; }

}

/// <summary>

/// Gets or sets a callback that can be used to halt script execution.

/// </summary>

/// <remarks>

/// During script execution the script engine periodically invokes this callback to

/// determine whether it should continue. If the callback returns <c>false</c>, the script

/// engine terminates script execution and throws an exception.

/// </remarks>

public ContinuationCallback ContinuationCallback { get; set; }

/// <summary>

/// Allows the host to access script resources directly.

/// </summary>

/// <remarks>

/// The value of this property is an object that is bound to the script engine's root

/// namespace. It dynamically supports properties and methods that correspond to global

/// script objects and functions.

/// </remarks>

public abstract dynamic Script { get; }

/// <summary>

/// Gets or sets the script engine's document settings.

/// </summary>

public DocumentSettings DocumentSettings

{

get { return documentSettings ?? defaultDocumentSettings; }

set { documentSettings = value; }

}

/// <summary>

/// Exposes a host object to script code.

/// </summary>

/// <param name="itemName">A name for the new global script item that will represent the object.</param>

/// <param name="target">The object to expose.</param>

/// <remarks>

/// For information about the mapping between host members and script-callable properties

/// and methods, see <see cref="AddHostObject(string, HostItemFlags, object)"/>.

/// </remarks>

public void AddHostObject(string itemName, object target)

{

AddHostObject(itemName, HostItemFlags.None, target);

}

/// <summary>

/// Exposes a host object to script code with the specified options.

/// </summary>

/// <param name="itemName">A name for the new global script item that will represent the object.</param>

/// <param name="flags">A value that selects options for the operation.</param>

/// <param name="target">The object to expose.</param>

/// <remarks>

/// <para>

/// Once a host object is exposed to script code, its members are accessible via the script

/// language's native syntax for member access. The following table provides details about

/// the mapping between host members and script-accessible properties and methods.

/// </para>

/// <para>

/// <list type="table">

/// <listheader>

/// <term>Member&#xA0;Type</term>

/// <term>Exposed&#xA0;As</term>

/// <description>Remarks</description>

/// </listheader>

/// <item>

/// <term><b>Constructor</b></term>

/// <term>N/A</term>

/// <description>

/// To invoke a constructor from script code, call

/// <see cref="HostFunctions.newObj{T}">HostFunctions.newObj(T)</see>.

/// </description>

/// </item>

/// <item>

/// <term><b>Property/Field</b></term>

/// <term><b>Property</b></term>

/// <description>N/A</description>

/// </item>

/// <item>

/// <term><b>Method</b></term>

/// <term><b>Method</b></term>

/// <description>

/// Overloaded host methods are merged into a single script-callable method. At

/// runtime the correct host method is selected based on the argument types.

/// </description>

/// </item>

/// <item>

/// <term><b>Generic&#xA0;Method</b></term>

/// <term><b>Method</b></term>

/// <description>

/// The ClearScript library supports dynamic C#-like type inference when invoking

/// generic methods. However, some methods require explicit type arguments. To call

/// such a method from script code, you must place the required number of

/// <see cref="AddHostType(string, HostItemFlags, Type)">host type objects</see>

/// at the beginning of the argument list. Doing so for methods that do not require

/// explicit type arguments is optional.

/// </description>

/// </item>

/// <item>

/// <term><b>Extension&#xA0;Method</b></term>

/// <term><b>Method</b></term>

/// <description>

/// Extension methods are available if the type that implements them has been

/// exposed in the current script engine.

/// </description>

/// </item>

/// <item>

/// <term><b>Indexer</b></term>

/// <term><b>Property</b></term>

/// <description>

/// Indexers appear as properties named "Item" that accept one or more index values

/// as arguments. In addition, objects that implement <see cref="IList"/> expose

/// properties with numeric names that match their valid indices. This includes

/// one-dimensional host arrays and other collections. Multidimensional host arrays

/// do not expose functional indexers; you must use

/// <see href="https://docs.microsoft.com/en-us/dotnet/api/system.array.getvalue">Array.GetValue</see>

/// and

/// <see href="https://docs.microsoft.com/en-us/dotnet/api/system.array.setvalue">Array.SetValue</see>

/// instead.

/// </description>

/// </item>

/// <item>

/// <term><b>Event</b></term>

/// <term><b>Property</b></term>

/// <description>

/// Events are exposed as read-only properties of type <see cref="EventSource{T}"/>.

/// </description>

/// </item>

/// </list>

/// </para>

/// </remarks>

public void AddHostObject(string itemName, HostItemFlags flags, object target)

{

MiscHelpers.VerifyNonNullArgument(target, "target");

AddHostItem(itemName, flags, target);

}

/// <summary>

/// Exposes a host object to script code with the specified type restriction.

/// </summary>

/// <typeparam name="T">The type whose members are to be made accessible from script code.</typeparam>

/// <param name="itemName">A name for the new global script item that will represent the object.</param>

/// <param name="target">The object to expose.</param>

/// <remarks>

/// <para>

/// This method can be used to restrict script access to the members of a particular

/// interface or base class.

/// </para>

/// <para>

/// For information about the mapping between host members and script-callable properties

/// and methods, see <see cref="AddHostObject(string, HostItemFlags, object)"/>.

/// </para>

/// </remarks>

public void AddRestrictedHostObject<T>(string itemName, T target)

{

AddRestrictedHostObject(itemName, HostItemFlags.None, target);

}

/// <summary>

/// Exposes a host object to script code with the specified type restriction and options.

/// </summary>

/// <typeparam name="T">The type whose members are to be made accessible from script code.</typeparam>

/// <param name="itemName">A name for the new global script item that will represent the object.</param>

/// <param name="flags">A value that selects options for the operation.</param>

/// <param name="target">The object to expose.</param>

/// <remarks>

/// <para>

/// This method can be used to restrict script access to the members of a particular

/// interface or base class.

/// </para>

/// <para>

/// For information about the mapping between host members and script-callable properties

/// and methods, see <see cref="AddHostObject(string, HostItemFlags, object)"/>.

/// </para>

/// </remarks>

public void AddRestrictedHostObject<T>(string itemName, HostItemFlags flags, T target)

{

AddHostItem(itemName, flags, HostItem.Wrap(this, target, typeof(T)));

}

/// <summary>

/// Creates a COM/ActiveX object and exposes it to script code. The registered class is

/// specified by programmatic identifier (ProgID).

/// </summary>

/// <param name="itemName">A name for the new global script item that will represent the object.</param>

/// <param name="progID">The programmatic identifier (ProgID) of the registered class to instantiate.</param>

/// <remarks>

/// <para>

/// The <paramref name="progID"/> argument can be a class identifier (CLSID) in standard

/// GUID format with braces (e.g., "{0D43FE01-F093-11CF-8940-00A0C9054228}").

/// </para>

/// <para>

/// For information about the mapping between host members and script-callable properties

/// and methods, see <see cref="AddHostObject(string, HostItemFlags, object)"/>.

/// </para>

/// </remarks>

public void AddCOMObject(string itemName, string progID)

{

AddCOMObject(itemName, HostItemFlags.None, progID);

}

/// <summary>

/// Creates a COM/ActiveX object on the specified server and exposes it to script code. The

/// registered class is specified by programmatic identifier (ProgID).

/// </summary>

/// <param name="itemName">A name for the new global script item that will represent the object.</param>

/// <param name="progID">The programmatic identifier (ProgID) of the registered class to instantiate.</param>

/// <param name="serverName">The name of the server on which to create the object.</param>

/// <remarks>

/// <para>

/// The <paramref name="progID"/> argument can be a class identifier (CLSID) in standard

/// GUID format with braces (e.g., "{0D43FE01-F093-11CF-8940-00A0C9054228}").

/// </para>

/// <para>

/// For information about the mapping between host members and script-callable properties

/// and methods, see <see cref="AddHostObject(string, HostItemFlags, object)"/>.

/// </para>

/// </remarks>

public void AddCOMObject(string itemName, string progID, string serverName)

{

AddCOMObject(itemName, HostItemFlags.None, progID, serverName);

}

/// <summary>

/// Creates a COM/ActiveX object and exposes it to script code with the specified options.

/// The registered class is specified by programmatic identifier (ProgID).

/// </summary>

/// <param name="itemName">A name for the new global script item that will represent the object.</param>

/// <param name="flags">A value that selects options for the operation.</param>

/// <param name="progID">The programmatic identifier (ProgID) of the registered class to instantiate.</param>

/// <remarks>

/// <para>

/// The <paramref name="progID"/> argument can be a class identifier (CLSID) in standard

/// GUID format with braces (e.g., "{0D43FE01-F093-11CF-8940-00A0C9054228}").

/// </para>

/// <para>

/// For information about the mapping between host members and script-callable properties

/// and methods, see <see cref="AddHostObject(string, HostItemFlags, object)"/>.

/// </para>

/// </remarks>

public void AddCOMObject(string itemName, HostItemFlags flags, string progID)

{

AddCOMObject(itemName, flags, progID, null);

}

/// <summary>

/// Creates a COM/ActiveX object on the specified server and exposes it to script code with

/// the specified options. The registered class is specified by programmatic identifier (ProgID).

/// </summary>

/// <param name="itemName">A name for the new global script item that will represent the object.</param>

/// <param name="flags">A value that selects options for the operation.</param>

/// <param name="progID">The programmatic identifier (ProgID) of the registered class to instantiate.</param>

/// <param name="serverName">The name of the server on which to create the object.</param>

/// <remarks>

/// <para>

/// The <paramref name="progID"/> argument can be a class identifier (CLSID) in standard

/// GUID format with braces (e.g., "{0D43FE01-F093-11CF-8940-00A0C9054228}").

/// </para>

/// <para>

/// For information about the mapping between host members and script-callable properties

/// and methods, see <see cref="AddHostObject(string, HostItemFlags, object)"/>.

/// </para>

/// </remarks>

public void AddCOMObject(string itemName, HostItemFlags flags, string progID, string serverName)

{

AddHostItem(itemName, flags, MiscHelpers.CreateCOMObject(progID, serverName));

}

/// <summary>

/// Creates a COM/ActiveX object and exposes it to script code. The registered class is

/// specified by class identifier (CLSID).

/// </summary>

/// <param name="itemName">A name for the new global script item that will represent the object.</param>

/// <param name="clsid">The class identifier (CLSID) of the registered class to instantiate.</param>

/// <remarks>

/// For information about the mapping between host members and script-callable properties

/// and methods, see <see cref="AddHostObject(string, HostItemFlags, object)"/>.

/// </remarks>

public void AddCOMObject(string itemName, Guid clsid)

{

AddCOMObject(itemName, HostItemFlags.None, clsid);

}

/// <summary>

/// Creates a COM/ActiveX object on the specified server and exposes it to script code. The

/// registered class is specified by class identifier (CLSID).

/// </summary>

/// <param name="itemName">A name for the new global script item that will represent the object.</param>

/// <param name="clsid">The class identifier (CLSID) of the registered class to instantiate.</param>

/// <param name="serverName">The name of the server on which to create the object.</param>

/// <remarks>

/// For information about the mapping between host members and script-callable properties

/// and methods, see <see cref="AddHostObject(string, HostItemFlags, object)"/>.

/// </remarks>

public void AddCOMObject(string itemName, Guid clsid, string serverName)

{

AddCOMObject(itemName, HostItemFlags.None, clsid, serverName);

}

/// <summary>

/// Creates a COM/ActiveX object and exposes it to script code with the specified options.

/// The registered class is specified by class identifier (CLSID).

/// </summary>

/// <param name="itemName">A name for the new global script item that will represent the object.</param>

/// <param name="flags">A value that selects options for the operation.</param>

/// <param name="clsid">The class identifier (CLSID) of the registered class to instantiate.</param>

/// <remarks>

/// For information about the mapping between host members and script-callable properties

/// and methods, see <see cref="AddHostObject(string, HostItemFlags, object)"/>.

/// </remarks>

public void AddCOMObject(string itemName, HostItemFlags flags, Guid clsid)

{

AddCOMObject(itemName, flags, clsid, null);

}

/// <summary>

/// Creates a COM/ActiveX object on the specified server and exposes it to script code with

/// the specified options. The registered class is specified by class identifier (CLSID).

/// </summary>

/// <param name="itemName">A name for the new global script item that will represent the object.</param>

/// <param name="flags">A value that selects options for the operation.</param>

/// <param name="clsid">The class identifier (CLSID) of the registered class to instantiate.</param>

/// <param name="serverName">The name of the server on which to create the object.</param>

/// <remarks>

/// For information about the mapping between host members and script-callable properties

/// and methods, see <see cref="AddHostObject(string, HostItemFlags, object)"/>.

/// </remarks>

public void AddCOMObject(string itemName, HostItemFlags flags, Guid clsid, string serverName)

{

AddHostItem(itemName, flags, MiscHelpers.CreateCOMObject(clsid, serverName));

}

/// <summary>

/// Exposes a host type to script code with a default name.

/// </summary>

/// <param name="type">The type to expose.</param>

/// <remarks>

/// <para>

/// This method uses <paramref name="type"/>'s name for the new global script item that

/// will represent it.

/// </para>

/// <para>

/// Host types are exposed to script code in the form of objects whose properties and

/// methods are bound to the type's static members and nested types. If the type has

/// generic parameters, the corresponding object will be invocable with type arguments to

/// yield a specific type.

/// </para>

/// <para>

/// For more information about the mapping between host members and script-callable

/// properties and methods, see <see cref="AddHostObject(string, HostItemFlags, object)"/>.

/// </para>

/// </remarks>

public void AddHostType(Type type)

{

AddHostType(HostItemFlags.None, type);

}

/// <summary>

/// Exposes a host type to script code with a default name and the specified options.

/// </summary>

/// <param name="flags">A value that selects options for the operation.</param>

/// <param name="type">The type to expose.</param>

/// <remarks>

/// <para>

/// This method uses <paramref name="type"/>'s name for the new global script item that

/// will represent it.

/// </para>

/// <para>

/// Host types are exposed to script code in the form of objects whose properties and

/// methods are bound to the type's static members and nested types. If the type has

/// generic parameters, the corresponding object will be invocable with type arguments to

/// yield a specific type.

/// </para>

/// <para>

/// For more information about the mapping between host members and script-callable

/// properties and methods, see <see cref="AddHostObject(string, HostItemFlags, object)"/>.

/// </para>

/// </remarks>

public void AddHostType(HostItemFlags flags, Type type)

{

AddHostType(type.GetRootName(), flags, type);

}

/// <summary>

/// Exposes a host type to script code.

/// </summary>

/// <param name="itemName">A name for the new global script item that will represent the type.</param>

/// <param name="type">The type to expose.</param>

/// <remarks>

/// <para>

/// Host types are exposed to script code in the form of objects whose properties and

/// methods are bound to the type's static members and nested types. If the type has

/// generic parameters, the corresponding object will be invocable with type arguments to

/// yield a specific type.

/// </para>

/// <para>

/// For more information about the mapping between host members and script-callable

/// properties and methods, see <see cref="AddHostObject(string, HostItemFlags, object)"/>.

/// </para>

/// </remarks>

public void AddHostType(string itemName, Type type)

{

AddHostType(itemName, HostItemFlags.None, type);

}

/// <summary>

/// Exposes a host type to script code with the specified options.

/// </summary>

/// <param name="itemName">A name for the new global script item that will represent the type.</param>

/// <param name="flags">A value that selects options for the operation.</param>

/// <param name="type">The type to expose.</param>

/// <remarks>

/// <para>

/// Host types are exposed to script code in the form of objects whose properties and

/// methods are bound to the type's static members and nested types. If the type has

/// generic parameters, the corresponding object will be invocable with type arguments to

/// yield a specific type.

/// </para>

/// <para>

/// For more information about the mapping between host members and script-callable

/// properties and methods, see <see cref="AddHostObject(string, HostItemFlags, object)"/>.

/// </para>

/// </remarks>

public void AddHostType(string itemName, HostItemFlags flags, Type type)

{

MiscHelpers.VerifyNonNullArgument(type, "type");

AddHostItem(itemName, flags, HostType.Wrap(type));

}

/// <summary>

/// Exposes a host type to script code. The type is specified by name.

/// </summary>

/// <param name="itemName">A name for the new global script item that will represent the type.</param>

/// <param name="typeName">The fully qualified name of the type to expose.</param>

/// <param name="typeArgs">Optional generic type arguments.</param>

/// <remarks>

/// <para>

/// Host types are exposed to script code in the form of objects whose properties and

/// methods are bound to the type's static members and nested types. If the type has

/// generic parameters, the corresponding object will be invocable with type arguments to

/// yield a specific type.

/// </para>

/// <para>

/// For more information about the mapping between host members and script-callable

/// properties and methods, see <see cref="AddHostObject(string, HostItemFlags, object)"/>.

/// </para>

/// </remarks>

public void AddHostType(string itemName, string typeName, params Type[] typeArgs)

{

AddHostType(itemName, HostItemFlags.None, typeName, typeArgs);

}

/// <summary>

/// Exposes a host type to script code with the specified options. The type is specified by name.

/// </summary>

/// <param name="itemName">A name for the new global script item that will represent the type.</param>

/// <param name="flags">A value that selects options for the operation.</param>

/// <param name="typeName">The fully qualified name of the type to expose.</param>

/// <param name="typeArgs">Optional generic type arguments.</param>

/// <remarks>

/// <para>

/// Host types are exposed to script code in the form of objects whose properties and

/// methods are bound to the type's static members and nested types. If the type has

/// generic parameters, the corresponding object will be invocable with type arguments to

/// yield a specific type.

/// </para>

/// <para>

/// For more information about the mapping between host members and script-callable

/// properties and methods, see <see cref="AddHostObject(string, HostItemFlags, object)"/>.

/// </para>

/// </remarks>

public void AddHostType(string itemName, HostItemFlags flags, string typeName, params Type[] typeArgs)

{

AddHostItem(itemName, flags, TypeHelpers.ImportType(typeName, null, false, typeArgs));

}

/// <summary>

/// Exposes a host type to script code. The type is specified by type name and assembly name.

/// </summary>

/// <param name="itemName">A name for the new global script item that will represent the type.</param>

/// <param name="typeName">The fully qualified name of the type to expose.</param>

/// <param name="assemblyName">The name of the assembly that contains the type to expose.</param>

/// <param name="typeArgs">Optional generic type arguments.</param>

/// <remarks>

/// <para>

/// Host types are exposed to script code in the form of objects whose properties and

/// methods are bound to the type's static members and nested types. If the type has

/// generic parameters, the corresponding object will be invocable with type arguments to

/// yield a specific type.

/// </para>

/// <para>

/// For more information about the mapping between host members and script-callable

/// properties and methods, see <see cref="AddHostObject(string, HostItemFlags, object)"/>.

/// </para>

/// </remarks>

public void AddHostType(string itemName, string typeName, string assemblyName, params Type[] typeArgs)

{

AddHostType(itemName, HostItemFlags.None, typeName, assemblyName, typeArgs);

}

/// <summary>

/// Exposes a host type to script code with the specified options. The type is specified by

/// type name and assembly name.

/// </summary>

/// <param name="itemName">A name for the new global script item that will represent the type.</param>

/// <param name="flags">A value that selects options for the operation.</param>

/// <param name="typeName">The fully qualified name of the type to expose.</param>

/// <param name="assemblyName">The name of the assembly that contains the type to expose.</param>

/// <param name="typeArgs">Optional generic type arguments.</param>

/// <remarks>

/// <para>

/// Host types are exposed to script code in the form of objects whose properties and

/// methods are bound to the type's static members and nested types. If the type has

/// generic parameters, the corresponding object will be invocable with type arguments to

/// yield a specific type.

/// </para>

/// <para>

/// For more information about the mapping between host members and script-callable

/// properties and methods, see <see cref="AddHostObject(string, HostItemFlags, object)"/>.

/// </para>

/// </remarks>

public void AddHostType(string itemName, HostItemFlags flags, string typeName, string assemblyName, params Type[] typeArgs)

{

AddHostItem(itemName, flags, TypeHelpers.ImportType(typeName, assemblyName, true, typeArgs));

}

/// <summary>

/// Imports a COM/ActiveX type and exposes it to script code. The registered class is

/// specified by programmatic identifier (ProgID).

/// </summary>

/// <param name="itemName">A name for the new global script item that will represent the type.</param>

/// <param name="progID">The programmatic identifier (ProgID) of the registered class to import.</param>

/// <remarks>

/// <para>

/// The <paramref name="progID"/> argument can be a class identifier (CLSID) in standard

/// GUID format with braces (e.g., "{0D43FE01-F093-11CF-8940-00A0C9054228}").

/// </para>

/// <para>

/// For information about the mapping between host members and script-callable properties

/// and methods, see <see cref="AddHostObject(string, HostItemFlags, object)"/>.

/// </para>

/// </remarks>

public void AddCOMType(string itemName, string progID)

{

AddCOMType(itemName, HostItemFlags.None, progID);

}

/// <summary>

/// Imports a COM/ActiveX type from the specified server and exposes it to script code. The

/// registered class is specified by programmatic identifier (ProgID).

/// </summary>

/// <param name="itemName">A name for the new global script item that will represent the type.</param>

/// <param name="progID">The programmatic identifier (ProgID) of the registered class to import.</param>

/// <param name="serverName">The name of the server from which to import the type.</param>

/// <remarks>

/// <para>

/// The <paramref name="progID"/> argument can be a class identifier (CLSID) in standard

/// GUID format with braces (e.g., "{0D43FE01-F093-11CF-8940-00A0C9054228}").

/// </para>

/// <para>

/// For information about the mapping between host members and script-callable properties

/// and methods, see <see cref="AddHostObject(string, HostItemFlags, object)"/>.

/// </para>

/// </remarks>

public void AddCOMType(string itemName, string progID, string serverName)

{

AddCOMType(itemName, HostItemFlags.None, progID, serverName);

}

/// <summary>

/// Imports a COM/ActiveX type and exposes it to script code with the specified options.

/// The registered class is specified by programmatic identifier (ProgID).

/// </summary>

/// <param name="itemName">A name for the new global script item that will represent the type.</param>

/// <param name="flags">A value that selects options for the operation.</param>

/// <param name="progID">The programmatic identifier (ProgID) of the registered class to import.</param>

/// <remarks>

/// <para>

/// The <paramref name="progID"/> argument can be a class identifier (CLSID) in standard

/// GUID format with braces (e.g., "{0D43FE01-F093-11CF-8940-00A0C9054228}").

/// </para>

/// <para>

/// For information about the mapping between host members and script-callable properties

/// and methods, see <see cref="AddHostObject(string, HostItemFlags, object)"/>.

/// </para>

/// </remarks>

public void AddCOMType(string itemName, HostItemFlags flags, string progID)

{

AddCOMType(itemName, flags, progID, null);

}

/// <summary>

/// Imports a COM/ActiveX type from the specified server and exposes it to script code with

/// the specified options. The registered class is specified by programmatic identifier (ProgID).

/// </summary>

/// <param name="itemName">A name for the new global script item that will represent the type.</param>

/// <param name="flags">A value that selects options for the operation.</param>

/// <param name="progID">The programmatic identifier (ProgID) of the registered class to import.</param>

/// <param name="serverName">The name of the server from which to import the type.</param>

/// <remarks>

/// <para>

/// The <paramref name="progID"/> argument can be a class identifier (CLSID) in standard

/// GUID format with braces (e.g., "{0D43FE01-F093-11CF-8940-00A0C9054228}").

/// </para>

/// <para>

/// For information about the mapping between host members and script-callable properties

/// and methods, see <see cref="AddHostObject(string, HostItemFlags, object)"/>.

/// </para>

/// </remarks>

public void AddCOMType(string itemName, HostItemFlags flags, string progID, string serverName)

{

AddHostItem(itemName, flags, HostType.Wrap(MiscHelpers.GetCOMType(progID, serverName)));

}

/// <summary>

/// Imports a COM/ActiveX type and exposes it to script code. The registered class is

/// specified by class identifier (CLSID).

/// </summary>

/// <param name="itemName">A name for the new global script item that will represent the type.</param>

/// <param name="clsid">The class identifier (CLSID) of the registered class to import.</param>

/// <remarks>

/// For information about the mapping between host members and script-callable properties

/// and methods, see <see cref="AddHostObject(string, HostItemFlags, object)"/>.

/// </remarks>

public void AddCOMType(string itemName, Guid clsid)

{

AddCOMType(itemName, HostItemFlags.None, clsid);

}

/// <summary>

/// Imports a COM/ActiveX type from the specified server and exposes it to script code. The

/// registered class is specified by class identifier (CLSID).

/// </summary>

/// <param name="itemName">A name for the new global script item that will represent the type.</param>

/// <param name="clsid">The class identifier (CLSID) of the registered class to import.</param>

/// <param name="serverName">The name of the server from which to import the type.</param>

/// <remarks>

/// For information about the mapping between host members and script-callable properties

/// and methods, see <see cref="AddHostObject(string, HostItemFlags, object)"/>.

/// </remarks>

public void AddCOMType(string itemName, Guid clsid, string serverName)

{

AddCOMType(itemName, HostItemFlags.None, clsid, serverName);

}

/// <summary>

/// Imports a COM/ActiveX type and exposes it to script code with the specified options.

/// The registered class is specified by class identifier (CLSID).

/// </summary>

/// <param name="itemName">A name for the new global script item that will represent the type.</param>

/// <param name="flags">A value that selects options for the operation.</param>

/// <param name="clsid">The class identifier (CLSID) of the registered class to import.</param>

/// <remarks>

/// For information about the mapping between host members and script-callable properties

/// and methods, see <see cref="AddHostObject(string, HostItemFlags, object)"/>.

/// </remarks>

public void AddCOMType(string itemName, HostItemFlags flags, Guid clsid)

{

AddCOMType(itemName, flags, clsid, null);

}

/// <summary>

/// Imports a COM/ActiveX type from the specified server and exposes it to script code with

/// the specified options. The registered class is specified by class identifier (CLSID).

/// </summary>

/// <param name="itemName">A name for the new global script item that will represent the type.</param>

/// <param name="flags">A value that selects options for the operation.</param>

/// <param name="clsid">The class identifier (CLSID) of the registered class to import.</param>

/// <param name="serverName">The name of the server from which to import the type.</param>

/// <remarks>

/// For information about the mapping between host members and script-callable properties

/// and methods, see <see cref="AddHostObject(string, HostItemFlags, object)"/>.

/// </remarks>

public void AddCOMType(string itemName, HostItemFlags flags, Guid clsid, string serverName)

{

AddHostItem(itemName, flags, HostType.Wrap(MiscHelpers.GetCOMType(clsid, serverName)));

}

/// <summary>

/// Executes script code.

/// </summary>

/// <param name="code">The script code to execute.</param>

/// <remarks>

/// <para>

/// In some script languages the distinction between statements and expressions is

/// significant but ambiguous for certain syntactic elements. This method always

/// interprets the specified script code as a statement.

/// </para>

/// <para>

/// If a debugger is attached, it will present the specified script code to the user as a

/// document with an automatically selected name. This document will not be discarded

/// after execution.

/// </para>

/// </remarks>

public void Execute(string code)

{

Execute(null, code);

}

/// <summary>

/// Executes script code with an associated document name.

/// </summary>

/// <param name="documentName">A document name for the script code. Currently this name is used only as a label in presentation contexts such as debugger user interfaces.</param>

/// <param name="code">The script code to execute.</param>

/// <remarks>

/// <para>

/// In some script languages the distinction between statements and expressions is

/// significant but ambiguous for certain syntactic elements. This method always

/// interprets the specified script code as a statement.

/// </para>

/// <para>

/// If a debugger is attached, it will present the specified script code to the user as a

/// document with the specified name. This document will not be discarded after execution.

/// </para>

/// </remarks>

public void Execute(string documentName, string code)

{

Execute(documentName, false, code);

}

/// <summary>

/// Executes script code with an associated document name, optionally discarding the document after execution.

/// </summary>

/// <param name="documentName">A document name for the script code. Currently this name is used only as a label in presentation contexts such as debugger user interfaces.</param>

/// <param name="discard"><c>True</c> to discard the script document after execution, <c>false</c> otherwise.</param>

/// <param name="code">The script code to execute.</param>

/// <remarks>

/// <para>

/// In some script languages the distinction between statements and expressions is

/// significant but ambiguous for certain syntactic elements. This method always

/// interprets the specified script code as a statement.

/// </para>

/// <para>