Integrate Third-Party Tools with dotCover

The JetBrains .NET tools (dotTrace, dotCover, and dotMemory) are based on the common profiler core. The core provides low-level profiling functionality like attaching to profiled processes, communication with the .NET Framework, .NET Core, or .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 can 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 the 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 dotCover

Before starting profiling, your tool must provide its integration configuration in at least one of following places:

On Linus and macOS:
- The file $HOME/.jetbrains-profiler-transparent-integration-config
On Windows:
- The registry HKCU\SOFTWARE\JetBrains\Profiler\TransparentIntegration
- The registry HKLM\SOFTWARE\JetBrains\Profiler\TransparentIntegration
- The registry HKLM\SOFTWARE\WOW6432Node\JetBrains\Profiler\TransparentIntegration
- The file %USERPROFILE%\.jetbrains-profiler-transparent-integration-config

The configuration file contains the list of key-value pairs. Only one key-value pair per line is allowed. The key and value must be separated with =. The parser disregards any text following the # symbol on a line. Empty lines are ignored.

Key name	Windows registry data type	Description
`CoverageProfiler`	`REG_SZ`	(Required) A class ID of the third-party profiler COM object.
`CoverageProfiler_Path32`	`REG_SZ`	(Required on Windows ARM64/x64/x86) An absolute path to the x86 third-party profiler shared library.
`CoverageProfiler_Path64`	`REG_SZ`	(Required on Linux x64, macOS ARM64/x64, Windows ARM64/x64) An absolute path to the x64 third-party profiler shared library.
`CoverageProfiler_PathArm32`		(Required on Linux ARM) An absolute path to the ARM third-party profiler shared library.
`CoverageProfiler_PathArm64`	`REG_SZ`	(Required on Linux ARM64, macOS ARM64, Windows ARM64) An absolute path to the ARM64 third-party profiler shared library.
`CoverageProfiler_RegistryFreeActivation`	`REG_DWORD`	(Optional, Windows only) `0` by default. Specify any number other than `0` if you are going to skip step 2, i.e., if you're not going to profile .NET Framework 2.0 - 4.5.2 processes.

This step is required only if you're going to profile:
- NET Framework 2.0 - 3.5 x64/x86 processes on Windows ARM64/x64/x86
- .NET Framework 4.0 - 4.5.2 x64/x86 processes on Windows x64/x86
Register your tool as a COM object using the Win32 API or regsvr32 for x86 and x64 (ARM64 CPUs don't support .NET Framework 2.0 - 4.5.2).

To load the JetBrains profiler core into the profiled process, use the following data:

Variable	Windows registry data type	Description
`JETBRAINS_PROFILER_CORE_GUID`	`REG_SZ`	(Required) The profiler core GUID.
`JETBRAINS_PROFILER_CORE_PATH32`	`REG_SZ`	(Required on Windows ARM64/x64/x86) An absolute path to the x86 profiler core shared library.
`JETBRAINS_PROFILER_CORE_PATH64`	`REG_SZ`	(Required on Linux x64, macOS ARM64/x64, Windows ARM64/x64) An absolute path to the x64 profiler core shared library.
`JETBRAINS_PROFILER_CORE_PATH_ARM32`	`REG_SZ`	(Required on Linux ARM) An absolute path to the ARM profiler core shared library.
`JETBRAINS_PROFILER_CORE_PATH_ARM64`	`REG_SZ`	(Required on Linux ARM64, macOS ARM64, Windows ARM64) An absolute path to the ARM64 profiler core shared library.

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):

On Linus and macOS:
1. Files: /tmp/Upid_<pid>_<pst>/<var>
2. Environment variables
On Windows:
1. Registry: HKCU\SOFTWARE\JetBrains\Profiler\Upid_<pid>_<pst>
2. Registry: HKLM\SOFTWARE\JetBrains\Profiler\Upid_<pid>_<pst>
3. Environment variables
4. Registry: HKLM\SOFTWARE\JetBrains\Profiler\Global

Where:

<var> – a Variable from the table above.
<pid> – an unsigned decimal process id.
<pst> – a hexadecimal process start time:
- On Linux: in clock ticks from the system boot.
- On Windows and macOS: in 100-nanosecond intervals since 01-Jan-1601 (UTC).

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

Last modified: 11 February 2024