Page Comparison - Using dotTrace Perfomance API (v.33 vs v.34)

Versions Compared


  • This line was added.
  • This line was removed.
  • Formatting was changed.

Disclaimer: This tutorial covers the usage of API only for the performance profiling method. The implementation of the timeline profiling API is very similar, with a few minor exceptions. For details on timeline profiling API classes, refer to the dotTrace documentation.


Now, let’s take some simple app and try both scenarios in action!


Sample App
Profiling a Specific Part of the Code
Self-Profiled Application



  1. Open our Game of Life application in Visual Studio.
  2. To use the dotTrace API, you must reference the JetBrains.Profiler.Windows.SelfApi assembly which contains the API classes. To do this:
    1. In the Solution Explorer, right click the References folder.
    2. In the context menu, select Add Reference.
    3. In the opened window, click Browse | Browse and specify the path to JetBrains.Profiler.Windows.SelfApi.dll located in the main directory of the dotTrace SDK. 
    4. Click OK.
  3. First, we need to initiate self-profiling using the SelfAttach class. This can be done anywhere in the app before we call the PerformanceProfiler methods. In our case, this could be done in the constructor of the main window. To do this, open the public MainWindow() constructor in MainWindow.xaml.cs and add the following lines in the end of the constructor:

    Code Block
    SelfAttach.Attach(new SaveSnapshotProfilingConfig()
         ProfilingControlKind = ProfilingControlKind.Api,
         SaveDir = "C:\\Temp",
         RedistDir = "C:\\ProfilerSDK",
         ProfilingType = ProfilingType.Performance,
         ListFile = "C:\\snapshot_list.xml"

    * Some of these parameters are optional. For more information about them, refer to the dotTrace Help.

    As you see, we pass an instance of the SaveSnapshotProfilingConfig class as a parameter to the Attach method. This tells dotTrace how to process the resulting snapshot. In our case, we tell the profiler to save the snapshot file on the disk. There is also one more option you can use instead: ExecutableSnapshotProfilingConfig will run an external application passing the path to the snapshot as a command-line parameter. This option is of most interest in case you’re going to get snapshots from end-user computers remotely.
    Public fields of the SaveSnapshotProfilingConfig class allow us to specify the following profiling options*:

    • SaveDir (passed to the constructor) specifies the location where we want to save snapshot files (../ in our case).
    • ProfilingControlKind defines how the profiling must be controlled. The ProfilingControlKind.API value means we’ll control the session by means of the API. You can also decide to control the session using the Controller window or don’t control it at all.
    • RedistDir specifies the path to the dotTrace redistributables.
    • ProfilingType defines the profiling method. E.g., if you want to perform timeline profiling, you should specify ProfilingType.Timeline here.
    • ListFile stores file names of snapshots collected during profiling. This file is created automatically during profiling.
  4. As mentioned in the beginning, the only possible profiling type when using self-profiling is Sampling. Due to this, we cannot profile just a single execution of the OnTimer event handler as in the previous scenario. As the OnTimer execution probably takes less than the sampling time (5 – 11 ms), the chances it won’t be detected by the profiler are quite high. Therefore, we need to extend the profiling scope and take performance results of, for example, first 10 OnTimer executions. To do this, in the OnTimer event hanlder, we must say the profiler to stop and save snapshot only after the 10th Game of Life generation:

    Code Block
    private void OnTimer(object sender, EventArgs e)
         while (SelfAttach.State != SelfApiState.Active)
             Thread.Sleep(250);   // wait is needed for the API to start
         if ((genCounter == 1) && (PerformanceProfiler.IsActive))
         lblGenCount.Content = "Generations: " + genCounter;
         if (genCounter == 10)
  5. Build and run the app.
  6. Start Game of Life using the Start button. Wait until 10 generations pass.
  7. Check the app’s folder. If everything works fine, it should contain the snapshot file.

    The resulting snapshot file can be then opened and inspected in dotTrace Performance Viewer.