IVsaEngine.Name Property
Sets or gets the display name of the script engine that is used primarily for identifying individual script engines to users in a hosted environment.
public: _property String* get_Name();
public: _property void set_Name(String* value);
public string Name { get; set; }
Property Get Name() As String
Public Property Let Name(ByVal value As String)
Return Value
Returns the value of the script engine's Name property, which may be the empty string.
Remarks
The IVsaEngine.Name property is used primarily for identifying individual script engines. The Name property does not need to be globally unique, as the IVsaEngine.RootMoniker property is the script engine's unique identifier. However, every script engine hosted by an application simultaneously must have a unique Name property, as designated by the host. In general it is not possible for one script engine implementation to know the names of other script engines. Nevertheless, a script engine may throw an EngineNameInUse exception if it detects that two of its own instances have the same name.
In other words, it is legal for a host to have multiple instances, each of which has an engine with the name "MyEngine," but it is not legal for a single instance to have two script engines with the name "MyEngine" hosted at the same time. The exception to this rule is that more than one script engine can have a blank Name property in the form of an empty string.
The default value of the Name property is the empty string; furthermore, there is no requirement that this property be set. If this property is set by the host, it can contain any valid string, as the IVsaEngine interface does not impose any semantics on the string.
The following table shows the exceptions that the Name 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. |
EngineNotInitialized |
The engine has not been initialized. |
EngineRunning |
The engine is currently running. |
EngineNameInUse |
The specified engine name is already in use by another engine. |
Example
The following example creates a new script engine and attempts to give it a default name. If the name is already in use, a counter is incremented and the attempt is made to set the name again.
// Create a new script engine.
var newEngine : IVsaEngine = new ScriptEngine();
// Start counting at 1.
var iNameCounter : int = 1;
do
{
try
{
// Set the name to "Engine1", "Engine2", "Engine3"
// and so on until the name is unique.
newEngine.Name = "Engine" + iNameCounter;
break;
}
catch(e : VsaException)
{
// Only expect a duplicate name exception; anything
// else needs to be dealt with elsewhere.
if (e.ErrorNumber != VsaError.EngineNameInUse)
throw(e);
}
// Try the next number.
iNameCounter++
// Loop until the name is set correctly and the
// break statement is executed.
} while (true);