Profiler Compatibility Settings
By default, in the .NET Framework version 4, the common language runtime (CLR) loads and uses only profilers that were built for the .NET Framework 4. The CLR does not load or run profilers that were built for the .NET Framework versions 2.0, 3.0, or 3.5 unless this is explicitly specified. (In this topic, the term "version 2.0 profiler" refers to profilers that were built for the .NET Framework versions 2.0, 3.0, and 3.5.)
Profiler users must explicitly opt-in to use version 2.0 profilers by using the COMPLUS_ProfAPI_ProfilerCompatibilitySetting environment variable. Version 2.0 profilers that are used in the .NET Framework 4 behave as follows:
The .NET Framework version 2.0 profiling APIs continue to function in the .NET Framework 4 according to the version 2.0 documentation.
Undocumented version 2.0 profiling API or CLR behavior is not guaranteed in .NET Framework 4. Version 2.0 profilers that have dependencies on undocumented behavior are not guaranteed to work in the .NET Framework 4. Please note that this compatibility setting does not provide backward compatibility with CLR 2.0 behavior.
COMPLUS_ProfAPI_ProfilerCompatibilitySetting
Before you set the COMPLUS_ProfAPI_ProfilerCompatibilitySetting environment variable, you must set the COR_PROFILER or COR_ENABLE_PROFILING environment variables. (See Setting Up a Profiling Environment for instructions.)
You can set the COMPLUS_ProfAPI_ProfilerCompatibilitySetting environment variable to one of three values, as shown in the following table.
Note
In the .NET Framework version 3.5 and earlier versions, the CLR does not support the COMPLUS_ProfAPI_ProfilerCompatibilitySetting variable. It always tries to load a profiler if the COR_PROFILER or COR_ENABLE_PROFILING environment variables have been set.
Setting |
CLR behavior |
|---|---|
EnableV2Profiler |
Loads and activates version 2.0 profilers. |
DisableV2Profiler |
Disables version 2.0 profilers, but does not unload them. The .NET Framework 4 profilers are unaffected. This is the default setting. |
PreventLoad |
Does not load any profilers, regardless of which version of the .NET Framework the profiler was written for. |
The detailed behavior is as follows:
EnableV2Profiler
The .NET Framework 4 CLR loads and uses the available profiler, regardless of which version of the .NET Framework the profiler was written for. In in-process side-by-side profiling, if the .NET Framework version 2.0 CLR loads a profiler first in the process, the .NET Framework 4 CLR does not reload that version 2.0 profiler.
DisableV2Profiler (default)
The .NET Framework 4 CLR loads the profiler and determines its version by calling the profiler’s IUnknown::QueryInterface method to locate the ICorProfilerCallback3 interface.
If the profiler implements ICorProfilerCallback3, it is a .NET Framework version 4 profiler, and the CLR continues to use it.
If the profiler does not implement ICorProfilerCallback3, it is a version 2.0 profiler. In this case, the CLR releases the profiler interface and does not activate the profiler. However, the CLR does not unload the profiler DLL, so it can maintain backward compatibility with the .NET Framework version 2.0 CLR, which does not unload profiler DLLs. (Note that .NET Framework 4 profilers do get unloaded at detach or shutdown time, so if you are revising your profiler for the .NET Framework 4, you will have to change this behavior.)
PreventLoad
The .NET Framework 4 CLR ignores the profiler completely. This setting is useful for some in-process side-by-side scenarios. For more information, see In-Process Side-by-Side Profiling.
For example, to instruct the CLR to load your .NET Framework 2.0 profiler, open a Command Prompt window and type the following:
set COMPLUS_ProfAPI_ProfilerCompatibilitySetting=EnableV2Profiler
Note
This compatibility switch only affects the profiler startup path. For attach-load profilers, the runtime calls the IUnknown::QueryInterface function for the ICorProfilerCallback3 interface. If the profiler does not implement this interface (which is true for version 2.0 profilers), the runtime does not load the profiler and logs a profiler load failure entry in the event log.
See Also
Concepts
Profiling in the .NET Framework 4