Managing Profiling Areas via COM

Applies to AQTime 8.81, last modified on January 18, 2022

This topic explains how you can create profiling areas, modify and remove profiling areas via AQTime COM interfaces. It contains the following sections:

Basic Concepts

Profiling areas help you specify which parts of your application are to be profiled and how (see About Areas).

Each area includes one or more classes, routines, units and other elements that correspond to various parts of your application’s code. AQTime obtains information about routines, classes, units and other code parts of your application from debug information. In AQTime terms, profiling areas contain not units, classes and routines, but debug symbols that correspond to these units, classes and routines. So, in order for you to include some code in profiling tasks, you need to have a reference to the desired profiling area and to the debug symbol that corresponds to the desired code part.

AQTime includes two internal objects that provide a programming interface to profiling areas and to the debug information storage of your project:

  • The area manager provides access to profiling areas. Using this object you can create, modify and remove profiling areas as well as change settings of predefined areas (like All Project Modules or Entire .NET Code). The area manager implements the IaqCOMAccessAreaManager interface.

  • The debug info manager provides access to debug symbols (routines, classes, units and so on), which you can add to profiling areas. The area manager object implements the IaqCOMAccessDebugInfoManager interface.

Using the area manager and debug info manager objects you can create new and delete existing areas, add classes, routines, units and other code parts to areas, modify area attributes like the profiling level and perform other actions.

Note: If the currently selected profiler supports stack areas, you can create and modify them in the same way you create profiling areas (see a step-by-step description below). After you create a routine-level or a line-level profiling area, AQTime automatically recognizes it as a stack area and collects stack data for all routines specified in this area.

One of the most frequent tasks is adding classes, routines or files to some profiling area. To do this, you perform the following operations:

  1. Connect to AQTime via COM and open your profiling project in AQTime.

  2. Obtain references to AQTime’s objects that provide access to profiling areas and debug information.

  3. Create a new profiling area or obtain the existing area in which you would like to include classes, files or routines.

  4. Obtain debug symbols that correspond to the class, unit, or routine to be added to an area.

  5. Add the debug symbols to the area.

Let’s go through these steps in details.

Step-by-Step Procedure

1. Connecting to AQTime and Opening a Project

For information on connecting to AQTime via COM and opening an AQTime project, see Working With AQTime via COM - Overview.

It is important to open your project prior to working with area and debug info managers. These objects exists only if there is an open project.

2. Obtaining the Area Manager and Debug Info Manager Objects

To create a profiling area and to add code parts to it, you have to obtain the area manager and debug info manager objects. To do this, use the AreaManager and DebugInfoManager properties of AQTime’s IntegrationManager object:

Example

After you obtain the area and debug info managers, you can use their methods and properties to create, modify or remove areas, and to add units, classes, routines and other code elements to the areas.

Note: The area and debug info manager objects are available only if there is an open project in AQTime. Otherwise, the AreaManager and DebugInfoManager properties return null.

3. Obtaining the Profiling Area

The next step is to obtain a programming interface to the desired profiling area. You can either create a new area, or find an existing area:

  • To create a new area, use the AddArea(AreaName, AreaType, AreaLevel) method of the area manager object:

    Example

  • To get a reference to an existing area, use the Area(Index) or AreaByName(AreaName) property of the area manager object:

    Example

4. Obtaining Debug Symbols to Be Included In the Area

AQTime gets routine, class and unit names defined in your application from the application’s debug information. To add a routine, class or file to a profiling area, you need to find a debug symbol that corresponds to the desired routine, class or file.

To obtain the needed debug symbols, you have to iterate through debug information. You start iteration with the Module(Index) and ModuleCount properties of the debug info manager object. The ModuleCount property returns the total number of modules in the project, and the Module property provides access to debug information of a module by the module’s index:

Example

The Module property returns an IaqCOMAccessDbgModule object that provides a programming interface to the “module” debug symbol. All the debug symbols have the FullName and Name properties. In our example above, we check the Name property of the debug symbol to determine if it corresponds to the module we need. This property returns the fully-qualified file name of the module which can change from one computer to another, so we search for the application’s file name within the string returned by the Name property (see below).

After you obtain the debug symbol for a module, you can obtain debug symbols that correspond to units, classes, routines, namespace and source files included in the module. You do this by using the ItemCount(DbgType) and Item(DbgType, Index) properties of the “module” object. The DbgType parameter specifies the type of the debug symbol you would like to obtain: a routine, class, unit and so on. It is a value of the TDebugType enumeration type, or the appropriate integer value. Below are some frequently used constants:

Constant Value Description
dtSourceFile 2 Source file
dtUnit 3 Unit.
dtClass 5 Class
dtRoutine 6 Routine (function, procedure, method).

