AQTime is a COM server and it can be controlled from other applications like any other COM server. Other SmartBear applications, for example, TestComplete, use much of it to integrate AQTime tests and results. This topic provides a step-by-step explanation of how you can control AQTime via COM from Visual Basic and Visual C++ applications. For information on automating AQTime from managed code (for instance, C#), see Working With AQTime From Managed Code.

In this topic:

Connecting to AQTime via COM

Using IntegrationManager to Automate AQTime

Working With Profiling Areas

Three notes before we proceed:

A simple alternative to profiling your applications with AQTime via COM is to run AQTime and pass it certain command-line arguments. See AQTime Command Line for more information.
COM commands work if only one instance of AQTime is running.
To automate AQTime via COM on Windows Vista and later, your COM client application must be running with administrator privileges.

Setting up Visual Basic

To work with AQTime in your VB application, add a reference to the AQTime object library to your application that will use AQTime as a COM server. The following steps explain how you can do this. Note that this step is optional. It is not required if you will work with AQTime via IntegrationManager (see below).

Open your COM client application in Microsoft Visual Basic.
Select Project > References from Visual Basic menu. This will call the References dialog.
In the dialog, check SmartBear AQTime Library and press OK. This will add a reference to the AQTime object library to your COM client application:

If AQTime library is not present in the dialog, you can add it directly by pressing Browse and selecting the <AQTime>\Bin\AQTime.exe file in the ensuing Open File dialog.

Setting Up Visual C++

To automate AQTime from a Visual C++ application, you need to include the AQtimeConstants.h header file in your project. This file contains the CLSID of the AQTime COM object and imports the AQTime type library information. It is shipped with AQTime SDK and is located in the <AQTime SDK>\CPP\Common folder.

In order for the compiler to be able to find this header file, you need to add the <AQTime SDK>\CPP\Common folder to your project’s search directories. To do this:

From the Visual C++ menu, select Project > Properties. The Property Pages dialog box will open.
In the tree on the left of the dialog, select the Configuration Properties > C\C++ > General property page.
In the Additional Include Directories property value, specify the fully-qualified path to the <AQTime SDK>\CPP\Common folder.

Then add the following line to the precompiled header file (usually stdafx.h) or the source file that will contain the AQTime automation code:

Visual C++

#include <AQtimeConstants.h>

Connecting to AQTime via COM

The first step in using AQTime as a COM server is connecting to it. To create a connection, you have to create reference to AQTime object. This object implements methods and properties to connect and work with AQTime.

In Visual Basic, you can create the AQTime COM object by calling the CreateObject function with the AQtime.AQtime or AQtime.AQtime.8 ProgID as a parameter:

Visual Basic

Set AQtimeObject = CreateObject("AQtime.AQtime")

In Visual C++, you can create the AQTime COM object either by using the CoCreateInstance function or the ATL smart pointer class CComPtr and its CComPtr::CoCreateInstance method (recommended). The CLSID is specified via the CProductAQtime constant from the AQTime SDK’s AQtimeConstants.h file:

Visual C++

CComPtr<IAQtimeManager> aqTimeManager;
HRESULT hr = aqTimeManager.CoCreateInstance(CProductAQtime);

The code above will connect your COM client application to the currently running instance of AQTime. If AQTime has not been launched yet, this code will launch it.

The AQtime object contains the following methods and properties:

Property (Method)	Description
`Quit`	Method. Use it to exit AQTime.
`Manager`	Property. Returns a reference to the `IaqBaseManager` object that provides access to internal AQTime interfaces. These are the same interfaces that different components of AQTime use to connect and work with each other. Using these interfaces you can perform almost any action that you can do via AQTime’s user interface.
`IntegrationManager`	Property. Returns a reference to the `IaqTimeIntegrationSupportManager` object (hereinafter we will call it `IntegrationManager` for short). It provides access to a subset of higher-level functions specifically engineered to let users perform most typical actions over AQTime with ease. For a list of these functions, see IaqTimeIntegrationSupportManager Object.

Functionality provided by IntegrationManager is less than what you could do if you would decide to use Manager. However, use of IntegrationManager is much more easier. For instance, you can start the profiler run and save results by calling only one IntegrationManager’s method. If you used Manager, you would have to write more complex code.

If you will work with AQTime via the IntegrationManager property, you may skip the Setting up Visual Basic step (see above).

Using IntegrationManager to Automate AQTime

The IntegrationManager includes methods and properties that let you easily perform typical tasks over AQTime: open a project, select and run a profiler and save profiling results to a file. For detailed information, see IaqTimeIntegrationSupportManager Object.

Using the IntegrationManager is the easiest way to automate AQTime. Let’s create sample code that will:

Connect to AQTime via COM.
Open a project.
Select a profiler.
Start profiling and save results to an .xml file.

To perform these tasks, we will use only three methods and one property of the IntegrationManager object: OpenProject, SelectProfiler, Start and ProfilingStarted. The code snippet below also demonstrates how you can specify run parameters:

View Sample Code

Hide Sample Code

Visual Basic

Sub AutomateAQtime()
Dim AQtimeObject, IntegrationManager, RunMode, aParamValue

' Connects to AQTime
Set AQtimeObject = CreateObject("AQtime.AQtime")

' Obtains the IntegrationManager
Set IntegrationManager = AQtimeObject.IntegrationManager

' Loads the project
If Not IntegrationManager.OpenProject("C:\Work\MyVCApp\Debug\MyVCApp.aqt") Then
    MsgBox "Cannot open the specified project."
    AQtimeObject.Quit
   Exit Sub
End If

' Selects the desired profiler
If Not IntegrationManager.SelectProfiler("Performance Profiler") Then
    MsgBox "The specified profiler was not found."
    AQtimeObject.Quit
   Exit Sub
End If

' Obtain the object for the "Normal" profiling mode
RunMode = IntegrationManager.GetRunMode(4)

' Get the "Work Directory" parameter
aParamValue = RunMode.GetParameterValue(2)

' If the parameter is empty assign a value
If aParamValue = Nothing Then
    RunMode.SetParameterValue(2, "C:\Work")
End If

' Select "Normal" profiling mode
IntegrationManager.SelectRunMode("Normal")

' Add new module to AQTime project
IntegrationManager.AddModule("C:\Work\MyApp.exe")

' Starts profiling and saves results to xml files
Call IntegrationManager.Start("C:\SummaryResults.xml", _
                               "C:\ProfilingResults.xml")

' Waits until profiling is over
While IntegrationManager.ProfilingStarted
    DoEvents
WEnd

' Remove previously added module
IntegrationManager.RemoveModule("C:\Work\MyApp.exe")

' Closes AQTime
  AQtimeObject.Quit
End Sub

Visual C++

/* stdafx.h */
...
#include <AQtimeConstants.h>

/* AQtimeAutomation.cpp */
#include "stdafx.h"
...

HRESULT AQtimeAutomation()
{
    HRESULT hr;

    hr = CoInitialize(NULL);
    if (FAILED(hr)) return hr;

    // Connect to AQTime
    CComPtr<IAQtimeManager> aqTimeManager;
    hr = aqTimeManager.CoCreateInstance(CProductAQtime);
    if (FAILED(hr)) return hr;

    // Obtain the IntegrationManager object
    CComPtr<IaqTimeIntegrationSupportManager> integrationManager;
    hr = aqTimeManager->get_IntegrationManager(&integrationManager);
    if (FAILED(hr)) return hr;

    VARIANT_BOOL res;

    // Open an AQTime project
    hr = integrationManager->OpenProject(CComBSTR(L"C:\\Work\\MyVCApp\\Debug\\MyVCApp.aqt"), &res);
    if (FAILED(hr)) return hr;

    if (res == VARIANT_FALSE)
    {
        MessageBoxW(NULL, L"Cannot open the specified project.", L"AQtime Automation", MB_ICONERROR>MB_OK);
        aqTimeManager->Quit();
        return E_FAIL;
    }

    // Activate the Performance profiler
    hr = integrationManager->SelectProfiler(CComBSTR(L"Performance Profiler"), &res);
    if (FAILED(hr)) return hr;

    if (res == VARIANT_FALSE)
    {
        MessageBoxW(NULL, L"The specified profiler was not found.", L"AQtime Automation", MB_ICONERROR>MB_OK);
        aqTimeManager->Quit();
        return E_FAIL;
    }

    // Configure parameters for the "Normal" profiling mode

    // Get the object corresponding to the "Normal" profiling mode
    CComPtr<IaqTimeIntegrationRunMode> runMode;
    hr = integrationManager->GetRunMode(4, &runMode);
    if (FAILED(hr)) return hr;

    // Get the "Work Directory" parameter
    CComVariant workDirParam;
    CComVariant outValue;
    hr = runMode->GetParameterValue(2, &workDirParam);
    if (FAILED(hr)) return hr;

    // If the parameter is empty, assign a value
    if ((workDirParam.ChangeType(VT_BSTR) == S_OK) && (CComBSTR(workDirParam.bstrVal).Length() == 0))
    {
        hr = runMode->SetParameterValue(2, CComVariant(L"C:\\Work"), &outValue);
        if (FAILED(hr)) return hr;
    }

    // Activate the "Normal" profiling mode
    hr = integrationManager->SelectRunMode(CComBSTR(L"Normal"));
    if (FAILED(hr)) return hr;

    // Add a new module to the AQTime project
    hr = integrationManager->AddModule(CComBSTR(L"C:\\Work\\MyApp.exe"));
    if (FAILED(hr)) return hr;

    // Start profiling and specify to save results to xml files
    hr = integrationManager->Start(CComBSTR(L"C:\\SummaryResults.xml"), CComBSTR(L"C:\\ProfilingResults.xml"), &res);
    if (FAILED(hr)) return hr;

    // Wait until profiling is finished
    VARIANT_BOOL profilingStarted;
    do
    {
        hr = integrationManager->get_ProfilingStarted(&profilingStarted);
        if (FAILED(hr)) return hr;
        Sleep(200);
    }
    while (profilingStarted != VARIANT_FALSE);

    // Remove the previously added module from the AQTime project
    hr = integrationManager->RemoveModule(CComBSTR(L"C:\\Work\\MyApp.exe"));
    if (FAILED(hr)) return hr;

    // Close AQTime
    hr = aqTimeManager->Quit();
    if (FAILED(hr)) return hr;

    return S_OK;
}

C#

For sample code that demonstrates AQTime automation from C# applications, see Working With AQTime From Managed Code.

Two notes:

Both Start and Attach methods returns immediately after profiling is started. If you try to close AQTime when it is profiling an application (this happens, for example, when you call Quit right after Start), AQTime displays a message that asks you whether you want to close application and terminate profiling. To avoid this message, we used a loop that waits until the profiling is over.
Settings of profiling areas and triggers, selected profiling mode (Normal, ASP.NET, IIS, Service or COM Server), currently selected profiler, and others, are stored in AQTime project files. When you profile your application using the Start or Attach methods of the IntegrationManager object, AQTime uses profiling mode and area and trigger settings stored in your AQTime project.

Therefore, we recommend to prepare your project in AQTime before you profile that project with AQTime via COM.

Working With Profiling Areas

Using AQTime COM interfaces, you can create, remove and modify profiling areas of your projects. For complete information on how to do this, see Managing Profiling Areas via COM.

Working With AQTime via COM - Overview

Setting up Visual Basic

Setting Up Visual C++

Connecting to AQTime via COM

Using IntegrationManager to Automate AQTime

Working With Profiling Areas

See Also