QTAssistant Shell provides support for automation through scripting. The scripts can be executed In-Process and Out-of-Process. A script running in-process has access to all shared resources in the QTAssistant shell; an out-of-process script execution relies on a separate surrogate .exe, and it has limited access to the resources in the QTAssistant shell.

The same surrogate .exe may be used to drive functionality using command line tools, or to create Windows Explorer shortcuts as a convenience method to easily invoke QTAssistant functionality, even without loading QTAssistant and its modules.

While some of the examples below use full path names to the executable, we do not consider it as a best practice. By default, QTAssistant installer uses a version specific directory for its files, including the surrogate .exe. As such, references that use the full path name for the surrogate .exe may not resolve anymore once a new version of QTAssistant is installed in another folder. Irrespective of the migration policies in effect for your QTAssistant deployment (e.g. side-by-side vs. single version in an invariable folder), we recommend the use of environment variables, such as QTASSISTANT_HOME to configure the use of a specific QTAssistant version, or PATH, by adding the install folder to it.

The following C# script (named Test.cs) is used to illustrate various ways to run a script using the command line interface.

class Script
{
    public static void Main(string[] args)
    {
        Console.WriteLine(Session.ScriptUri);
        if (args != null)
        {
            foreach (string arg in args)
            {
                Console.WriteLine(arg);
            }
        }
        else
        {
            Console.WriteLine("No arguments provided.");
        }
    }
}

 Windows Command Prompt

The surrogate .exe is a window application (as opposed to a console application). Therefore, the recommended way to invoke the executable under a Windows Command Prompt is based on the following stub:

start /b /wait Paschi.QTAssistant.Cli

This ensures that cmd waits for the application script to complete before returning to the command prompt which in turns means that the ERRORLEVEL is available for inspection. The following commands:

start /b /wait Paschi.QTAssistant.Cli
echo %ERRORLEVEL%

generate the output:

Starts a separate process to run a specified script.

Paschi.QTAssistant.Cli   /s:<script path> [/a:<assembly path>]
                         [/w: | /c:] [/p:<script parameter>]
    /s:<script path>       The full file name of the script to run.
    /a:<assembly path>     One full file name for each .NET assembly reference.
    /w:                    Display a separate window to capture messages.
    /c:                    Allow messages to be captured by the parent process.
    /p:<script parameter>  One for each parameter passed to the script.

The following command:

start /b /wait Paschi.QTAssistant.Cli  /s:"X:\...\Test.cs" /p:"Hello!"

generates the output:

Script: file:///X:/.../Test.cs
Hello!

Windows Desktop Shortcut

Setting up a script to run from a desktop shortcut requires very little effort; beside setting up the shortcut itself using one of the many ways supported in your version of Windows, the recommended way to setup the Target field is based on the following stub:

start /w: %QTASSISTANT_HOME%Paschi.QTAssistant.Cli.exe

If an environment variable is not desired, the full path can be used instead. The w switch is used for scenarios where a console is required to capture the messages generated by the script.

 The following shortcut target:

%QTASSISTANT_HOME%Paschi.QTAssistant.Cli.exe /w: /s:"X:\...\Test.cs" /p:Hello!

will run as follow:

MSBuild

The MSBuild's Exec task can be used to run the script; the typical way to setup it up is based on the following stub:

<Exec Command="&quot;$(QTASSISTANT_HOME)Paschi.QTAssistant.Cli.exe&quot; /c:" />

Other approaches may rely on pre/post-build events, using the same command as above.

The following pre-build event associated in a Microsoft Visual Studio project:

<PropertyGroup>
  <PreBuildEvent>$(QTASSISTANT_HOME)Paschi.QTAssistant.Cli.exe /c: /s:"X:\...\Testcs" /p:Hello</PreBuildEvent>
</PropertyGroup>

 with this MSBuild command line:

msbuild /nologo /t:Rebuild /verbosity:m /p:Configuration=Debug /p:Platform="Any CPU"

generates this output:

  ConsoleApplication2 -> X:\...\ConsoleApplication2\bin\Debug\ConsoleApplication2.exe
  Script: file:///X:/.../Test.cs
  Hello

Apache Ant Buildfile

 The Ant's Exec task can be used to run the script; the typical way to setup it up is based on the following stub:

<?xml version="1.0" encoding="UTF-8"?>
<project name="changeme" default="all" basedir=".">
    <property environment="env"/>
    <target name="qtassistant-cli">
        <exec executable="${env.QTASSISTANT_HOME}Paschi.QTAssistant.Cli.exe">
            <arg value="/c:"/> 
        </exec>
    </target>
</project>

 Consistent with the other examples, the following build file: 

<?xml version="1.0" encoding="UTF-8"?>
<project name="changeme" default="all" basedir=".">
    <property environment="env"/>
    <target name="qtassistant-cli">
        <exec executable="${env.QTASSISTANT_HOME}Paschi.QTAssistant.Cli.exe">
            <arg value="/c:"/>
            <arg value="/s:&quot;X:\...\Test.cs&quot;"/>
            <arg value="/p:Hello!"/> 
        </exec>
    </target>
</project>

 generates this output:

qtassistant-cli:
Script:file:///X:/.../Test.cs
Hello!