IVsaEngine.RootMoniker Property

Sets or gets a script engine's root moniker.

public: _property String* get_RootMoniker(); 
public: _property void setRootMoniker(String* value);
public string RootMoniker { get; set; }
Property Get RootMoniker() As String 
Public Property Let RootMoniker(ByVal value As String)

Return Value

Returns the current value of the RootMoniker property.

Remarks

The moniker, or root moniker, is the unique name by which a script engine is identified. The host is responsible for ensuring the uniqueness of the root moniker, as in general it is not possible for one script engine implementation to know the root monikers of other script engines. However, an engine may throw a RootMonikerInUse exception if it detects that the moniker you are attempting to assign it is already assigned to another script engine.

The root moniker cannot exceed 256 characters in length.

Warning

The RootMoniker property should not expose personal information, such as a user name or data store file paths. Placing sensitive information into a root moniker may expose it to malicious exploitation that could result in code running unexpectedly with elevated privileges, denial of rightful access to the real user, or other undesirable behaviors. For greatest security, hosts should use monikers that have no literal or logical meaning. Furthermore, hosts should never allow a user to specify a root moniker. Monikers should always be generated by the host.

The moniker must be in the form <protocol>://<path> where <protocol> is a string guaranteed to be unique to the host, and where <path> is a unique sequence of characters recognized by the host. Again, for security reasons, the <path> portion should be nonlogical string and should not include actual file path or such personal information as a user name. Where necessary, configure the host to use a lookup table that maps nonlogical root monikers to meaningful values. Note that the protocol used in the RootMoniker property cannot be a registered protocol, such as HTTP or FILE, on the machine on which the script engine is running.

One approach is to use a system wherein the protocol handler segment of the root moniker takes the form of the independent software vendor's (ISV's) company URL written backwards, for example, com.Microsoft://<path>. Insofar as URLs are globally unique, such a scheme helps ensure uniqueness of the project moniker.

Other than the fact that the protocol must be unique to the host, and the overall moniker must be globally unique, the only restrictions placed on the value of the RootMoniker property are that it follows the form of a Uniform Resource Identifier (URI). For more information about valid characters, see Request For Comments 2396 at the IETF Web site: https://www.ietf.org/rfc/rfc2396. Invalid characters must be escaped using the escaping mechanism described in the RFC. For more information about Web addressing in general, see guidelines at the W3C Web site: https://www.w3.org/Addressing.

The initial value of the RootMoniker property is the empty string. Note, however, that it must be set to a valid value before any other operation can be performed on the script engine, other than calling the IVsaEngine.Close method. Once set, this property cannot be changed.

The following table shows the exceptions that the RootMoniker property can throw.

Exception Type

Condition

EngineClosed

The IVsaEngine.Close method has been called and the engine is closed.

EngineBusy

The engine is currently executing code for another thread.

RootMonikerAlreadySet

The engine attempted to change the RootMoniker property after it had been set.

RootMonikerInvalid

The value does not follow the correct syntax for a moniker.

RootMonikerInUse

The value is already in use by another engine.

RootMonikerProtocolInvalid

The protocol portion of the moniker is not valid.

Example

The following example shows how to set the RootMoniker property to a unique value. The object using the engine is an Order object exposed by the MyWebApp application, written by an independent software vendor (ISV).

// Create the script engine.
var pEngine : IVsaEngine = new ScriptEngine();

// The RootMoniker must be the first property set on the engine.
pEngine.RootMoniker = "com.theordercompany://MyWebApp/Order/Project1";

// Set the Site.
pEngine.Site = pMySite;

// Now other properties and methods can be called.
pEngine.LoadSourceState(pMyPersistSite);

See Also

Reference

IVsaEngine Interface