Managing Profiling Areas via COM

Basic Concepts

Step-by-Step Procedure

Full Code Example

Typical Tasks

Some Tips

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.

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.

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

ExampleExample

Visual Basic

' Connect to AQTime and open a project
Set AQtimeObject = CreateObject("AQtime.AQtime")
Set IntegrationManager = AQtimeObject.IntegrationManager
IntegrationManager.OpenProject(...)
 
' Obtain the area manager
Set AreaManager = IntegrationManager.AreaManager
' Obtain the debug info manager
Set DebugInfoManager = IntegrationManager.DebugInfoManager

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

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

ExampleExample

Visual Basic

...
' Obtain the debug info manager
Set DebugInfoManager = IntegrationManager.DebugInfoManager
 
' Iterate through modules
For i = 0 To DebugInfoManager.ModuleCount - 1
  Set ModuleObject = DebugInfoManager.Module(i)
  ' Check the module name
  If InStr(ModuleObject.Name, "MyApp.exe") Then
    ' Process the module
  End If
Next
...

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

ExampleExample

Visual Basic

...
' Obtain the debug info manager
Set DebugInfoManager = IntegrationManager.DebugInfoManager
 
' Iterate through modules
For i = 0 To DebugInfoManager.ModuleCount - 1
  Set ModuleObject = DebugInfoManager.Module(i)
  If InStr(ModuleObject.Name, "MyApp.exe") Then
  ' Iterating through classes
    For j = 0 To ModuleObject.ItemCount(5) - 1
      Set ClassObject = ModuleObject.Item(5, j)
      ' Do something ...
    Next
    
  End If
...

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

ExampleExample

Visual Basic

...
' Obtain the debug info manager
Set DebugInfoManager = IntegrationManager.DebugInfoManager
 
' Iterate through modules
For i = 0 To DebugInfoManager.ModuleCount - 1
  Set ModuleObject = DebugInfoManager.Module(i)
  If InStr(ModuleObject.Name, "MyApp.exe") Then
  ' Iterate through source files
    For j = 0 To ModuleObject.ItemCount(2) - 1
      Set SourceFileObject = ModuleObject.Item(2, j)
      ' Do something ...
    Next
    
  End If
...

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

ExampleExample

Visual Basic

...
' Iterating through classes
For j = 0 To ModuleObject.ItemCount(5) - 1
  Set ClassObject = ModuleObject.Item(5, j)
  For k = 0 To ClassObject.ItemCount(6) - 1
    Set RoutineObject = ClassObjectItem(6, k)
    If RoutineObject.Name = "MyFoo" Then
      ' Do something ...
    End If
  Next
Next
...

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

ExampleExample

Visual Basic

...
' AreaObject is an object that corresponds to a profiling area
' DbgSymbol is any debug symbol object (unit, source file, class, routine, unit, or other)
Set AreaItem = AreaObject.AddItem(DbgSymbol)
...

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

ExampleExample

Visual Basic

...
Set AreaItem = AreaObject.AddItem(DbgSymbol)
' Unselect the area item
AreaItem.Enabled = False
...

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

Example

ExampleExample

VBScript

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

' Obtain the IntegrationManager object
Set IntegrationManager = AQtimeObject.IntegrationManager

' Open a project
If Not IntegrationManager.OpenProject("C:\My Projects\My_AQtime_Project.aqt") Then
  ' Unable to open the project
  AQtimeObject.Quit
  Exit Sub 
End If
 
' Obtain the area manager
Set AreaManager = IntegrationManager.AreaManager
' Obtain the debug info manager
Set DebugInfoManager = IntegrationManager.DebugInfoManager
  
' Create a new area
Set AreaObject = AreaManager.AddArea("", 0, 2)
  
' Iterate through modules
For i = 0 to DebugInfoManager.ModuleCount - 1
  Set ModuleObject = DebugInfoManager.Module(i)
  ' Check the module name
  If InStr(ModuleObject.Name, "MyApp.exe") Then

    ' Iterate through classes of the module
    For j = 0 To ModuleObject.ItemCount(5) - 1
      Set ClassObject = ModuleObject.Item(5, j)
      If ClassObject.Name = "MyClass" Then
          
        ' Iterate through routines
        For k = 0 To ClassObject.ItemCount(6) - 1
          Set RoutineObject = ClassObject.Item(6, k)
          If RoutineObject.Name = "MyFoo" Then
            ' Add the routine to the profiling area
            AreaObject.AddItem(RoutineObject)
          End If
        Next

      End If
    Next
  End If

Next 

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

ExampleExample

Visual Basic

' Connect to AQTime and obtain the IntegrationManager object
Set AQtimeObject = CreateObject("AQtime.AQtime")
Set IntegrationManager = AQtimeObject.IntegrationManager
  
' Open a project
If Not IntegrationManager.OpenProject("C:\My Projects\MyApp_exe.aqt") Then
  ' Unable to open the project
  AQtimeObject.Quit
  Exit Sub 
End If

' Obtain the area manager and debug info manager
Set AreaManager = IntegrationManager.AreaManager
Set DebugInfoManager = IntegrationManager.DebugInfoManager
  
' Create a new area (default name, routine-level, including)
Set AreaObject = AreaManager.AddArea("", 0, 2)
  
