General ATF Scripting Support

Table of Contents Support Classes Scripting Components ScriptingService Class ScriptConsole Component AtfScriptVariables Component AutomationService Component AutomationService Constructor Key Methods Topics in this section

ATF provides facilities to script your applications. Scripts allow access to C# objects in the application's classes. Scripts have many uses. For example, you can create suites of tests for applications.

This section describes the general scripting facilities. As far as a specific scripting language goes, ATF provides support for Python. For details on Python scripting facilities, see Scripting Applications with Python and Writing Python Scripts for ATF Applications.

Support Classes

ATF's general scripting support comes in the following classes, which are MEF components or the base for them:

• ScriptingService: Base class for any scripting service component. For details, see ScriptingService Class.
• ScriptConsole: Scripting console window component. For a description of this class, see ScriptConsole Component.
• AtfScriptVariables: Component to set script variables for common ATF services. For the full list, see AtfScriptVariables Component
• AutomationService: Component that provides facilities to run automated scripts. For more information, see AutomationService Component.

Scripting Components

Nearly all the ATF sample applications support scripting, for Python in particular. Most of the samples have the following entries in their MEF TypeCatalog:

typeof(PythonService),                  // scripting service for automated tests
typeof(ScriptConsole),                  // provides a dockable command console for entering Python commands
typeof(AtfScriptVariables),             // exposes common ATF services as script variables
typeof(AutomationService)               // provides facilities to run an automated script using the .NET remoting service

In general, an application should import all of these components to provide the best scripting support.

ScriptingService Class

ScriptingService is an abstract base class for services (MEF components, for example) that can expose C# objects to a scripting language. This is the fundamental scripting class that specific scripting language services derive from.

ScriptingService offers the following methods for working with scripts:

• LoadAssembly(): Load the specified assembly into the script domain. This adds all the namespaces in the assembly to the script domain, so that you can import types (such as classes) from these namespaces. Many samples use this to load the application's assembly, as in:

m_scriptingService.LoadAssembly(GetType().Assembly);

• ImportType(): Imports the given type from the given namespace.
• ImportAllTypes(): Import all types from the given namespace. Nearly all the ATF samples call this to import all types from the sample's namespace. For instance, this statement is part of the ATF Circuit Editor Sample Editor component's initialization:

m_scriptingService.ImportAllTypes("CircuitEditorSample");

• TryGetVariable(): Check whether a variable is available in the script domain.
• SetVariable(): Make the given variable accessible to the script domain, associating the variable name with the given C# object. You can then use the variable in a script as you would the C# object, accessing its methods and properties, for example. You would generally not set this variable to another value in a script, because that would destroy its connection to the C# object.
• RemoveVariable(): Remove the given variable from the script domain.
• ExecuteStatement(): Execute a single script statement. The statement does not need a carriage return at the end. For example, the ATF State Chart Editor Sample calls this method in its Editor class to import types from a class:

m_scriptingService.ExecuteStatement("from Sce.Atf.Controls.Adaptable.Graphs import *");

• ExecuteStatements(): Execute multiple script statements. Each statement should end with a carriage return.
• ExecuteFile(): Execute the statements in the given file.
• SetEngine(): Set the scripting engine to a given language's engine. You must set this engine prior to using any scripts. The engine is a Microsoft.Scripting.Hosting.ScriptEngine object. This class represents a language in the Hosting API and is the Hosting API counterpart for Microsoft.Scripting.Hosting.ScriptEngine.LanguageContext. The BasicPythonService component calls this method to set up Python scripting.
• LoadDefaultAssemblies(): Load the initial assemblies into the given Microsoft.Scripting.Hosting.ScriptRuntime. This class represents a Dynamic Language Runtime in the Hosting API. It is the Hosting API counterpart for Microsoft.Scripting.Runtime.ScriptDomainManager. SetEngine calls LoadDefaultAssemblies() to load assemblies for the script engine runtime. SetEngine() calls this method for the given engine's ScriptRuntime.

ScriptConsole Component

ScriptConsole provides a dockable command console for entering script commands. It uses a ConsoleTextBox as the text box for a console. ConsoleTextBox derives from System.Windows.Forms.TextBox and also implements IConsoleTextBox. ScriptConsole is the control host client for the ConsoleTextBox.