For complete information on the available values, see the description of the TDebugType enumeration type.

The following code demonstrates, how you can enumerate all the classes defined in the module:

Example

To iterate through debug symbols of another type, you simply pass another constant to the Item and ItemCount properties. For instance, the following code enumerates source files included in the module:

Example

After you obtain the desired class or file, you can iterate through its methods. Each debug symbol that corresponds to some “containers” (that is, to a class, file, unit, package, or namespace) contains the Item and ItemCount properties that let you iterate through symbols in this “container”. For example, the following code demonstrates how to iterate through routines that belong to some class:

Example

Note: The debug info storage does not have a strict hierarchy. So, to obtain a routine, for example, you can first find the class that contains this routine and then search for the routine within that class, or find a source file that contains the routine and then search for the routine in the file, or search for the routine in the module.

5. Adding Debug Symbols to Areas

To add debug symbols to an area, use the AddItem method of the area object. This is very simple:

Example

The method returns the IaqCOMAccessAreaItem object that provides an interface to the area item (that is, to the routine, class, unit or other code part that was added to the area). You can use the object’s Enabled property to select or unselect the item within the area.

Example

Full Code Example

Below is the full code of a sample that demonstrates how to append a routine to a profiling area:

Example

Typical Tasks

The following code snippets demonstrate how to perform typical tasks that concern managing profiling areas via COM.

Including source files in profiling

You may need to include entire units or source files in profiling tasks. By including a source file, you command AQTime to profile all the routines defined in this source file (or to ignore all the routines if the area has the excluding type), so you do not have to add each routine. This is especially convenient for coverage profiling. The following code demonstrates how to iterate through debug symbols and find the desired source files:

Example

AQTime uses file names in the format, in which they are included in debug information. Depending on the compiler that was used to build your application, this information can include fully-qualified file names or file names without paths, that is, the file name can be a substring of the string that is returned by the FullName or Name property. So, it is recommended to search for a file name like a substring within the string that is returned by the FullName or Name properties.

This approach lets you easily vary the search criteria, for example --

  • You can search for files located in certain folders by checking the folder name in the string returned by the FullName or Name property. This helps you profile only your files and skip the MFC or VCL unit.

  • You can search for files whose names have certain prefix or postfix. For instance, you can skip files that have unitTesting_ prefix in their names.

Including classes with specific names

You may need to include specific classes in profiling. For instance, these can be unit testing classes whose names start with some prefix, say, unitTest_. To add these classes to profiling, iterate through debug symbols and search for the classes whose names contain the prefix. For following code snippet demonstrates how you can do this:

Example

Managing a Predefined Area

AQTime has a number of predefined areas that let you easily include the whole application code in profiling tasks: All Project Modules, Entire .NET Code, Entire Java Code and others. The area manager object contains properties that let you enable or disable these predefined areas and change their levels. The sample code below demonstrates how you can manage predefined areas.

Notes:

Example

Enabling and disabling profiling areas and area items

In certain cases, you may need to disable all the profiling areas and enable only the area that contains the needed files, classes or routines. AQTime does not have a method or property that lets you enable or disable an area, because the area’s “enabled/disabled” attribute depends on whether the area items are enabled or disabled. So, to disable an area, you have to iterate through its items and disable each item in it. Similarly, to enable an area, you have to iterate through its items and enable the needed items. The following code demonstrates how you can accomplish this task:

Example

Some Tips

  • Search for substrings in module or file names.

    All the debug symbols have the FullName and Name properties. You use them to determine the routine, class, unit or other code part to which this or that symbol corresponds. The Name property specifies the name of the code part, for instance, a class name or a routine name. FullName specifies the code part name along with the names of the parent parts, for instance, a routine’s full name can include a class name and the full name of a class can include a namespace or the names of parent classes.

    For some objects, for example, for modules and source files, the FullName and Name properties return the same values. So, when iterating through modules or files, it is not recommended to compare strings, it is recommended to search for a module or file name within the FullName or Name value. In code snippets above you can see that we follow this recommendation.

  • Add larger code parts rather than routines.

    If you need to profile routines defined in a source file, unit or class, you can add the entire source file, unit or class to profiling areas. This automatically includes all the routines defined in this class, source file or unit in the profiling area, so you do not have to iterate through the routines and append each of them.

  • Search in several steps.

    The debug info storage does not have a strict hierarchy. Once you obtain a debug symbol corresponding to a module, you can then search for routines included in this module. However, there can be several classes that contain the same routines. To avoid confusion, you can search for the source file or class first, and then iterate through the routines defined in this file or class.

See Also

Working With AQTime via COM - Overview
COM Type Reference
Automating AQTime

Highlight search results