' Iterate through modules
For i = 0 to DebugInfoManager.ModuleCount - 1
  ' Obtain a module debug symbol
  Set ModuleObject = DebugInfoManager.Module(i)
  ' Check the module name
  If InStr(ModuleObject.Name, "MyApp.exe") Then

    ' Iterate through source files
    For j = 0 To ModuleObject.ItemCount(2) - 1
      ' Obtain a debug symbol that corresponds to a source file
      Set SrcFileDbgSymbol = ModuleObject.Item(2, j)
      ' Check the source file name
      If InStr(SrcFileDbgSymbol.Name, "MySourceFile.cs") Then
         ' Add the source file to the profiling area
          AreaObject.AddItem(SrcFileDbgSymbol)
      End If
    Next

  End If
Next

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

ExampleExample

Visual Basic

' Connect to AQTime and obtain the IntegrationManager object
Set AQtimeObject = CreateObject("AQtime.AQtime")
Set IntegrationManager = AQtimeObject.IntegrationManager
  
' Open a project
If Not IntegrationManager.OpenProject("C:\My Projects\MyApp_exe.aqt") Then
  ' Unable to open the project
  AQtimeObject.Quit
  Exit Sub 
End If

' Obtain the area manager and debug info manager
Set AreaManager = IntegrationManager.AreaManager
Set DebugInfoManager = IntegrationManager.DebugInfoManager
  
' Create a new area (default name, routine-level, including)
Set AreaObject = AreaManager.AddArea("", 0, 2)
  
' Iterate through modules
For i = 0 to DebugInfoManager.ModuleCount - 1
  ' Obtain a module's debug symbol
  Set ModuleObject = DebugInfoManager.Module(i)
  ' Check the module name
  If InStr(ModuleObject.Name, "MyApp.exe") Then

    ' Iterate through classes
    For j = 0 To ModuleObject.ItemCount(5) - 1
      ' Obtain the class debug symbol
      Set ClassDbgSymbol = ModuleObject.Item(5, j)
      ' Check the source file name
      If InStr(ClassDbgSymbol.Name, "unitTesting_") Then
         ' Add the class to the profiling area
          AreaObject.AddItem(ClassDbgSymbol)
      End If
    Next
 
  End If
Next

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:

• Important: AQTime stores settings of the predefined areas for each profiler. So if you need to set up predefined areas, do this after you select the desired profiler.

• The Allocation and Reference Count profilers support both Classes to Profile and Collect Stack Information panes. Each of these panes contains predefined areas. To work with them, you should use different properties. For detailed information, see IaqCOMAccessAreaManager Object.

Example

ExampleExample

Visual Basic

' Connect to AQTime and obtain the IntegrationManager object
Set AQtimeObject = CreateObject("AQtime.AQtime")
Set IntegrationManager = AQtimeObject.IntegrationManager
  
' Open a project
  If Not IntegrationManager.OpenProject("C:\My Projects\MyApp_exe.aqt") Then
    ' Unable to open the project
    AQtimeObject.Quit
    Exit Sub 
End If
 
' Select the desired profiler
If Not IntegrationManager.SelectProfiler("Performance Profiler") Then
  ' The specified profiler was not found
   AQtimeObject.Quit
  Exit Sub
End If

' Obtain the area manager and debug info manager
Set AreaManager = IntegrationManager.AreaManager

' Activate the All Project Modules area
AreaManager.FullCheck = True
AreaManager.FullCheckLevel = 1 ' Set the Routine level for All Project Modules
  
' Disable the Entire .NET Code area
AreaManager.ProfileEntireDotNetCode = False
' Disable the Entire Java Code area
AreaManager.ProfileEntireJavaCode = False
  
' Activates the Entire Script Code area
AreaManager.ProfileEntireScriptCode = True
AreaManager.ProfileEntireScriptCodeLevel = 2 ' Set the Line level
  

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

ExampleExample

Visual Basic

' Connect to AQTime and obtain the IntegrationManager object
Set AQtimeObject = CreateObject("AQtime.AQtime")
Set IntegrationManager = AQtimeObject.IntegrationManager
  
' Open a project
If Not IntegrationManager.OpenProject("C:\Users\Public\Documents\AQtime 8 Samples\Managed\VS2005\Coverage\CS\Coverage_exe.aqt") Then
  ' Unable to open the project
  AQtimeObject.Quit
  Exit Sub 
End If

' Obtain the area manager and debug info manager
Set AreaManager = IntegrationManager.AreaManager
 
' Disable predefined areas
AreaManager.FullCheck = False
AreaManager.ProfileEntireDotNetCode = False
AreaManager.ProfileEntireJavaCode = False
AreaManager.ProfileEntireScriptCode = False

' Create a new area
Set AreaObject = AreaManager.AddArea("My Area", 0, 2)
  
' ...
' Add the needed code parts to the area
' ...
  
' Iterate through profiling areas and disable them
For i = 0 To AreaManager.AreaCount - 1
  ' Obtain the area object
  Set AreaObject = AreaManager.Area(i)
  ' If the area is the needed area...
  If AreaObject.Name = "My Area" Then
    ' Enable the area items
    For j = 0 To AreaObject.ItemCount - 1
      Set AreaItemObject = AreaObject.Item(j)
      AreaItemObject.Enabled = True
    Next
  Else
    ' Else, disable the area items
    For j = 0 To AreaObject.ItemCount - 1
      Set AreaItemObject = AreaObject.Item(j)
      AreaItemObject.Enabled = False
    Next
  End If
Next 

• 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.