Modifying Instrumentation Programmatically

As mentioned before, instrumentation can quickly generate a lot of data. There are ways to control which parts of your binaries generate this data so you can create reports that are focused only on the areas you wish to observe. This also has the welcome effect of reducing the impact that instrumentation will have on your running application.

Visual Studio features code to help you identify areas that should be included or excluded from instrumentation. For managed code, use the Microsoft.VisualStudio.Profiler assembly, located in your Visual Studio installation directory under \Team Tools\Performance Tools. If you are working with unmanaged code, use the VSPerf.lib and VSPerf.h files, found in the PerfSDK subdirectory. We focus on managed code in this section.

Microsoft.VisualStudio.Profiler features a DataCollection class that can be used to enable and disable profiling. The two methods of greatest interest here are StartProfile and StopProfile. Use these calls to wrap a region of your code for which you want to control profiling. Both methods accept a DataCollection.ProfileLevel enumeration value and an identifier that is related to the chosen ProfileLevel.

In the following code, we wish to profile only the call to GetActiveEmployees, ignoring all other code:

      using Microsoft.VisualStudio.Profiler;      public class TestApplication      {          public static void ProcessEmployees()          {              // Code here will not be profiled              DataCollection.StartProfile(DataCollection.ProfileLevel.Global,                                          DataCollection.CurrentId);              // Here is the code that will be profiled              Employees emps = HumanResources.GetActiveEmployees();              DataCollection.StopProfile(DataCollection.ProfileLevel.Global,                                         DataCollection.CurrentId);              // Code here will not be profiled          }      }

The calls to StartProfile and StopProfile are given a ProfileLevel of Global, indicating this should affect all executions. Because it is global, there is no need for a specific identifier, so the constant DataCollection.CurrentId is passed as the second argument.

The possible values for DataCollection.ProfileLevel are as follows:

• Global

• Process

• Thread

As you can see, you can constrain the profiling to a specific process or thread, supplying the appropriate process or thread ID as the second argument or you can pass DataCollection.CurrentId to reference the currently executing context.

To profile code such as the preceding example, use the same approach as described in the "Command-line Execution" section earlier. However, you will need to include one extra option. By default, the profiler will observe everything. Unless you disable this, all of the code before the StopProfile marker will be profiled, instead of just the code between StartProfile and StopProfile.

VSPerfCmd has an option to disable collection, but you'll typically use it only in this specific case. Follow the same steps as outlined before, but after you start instrumentation profiling with VSPerfCmd and before you start your profiled application, execute the following command:

      VSPerfCmd /globaloff

By disabling data collection, the profiler relies on your code to call DataCollection.StartProfile in order to begin the collection process.

The Microsoft.VisualStudio.Profiler.DataCollection class supports other methods that can affect profiling.

SuspendProfile and ResumeProfile are used like the StartProfile and StopProfile methods. The difference is that calls to Suspend/Resume are incremented and decremented, similar to the way object reference counting worked in COM programming. For example, if the code you are profiling calls SuspendProfile twice, profiling will not resume until ResumeProfile is likewise called twice. These methods, including calls to StartProfile and StopProfile, return a DataCollection.Profile OperationResult enumeration value that you can verify equals ProfileOperationResult.OK, indicating success.

You can add custom details that will be inserted with the other profiling data:

• MarkProfile enables you to insert an integer.

• CommentMarkProfile inserts an integer with a string comment.

• CommentMarkAtProfile inserts an integer with a string comment at a specified timestamp.

Any data you add with these methods can be seen in the Call Tree View. Each of these operations returns a DataCollection.MarkOperationResult enumeration value that you can use to verify success.