IConsoleTextBox contains these useful properties and methods:

• Prompt: Get or set the command prompt. The default is ">>> ".
• CommandHandler: Set the command handler delegate that is called when a command is entered.
• Clear(): Clear the console window.
• EnterCommand(): Enter a command programmatically. The result is equivalent to manually typing the command and pressing the Enter key. The command doesn't need to terminate with a newline.
• Write(): Write the specified string to the console window.
• WriteLine(): Write the specified string to the console window, appending a newline character.
• Control: Get the underlying control for the console, which is a ConsoleTextBox.

ScriptConsole needs a ScriptingService, which it either imports or is specified in its constructor when MEF is not used. ScriptConsole has a private ProcessCommand() method to process console commands. ProcessCommand() uses ScriptingService to process the command. IConsoleTextBox.CommandHandler is set to ProcessCommand().

AtfScriptVariables Component

AtfScriptVariables exposes common ATF services as script variables, so that scripts can easily use these ATF services. AtfScriptVariables uses ScriptingService to set the variables.

In addition to ScriptingService, AtfScriptVariables imports numerous common ATF services, such as the Control Host Service:

[Import(AllowDefault = true)]
private IControlHostService m_controlHostService = null;

These services are all imported with AllowDefault = true in case the service is not used by the application.

A variable is associated with each service by calling the ScriptingService.SetVariable() method, as in this statement:

if (m_controlHostService != null)
    m_scriptingService.SetVariable("atfControls", m_controlHostService);

The script variables and services set by AtfScriptVariables are listed in this table:

Script variable	Service
atfControls	IControlHostService
atfCommands	ICommandService
atfSelect	StandardSelectionCommands
atfFile	StandardFileCommands
atfFileExit	StandardFileExitCommand
atfEdit	StandardEditCommands
atfHistory	StandardEditHistoryCommands
atfContextReg	IContextRegistry
atfDocReg	IDocumentRegistry
atfDocService	IDocumentService
atfPropertyEditor	PropertyEditor

Scripts can use any of these variables on applications that import AtfScriptVariables.

AutomationService Component

AutomationService provides facilities to run an automated script. It also allows using the .NET remoting service to run a script. AutomationService tries to import LiveConnectService, which can be used for communication, if available. For more information, see LiveConnectService Component.

AutomationService derives from MarshalByRefObject. AutomationService is marshaled explicitly by registering the MarshalByRefObject object with the remoting infrastructure in the AutomationService's StartService() method, called by its IInitializable.Initialize() method. This allows creating a proxy for AutomationService in another process, so that the two processes can communicate.

ATF provides several test classes that can be used to run scripts, FunctionalTestBase and TestBase. ATF's test code uses these classes to create a test application that runs as a separate process from the ATF application. When AutomationService is part of the ATF application, the test application can marshal the AutomationService so the processes communicate with each other. For details about ATF's testing facilities and these testing classes, see ATF Test Code.

AutomationService Constructor

The constructor for AutomationService checks whether AutomationService command line arguments were used to run the application:

• -automation: Use AutomationService. This must be set in the command line for the application to run scripts using AutomationService.
• -port <number>: Use this port number for TCP communcation, using a default value if not provided.

Key Methods

These are the methods of note in AutomationService:

• IInitializable.Initialize(): Initialize the AutomationService, calling StartService() to marshal AutomationService. If LiveConnect is running, subscribe to its MessageReceived event to receive LiveConnect broadcast messages.
• StartService(): Start the .NET remoting service, marshaling the AutomationService for interprocess communication.
• Connect(): Called by a test client to verify the connection to AutomationService is ready. If this call throws an exception, most likely AutomationService has not yet finished starting. It returns false if the application's main form has not finished loading yet.
• ExecuteStatement(): Execute a given single statement. The statement is executed using a Dispatcher object created by StartService(). Another process can invoke this method to execute a statement.
• ExecuteScript(): Execute a given script file. The script is executed using a Dispatcher object created by StartService(). Another process can invoke this method to run scripts. For example, FunctionalTestBase calls this method to process scripts. For details, see FunctionalTestBase Class.
• SendMessage(): Send a message using LiveConnect.
• GetLastMessage(): Get the last message received from LiveConnect.

Topics in this section