ClearScript.Core
Represents a method that specifies to a script engine whether script execution should continue.
True to continue script execution, false to interrupt it.
Specifies defaults for how type members are to be exposed to script code.
This attribute is applicable to classes, enums, interfaces, structs, and assemblies. Use
, , or
to override it for individual type members.
Initializes a new instance.
Initializes a new instance with the specified default script access setting.
The default script access setting for type members.
Gets the default script access setting for type members.
Provides an abstract representation of a document.
Initializes a new instance.
Gets a structure containing meta-information for the document.
Gets a stream that provides read access to the document.
Gets the document's character encoding.
This property returns null if the document contains binary data or if its
character encoding is unknown.
Defines document access options.
Specifies that no options are selected.
Specifies that documents may be loaded from the file system.
Specifies that documents may be downloaded from the Web.
Specifies that documents may be loaded from any location.
Specifies that a document path must begin with a segment of "." or ".." to be
considered a relative path. By default, any path that is not explicitly a top-level
or root path is eligible.
Represents a document category.
Gets or sets the maximum cache size for the document category.
This property specifies the maximum number of prepared or compiled documents of the
current category to be cached by script engines. Its initial value is 1024.
Each script engine or runtime maintains private caches for supported document
categories. These are distinct from the caches used by document loaders.
Gets the document category for normal scripts.
Represents a method that retrieves context information for a document.
A structure containing meta-information for the document.
A property collection containing context information for the document.
Defines document attributes.
Indicates that no attributes are present.
Indicates that the document is temporary and can be discarded after use. Only Windows
Script engines honor this attribute.
Contains meta-information for a document.
Initializes a new structure with the specified document name.
The document name.
Initializes a new structure with the specified document URI.
The document URI.
Gets the document's name.
This property always returns a non-blank string. If a null or blank document name was
specified at instantiation time, this property returns a default document name.
Gets the document's URI.
This property returns null if a URI was not specified at instantiation time.
Gets or sets an optional source map URI for the document.
Gets or sets the document's category.
Gets or sets optional document attributes.
Gets or sets an optional context callback for the document.
This property currently applies only to modules. If specified, the callback is invoked
the first time the module attempts to retrieve its context information. The properties
it returns are made available to the module implementation. This mechanism can be used
to expose host resources selectively, securely, and without polluting the script
engine's global namespace.
Use
import.meta
to access the context information of a JavaScript
module. In a module, use module.meta.
Represents a method to be called when a document is loaded.
A structure containing meta-information for the document.
The callback can modify the document meta-information by specifying or overriding any of
its mutable properties.
Represents a document loader.
Initializes a new instance.
Gets the default document loader.
Gets or sets the maximum size of the document loader's cache.
This property specifies the maximum number of documents to be cached by the document
loader. For the default document loader, its initial value is 1024.
Loads a document.
Document access settings for the operation.
An optional structure containing meta-information for the requesting document.
A string specifying the document to be loaded.
An optional category for the requested document.
An optional context callback for the requested document.
A instance that represents the loaded document.
A loaded document must have an absolute URI. Once a
load operation has completed successfully, subsequent requests that resolve to the same
URI are expected to return the same reference, although loaders
are not required to manage document caches of unlimited size.
Loads a document asynchronously.
Document access settings for the operation.
An optional structure containing meta-information for the requesting document.
A string specifying the document to be loaded.
An optional category for the requested document.
An optional context callback for the requested document.
A task that represents the asynchronous operation. Upon completion, the task's result is a instance that represents the loaded document.
A loaded document must have an absolute URI. Once a
load operation has completed successfully, subsequent requests that resolve to the same
URI are expected to return the same reference, although loaders
are not required to manage document caches of unlimited size.
Searches for a cached document by URI.
The document URI for which to search.
The cached document if it was found, null otherwise.
Stores a document in the cache.
The document to store in the cache.
True to replace any existing document with the same URI, false otherwise.
The cached document, which may be different from if is false.
A cached document must have an absolute URI.
Discards all cached documents.
Represents a document access configuration.
This class can be extended to accommodate custom document loaders.
Initializes a new instance.
Gets or sets a document loader.
Gets or sets document access options.
Gets or sets a semicolon-delimited list of directory URLs or paths to search for documents.
Gets or sets a semicolon-delimited list of supported file name extensions.
Gets or set an optional method to be called when a document is loaded.
Gets or sets an optional document context callback.
This property is used as an alternative to .
If specified, the callback is invoked the first time a module attempts to retrieve its
context information. The properties it returns are made available to the module
implementation. This mechanism can be used to expose host resources selectively,
securely, and without polluting the script engine's global namespace.
Use
import.meta
to access the context information of a JavaScript
module. In a module, use module.meta.
Adds a system document to the configuration.
An identifier for the document.
A string containing the document's contents.
System documents take precedence over loaded documents. Once this method is invoked,
document access using this configuration will always map the combination of
and to the
specified document, bypassing the configuration's document loader.
Adds a system document with the specified category to the configuration.
An identifier for the document.
An optional category for the document.
A string containing the document's contents.
System documents take precedence over loaded documents. Once this method is invoked,
document access using this configuration will always map the combination of
and to the specified
document, bypassing the configuration's document loader.
Adds a system document with the specified category and context callback to the configuration.
An identifier for the document.
An optional category for the document.
A string containing the document's contents.
An optional context callback for the document.
System documents take precedence over loaded documents. Once this method is invoked,
document access using this configuration will always map the combination of
and to the specified
document, bypassing the configuration's document loader.
Adds the specified document as a system document to the configuration.
An identifier for the document.
The document to be added as a system document.
System documents take precedence over loaded documents. Once this method is invoked,
document access using this configuration will always map the combination of
and the specified document's category to the specified
document, bypassing the configuration's document loader.
Extends for enhanced behavior and performance in a scripting environment.
Initializes a new instance.
Determines whether the object has the specified named member.
The member name for which to search.
True to perform a case-insensitive search, false otherwise.
True if the named member was found, false otherwise.
Defines extension methods for use with all script engines.
Converts a type to a host type for use with script code currently running on the
calling thread.
The type to convert to a host type.
A host type for use with script code.
Converts a type to a host type for use with script code running in the specified
script engine.
The type to convert to a host type.
The script engine in which the host type will be used.
A host type for use with script code.
Converts an object to a host object with the specified type restriction, for use with
script code currently running on the calling thread.
The type whose members are to be made accessible from script code.
The object to convert to a host object for use with script code.
A host object with the specified type restriction.
Converts an object to a host object with the specified type restriction, for use with
script code running in the specified script engine.
The type whose members are to be made accessible from script code.
The object to convert to a host object for use with script code.
The script engine in which the host object will be used.
A host object with the specified type restriction.
Represents a host event source.
The event handler delegate type.
Connects the host event source to the specified script handler function.
The script function that will handle the event.
An that represents the connection.
Represents a connection between a host event source and a script handler function.
The event handler delegate type.
Disconnects the host event source from the script handler function.
Provides optional script-callable utility functions.
Use AddHostObject to expose a
HostFunctions instance to script code. Each instance can only be exposed in one
script engine.
Initializes a new instance.
Creates an empty host object.
A new empty host object.
This function is provided for script languages that do not support external
instantiation. It creates an object that supports dynamic property addition and
removal. The host can manipulate it via the interface.
The following code creates an empty host object and adds several properties to it.
It assumes that an instance of is exposed under
the name "host"
(see AddHostObject).
var item = host.newObj();
item.label = "Widget";
item.weight = 123.45;
Creates a host object of the specified type. This version is invoked if the specified
type can be used as a type argument.
The type of object to create.
Optional constructor arguments.
A new host object of the specified type.
This function is provided for script languages that do not support external
instantiation. It is overloaded with and
selected at runtime if can be used as a type argument.
For information about the mapping between host members and script-callable properties
and methods, see
AddHostObject.
The following code imports the class, creates an
instance using the
Random(Int32)
constructor, and calls the method.
It assumes that an instance of is exposed under
the name "host"
(see AddHostObject).
var RandomT = host.type("System.Random");
var random = host.newObj(RandomT, 100);
var value = random.NextDouble();
Creates a host object of the specified type. This version is invoked if the specified
type cannot be used as a type argument.
The type of object to create.
Optional constructor arguments.
A new host object of the specified type.
This function is provided for script languages that do not support external
instantiation. It is overloaded with and selected at runtime if
cannot be used as a type argument. Note that this applies
to some host types that support instantiation, such as certain COM/ActiveX types.
For information about the mapping between host members and script-callable properties
and methods, see
AddHostObject.
Performs dynamic instantiation.
The dynamic host object that provides the instantiation operation to perform.
Optional instantiation arguments.
The result of the operation, which is usually a new dynamic host object.
This function is provided for script languages that do not support external
instantiation.
Creates a host array with the specified element type.
The element type of the array to create.
One or more integers representing the array dimension lengths.
A new host array with the specified element type.
For information about the mapping between host members and script-callable properties
and methods, see
AddHostObject.
The following code creates a 5x3 host array of strings.
It assumes that an instance of is exposed under
the name "host"
(see AddHostObject).
var StringT = host.type("System.String");
var array = host.newArr(StringT, 5, 3);
Creates a host array with as the element type.
One or more integers representing the array dimension lengths.
A new host array with as the element type.
For information about the mapping between host members and script-callable properties
and methods, see
AddHostObject.
Creates a host variable of the specified type.
The type of variable to create.
An optional initial value for the variable.
A new host variable of the specified type.
A host variable is a strongly typed object that holds a value of the specified type.
Host variables are useful for passing method arguments by reference. In addition to
being generally interchangeable with their stored values, host variables support the
following properties:
Property
Access
Description
-
value
read-write
The current value of the host variable.
-
out
read-only
A reference to the host variable that can be passed as an out argument.
-
ref
read-only
A reference to the host variable that can be passed as a ref argument.
The following code demonstrates using a host variable to invoke a method with an
out parameter.
It assumes that an instance of is exposed under
the name "host"
(see AddHostObject).
// import a dictionary type
var StringT = host.type("System.String");
var StringDictT = host.type("System.Collections.Generic.Dictionary", StringT, StringT);
// create and populate a dictionary
var dict = host.newObj(StringDictT);
dict.Add("foo", "bar");
dict.Add("baz", "qux");
// look up a dictionary entry
var result = host.newVar(StringT);
var found = dict.TryGetValue("baz", result.out);
Creates a delegate that invokes a script function.
The type of delegate to create.
The script function for which to create a delegate.
A new delegate that invokes the specified script function.
If the delegate signature includes parameters passed by reference, the corresponding
arguments to the script function will be host variables.
The script function can set the value of an output argument by assigning the
corresponding host variable's value property.
The following code demonstrates delegating a callback to a script function.
It assumes that an instance of is exposed under
the name "host"
(see AddHostObject).
// create and populate an array of integers
var EnumerableT = host.type("System.Linq.Enumerable", "System.Core");
var array = EnumerableT.Range(1, 5).ToArray();
// import the callback type required to call Array.ForEach
var Int32T = host.type("System.Int32");
var CallbackT = host.type("System.Action", Int32T);
// use Array.ForEach to calculate a sum
var sum = 0;
var ArrayT = host.type("System.Array");
ArrayT.ForEach(array, host.del(CallbackT, function (value) { sum += value; }));
Creates a delegate that invokes a script function and returns no value.
The number of arguments to pass to the script function.
The script function for which to create a delegate.
A new delegate that invokes the specified script function and returns no value.
This function creates a delegate that accepts arguments and
returns no value. The type of all parameters is . Such a
delegate is often useful in strongly typed contexts because of
contravariance.
The following code demonstrates delegating a callback to a script function.
It assumes that an instance of is exposed under
the name "host"
(see AddHostObject).
// create and populate an array of strings
var StringT = host.type("System.String");
var array = host.newArr(StringT, 3);
array.SetValue("first", 0);
array.SetValue("second", 1);
array.SetValue("third", 2);
// use Array.ForEach to generate console output
var ArrayT = host.type("System.Array");
var ConsoleT = host.type("System.Console");
ArrayT.ForEach(array, host.proc(1, function (value) { ConsoleT.WriteLine(value); }));
Creates a delegate that invokes a script function and returns a value of the specified type.
The return value type.
The number of arguments to pass to the script function.
The script function for which to create a delegate.
A new delegate that invokes the specified script function and returns a value of the specified type.
This function creates a delegate that accepts arguments and
returns a value of the specified type. The type of all parameters is
. Such a delegate is often useful in strongly typed contexts
because of
contravariance.
The following code demonstrates delegating a callback to a script function.
It assumes that an instance of is exposed under
the name "host"
(see AddHostObject).
// create and populate an array of strings
var StringT = host.type("System.String");
var array = host.newArr(StringT, 3);
array.SetValue("first", 0);
array.SetValue("second", 1);
array.SetValue("third", 2);
// import LINQ extensions
var EnumerableT = host.type("System.Linq.Enumerable", "System.Core");
// use LINQ to create an array of modified strings
var selector = host.func(StringT, 1, function (value) { return value.toUpperCase(); });
array = array.Select(selector).ToArray();
Creates a delegate that invokes a script function and returns its result value.
The number of arguments to pass to the script function.
The script function for which to create a delegate.
A new delegate that invokes the specified script function and returns its result value.
This function creates a delegate that accepts arguments and
returns the result of invoking . The type of all
parameters and the return value is . Such a delegate is
often useful in strongly typed contexts because of
contravariance.
For information about the types of result values that script code can return, see
.
Gets the for the specified host type. This version is invoked
if the specified object can be used as a type argument.
The host type for which to get the .
The for the specified host type.
This function is similar to C#'s
typeof
operator. It is overloaded with and selected at runtime if
can be used as a type argument.
This function throws an exception if the script engine's
property is set to false.
The following code retrieves the assembly-qualified name of a host type.
It assumes that an instance of is exposed under
the name "host"
(see AddHostObject).
var StringT = host.type("System.String");
var name = host.typeOf(StringT).AssemblyQualifiedName;
Gets the for the specified host type. This version is invoked
if the specified object cannot be used as a type argument.
The host type for which to get the .
The for the specified host type.
This function is similar to C#'s
typeof
operator. It is overloaded with and selected at runtime if
cannot be used as a type argument. Note that this applies to
some host types; examples are static types and overloaded generic type groups.
This function throws an exception if the script engine's
property is set to false.
The following code retrieves the assembly-qualified name of a host type.
It assumes that an instance of is exposed under
the name "host"
(see AddHostObject).
var ConsoleT = host.type("System.Console");
var name = host.typeOf(ConsoleT).AssemblyQualifiedName;
Determines whether an object is compatible with the specified host type.
The host type with which to test for compatibility.
The object to test for compatibility with the specified host type.
True if is compatible with the specified type, false otherwise.
This function is similar to C#'s
is
operator.
The following code defines a function that determines whether an object implements
.
It assumes that an instance of is exposed under
the name "host"
(see AddHostObject).
function isComparable(value)
{
var IComparableT = host.type("System.IComparable");
return host.isType(IComparableT, value);
}
Casts an object to the specified host type, returning null if the cast fails.
The host type to which to cast .
The object to cast to the specified host type.
The result of the cast if successful, null otherwise.
This function is similar to C#'s
as
operator.
The following code defines a function that disposes an object if it implements
.
It assumes that an instance of is exposed under
the name "host"
(see AddHostObject).
function dispose(value)
{
var IDisposableT = host.type("System.IDisposable");
var disposable = host.asType(IDisposableT, value);
if (disposable) {
disposable.Dispose();
}
}
Casts an object to the specified host type.
The host type to which to cast .
The object to cast to the specified host type.
The result of the cast.
If the cast fails, this function throws an exception.
The following code casts a floating-point value to a 32-bit integer.
It assumes that an instance of is exposed under
the name "host"
(see AddHostObject).
var Int32T = host.type("System.Int32");
var intValue = host.cast(Int32T, 12.5);
Determines whether an object is a host type. This version is invoked if the specified
object cannot be used as a type argument.
The object to test.
True if is a host type, false otherwise.
This function is overloaded with and selected at runtime if
cannot be used as a type argument. Note that this applies to
some host types; examples are static types and overloaded generic type groups.
Determines whether an object is a host type. This version is invoked if the specified
object can be used as a type argument.
The host type (ignored).
True.
This function is overloaded with and selected at
runtime if can be used as a type argument. Because type
arguments are always host types, this method ignores its type argument and always
returns true.
Determines whether the specified value is null.
The value to test.
True if is null, false otherwise.
Use this function to test field, property, and method return values when null
result wrapping is in effect (see
and
).
Creates a strongly typed flag set.
The type of flag set to create.
The flags to include in the flag set.
A strongly typed flag set containing the specified flags.
This function throws an exception if is not a flag set type.
The following code demonstrates using a strongly typed flag set.
It assumes that an instance of is exposed under
the name "host"
(see AddHostObject).
// import URI types
var UriT = host.type("System.Uri", "System");
var UriFormatT = host.type("System.UriFormat", "System");
var UriComponentsT = host.type("System.UriComponents", "System");
// create a URI
var uri = host.newObj(UriT, "http://www.example.com:8080/path/to/file/sample.htm?x=1&y=2");
// extract URI components
var components = host.flags(UriComponentsT.Scheme, UriComponentsT.Host, UriComponentsT.Path);
var result = uri.GetComponents(components, UriFormatT.Unescaped);
Converts the specified value to a strongly typed instance.
The value to convert.
An object that can be passed to a parameter of type .
This function converts to and
packages the result to retain its numeric type across the host-script boundary. It may
be useful for passing arguments to parameters if the script
engine does not support that type natively.
The following code adds an element of type to a strongly
typed list.
It assumes that an instance of is exposed under
the name "host"
(see AddHostObject).
// import types
var ElementT = host.type("System.SByte");
var ListT = host.type("System.Collections.Generic.List", ElementT);
// create a list
var list = host.newObj(ListT);
// add a list element
list.Add(host.toSByte(42));
Converts the specified value to a strongly typed instance.
The value to convert.
An object that can be passed to a parameter of type .
This function converts to and
packages the result to retain its numeric type across the host-script boundary. It may
be useful for passing arguments to parameters if the script
engine does not support that type natively.
The following code adds an element of type to a strongly
typed list.
It assumes that an instance of is exposed under
the name "host"
(see AddHostObject).
// import types
var ElementT = host.type("System.Byte");
var ListT = host.type("System.Collections.Generic.List", ElementT);
// create a list
var list = host.newObj(ListT);
// add a list element
list.Add(host.toByte(42));
Converts the specified value to a strongly typed instance.
The value to convert.
An object that can be passed to a parameter of type .
This function converts to and
packages the result to retain its numeric type across the host-script boundary. It may
be useful for passing arguments to parameters if the script
engine does not support that type natively.
The following code adds an element of type to a strongly
typed list.
It assumes that an instance of is exposed under
the name "host"
(see AddHostObject).
// import types
var ElementT = host.type("System.Int16");
var ListT = host.type("System.Collections.Generic.List", ElementT);
// create a list
var list = host.newObj(ListT);
// add a list element
list.Add(host.toInt16(42));
Converts the specified value to a strongly typed instance.
The value to convert.
An object that can be passed to a parameter of type .
This function converts to and
packages the result to retain its numeric type across the host-script boundary. It may
be useful for passing arguments to parameters if the script
engine does not support that type natively.
The following code adds an element of type to a strongly
typed list.
It assumes that an instance of is exposed under
the name "host"
(see AddHostObject).
// import types
var ElementT = host.type("System.UInt16");
var ListT = host.type("System.Collections.Generic.List", ElementT);
// create a list
var list = host.newObj(ListT);
// add a list element
list.Add(host.toUInt16(42));
Converts the specified value to a strongly typed instance.
The value to convert.
An object that can be passed to a parameter of type .
This function converts to and
packages the result to retain its numeric type across the host-script boundary. It may
be useful for passing arguments to parameters if the script
engine does not support that type natively.
The following code adds an element of type to a strongly
typed list.
It assumes that an instance of is exposed under
the name "host"
(see AddHostObject).
// import types
var ElementT = host.type("System.Char");
var ListT = host.type("System.Collections.Generic.List", ElementT);
// create a list
var list = host.newObj(ListT);
// add a list element
list.Add(host.toChar(42));
Converts the specified value to a strongly typed instance.
The value to convert.
An object that can be passed to a parameter of type .
This function converts to and
packages the result to retain its numeric type across the host-script boundary. It may
be useful for passing arguments to parameters if the script
engine does not support that type natively.
The following code adds an element of type to a strongly
typed list.
It assumes that an instance of is exposed under
the name "host"
(see AddHostObject).
// import types
var ElementT = host.type("System.Int32");
var ListT = host.type("System.Collections.Generic.List", ElementT);
// create a list
var list = host.newObj(ListT);
// add a list element
list.Add(host.toInt32(42));
Converts the specified value to a strongly typed instance.
The value to convert.
An object that can be passed to a parameter of type .
This function converts to and
packages the result to retain its numeric type across the host-script boundary. It may
be useful for passing arguments to parameters if the script
engine does not support that type natively.
The following code adds an element of type to a strongly
typed list.
It assumes that an instance of is exposed under
the name "host"
(see AddHostObject).
// import types
var ElementT = host.type("System.UInt32");
var ListT = host.type("System.Collections.Generic.List", ElementT);
// create a list
var list = host.newObj(ListT);
// add a list element
list.Add(host.toUInt32(42));
Converts the specified value to a strongly typed instance.
The value to convert.
An object that can be passed to a parameter of type .
This function converts to and
packages the result to retain its numeric type across the host-script boundary. It may
be useful for passing arguments to parameters if the script
engine does not support that type natively.
The following code adds an element of type to a strongly
typed list.
It assumes that an instance of is exposed under
the name "host"
(see AddHostObject).
// import types
var ElementT = host.type("System.Int64");
var ListT = host.type("System.Collections.Generic.List", ElementT);
// create a list
var list = host.newObj(ListT);
// add a list element
list.Add(host.toInt64(42));
Converts the specified value to a strongly typed instance.
The value to convert.
An object that can be passed to a parameter of type .
This function converts to and
packages the result to retain its numeric type across the host-script boundary. It may
be useful for passing arguments to parameters if the script
engine does not support that type natively.
The following code adds an element of type to a strongly
typed list.
It assumes that an instance of is exposed under
the name "host"
(see AddHostObject).
// import types
var ElementT = host.type("System.UInt64");
var ListT = host.type("System.Collections.Generic.List", ElementT);
// create a list
var list = host.newObj(ListT);
// add a list element
list.Add(host.toUInt64(42));
Converts the specified value to a strongly typed instance.
The value to convert.
An object that can be passed to a parameter of type .
This function converts to and
packages the result to retain its numeric type across the host-script boundary. It may
be useful for passing arguments to parameters if the script
engine does not support that type natively.
The following code adds an element of type to a strongly
typed list.
It assumes that an instance of is exposed under
the name "host"
(see AddHostObject).
// import types
var ElementT = host.type("System.Single");
var ListT = host.type("System.Collections.Generic.List", ElementT);
// create a list
var list = host.newObj(ListT);
// add a list element
list.Add(host.toSingle(42));
Converts the specified value to a strongly typed instance.
The value to convert.
An object that can be passed to a parameter of type .
This function converts to and
packages the result to retain its numeric type across the host-script boundary. It may
be useful for passing arguments to parameters if the script
engine does not support that type natively.
The following code adds an element of type to a strongly
typed list.
It assumes that an instance of is exposed under
the name "host"
(see AddHostObject).
// import types
var ElementT = host.type("System.Double");
var ListT = host.type("System.Collections.Generic.List", ElementT);
// create a list
var list = host.newObj(ListT);
// add a list element
list.Add(host.toDouble(42));
Converts the specified value to a strongly typed instance.
The value to convert.
An object that can be passed to a parameter of type .
This function converts to and
packages the result to retain its numeric type across the host-script boundary. It may
be useful for passing arguments to parameters if the script
engine does not support that type natively.
The following code adds an element of type to a strongly
typed list.
It assumes that an instance of is exposed under
the name "host"
(see AddHostObject).
// import types
var ElementT = host.type("System.Decimal");
var ListT = host.type("System.Collections.Generic.List", ElementT);
// create a list
var list = host.newObj(ListT);
// add a list element
list.Add(host.toDecimal(42));
Gets the value of a property in a dynamic host object that implements .
The dynamic host object that contains the property to get.
The name of the property to get.
The value of the specified property.
This function is provided for script languages that do not support dynamic properties.
Sets a property value in a dynamic host object that implements .
The dynamic host object that contains the property to set.
The name of the property to set.
The new value of the specified property.
The result of the operation, which is usually the value assigned to the specified property.
This function is provided for script languages that do not support dynamic properties.
Removes a property from a dynamic host object that implements .
The dynamic host object that contains the property to remove.
The name of the property to remove.
True if the property was found and removed, false otherwise.
This function is provided for script languages that do not support dynamic properties.
Gets the value of a property in a dynamic host object that implements .
The dynamic host object that contains the property to get.
The name of the property to get.
The value of the specified property.
This function is provided for script languages that do not support dynamic properties.
Sets a property value in a dynamic host object that implements .
The dynamic host object that contains the property to set.
The name of the property to set.
The new value of the specified property.
The result of the operation, which is usually the value assigned to the specified property.
This function is provided for script languages that do not support dynamic properties.
Removes a property from a dynamic host object that implements .
The dynamic host object that contains the property to remove.
The name of the property to remove.
True if the property was found and removed, false otherwise.
This function is provided for script languages that do not support dynamic properties.
Gets the value of an element in a dynamic host object that implements .
The dynamic host object that contains the element to get.
One or more indices that identify the element to get.
The value of the specified element.
This function is provided for script languages that do not support general indexing.
Sets an element value in a dynamic host object that implements .
The dynamic host object that contains the element to set.
The new value of the element.
One or more indices that identify the element to set.
The result of the operation, which is usually the value assigned to the specified element.
This function is provided for script languages that do not support general indexing.
Removes an element from a dynamic host object that implements .
The dynamic host object that contains the element to remove.
One or more indices that identify the element to remove.
True if the element was found and removed, false otherwise.
This function is provided for script languages that do not support general indexing.
Casts a dynamic host object to its static type.
The object to cast to its static type.
The specified object in its static type form, stripped of its dynamic members.
A dynamic host object that implements may have
dynamic members that override members of its static type. This function can be used to
gain access to type members overridden in this manner.
Allows script code to handle host exceptions.
A script function that invokes one or more host methods or properties.
A script function to invoke if throws an exception.
An optional script function that performs cleanup for the operation.
True if completed successfully, false if it threw an exception that was handled by .
This function uses a try-catch-finally statement to invoke
. If an exception is thrown, it is caught and passed to
for analysis. If returns
false, the exception is rethrown. Regardless of the outcome,
, if specified, is invoked as a final step before the
function exits.
The following code demonstrates handling host exceptions in script code.
It assumes that an instance of is exposed under
the name "host"
(see AddHostObject).
// import types
var ConsoleT = host.type("System.Console");
var WebClientT = host.type("System.Net.WebClient", "System");
// create a Web client
var webClient = host.newObj(WebClientT);
host.tryCatch(
function () {
// download Web document
ConsoleT.WriteLine(webClient.DownloadString("http://cnn.com"));
},
function (exception) {
// dump exception
ConsoleT.WriteLine("*** ERROR: " + exception.GetBaseException().ToString());
return true;
},
function () {
// clean up
ConsoleT.WriteLine("*** CLEANING UP ***");
webClient.Dispose();
}
);
Provides optional script-callable utility functions. This extended version allows script
code to import host types.
Initializes a new instance.
Imports a host type by name.
The fully qualified name of the host type to import.
Optional generic type arguments.
The imported host type.
Host types are imported in the form of objects whose properties and methods are bound
to the host type's static members and nested types. If refers
to a generic type, the corresponding object will be invocable with type arguments to
yield a specific type.
For more information about the mapping between host members and script-callable
properties and methods, see
AddHostObject.
The following code imports the
Dictionary
generic type and uses it to create a string dictionary.
It assumes that an instance of is exposed under
the name "host"
(see AddHostObject).
var DictT = host.type("System.Collections.Generic.Dictionary");
var StringT = host.type("System.String");
var dict = host.newObj(DictT(StringT, StringT));
Another way to create a string dictionary is to import the specific type directly.
var StringT = host.type("System.String");
var StringDictT = host.type("System.Collections.Generic.Dictionary", StringT, StringT);
var dict = host.newObj(StringDictT);
Imports a host type by name from the specified assembly.
The fully qualified name of the host type to import.
The name of the assembly that contains the host type to import.
Optional generic type arguments.
The imported host type.
Host types are imported in the form of objects whose properties and methods are bound
to the host type's static members and nested types. If refers
to a generic type, the corresponding object will be invocable with type arguments to
yield a specific type.
For more information about the mapping between host members and script-callable
properties and methods, see
AddHostObject.
The following code imports and uses it to create
an array of strings.
It assumes that an instance of is exposed under
the name "host"
(see AddHostObject).
var EnumerableT = host.type("System.Linq.Enumerable", "System.Core");
var Int32T = host.type("System.Int32");
var StringT = host.type("System.String");
var SelectorT = host.type("System.Func", Int32T, StringT);
var selector = host.del(SelectorT, function (num) { return StringT.Format("The number is {0}.", num); });
var array = EnumerableT.Range(0, 5).Select(selector).ToArray();
Imports the host type for the specified .
The that specifies the host type to import.
The imported host type.
Host types are imported in the form of objects whose properties and methods are bound
to the host type's static members and nested types. If refers
to a generic type, the corresponding object will be invocable with type arguments to
yield a specific type.
For more information about the mapping between host members and script-callable
properties and methods, see
AddHostObject.
Imports the host array type for the specified element type.
The element type for the host array type to import.
The number of dimensions for the host array type to import.
The imported host array type.
Imports types from one or more host assemblies.
The names of the assemblies that contain the types to import.
The imported host type collection.
Host type collections provide convenient scriptable access to all the types defined in one
or more host assemblies. They are hierarchical collections where leaf nodes represent types
and parent nodes represent namespaces. For example, if an assembly contains a type named
"Acme.Gadgets.Button", the corresponding collection will have a property named "Acme" whose
value is an object with a property named "Gadgets" whose value is an object with a property
named "Button" whose value represents the Acme.Gadgets.Button host type.
The following code imports types from several core assemblies and uses
to create an array of integers.
It assumes that an instance of is exposed under
the name "host"
(see AddHostObject).
var clr = host.lib("mscorlib", "System", "System.Core");
var array = clr.System.Linq.Enumerable.Range(0, 5).ToArray();
Imports types from one or more host assemblies and merges them with an existing host type collection.
The host type collection with which to merge types from the specified assemblies.
The names of the assemblies that contain the types to import.
A host type collection: if it is not null, a new host type collection otherwise.
Host type collections provide convenient scriptable access to all the types defined in one
or more host assemblies. They are hierarchical collections where leaf nodes represent types
and parent nodes represent namespaces. For example, if an assembly contains a type named
"Acme.Gadgets.Button", the corresponding collection will have a property named "Acme" whose
value is an object with a property named "Gadgets" whose value is an object with a property
named "Button" whose value represents the Acme.Gadgets.Button host type.
The following code imports types from several core assemblies and uses
to create an array of integers.
It assumes that an instance of is exposed under
the name "host"
(see AddHostObject).
var clr = host.lib("mscorlib");
host.lib(clr, "System");
host.lib(clr, "System.Core");
var array = clr.System.Linq.Enumerable.Range(0, 5).ToArray();
Imports a COM/ActiveX type.
The programmatic identifier (ProgID) of the registered class to import.
An optional name that specifies the server from which to import the type.
The imported COM/ActiveX type.
The argument can be a class identifier (CLSID) in standard
GUID format with braces (e.g., "{0D43FE01-F093-11CF-8940-00A0C9054228}").
The following code imports the
Scripting.Dictionary
class and uses it to create and populate an instance.
It assumes that an instance of is exposed under
the name "host"
(see AddHostObject).
var DictT = host.comType('Scripting.Dictionary');
var dict = host.newObj(DictT);
dict.Add('foo', 123);
dict.Add('bar', 456.789);
dict.Add('baz', 'abc');
Creates a COM/ActiveX object of the specified type.
The programmatic identifier (ProgID) of the registered class to instantiate.
An optional name that specifies the server on which to create the object.
A new COM/ActiveX object of the specified type.
The argument can be a class identifier (CLSID) in standard
GUID format with braces (e.g., "{0D43FE01-F093-11CF-8940-00A0C9054228}").
The following code creates a
Scripting.FileSystemObject
instance and uses it to list the drives on the local machine.
It assumes that an instance of is exposed under
the name "host"
(see AddHostObject).
var fso = host.newComObj('Scripting.FileSystemObject');
var ConsoleT = host.type('System.Console');
for (en = fso.Drives.GetEnumerator(); en.MoveNext();) {
ConsoleT.WriteLine(en.Current.Path);
}
Imports enumerations defined within or referenced from a COM/ActiveX type library.
The imported type whose parent library is to be searched for relevant enumerations.
An instance of the representative type.
An optional host type collection with which to merge the imported enumerations.
A host type collection: if it is not null, a new host type collection otherwise.
Defines options for exposing host resources to script code.
Specifies that no options are selected.
Specifies that the host resource's members are to be exposed as global items in the
script engine's root namespace.
Specifies that the host resource's non-public members are to be exposed.
Specifies that the host resource's dynamic members are not to be exposed. This option
applies only to objects that implement .
Specifies that the script engine is to be given direct access to the exposed object if
possible. This option, when supported, suppresses marshaling and hands off the object
for script access without the host's involvement. It is currently supported only for
COM and COM-visible
objects exposed in Windows Script engines.
Defines properties that comprise ClearScript's global configuration.
Enables or disables assembly table usage.
The assembly table is a legacy internal feature intended to accelerate assembly
loading. Because it relies on deprecated platform functionality, this feature is now
disabled by default. Although its replacement is simpler and more efficient, the
feature is still available to provide full compatibility with older ClearScript
releases.
The assembly table feature is only available on .NET Framework. This property has no
effect on other platforms.
Gets or sets a semicolon-delimited list of directory paths to search for auxiliary files.
This property allows the host to augment ClearScript's algorithm for locating unmanaged
resources such as native assemblies and related data files.
Represents a scriptable collection of host types.
Host type collections provide convenient scriptable access to all the types defined in one
or more host assemblies. They are hierarchical collections where leaf nodes represent types
and parent nodes represent namespaces. For example, if an assembly contains a type named
"Acme.Gadgets.Button", the corresponding collection will have a property named "Acme" whose
value is an object with a property named "Gadgets" whose value is an object with a property
named "Button" whose value represents the Acme.Gadgets.Button host type. Use
AddHostObject to expose a host
type collection to script code.
Initializes a new host type collection.
Initializes a new host type collection with types from one or more assemblies.
The assemblies that contain the types with which to initialize the collection.
Initializes a new host type collection with types from one or more assemblies. The
assemblies are specified by name.
The names of the assemblies that contain the types with which to initialize the collection.
Initializes a new host type collection with selected types from one or more assemblies.
A filter for selecting the types to add.
The assemblies that contain the types with which to initialize the collection.
Initializes a new host type collection with selected types from one or more assemblies.
The assemblies are specified by name.
A filter for selecting the types to add.
The names of the assemblies that contain the types with which to initialize the collection.
Adds types from an assembly to a host type collection.
The assembly that contains the types to add.
Adds types from an assembly to a host type collection. The assembly is specified by name.
The name of the assembly that contains the types to add.
Adds selected types from an assembly to a host type collection.
The assembly that contains the types to add.
A filter for selecting the types to add.
Adds selected types from an assembly to a host type collection. The assembly is
specified by name.
The name of the assembly that contains the types to add.
A filter for selecting the types to add.
Adds a type to a host type collection.
The type to add.
Adds a type to a host type collection. The type is specified by name.
The fully qualified name of the type to add.
Optional generic type arguments.
Adds a type to a host type collection. The type is specified by type name and assembly name.
The fully qualified name of the type to add.
The name of the assembly that contains the type to add.
Optional generic type arguments.
Locates a namespace within a host type collection.
The full name of the namespace to locate.
The node that represents the namespace if it was found, null otherwise.
Specifies that instances of the target struct are immutable.
When this attribute is applied to a struct, ClearScript exposes the same object reference
for all instances of the struct that satisfy equality comparison, giving script code the
ability to use native equality operators to compare the exposed objects. This behavior is
also enabled automatically for all enums, numeric types, ,
, and .
Initializes a new instance.
Defines a method to be called when a host object is exposed to script code.
Notifies the host object that it has been exposed to script code.
The script engine in which the host object was exposed.
This method may be called more than once for a given host object. The object may be
exposed in multiple script engines or many times in one script engine. Implementers
should avoid expensive operations within this method, or cache the results of such
operations for efficient retrieval during subsequent invocations.
Defines common script engine exception properties.
Gets the error message.
Gets an HRESULT error code if one is available, zero otherwise.
Gets the name associated with the script engine instance.
Gets a detailed error message if one is available, null otherwise.
Gets a value that indicates whether the exception represents a fatal error.
Gets a value that indicates whether script code execution had started before the current exception was thrown.
Gets the script exception that caused the current exception to be thrown, or null if one was not specified.
Gets the host exception that caused the current exception to be thrown, or null if one was not specified.
Represents a JavaScript
ArrayBuffer.
Gets the size of the ArrayBuffer in bytes.
Creates a byte array containing a copy of the ArrayBuffer's contents.
A new byte array containing a copy of the ArrayBuffer's contents.
Copies bytes from the ArrayBuffer into the specified byte array.
The offset within the ArrayBuffer of the first byte to copy.
The maximum number of bytes to copy.
The byte array into which to copy the bytes.
The index within at which to store the first copied byte.
The number of bytes copied.
Copies bytes from the specified byte array into the ArrayBuffer.
The byte array from which to copy the bytes.
The index within of the first byte to copy.
The maximum number of bytes to copy.
The offset within the ArrayBuffer at which to store the first copied byte.
The number of bytes copied.
Invokes a delegate that returns no value, giving it direct access to the ArrayBuffer's contents.
The delegate to invoke.
This method invokes the specified delegate, passing in the memory address of the
ArrayBuffer's contents. This memory address is valid only while the delegate is
executing. The delegate must not access memory outside the ArrayBuffer's range.
Invokes a delegate that returns a value, giving it direct access to the ArrayBuffer's contents.
The delegate's return type.
The delegate to invoke.
The delegate's return value.
This method invokes the specified delegate, passing in the memory address of the
ArrayBuffer's contents. This memory address is valid only while the delegate is
executing. The delegate must not access memory outside the ArrayBuffer's range.
Defines properties and methods common to all
ArrayBuffer
views.
Gets view's underlying ArrayBuffer.
Gets the view's offset within the underlying ArrayBuffer.
Gets the view's size in bytes.
Creates a byte array containing a copy of the view's contents.
A new byte array containing a copy of the view's contents.
Copies bytes from the view into the specified byte array.
The offset within the view of the first byte to copy.
The maximum number of bytes to copy.
The byte array into which to copy the bytes.
The index within at which to store the first copied byte.
The number of bytes copied.
Copies bytes from the specified byte array into the view.
The byte array from which to copy the bytes.
The index within of the first byte to copy.
The maximum number of bytes to copy.
The offset within the view at which to store the first copied byte.
The number of bytes copied.
Invokes a delegate that returns no value, giving it direct access to the view's contents.
The delegate to invoke.
This method invokes the specified delegate, passing in the memory address of the view's
contents. This memory address is valid only while the delegate is executing. The
delegate must not access memory outside the view's range.
Invokes a delegate that returns a value, giving it direct access to the view's contents.
The delegate's return type.
The delegate to invoke.
The delegate's return value.
This method invokes the specified delegate, passing in the memory address of the view's
contents. This memory address is valid only while the delegate is executing. The
delegate must not access memory outside the view's range.
Represents a JavaScript
DataView.
Defines properties and methods common to all JavaScript
typed arrays.
Gets the typed array's length.
Represents a JavaScript typed array.
The typed array's element type.
The following table lists the specific interfaces implemented by JavaScript typed arrays:
Typed Array
Interface(s) (C#)
-
Uint8Array
ITypedArray<byte>
-
Uint8ClampedArray
ITypedArray<byte>
-
Int8Array
ITypedArray<sbyte>
-
Uint16Array
ITypedArray<ushort> and ITypedArray<char>
-
Int16Array
ITypedArray<short>
-
Uint32Array
ITypedArray<uint>
-
Int32Array
ITypedArray<int>
-
BigUint64Array
ITypedArray<ulong>
-
BigInt64Array
ITypedArray<long>
-
Float32Array
ITypedArray<float>
-
Float64Array
ITypedArray<double>
Creates an array containing a copy of the typed array's contents.
A new array containing a copy of the typed array's contents.
Copies elements from the typed array into the specified array.
The index within the typed array of the first element to copy.
The maximum number of elements to copy.
The array into which to copy the elements.
The index within at which to store the first copied element.
The number of elements copied.
Copies elements from the specified array into the typed array.
The array from which to copy the elements.
The index within of the first element to copy.
The maximum number of elements to copy.
The index within the typed array at which to store the first copied element.
The number of elements copied.
Defines extension methods for use with JavaScript engines.
Converts a instance to a
promise
for use with script code currently running on the calling thread.
The task's result type.
The task to convert to a promise.
A promise that represents the task's asynchronous operation.
Converts a instance to a
promise
for use with script code running in the specified script engine.
The task's result type.
The task to convert to a promise.
The script engine in which the promise will be used.
A promise that represents the task's asynchronous operation.
Converts a instance to a
promise
for use with script code currently running on the calling thread.
The task to convert to a promise.
A promise that represents the task's asynchronous operation.
Converts a instance to a
promise
for use with script code running in the specified script engine.
The task to convert to a promise.
The script engine in which the promise will be used.
A promise that represents the task's asynchronous operation.
Converts a
promise
to a instance.
The promise to convert to a task.
A task that represents the promise's asynchronous operation.
Defines document categories for JavaScript modules.
Gets the document category for standard ECMAScript 6 modules.
Gets the document category for CommonJS modules.
Specifies that script code is to have no access to type members by default.
This attribute is applicable to classes, enums, interfaces, structs, and assemblies. Use
, , or
to override it for individual type members. Note that
it has no effect on the method binding algorithm. If a script-based call is bound to a
method that is blocked by this attribute, it will be rejected even if an overload exists
that could receive the call.
Initializes a new instance.
Specifies that script code is to have no access to the target type member.
This attribute is applicable to events, fields, methods, properties, and nested types. Note
that it has no effect on the method binding algorithm. If a script-based call is bound to a
method that is blocked by this attribute, it will be rejected even if an overload exists
that could receive the call.
Initializes a new instance.
Represents a scriptable collection of named properties.
If an object that implements this interface is added to a script engine (see
AddHostObject), script code
will be able to access the properties stored in the collection as if they were members of
the object itself, using the script language's native syntax for member access. No
other members of the object will be accessible. This interface also allows objects to
implement dynamic properties for script languages that support them.
Provides a default implementation.
Initializes a new writable .
Initializes a new .
True to make the read-only, false to make it writable.
The host can modify a read-only by calling
SetPropertyNoCheck,
RemovePropertyNoCheck, or
ClearNoCheck.
Sets a property value without checking whether the is read-only.
The name of the property to set.
The property value.
This operation is never exposed to script code.
Removes a property without checking whether the is read-only.
The name of the property to remove.
True if the property was found and removed, false otherwise.
This operation is never exposed to script code.
Removes all properties without checking whether the is read-only.
This operation is never exposed to script code.
Determines whether the contains a property with the specified name.
The name of the property to locate.
True if the contains a property with the specified name, false otherwise.
Adds a property to the .
The name of the property to add.
The property value.
Removes a property from the .
The name of the property to remove.
True if the property was successfully found and removed, false otherwise.
Looks up a property value in the .
The name of the property to locate.
The property value if the property was found, null otherwise.
True if the property was found, false otherwise.
Gets or sets a property value in the .
The name of the property to get or set.
The property value.
Gets a collection of property names from the .
Gets a collection of property values from the .
Occurs when a property is added or replaced, or when the collection is cleared.
Defines script access settings for type members.
Specifies that script code is to have full access to the type member. This is the
default setting.
Specifies that script code is to have read-only access to the type member. This setting
only affects fields and writable properties.
Specifies that script code is to have no access to the type member. Note that this
setting has no effect on the method binding algorithm. If a script-based call is bound
to a method that is blocked by this setting, it will be rejected even if an overload
exists that could receive the call.
Provides the base implementation for all script engines.
Initializes a new script engine instance.
A name to associate with the instance. Currently this name is used only as a label in presentation contexts such as debugger user interfaces.
Initializes a new script engine instance with the specified list of supported file name extensions.
A name to associate with the instance. Currently this name is used only as a label in presentation contexts such as debugger user interfaces.
A semicolon-delimited list of supported file name extensions.
Gets the name associated with the script engine instance.
Gets the script engine that is invoking a host member on the current thread.
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
null.
Gets the script engine's recommended file name extension for script files.
Allows script code to access non-public host resources.
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.
Gets or sets the default script access setting for all members of exposed objects.
Use , , 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.
Enables or disables access restrictions for anonymous types.
Anonymous types are
internal
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 , 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 true.
Controls whether host objects provide access to the static members of their exposed types to script code.
Enables or disables extension method support.
Enables or disables script code formatting.
When this property is set to true, 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.
Controls whether script code is permitted to use reflection.
When this property is set to true, script code running in the current script
engine is permitted to use reflection. This affects
Object.GetType(),
Exception.GetType(),
Delegate.Method,
and .
By default, any attempt to invoke these members from script code results in an
exception.
Enables or disables type restriction for field, property, and method return values.
When this property is set to true, 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 true is not recommended.
Enables or disables type restriction for array and list elements retrieved by index.
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 true to restore the exemption if you have older script code
that depends on it.
Enables or disables null wrapping for field, property, and method return values.
When this property is set to true, all field, property, and method return values
are marshaled with full .NET type information even if they are null. Note that
such values will always fail equality comparison with JavaScript's
null,
VBScript's
Nothing,
and other similar values. Instead, use or
to perform such a comparison.
Enables or disables floating point narrowing.
When this property is set to true, no attempt is made to convert floating-point
values imported from the script engine to the narrowest equivalent .NET representation.
The default behavior is more likely to result in successful method binding in specific
scenarios, so setting this property to true is not recommended.
Enables or disables the use of reflection-based method binding as a fallback.
When this property is set to true, 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.
Enables or disables automatic host variable tunneling for by-reference arguments to script functions and delegates.
When this property is set to true, 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.
Gets or sets the engine's undefined import value.
Some script languages support one or more special non-null 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
.
Gets or sets a callback that can be used to halt script execution.
During script execution the script engine periodically invokes this callback to
determine whether it should continue. If the callback returns false, the script
engine terminates script execution and throws an exception.
Allows the host to access script resources dynamically.
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.
Allows the host to access script resources.
The value of this property is an object that is bound to the script engine's root
namespace. It allows you to access global script resources via the
class interface. Doing so is likely to perform better than
dynamic access via .
Gets or sets the script engine's document settings.
Exposes a host object to script code.
A name for the new global script item that will represent the object.
The object to expose.
For information about the mapping between host members and script-callable properties
and methods, see .
Exposes a host object to script code with the specified options.
A name for the new global script item that will represent the object.
A value that selects options for the operation.
The object to expose.
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.
Member Type
Exposed As
Remarks
-
Constructor
N/A
To invoke a constructor from script code, call
HostFunctions.newObj(T).
-
Property/Field
Property
N/A
-
Method
Method
Overloaded host methods are merged into a single script-callable method. At
runtime the correct host method is selected based on the argument types.
-
Generic Method
Method
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
host type objects
at the beginning of the argument list. Doing so for methods that do not require
explicit type arguments is optional.
-
Extension Method
Method
Extension methods are available if the type that implements them has been
exposed in the current script engine.
-
Indexer
Property
Indexers appear as properties named "Item" that accept one or more index values
as arguments. In addition, objects that implement 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
Array.GetValue
and
Array.SetValue
instead.
-
Event
Property
Events are exposed as read-only properties of type .
Exposes a host object to script code with the specified type restriction.
The type whose members are to be made accessible from script code.
A name for the new global script item that will represent the object.
The object to expose.
This method can be used to restrict script access to the members of a particular
interface or base class.
For information about the mapping between host members and script-callable properties
and methods, see .
Exposes a host object to script code with the specified type restriction and options.
The type whose members are to be made accessible from script code.
A name for the new global script item that will represent the object.
A value that selects options for the operation.
The object to expose.
This method can be used to restrict script access to the members of a particular
interface or base class.
For information about the mapping between host members and script-callable properties
and methods, see .
Creates a COM/ActiveX object and exposes it to script code. The registered class is
specified by programmatic identifier (ProgID).
A name for the new global script item that will represent the object.
The programmatic identifier (ProgID) of the registered class to instantiate.
The argument can be a class identifier (CLSID) in standard
GUID format with braces (e.g., "{0D43FE01-F093-11CF-8940-00A0C9054228}").
For information about the mapping between host members and script-callable properties
and methods, see .
Creates a COM/ActiveX object on the specified server and exposes it to script code. The
registered class is specified by programmatic identifier (ProgID).
A name for the new global script item that will represent the object.
The programmatic identifier (ProgID) of the registered class to instantiate.
The name of the server on which to create the object.
The argument can be a class identifier (CLSID) in standard
GUID format with braces (e.g., "{0D43FE01-F093-11CF-8940-00A0C9054228}").
For information about the mapping between host members and script-callable properties
and methods, see .
Creates a COM/ActiveX object and exposes it to script code with the specified options.
The registered class is specified by programmatic identifier (ProgID).
A name for the new global script item that will represent the object.
A value that selects options for the operation.
The programmatic identifier (ProgID) of the registered class to instantiate.
The argument can be a class identifier (CLSID) in standard
GUID format with braces (e.g., "{0D43FE01-F093-11CF-8940-00A0C9054228}").
For information about the mapping between host members and script-callable properties
and methods, see .
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).
A name for the new global script item that will represent the object.
A value that selects options for the operation.
The programmatic identifier (ProgID) of the registered class to instantiate.
The name of the server on which to create the object.
The argument can be a class identifier (CLSID) in standard
GUID format with braces (e.g., "{0D43FE01-F093-11CF-8940-00A0C9054228}").
For information about the mapping between host members and script-callable properties
and methods, see .
Creates a COM/ActiveX object and exposes it to script code. The registered class is
specified by class identifier (CLSID).
A name for the new global script item that will represent the object.
The class identifier (CLSID) of the registered class to instantiate.
For information about the mapping between host members and script-callable properties
and methods, see .
Creates a COM/ActiveX object on the specified server and exposes it to script code. The
registered class is specified by class identifier (CLSID).
A name for the new global script item that will represent the object.
The class identifier (CLSID) of the registered class to instantiate.
The name of the server on which to create the object.
For information about the mapping between host members and script-callable properties
and methods, see .
Creates a COM/ActiveX object and exposes it to script code with the specified options.
The registered class is specified by class identifier (CLSID).
A name for the new global script item that will represent the object.
A value that selects options for the operation.
The class identifier (CLSID) of the registered class to instantiate.
For information about the mapping between host members and script-callable properties
and methods, see .
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).
A name for the new global script item that will represent the object.
A value that selects options for the operation.
The class identifier (CLSID) of the registered class to instantiate.
The name of the server on which to create the object.
For information about the mapping between host members and script-callable properties
and methods, see .
Exposes a host type to script code with a default name.
The type to expose.
This method uses 's name for the new global script item that
will represent it.
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.
For more information about the mapping between host members and script-callable
properties and methods, see .
Exposes a host type to script code with a default name and the specified options.
A value that selects options for the operation.
The type to expose.
This method uses 's name for the new global script item that
will represent it.
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.
For more information about the mapping between host members and script-callable
properties and methods, see .
Exposes a host type to script code.
A name for the new global script item that will represent the type.
The type to expose.
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.
For more information about the mapping between host members and script-callable
properties and methods, see .
Exposes a host type to script code with the specified options.
A name for the new global script item that will represent the type.
A value that selects options for the operation.
The type to expose.
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.
For more information about the mapping between host members and script-callable
properties and methods, see .
Exposes a host type to script code. The type is specified by name.
A name for the new global script item that will represent the type.
The fully qualified name of the type to expose.
Optional generic type arguments.
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.
For more information about the mapping between host members and script-callable
properties and methods, see .
Exposes a host type to script code with the specified options. The type is specified by name.
A name for the new global script item that will represent the type.
A value that selects options for the operation.
The fully qualified name of the type to expose.
Optional generic type arguments.
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.
For more information about the mapping between host members and script-callable
properties and methods, see .
Exposes a host type to script code. The type is specified by type name and assembly name.
A name for the new global script item that will represent the type.
The fully qualified name of the type to expose.
The name of the assembly that contains the type to expose.
Optional generic type arguments.
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.
For more information about the mapping between host members and script-callable
properties and methods, see .
Exposes a host type to script code with the specified options. The type is specified by
type name and assembly name.
A name for the new global script item that will represent the type.
A value that selects options for the operation.
The fully qualified name of the type to expose.
The name of the assembly that contains the type to expose.
Optional generic type arguments.
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.
For more information about the mapping between host members and script-callable
properties and methods, see .
Exposes host types to script code.
The types to expose.
This method uses each specified type's name for the new global script item that will
represent it.
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.
For more information about the mapping between host members and script-callable
properties and methods, see .
Imports a COM/ActiveX type and exposes it to script code. The registered class is
specified by programmatic identifier (ProgID).
A name for the new global script item that will represent the type.
The programmatic identifier (ProgID) of the registered class to import.
The argument can be a class identifier (CLSID) in standard
GUID format with braces (e.g., "{0D43FE01-F093-11CF-8940-00A0C9054228}").
For information about the mapping between host members and script-callable properties
and methods, see .
Imports a COM/ActiveX type from the specified server and exposes it to script code. The
registered class is specified by programmatic identifier (ProgID).
A name for the new global script item that will represent the type.
The programmatic identifier (ProgID) of the registered class to import.
The name of the server from which to import the type.
The argument can be a class identifier (CLSID) in standard
GUID format with braces (e.g., "{0D43FE01-F093-11CF-8940-00A0C9054228}").
For information about the mapping between host members and script-callable properties
and methods, see .
Imports a COM/ActiveX type and exposes it to script code with the specified options.
The registered class is specified by programmatic identifier (ProgID).
A name for the new global script item that will represent the type.
A value that selects options for the operation.
The programmatic identifier (ProgID) of the registered class to import.
The argument can be a class identifier (CLSID) in standard
GUID format with braces (e.g., "{0D43FE01-F093-11CF-8940-00A0C9054228}").
For information about the mapping between host members and script-callable properties
and methods, see .
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).
A name for the new global script item that will represent the type.
A value that selects options for the operation.
The programmatic identifier (ProgID) of the registered class to import.
The name of the server from which to import the type.
The argument can be a class identifier (CLSID) in standard
GUID format with braces (e.g., "{0D43FE01-F093-11CF-8940-00A0C9054228}").
For information about the mapping between host members and script-callable properties
and methods, see .
Imports a COM/ActiveX type and exposes it to script code. The registered class is
specified by class identifier (CLSID).
A name for the new global script item that will represent the type.
The class identifier (CLSID) of the registered class to import.
For information about the mapping between host members and script-callable properties
and methods, see .
Imports a COM/ActiveX type from the specified server and exposes it to script code. The
registered class is specified by class identifier (CLSID).
A name for the new global script item that will represent the type.
The class identifier (CLSID) of the registered class to import.
The name of the server from which to import the type.
For information about the mapping between host members and script-callable properties
and methods, see .
Imports a COM/ActiveX type and exposes it to script code with the specified options.
The registered class is specified by class identifier (CLSID).
A name for the new global script item that will represent the type.
A value that selects options for the operation.
The class identifier (CLSID) of the registered class to import.
For information about the mapping between host members and script-callable properties
and methods, see .
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).
A name for the new global script item that will represent the type.
A value that selects options for the operation.
The class identifier (CLSID) of the registered class to import.
The name of the server from which to import the type.
For information about the mapping between host members and script-callable properties
and methods, see .
Executes script code.
The script code to execute.
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.
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.
Executes script code with an associated document name.
A document name for the script code. Currently this name is used only as a label in presentation contexts such as debugger user interfaces.
The script code to execute.
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.
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.
Executes script code with an associated document name, optionally discarding the document after execution.
A document name for the script code. Currently this name is used only as a label in presentation contexts such as debugger user interfaces.
True to discard the script document after execution, false otherwise.
The script code to execute.
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.
If a debugger is attached, it will present the specified script code to the user as a
document with the specified name. Discarding this document removes it from view but
has no effect on the script engine. Only Windows Script engines honor
.
Executes script code with the specified document meta-information.
A structure containing meta-information for the script document.
The script code to execute.
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.
Loads and executes a script document.
A string specifying the document to be loaded and executed.
In some script languages the distinction between statements and expressions is
significant but ambiguous for certain syntactic elements. This method always
interprets script code loaded from the specified document as a statement.
Loads and executes a document with the specified category.
A string specifying the document to be loaded and executed.
An optional category for the requested document.
In some script languages the distinction between statements and expressions is
significant but ambiguous for certain syntactic elements. This method always
interprets script code loaded from the specified document as a statement.
Loads and executes a document with the specified category and context callback.
A string specifying the document to be loaded and executed.
An optional category for the requested document.
An optional context callback for the requested document.
In some script languages the distinction between statements and expressions is
significant but ambiguous for certain syntactic elements. This method always
interprets script code loaded from the specified document as a statement.
Executes script code as a command.
The script command to execute.
The command output.
This method is similar to but optimized for command
consoles. The specified command must be limited to a single expression or statement.
Script engines can override this method to customize command execution as well as the
process of converting the result to a string for console output.
Evaluates script code.
The script code to evaluate.
The result value.
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 an expression.
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 be discarded after
execution.
For information about the types of result values that script code can return, see
.
Evaluates script code with an associated document name.
A document name for the script code. Currently this name is used only as a label in presentation contexts such as debugger user interfaces.
The script code to evaluate.
The result value.
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 an expression.
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 be discarded after execution.
For information about the types of result values that script code can return, see
.
Evaluates script code with an associated document name, optionally discarding the document after execution.
A document name for the script code. Currently this name is used only as a label in presentation contexts such as debugger user interfaces.
True to discard the script document after execution, false otherwise.
The script code to evaluate.
The result value.
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 an expression.
If a debugger is attached, it will present the specified script code to the user as a
document with the specified name. Discarding this document removes it from view but
has no effect on the script engine. Only Windows Script engines honor
.
The following table summarizes the types of result values that script code can return.
Type
Returned As
Remarks
-
String
System.String
N/A
-
Boolean
System.Boolean
N/A
-
Number
System.Int32 or System.Double
Other numeric types are possible. The exact conversions between script and .NET
numeric types are defined by the script engine.
-
Null Reference
null
N/A
-
Undefined
This represents JavaScript's
undefined,
VBScript's
Empty,
etc.
-
Void
This is returned when script code forwards the result of a host method that returns no value.
-
Host Object
Native .NET type
This includes all .NET types not mentioned above, including value types (enums,
structs, etc.), and instances of all other classes. Script code can only create
these objects by invoking a host method or constructor. They are returned to
the host in their native .NET form.
-
Script Object
This includes all native script objects that have no .NET representation. C#'s
dynamic
keyword provides a convenient way to access them.
-
Other
Unspecified
This includes host types and other ClearScript-specific objects intended for
script code use only. It may also include language-specific values that the
ClearScript library does not support.
Evaluates script code with the specified document meta-information.
A structure containing meta-information for the script document.
The script code to evaluate.
The result value.
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 an expression.
For information about the types of result values that script code can return, see
.
Loads and evaluates a script document.
A string specifying the document to be loaded and evaluated.
The result value.
In some script languages the distinction between statements and expressions is
significant but ambiguous for certain syntactic elements. This method always
interprets script code loaded from the specified document as an expression.
For information about the types of result values that script code can return, see
.
Loads and evaluates a document with the specified category.
A string specifying the document to be loaded and evaluated.
An optional category for the requested document.
The result value.
In some script languages the distinction between statements and expressions is
significant but ambiguous for certain syntactic elements. This method always
interprets script code loaded from the specified document as an expression.
For information about the types of result values that script code can return, see
.
Loads and evaluates a document with the specified category and context callback.
A string specifying the document to be loaded and evaluated.
An optional category for the requested document.
An optional context callback for the requested document.
The result value.
In some script languages the distinction between statements and expressions is
significant but ambiguous for certain syntactic elements. This method always
interprets script code loaded from the specified document as an expression.
For information about the types of result values that script code can return, see
.
Invokes a global function or procedure.
The name of the global function or procedure to invoke.
Optional invocation arguments.
The return value if a function was invoked, an undefined value otherwise.
Gets a string representation of the script call stack.
The script call stack formatted as a string.
This method returns an empty string if the script engine is not executing script code.
The stack trace text format is defined by the script engine.
Interrupts script execution and causes the script engine to throw an exception.
This method can be called safely from any thread.
Performs garbage collection.
True to perform exhaustive garbage collection, false to favor speed over completeness.
Releases all resources used by the script engine.
Call Dispose() when you are finished using the script engine. Dispose()
leaves the script engine in an unusable state. After calling Dispose(), you must
release all references to the script engine so the garbage collector can reclaim the
memory that the script engine was occupying.
Releases the unmanaged resources used by the script engine and optionally releases the managed resources.
True to release both managed and unmanaged resources; false to release only unmanaged resources.
This method is called by the public method and the
Finalize method. invokes the
protected Dispose(Boolean) method with the
parameter set to true. Finalize invokes
Dispose(Boolean) with set to false.
Releases unmanaged resources and performs other cleanup operations before the script engine is reclaimed by garbage collection.
This method overrides . Application code should not
call this method; an object's Finalize() method is automatically invoked during
garbage collection, unless finalization by the garbage collector has been disabled by a
call to .
The exception that is thrown when an error occurs during script execution or script object access.
Initializes a new instance.
Initializes a new with the specified error message.
The error message.
Initializes a new with the specified error message and nested exception.
The error message.
The exception that caused the current exception to be thrown.
Initializes a new with serialized data.
The object that holds the serialized data.
The contextual information about the source or destination.
Gets an HRESULT error code if one is available, zero otherwise.
Gets the name associated with the script engine instance.
Gets a detailed error message if one is available, null otherwise.
Gets a value that indicates whether the exception represents a fatal error.
Gets a value that indicates whether script code execution had started before the current exception was thrown.
Gets the script exception that caused the current exception to be thrown, or null if one was not specified.
Returns a string that represents the current exception.
A string that represents the current exception.
Populates a with the data needed to serialize the target object.
The to populate with data.
The destination (see ) for this serialization.
The exception that is thrown when script execution is interrupted by the host.
Initializes a new instance.
Initializes a new with the specified error message.
The error message.
Initializes a new with the specified error message and nested exception.
The error message.
The exception that caused the current exception to be thrown.
Initializes a new with serialized data.
The object that holds the serialized data.
The contextual information about the source or destination.
Gets an HRESULT error code if one is available, zero otherwise.
Gets the name associated with the script engine instance.
Gets a detailed error message if one is available, null otherwise.
Gets a value that indicates whether the exception represents a fatal error.
Gets a value that indicates whether script code execution had started before the current exception was thrown.
Gets the script exception that caused the current exception to be thrown, or null if one was not specified.
Returns a string that represents the current exception.
A string that represents the current exception.
Populates a with the data needed to serialize the target object.
The to populate with data.
The destination (see ) for this serialization.
Specifies how the target type member is to be exposed to script code. This extended version
supports additional options.
This attribute is applicable to events, fields, methods, and properties.
Initializes a new instance.
Initializes a new instance with the specified name.
The name that script code will use to access the target type member.
Initializes a new instance with the specified script access setting.
The script access setting for the target type member.
Initializes a new instance with the specified name and script access setting.
The name that script code will use to access the target type member.
The script access setting for the target type member.
Initializes a new instance with the specified script options.
The script options for the target type member.
Initializes a new instance with the specified name and script options.
The name that script code will use to access the target type member.
The script options for the target type member.
Initializes a new instance with the specified script access setting and script options.
The script access setting for the target type member.
The script options for the target type member.
Initializes a new instance with the specified name, script access setting, and script options.
The name that script code will use to access the target type member.
The script access setting for the target type member.
The script options for the target type member.
Gets or sets the name that script code will use to access the target type member.
The default value is the name of the target type member. Note that this property has no
effect on the method binding algorithm. If a script-based call is bound to a method
that is exposed under a different name, it will be rejected even if an overload exists
that could receive the call.
Gets or sets the script options for the target type member.
Defines options for exposing type members to script code.
Specifies that no options are selected.
Specifies that the field, property, or method return value is not to be restricted to
its declared type.
Specifies that the field, property, or method return value is to be marshaled with full
.NET type information even if it is null. Note that such a value will always
fail equality comparison with JavaScript's
null,
VBScript's
Nothing,
and other similar values. Instead, use or
to perform such a comparison.
Represents a script object.
Gets the script engine that owns the object.
Gets the value of a named script object property.
The name of the property to get.
Optional arguments for property retrieval.
The value of the specified property.
Sets the value of a named script object property.
The name of the property to set.
An array containing optional arguments and the new property value.
The array must contain at least one element. The new
property value must be the last element of the array.
Removes a named script object property.
The name of the property to remove.
True if the property was removed successfully, false otherwise.
Enumerates the script object's property names.
Gets or sets the value of a named script object property.
The name of the property to get or set.
Optional arguments for property access.
The value of the specified property.
Gets the value of an indexed script object property.
The index of the property to get.
The value of the specified property.
Sets the value of an indexed script object property.
The index of the property to set.
The new property value.
Removes an indexed script object property.
The index of the property to remove.
True if the property was removed successfully, false otherwise.
Enumerates the script object's property indices.
Gets or sets the value of an indexed script object property.
The index of the property to get or set.
The value of the specified property.
Invokes the script object.
True to invoke the object as a constructor, false otherwise.
Optional arguments for object invocation.
The invocation result value.
Invokes a script object method.
The name of the method to invoke.
Optional arguments for method invocation.
The invocation result value.
Specifies how the target type member is to be exposed to script code.
This attribute is applicable to events, fields, methods, properties, and nested types.
Initializes a new instance.
Initializes a new instance with the specified script access setting.
The script access setting for the target type member.
Gets the script access setting for the target type member.
Provides an in-memory implementation for a text document.
Initializes a new instance.
A structure containing meta-information for the document.
A string containing the document's contents.
Gets a structure containing meta-information for the document.
Gets a stream that provides read access to the document.
The implementation of this property returns a
instance.
Gets the document's character encoding.
instances return for this property.
Represents an undefined value.
Some script languages support one or more special non-null values that represent
nonexistent, missing, unknown, or undefined data. The ClearScript library maps such values
to instances of this class.
The sole instance of the class.
Returns a string that represents the current object.
A string that represents the current object.
The version of this method returns "[undefined]".
Represents the result of a host method that returns no value.
Some script languages expect every subroutine call to return a value. When script code
written in such a language invokes a host method that explicitly returns no value (such as
a C# void method),
the ClearScript library provides an instance of this class as a dummy return value.