dotTrace 2023.1 Help

Integrate Third-Party Tools with dotTrace

The JetBrains .NET tools (dotTrace, dotCover, and dotMemory) are based on a common profiler core. The core provides low-level profiling functionality like attaching to profiled processes, communication with the .NET runtime, collecting profiling data, and so on.

The profiler core provides a mechanism that lets third-party tools to integrate with JetBrains .NET tools. An example of such integration is Typemock Isolator running along with JetBrains dotTrace: Users not only test their code but also investigate performance problems.

Transparent integration concepts

When a JetBrains .NET tool profiles a process, it loads the profiler core into the profiled process. In case of transparent integration, profiling is initiated by a third-party tool. So, the third-party tool becomes responsible for loading the profiler core into the profiled process.

How to integrate your tool with dotTrace

  1. Before starting profiling, your tool must add the following values (32-bit and/or 64-bit) to the HKCU\SOFTWARE\JetBrains\Profiler\TransparentIntegration or HKLM\SOFTWARE\JetBrains\Profiler\TransparentIntegration registries:

    1. {name}(REG_SZ) – (Required) a class ID of the third-party profiler COM object.

    2. {name}_Path32(REG_SZ) – (Required) a full path to the x86 third-party profiler shared library.

    3. {name}_Path64(REG_SZ) – (Required for Windows x64/ARM64) a full path to the x64 third-party profiler shared library.

    4. {name}_PathArm64(REG_SZ) – (Required for Windows ARM64) a full path to the ARM64 third-party profiler shared library.

    5. {name}_RegistryFreeActivation(REG_DWORD) – (Optional) 0 by default. Specify any number other than 0 if you are going to skip step 2 (if you're not going to profile .NET Framework 2.0 - 4.5.2 processes).

    If your tool starts a process that it's going to profile, create corresponding registry values for each {name} below:

    • SamplingPerformanceProfiler

    • TracingPerformanceProfiler

    • TracingInjectPerformanceProfiler

    • TimelineProfiler

    If your tool attaches to a running process that it's going to profile, create corresponding registry values for each {name} below:

    • SamplingPerformanceProfiler_Attach

    • TimelineProfiler_Attach

  2. (Required only if you're going to profile .NET Framework 2.0 - 4.5.2 processes) Register your tool as a COM object using the Win32 API or regsvr32 for x86 or x64 (ARM64 CPUs don't support .NET Framework 2.0 - 4.5.2).

  3. To load the JetBrains profiler core into the profiled process, you should use the following data:

    • JETBRAINS_PROFILER_CORE_GUID – the profiler core GUID.

    • JETBRAINS_PROFILER_CORE_PATH32, JETBRAINS_PROFILER_CORE_PATH64, or JETBRAINS_PROFILER_CORE_PATH_ARM64 – the path to the profiler core .dll (x86, x64, and ARM64 correspondingly).

    You must take the values of these variables from the following sources (search the sources exactly in the specified order until the required value is found):

    1. HKCU\SOFTWARE\JetBrains\Profiler\Upid_<X>_<Y>

    2. HKLM\SOFTWARE\JetBrains\Profiler\Upid_<X>_<Y>

    3. Environment variables

    4. HKLM\SOFTWARE\JetBrains\Profiler\Global

    Where:

    • <X> – an unsigned decimal process id.

    • <Y> – a hexadecimal process start time in 100-nanosecond intervals since 01-Jan-1601 (UTC).

  4. Make sure your tool implements and keeps up to date the translation of the interfaces: ICorProfilerInfo – ICorProfilerInfo13. Note that the implementation of the ICorProfilerInfo::QueryInterface() in your tool must return the same set of available interfaces as the CLR/CoreCLR it supports. For example, if CoreCLR supports only ICorProfilerInfo – ICorProfilerInfo10, then only these interfaces must be available to the JetBrains profiler core.

Last modified: 08 December 2022
Symbol Server Integration