David Broman's CLR Profiling API Blog

CLR V4: Profiler Attach Basics With Sample Code

2009-11-04T17:43:00Z

A new feature in CLR V4 is the ability to attach a profiler to a process after that process has already started. The usefulness of this is fairly obvious to anyone who's ever attached a debugger to a running-process: It's helpful when diagnosing hard-to-reproduce problems, and particularly useful when encountering issues in production.

Please note! You can't just take any profiler you bought and suddenly be able to attach it to a running application. The profiler must be built with "attachability" in mind. So if you're a profiler developer looking to pump some attachability into your product, read on--this article is for you. Everyone else, this article will probably be less useful--but just as riveting.

The Players

So how do you get your profiler attached to a running process? The process has already started, and the CLR code which interrogates the environment to determine whether to load a profiler has already run. So how do you kick the process into loading your profiler? The answer: Another process!

In order to force your profiler DLL to load into the target profilee process, you'll need to create a "trigger" process to send the attach message to the target profilee. Many profilers already ship with a GUI shell to control launching processes to profile. That shell will typically act as your trigger process as well.

Inside the Trigger Process

Your trigger uses a simple API method, AttachProfiler, to request the target process to load your profiler. Where is this method defined? Well, it doesn't make much sense to put it on ICorProfilerInfo, since that interface is only available to a profiler after it's been loaded. You could imagine a C export from mscoree.dll. But because of in-process side-by-side CLR instances, we're moving away from mscoree.dll exports to a COM-based interface model called "metahost".

Meta-whos-its?

Whereas the "hosting" interfaces enable one to host and manage a CLR in a process, the "metahost" interfaces allow one to manage multiple CLRs that may be installed onto a machine or loaded into a single process. Here's a high-level view of how you navigate your way through metahost to find AttachProfiler() (there’s a pointer to actual sample code below).

Get ICLRMetaHost
Enumerate the CLRs loaded into the target process
Get ICLRRuntimeInfo for the particular CLR in the target process you want to profile
Get the corresponding ICLRProfiling
Call ICLRProfiling::AttachProfiler

Users and Integrity

The permissions required to attach a profiler are similar to those required to attach a debugger. First, the trigger process must run as the same user as the target profilee OR as an administrator. Second, on OS's that support process integrity levels, the trigger process must be running at an integrity level higher than or equal to that of the target profilee process. For more information about integrity and mandatory labels, here's some reference from MSDN.

Sample Trigger Source Code

For some sample code to attach a profiler to a process, take a look at the sample uploaded to the MSDN Code Gallery here.

You'll notice the code attempts to enable the SE_DEBUG_NAME privilege, as this is required to open a process running as another user with PROCESS_ALL_ACCESS. Again, cross-user attach (i.e., trigger runs as a different user than the target profilee process) is only supported when the trigger is run as an administrator. Otherwise, only same-user attach is supported, and would not need to enable the SE_DEBUG_NAME privilege.

Inside the Profilee Process

Once your trigger has called AttachProfiler(), a message is sent to the target profilee process to load your actual profiler DLL, containing info such as your profiler's GUID. At this point, it's business as usual in the profilee. The profilee locates and loads your profiler DLL, the CLR then calls your class factory object to create an instance of your profiler's ICorProfilerCallback implementation.

Note that, instead of the CLR calling your Initialize() method, the CLR will call your ICorProfilerCallback3::InitializeForAttach() method. There are two reasons for this difference. First, this ensures that only profilers that have been upgraded to work with CLR V4 and opt into attaching will actually be attached. All other profilers can simply return an error from their InitializeForAttach() method (or won't have an ICorProfilerCallback3 implementation to begin with).

The second reason is that InitializeForAttach allows for some extra data to be passed from the trigger to your profilee via a blob of binary data. What's that for? Many profiler products pass configuration information from their shell to their startup-loaded profiler DLL via environment variables. After all, the shell has to set COR_PROFILER & COR_ENABLE_PROFILING in the environment anyway, so why not set some more values there to be read by their profiler? This scheme doesn't work for an attaching profiler, since the shell cannot affect the environment of the already-running profilee. Instead, the AttachProfiler API allows the caller to specify a pointer to a buffer containing whatever data the caller wishes. The CLR makes a copy of the data, sends it to the profilee, and then passes a pointer to this data to the profiler DLL via InitializeForAttach.

The management of the memory containing this binary data follows the usual COM rules. In the trigger process, your trigger code allocates memory for the blob, passes it to AttachProfiler (which will make its own copy of the data), and then your trigger code frees it once AttachProfiler returns. Stack allocation is perfect here; your trigger could just push your own custom structure of data onto the stack and pass a pointer to it in your call to AttachProfiler. Inside the profilee process, your profiler gets access to the blob of data from its InitializeForAttach method. Inside InitializeForAttach, your profiler accesses that memory. If your profiler will need to use that memory later on, your profiler should make a copy of the memory now. After InitializeForAttach returns, the CLR will free the memory.

From your InitializeForAttach implementation, your profiler will call SetEventMask as usual to announce your intentions, and you're off to the races.

Limitations

It was impossible to enable all profiling scenarios for attach in the time we had for the V4 release. So only profilers that do sampling and memory analysis will function properly after attaching to a live process. Attempts to use other profiling APIs after attach will be met with CORPROF_E_UNSUPPORTED_FOR_ATTACHING_PROFILER.

Specific Callback Limitations

When your attaching profiler calls SetEventMask, you will be limited to only those event mask flags present in the COR_PRF_ALLOWABLE_AFTER_ATTACH bitmask (you'll find it in corprof.idl). Any other flags, and SetEventMask will return CORPROF_E_UNSUPPORTED_FOR_ATTACHING_PROFILER.

Specific Info Limitations

Most of the ICorProfilerInfo* methods are available to your attaching profiler, however some are not--particularly those involved in IL rewriting. Here's a list of all ICorProfilerInfo* methods NOT supported for attaching profilers:

GetILFunctionBody
GetILFunctionBodyAllocator
SetILFunctionBody
SetILInstrumentedCodeMap
SetEnterLeaveFunctionHooks*
SetFunctionIDMapper*
GetNotifiedExceptionClauseInfo
All methods related to Enter/Leave/Tailcall

It's expected that future releases of the CLR will enable more API methods for use by attaching profilers.

GC Limitations

GC Modes

To understand limitations around the GC modes, here's a quick review of the GC modes an app can run under:

Workstation Blocking mode. The thread that triggered the GC performs the GC while all other threads executing managed code must wait.
Workstation Concurrent / Background mode (the default). Concurrent GC (V1 & V2) allows portions of a full GC to execute while other threads are allowed to run. Background GC (its replacement in V4) takes it one step further, and also allows an ephemeral GC (i.e., gen 0 or gen 1) to execute while a gen 2 GC is executing.
Server mode. Hosts like ASP.NET may choose to enable server mode which creates a heap + dedicated GC thread per CPU. This allows GCs to be fanned out to multiple threads.

Of course, Maoni's blog is required reading for anyone who wants to understand how the GC works.

The profiling API is able to work against workstation blocking mode and server mode, but not concurrent / background mode. This has been the case in V1 & V2, and remains the case in V4. When the app starts up, if a profiler is configured to load, then the CLR forcibly turns off concurrent / background mode, and you end up in workstation blocking mode (or you end up in server mode if the host requested that instead). Again, this has been the case in V1 & V2, and remains true in V4.

So here's the catch. What if a V4 app starts up in background GC mode without a profiler loading on startup, and you later attach a profiler to the process? If the profiler specifies COR_PRF_MONITOR_GC in its call to SetEventMask, then the CLR returns the error CORPROF_E_CONCURRENT_GC_NOT_PROFILABLE. In other words, if the profiler is late to the party, then it simply won't work if background GC is on. Since this is the default for client apps, the bottom line is that you can generally successfully attach your memory profiler to server apps (e.g., ASP.NET), but probably not to client apps.

Of course, you could forcibly turn off concurrent / background mode every time the app starts up via a config file:

But you don't really want to be running your apps with a sub-optimal GC mode all the time, just on the off-chance you might need to attach a memory profiler to it. If you suspect you might need to do some memory profiling of a client app, you should just start up your app with the memory profiler to begin with.

ObjectAllocated

The ObjectAllocated callback is disallowed for attaching profilers (i.e., COR_PRF_ENABLE_OBJECT_ALLOCATED is not part of the COR_PRF_ALLOWABLE_AFTER_ATTACH mask).

Go Forth and Attach

All right, dig through that sample trigger code, and see if you can add "attach" to your list of features. In later posts, I'll talk about how to catch up on application state once your profiler attaches, and also how to detach your profiler when it's done with its business.

CLR V4 Beta 2 Released!

2009-10-19T17:45:00Z

All you profiler writers will want to try out your profiler on the latest and greatest!

Information on getting beta 2 of CLR V4 and Visual Studio 2010 is available here.

The beta 2 docs for the profiling API start here.

There have been some bug fixes between beta 1 & beta 2 that may improve life for your profiler. It's also worth noting that, for those of you dabbling with getting your profiler to attach to a running process, the method to get an instance of the metahost API has been renamed (since beta 1) to CLRCreateInstance. If you're looking for more information on how to make your profiler attachable, I will be posting an entry on that as soon as I can.

Type Forwarding

2009-10-01T03:33:00Z

MSDN defines “type forwarding” as moving “a type to another assembly without having to recompile applications that use the original assembly”. In this post, I’ll talk about examining a particular type in Microsoft’s .NET Framework library that gets forwarded, how you can use type forwarding for your own types, and what type forwarding looks like to consumers of the profiling API. For some more official background on type forwarding, visit the MSDN topic. If you Bing type forwarding you’ll find many blogs that talk about it as well. Yes, that’s right. I used Bing as a verb. Get used to it; Bing is awesome.

Type forwarding is nothing new. However, in CLR V4, we are enabling type forwarding to work with generic types. And there has been some new refactoring in System.Core. This means you should expect to see type forwarding used more often than it had been in the past. So if you code up a profiler, you should make sure you can deal with type forwarding appropriately. The good news is that profiler code that uses the profiling API to inspect types generally should not need to change. But if you do certain kinds of metadata lookups yourself, you may need to be aware of type forwarding. More on that later.

Example: TimeZoneInfo

The example I’ll use where the .NET Framework uses type forwarding is the TimeZoneInfo class. In CLR V4, TimeZoneInfo is now forwarded from System.Core.dll to mscorlib.dll. If you open the CLR V4 copy of System.Core.dll in ildasm and choose Dump, you'll see the following:

.class extern /*27000004*/ forwarder System.TimeZoneInfo
{
  .assembly extern mscorlib /*23000001*/ 
}

In each assembly’s metadata is an exported types table. The above means that System.Core.dll's exported types table includes an entry for System.TimeZoneInfo (indexed by token 27000004). What's significant is that System.Core.dll no longer has a typeDef for System.TimeZoneInfo, only an exported type. The fact that the token begins at the left with 0x27 tells you that it's an mdtExportedType (not a mdtTypeDef, which begins at the left with 0x02).

At run-time, if the CLR type loader encounters this exported type, it knows it must now look in mscorlib for System.TimeZoneInfo. And by the way, if someday mscorlib chooses to forward the type elsewhere, and thus the type loader found another exported type with name System.TimeZoneInfo in mscorlib, then the type loader would have to make yet another hop to wherever that exported type pointed.

Walkthrough 1: Observe the forwarding of System.TimeZoneInfo

This walkthrough assumes you have .NET 4.0 Beta 1 installed (see here) and an older release of .NET, such as .NET 3.5, installed.

Code up a simple C# app that uses System.TimeZoneInfo:

namespace test
{
    class Class1
    {
        static void Main(string[] args)
        {
            System.TimeZoneInfo ti = null;
        }
    }
}

Next, compile this into an exe using a CLR V2-based toolset (e.g., .NET 3.5). You can use Visual Studio, or just run from the command-line (but be sure your path points to the pre-.NET 4.0 C# compiler!). Example:

csc /debug+ /o- /r:"C:\Program Files (x86)\Reference Assemblies\Microsoft\Framework\v3.5\System.Core.dll" Class1.cs

Again, be sure you’re using an old csc.exe from, say, a NET 3.5 installation. To verify, open up Class1.exe in ildasm, and take a look at Main(). It should look something like this:

.method /*06000001*/ private hidebysig static 
        void  Main(string[] args) cil managed
{
  .entrypoint
  // Code size       4 (0x4)
  .maxstack  1
  .locals /*11000001*/ init ([0] class [System.Core/*23000002*/]System.TimeZoneInfo/*01000006*/ ti)
  IL_0000:  nop
  IL_0001:  ldnull
  IL_0002:  stloc.0
  IL_0003:  ret
} // end of method Class1::Main

The key here is to note that the IL uses a TypeRef for System.TimeZoneInfo (01000006) that points to System.Core.dll. When you run Class1.exe against a .NET 3.5 runtime, it will find System.TimeZoneInfo in System.Core.dll as usual, and just use that, since System.TimeZoneInfo actually is defined in System.Core.dll in pre-.NET 4.0 frameworks. However, what happens when you run Class1.exe against .NET 4.0 without recompiling? Type forwarding would get invoked!

Note that, if you were to build the above C# code using the .NET 4.0 C# compiler, it would automatically have generated a TypeRef that points to mscorlib.dll instead, so you wouldn't be able to observe the type forwarding at run-time.

Ok, so how do we run this pre-.NET 4.0 executable against .NET 4.0? A config file, of course. Paste the following into a file named Class1.exe.config that sits next to Class1.exe:

<configuration>
   <startup>
      <supportedRuntime version="v4.0.20506"/>
   </startup>
</configuration>

The above will force Class1.exe to bind against .NET 4.0 Beta 1. And when it comes time to look for TimeZoneInfo, the CLR will first look in System.Core.dll, find the exported types table entry, and then hop over to mscorlib.dll to load the type. What does that look like to your profiler? Make your guess and hold that thought. First, another walkthrough…

Walkthrough 2: Forwarding your own type

To experiment with forwarding your own types, the process is:

Create Version 1 of your library
- Create version 1 of your library assembly that defines your type (MyLibAssemblyA.dll)
- Create an app that references your type in MyLibAssemblyA.dll (MyClient.exe)
Create version 2 of your library
- Recompile MyLibAssemblyA.dll to forward your type elsewhere (MyLibAssemblyB.dll)
- Don’t recompile MyClient.exe. Let it still think the type is defined in MyLibAssemblyA.dll.

Version 1

Just make a simple C# DLL that includes your type Foo. Something like this (MyLibAssemblyA.cs):

using System;
public class Foo
{
}

and compile it into MyLibAssemblyA.dll:

csc /target:library /debug+ /o- MyLibAssemblyA.cs

Then make yourself a client app that references Foo.

using System;
public class Test
{
    public static void Main()
    {
        Foo foo = new Foo();
        Console.WriteLine(typeof(Foo).AssemblyQualifiedName);
    }
}

and compile this into MyClient.exe:

csc /debug+ /o- /r:MyLibAssemblyA.dll MyClient.cs

When you run MyClient.exe, you get this boring output:

Foo, MyLibAssemblyA, Version=0.0.0.0, Culture=neutral, PublicKeyToken=null

Ok, time to upgrade!

Version 2

Time goes by, your library is growing, and its time to split it into two DLLs. Gotta move Foo into the new DLL. Save this into MyLibAssemblyB.cs

using System;
public class Foo
{
}

compile that into your new DLL, MyLibAssemblyB.dll:

csc /target:library /debug+ /o- MyLibAssemblyB.cs

And for the type forward. MyLibAssemblyA.cs now becomes:

using System;
using System.Runtime.CompilerServices;
[assembly: TypeForwardedTo(typeof(Foo))]

compile that into MyLibAssemblyA.dll (overwriting your Version 1 copy of that DLL):

csc /target:library /debug+ /o- /r:MyLibAssemblyB.dll MyLibAssemblyA.cs

Now, when you rerun MyClient.exe (without recompiling!), it will look for Foo first in MyLibAssemblyA.dll, and then hop over to MyLibAssemblyB.dll:

Foo, MyLibAssemblyB, Version=0.0.0.0, Culture=neutral, PublicKeyToken=null

And this all despite the fact that MyClient.exe still believes that Foo lives in MyLibAssemblyA:

.method /*06000001*/ public hidebysig static 
        void  Main() cil managed
{
  .entrypoint
  // Code size       29 (0x1d)
  .maxstack  1
  .locals /*11000001*/ init ([0] class [MyLibAssemblyA/*23000002*/]Foo/*01000006*/ foo)
  IL_0000:  nop
  IL_0001:  newobj     instance void [MyLibAssemblyA/*23000002*/]Foo/*01000006*/::.ctor() /* 0A000004 */
  IL_0006:  stloc.0
  IL_0007:  ldtoken    [MyLibAssemblyA/*23000002*/]Foo/*01000006*/
  IL_000c:  call       class [mscorlib/*23000001*/]System.Type/*01000007*/ [mscorlib/*23000001*/]System.Type/*01000007*/::GetTypeFromHandle(valuetype [mscorlib/*23000001*/]System.RuntimeTypeHandle/*01000008*/) /* 0A000005 */
  IL_0011:  callvirt   instance string [mscorlib/*23000001*/]System.Type/*01000007*/::get_AssemblyQualifiedName() /* 0A000006 */
  IL_0016:  call       void [mscorlib/*23000001*/]System.Console/*01000009*/::WriteLine(string) /* 0A000007 */
  IL_001b:  nop
  IL_001c:  ret
} // end of method Test::Main

Profilers

What does this look like to profilers? Types are represented as ClassIDs, and modules as ModuleIDs. When you query for info about a ClassID (via GetClassIDInfo2()), you get one and only one ModuleID to which it belongs. So when a ClassID gets forwarded from one ModuleID to another, which does the profiling API report as its real home? The answer: always the final module to which the type has been forwarded and therefore the module whose metadata contains the TypeDef (and not the exported type table entry).

This should make life easy for profilers, since they generally expect to be able to find the metadata TypeDef for a type inside the ModuleID that the profiling API claims is the type’s home. So much of type forwarding will be transparent to your profiler.

However, type forwarding is important to understand if your profiler needs to follow metadata references directly. More generally, if your profiler is reading through metadata and expects to come across a typeDef (e.g., perhaps a metadata reference points to a type in that module, or perhaps your profiler expects certain known types to be in certain modules), then your profiler should be prepared to find an mdtExportedType instead, and to deal gracefully with it rather than doing something silly like crashing.

In any case, whether you think your profiler will be affected by type forwarding, be sure to test, test, test!

CLR V4: Load your profiler without using the registry

2009-06-16T23:36:23Z

One of the new features in CLR V4 is the ability to load your profiler without needing to register it first. In V2, we would look at the following environment variables:

COR_ENABLE_PROFILING=1

COR_PROFILER={CLSID of profiler}

and look up the CLSID from COR_PROFILER in the registry to find the full path to your profiler's DLL. Just like with any COM server DLL, we look for your profiler's CLSID under HKEY_CLASSES_ROOT, which merges the classes from HKLM and HKCU.

We mostly follow the same algorithm in V4, so you can continue registering your profiler if you wish. However, in V4 we look for one more environment variable first:

COR_PROFILER_PATH=full path to your profiler's DLL

If that environment variable is present, we skip the registry look up altogether, and just use the path from COR_PROFILER_PATH to load your DLL. A couple things to note about this:

COR_PROFILER_PATH is purely optional. If you don't specify COR_PROFILER_PATH, we use the old procedure of looking up your profiler's CLSID in the registry to find its path
If you specify COR_PROFILER_PATH and register your profiler, then COR_PROFILER_PATH always wins. Even if COR_PROFILER_PATH points to an invalid path, we will still use COR_PROFILER_PATH, and just fail to load your profiler.
COR_PROFILER is always required. If you specify COR_PROFILER_PATH, we skip the registry look up; however, we still need to know your profiler's CLSID, so we can pass it to your class factory's CreateInstance call.

What does Dave look like?

2009-05-28T20:59:29Z

Find out on channel 9 as Jon Langdon, Thomas Lai, and I discuss some of the new diagnostics features in CLR V4.

Run your V2 profiler binary on CLR V4

2009-05-27T04:38:27Z

Ok, you've installed VS 2010 beta 1, along with .NET FX 4.0 beta 1, and you're wondering--can you run your profiler against this new .NET framework without recompiling the profiler?

Yes, you can! Though not by default. Although CLR V4 is much more compatible with CLR V2 than CLR V2 was with CLR V1.1, there are still some differences that can mess with your profiler's mind. So by default, the CLR V4 runtime refuses to activate V2 profilers. If you try, you'll see that the CLR will LoadLibrary the profiler, use the class factory to generate an instance of the callback object, try to QI for the new ICorProfilerCallback3, and then when that fails, the CLR will release the callback object and log an event to the event log explaining that you need to set COMPLUS_ProfAPI_ProfilerCompatibilitySetting appropriately as your way of "opting in" to running the older profiler binary against the newer CLR. This message is meant for your users, as a way of telling them that the profiler vendor (you) may not yet have tested the profiler against CLR V4.

So, how to use COMPLUS_ProfAPI_ProfilerCompatibilitySetting? Set it to one of the following 3 values:

EnableV2Profiler

It enables the V2 profiler to be activated by V4 CLR.

DisableV2Profiler (default)

V4 CLR refuses to activate the V2 profiler, and logs an event to the event log.

PreventLoad

V4 CLR does not load the profiler, regardless of the profiler’s version. This is useful for preventing problems in certain in-process side-by-side CLR scenarios. More on that in an upcoming post.

CLR V4 Beta 1 Released!

2009-05-27T04:23:54Z

Now is the time to try out your profiler against the new .NET FX 4.0 Beta 1 bits. I'll be writing about some gotchas, and how to take advantage of the new features. But first, get started downloading:

Visual Studio 2010 Product Page

You can find some reference documentation on the new profiling interfaces here:

http://msdn.microsoft.com/en-us/library/ms404386(VS.100).aspx

FunctionHooks.zip re-uploaded

2009-02-15T01:45:00Z

Jonathan Keljo's blog entry on the enter/leave/tailcall function hooks had a link to sample code that's been broken for a while. You can now find the sample code here: FunctionHooks.zip

Why we have CORPROF_E_UNSUPPORTED_CALL_SEQUENCE

2008-12-23T21:08:30Z

What follows is a long-lost blog entry that Jonathan Keljo had been working on. I brushed off some of the dust and am posting it here for your enjoyment. Thank you, Jonathan!

In CLR 2.0 we added a new HRESULT, CORPROF_E_UNSUPPORTED_CALL_SEQUENCE. This HRESULT is returned from ICorProfilerInfo methods when called in an "unsupported way". This "unsupported way" is primarily an issue with those nasty beasts, hijacking profilers (though read on for cases where non-hijacking profilers can see this HRESULT, too). Hijacking profilers are those profilers that forcibly reset a thread's register context at completely arbitrary times to enter profiler code, and then usually to re-enter the CLR via ICorProfilerInfo. Why is that so bad? Well, for the sake of performance, lots of the IDs the profiling API gives out are just pointers to relevant data structures within the CLR. So lots of ICorProfilerInfo calls just rip information out of those data structures and pass them back. Of course, the CLR might be changing things in those structures as it runs, maybe (or maybe not) taking locks to do so. Imagine the CLR was already holding (or attempting to acquire) such locks at the time the profiler hijacked the thread. Now, the thread re-enters the CLR, trying to take more locks or inspect structures that were in the process of being modified, and are thus in an inconsistent state. Deadlocks and AVs are easy to come by in such situations.

In general, if you're a non-hijacking profiler sitting inside an ICorProfilerCallback method and you're calling into ICorProfilerInfo, you're fine. For example, you get a ClassLoadFinished and you start asking for information about the class. You might be told that information isn't available yet (CORPROF_E_DATAINCOMPLETE) but the program won't deadlock or AV. This class of calls into ICorProfilerInfo are called "synchronous", because they are made from within an ICorProfilerCallback method.

On the other hand, if you're hijacking or otherwise calling ICorProfilerInfo functions on a managed thread but not from within an ICorProfilerCallback method, that is considered an "asynchronous" call. In v1.x you never knew what would happen in an asynchronous call. It might deadlock, it might crash, it might give a bogus answer, or it might give the right answer.

In 2.0 we've added some simple checks to help you avoid this problem. If you call an unsafe ICorProfilerInfo function asynchronously, instead of crossing its fingers and trying, it will fail with CORPROF_E_UNSUPPORTED_CALL_SEQUENCE. The general rule of thumb is, nothing is safe to call asynchronously. But here are the exceptions that are safe, and that we specifically allow to be called asynchronously:

GetEventMask/SetEventMask
GetCurrentThreadID
GetThreadContext
GetThreadAppDomain
GetFunctionFromIP
GetFunctionInfo/GetFunctionInfo2
GetCodeInfo/GetCodeInfo2
GetModuleInfo
GetClassIDInfo/GetClassIDInfo2
IsArrayClass
ForceGC
SetFunctionIDMapper
DoStackSnapshot

There are also a few things to keep in mind:

ICorProfilerInfo calls made from within the fast-path Enter/Leave callbacks are considered asynchronous. (Though ICorProfilerInfo calls made from within the slow-path Enter/Leave callbacks are considered synchronous.) See the blog entries here and here for more info on fast / slow path.
ICorProfilerInfo calls made from within instrumented code (i.e., IL you've rewritten to call into your profiler and then into ICorProfilerInfo) are considered asynchronous.
Calls made inside your FunctionIDMapper hook are considered to be synchronous.
Calls made on threads created by your profiler, are always considered to be synchronous. (This is because there's no danger of conflicts resulting from interrupting and then re-entering the CLR on that thread, since a profiler-created thread was not in the CLR to begin with.)
Calls made inside a StackSnapshotCallback are considered to be synchronous iff the call to DoStackSnapshot was synchronous.

New stuff in Profiling API for upcoming CLR 4.0

2008-11-11T02:05:18Z

Now that we've finally announced at PDC many of the new features coming up in the next major release of Visual Studio and CLR, I can elaborate some on what's coming up for the profiling API. Also, see Rick Byers's blog entry which also talks about debugging improvements.

What the CLR will do for you

Our upcoming profiling API-specific features are inspired by a vision to improve production troubleshooting, and happily such features will improve the developer desktop experience as well.

Attach / detach

We will now allow profilers to attach to and detach from managed processes that are already running. You no longer need to set environment variables and load the profiler when the managed app starts up. (However, if you would like your profiler to load when the process starts up, you would still use the existing activation mechanism with environment variables.) Attach / detach works with only a limited set of scenarios--see below.

You initiate the attach from a separate executable that we call the "trigger process". If you already have a shell for your profiler, then your shell will typically serve as the trigger process. We will provide you an API that your trigger process will call, which takes parameters that describe the target app to profile and details about your profiler. That API will cause the target app to load your profiler into the target app's process space using the same code that we currently use to load your profiler from startup.

When your profiler is ready to detach from the process, it calls a method right on ICorProfilerInfo3 (the new Info interface for CLR 4.0). That will cause the CLR to stop issuing profiling callbacks, and slip a bit until the profiler is provably off of all the threads' call stacks. The profiler will then be unloaded from the process space, and another profiler may be attached again if the end user wishes.

Due to the nature of the profiling APIs, only a subset of the APIs will be available to profilers that attach to a live process, as opposed to those profilers that load on startup. Specifically, attaching profilers will be able to use the APIs that enable sampling and memory profiling. This includes such operations as walking the stack, mapping instruction pointers to managed methods and their metadata, receiving most GC callbacks, and inspecting statics and object instances on the heap, along with their type information.

APIs that will not be supported for attaching profilers include the ObjectAllocated callback and APIs that enable instrumentation (IL rewriting) of methods. Those scenarios require the ability to "rejit" a method that has already been JITted or loaded from an NGENd module, and unfortunately we are unable to provide that functionality in CLR 4.

"Still no rejit?! Are you kidding me?"

I wish I were. Given customer demand, I personally rate rejit as more important than most of the other profiling API features we're doing combined. However, rejit is very expensive in terms of development and testing. After doing the math, it became apparent that even if we cut most of the other new profiling API features for CLR 4.0, rejit would still not fit. But given the high demand, we're certainly still looking to deliver rejit in a future release of the CLR, just not 4.0.

Registry-free activation

An obstacle to getting profilers installed into production data centers is that operations managers distrust "impactful" installations that modify machine state. So we're providing a way where you no longer need to register your profiler when it's installed or used. (I'm talking here about the COM registration that uses the Windows registry to map your profiler's CLSID to the full path to the profiler's DLL.) It also turns out that, even in developer desktop scenarios, relying on the registry can be a common cause of failures. For example, perhaps your profiler tries to regsvr32 itself under HKLM, but the user does not have administrative privileges. Or maybe the user does have administrative privileges, but is using Vista in non-elevated mode. So registry-free activation should help with all of those scenarios. Note that registry-free activation is optional. Your profiler may continue to use traditional COM registration if you like.

Profiler Backward Compatibility

CLR 2.0 saw significant enough changes from CLR 1.1 that we refused to load 1.1 profilers into CLR 2.0. However, CLR 4.0 is compatible enough with CLR 2.x that we will allow 2.x profilers to load into CLR 4.0 applications. This behavior would not be the default, however. If end users try to load their 2.x profiler into a CLR 4.0 application, the load will fail, and they will see an event log entry telling them either to upgrade their profiler, or to set a special environment variable to explicitly allow the older profiler to load. By forcing the end users to opt in to this behavior, we set the expectation that it is not guaranteed or tested that 2.x profilers will still work, though we believe it is likely they will work in many scenarios.

Enter/Leave/Tailcall Enhancements

We have made some enhancements to the Enter/Leave/Tailcall interface to cut down on overhead when your profiler does not care about getting parameter or return value information.

Other random stuff

You will also find several minor enhancements and bug fixes to the profiling API. Not worth listing them all out here, but the forthcoming documentation on ICorProfilerCallback3 / ICorProfilerInfo3 will describe them.

What you must do for the CLR

Here are some of your responsibilities for playing nicely with CLR 4.0 applications.

In-process side-by-side CLR instances

Probably the biggest impact to your profiler as you upgrade it to CLR 4.0 will be supporting in-process side-by-side CLR instances. This is actually a CLR-wide feature for 4.0 (not profiling API), but it has impact on profiling API tools. Certain scenarios will now result in multiple instances of the CLR loaded into a single process, primarily to support backward-compatibility for managed components that load into a host. (Imagine one old (2.x) CLR instance alongside a new (4.0) CLR instance in the same process.) From the profiler’s point of view, it will be loaded multiple times, once per CLR instance. This means your DLL gets LoadLibrary’d multiple times and you’ll receive multiple “CreateInstance” calls to your class factory object, to generate multiple instances of your ICorProfilerCallback implementation. You can deal with this by:

Returning failure from all but one of your CreateInstance() calls. This allows you to “pick” which CLR instance you wish to interact with. OR
Succeeding many or all of your CreateInstance() calls. This allows you to examine multiple CLRs simultaneously.

Pick 1 / Pick first: With this first approach, your profiler will choose to return success from only one CreateInstance() call. "Pick 1" implies you allow your user to specify "which" CLR to profile, usually specified in terms of the version number of the CLR of interest. "Pick First" implies you don't even ask your user--you just simplistically succeed the first CreateInstance() call, and fail the rest. First CLR wins. The advantages of these approaches are they are fairly easy to implement, and either one qualifies your profiler as being "side-by-side aware".

Pick many / Pick all: With this approach, your profiler collects data on multiple CLRs, with the intent of presenting that data to the user in some unified way. You will have to be careful to manage multiple instances of your ICorProfilerCallback implementation and probably eliminate much of your global state. For example, if you call into an ICorProfilerInfo from one CLR with IDs (e.g., AppDomainID) of the other CLR, that will likely cause an AV. Many profilers are implemented with a global pointer to the "one and only" instance of their ICorProfilerCallback implementation. This would no longer work, as you will now have multiple instances of your ICorProfilerCallback implementation, and each one must keep track of the corresponding ICorProfilerInfo interface to call into. There will be enhancements to the profiling API to make this management easier, most notably improvements to the Enter/Leave/Tailcall and FunctionIDMapper interfaces.

I cannot stress the following enough, so I will state it twice. When you update your profiler to work with CLR 4.0, you must update your profiler to become side-by-side aware. This means you must do some amount of work, even if it is the simple "pick first" approach. The CLR determines whether your profiler is "updated for CLR 4.0" by QI'ing for the new ICorProfilerCallback3 defined in the CLR 4.0 corprofl.IDL file. If your profiler successfully returns a pointer to your ICorProfilerCallback3 implementation, then your profiler is considered a 4.0 profiler. So to restate: If your profiler provides an ICorProfilerCallback3 implementation, then your profiler must be side-by-side aware. The reason for this rule is that the CLR puts certain safeguards in place to protect older (2.x) profilers when they might load into scenarios that involve in-process side-by-side CLR instances. If you claim your profiler is updated for 4.0, those safeguards are lifted, and you really don't want that to happen unless you're side-by-side aware.

If you're curious to learn more about this "in-process side-by-side CLR instances" feature, unfortunately the blogs and documentation are still pretty thin for the moment (though I imagine that will change in the coming months). You can take a look at the PDC talk on CLR futures, which discussed this feature at a high level. Go to the PDC 2008 site, and find the session called "PC49 Microsoft .NET Framework: CLR Futures".

Profiler Backward Compatibility

Not much extra to state here, but just to be explicit, you of course have a choice. If you have a profiler that works just fine against CLR 2.0, you may either update it to work with CLR 4.0, or not update it. If you choose to update it, that means you must implement ICorProfilerCallback3 and provide that implementation to the CLR when the CLR QI's for ICorProfilerCallback3. And, due to the contract stated above, you must also ensure your profiler is side-by-side aware (pick 1, pick first, pick many, pick all, it's up to you). The alternative is, don't update your profiler! You will miss out on the new profiling API features listed above. And your profiler may also not work well in scenarios that load in-process side-by-side CLR instances. But maybe you don't care, or maybe you just want a temporary stopgap for your users until you've had the time to update and test your profiler for CLR 4.0. Just remember that CLR 4.0 will not activate your 2.x profiler by default. You will need to tell your users about the special environment variable mentioned above to get your 2.0 profiler to load into CLR 4.0. Since this is all new stuff, the environment variable has not yet been documented at the time of this blog entry, but you can expect more info on it in MSDN when we release, and possibly info on this blog sooner.

I hope you've found this overview useful. Since this is new and not documented yet, there's not much you can do to start preparing for CLR 4.0 yet. However, I'd recommend you take a look through your code and see what it would take to become side-by-side aware.

Visual Studio 2008 SP1 and .NET Framework 3.5 SP1 Released

2008-08-14T00:21:18Z

See Soma's blog entry for more information. Also, I updated the table that maps Visual Studio versions, .NET Framework versions, and CLR versions here.

BUG: GetILFunctionBody returns wrong size

2008-05-23T02:26:30Z

In case you missed it, there was a post on our forum here:

http://forums.microsoft.com/MSDN/ShowPost.aspx?PostID=1366051&SiteID=1

and a comment on my blog here:

http://blogs.msdn.com/davbr/archive/2007/03/06/creating-an-il-rewriting-profiler.aspx#1881536

about an issue with GetILFunctionBody returning the wrong size. This is indeed a bug in CLR 2.x, and it is recommended you follow the ECMA spec help you parse the function header to determine the actual size. More details are in the forum post linked above. This bug will be fixed in a future release of the CLR.

Debugging Your Profiler II: SOS and IDs

2007-12-19T00:14:13Z

In this debugging post, I'll talk about the various IDs the profiling API exposes to your profiler, and how you can use SOS to give you more information about the IDs. As usual, this post assumes you're using CLR 2.x.

S.O.What Now?

SOS.DLL is a debugger extension DLL that ships with the CLR. You'll find it sitting alongside mscorwks.dll. While originally written as an extension to the windbg family of debuggers, Visual Studio can also load and use SOS. If you search the MSDN blogs for "SOS" you'll find lots of info on it. I'm not going to repeat all that's out there, but I'll give you a quick primer on getting it loaded.

In windbg, you'll need mscorwks.dll to load first, and then you can load SOS. Often, I don't need SOS until well into my debugging session, at which point mscorwks.dll has already been loaded anyway. However, there are some cases where you'd like SOS loaded at the first possible moment, so you can use some of its commands early (like !bpmd to set a breakpoint on a managed method). So a surefire way to get SOS loaded ASAP is to have the debugger break when mscorwks gets loaded (e.g., "sxe ld mscorwks"). Once mscorwks is loaded, you can load SOS using the .loadby command:

0:000> sxe ld mscorwks
0:000> g
ModLoad: 79e70000 7a3ff000   C:\Windows\Microsoft.NET\Framework\v2.0.50727\mscorwks.dll
eax=00000000 ebx=00000000 ecx=00000000 edx=00000000 esi=7efdd000 edi=20000000
eip=77a1a9fa esp=002fea38 ebp=002fea78 iopl=0         nv up ei pl nz na po nc
cs=0023  ss=002b  ds=002b  es=002b  fs=0053  gs=002b             efl=00000202
ntdll!NtMapViewOfSection+0x12:
77a1a9fa c22800          ret     28h
0:000> .loadby sos mscorwks

With SOS loaded, you can now use its commands to inspect the various IDs that the profiling API passes to your profiler.

Note: The following contains implementation details of the runtime. While these details are useful as a debugging aid, your profiler code cannot make assumptions about them. These implementation details are subject to change at whim.

FunctionID Walkthrough

For starters, take a look at FunctionIDs. Your profiler receives a FunctionID anytime you hit a callback that needs to, well, identify a function! For example, when it's time to JIT, the CLR issues JITCompilationStarted (assuming your profiler subscribed to that callback), and one of the parameters to the callback is a FunctionID. You can then use that FunctionID in later calls your profiler makes back into the CLR, such as GetFunctionInfo2.

As far as your profiler is concerned, a FunctionID is just an opaque number. It has no meaning in itself; it's merely a handle you can pass back into the CLR to refer to the function. Under the covers, however, a FunctionID is actually a pointer to an internal CLR data structure called a MethodDesc. I must warn you again that you cannot rely on this information when coding your profiler. The CLR team reserves the right to change the underlying meaning of a FunctionID to be something radically different in later versions. This info is for entertainment and debugging purposes only!

Ok, so FunctionID = (MethodDesc *). How does that help you? SOS just so happens to have a command to inspect MethodDescs: !dumpmd. So if you're in a debugger looking at your profiler code that's operating on a FunctionID, it can beneficial to you to find out which function that FunctionID actually refers to. In the example below, the debugger will break in my proifler's JITCompilationStarted callback and look at the FunctionID. It's assumed that you've already loaded SOS as per above.

0:000> bu UnitTestSampleProfiler!SampleCallbackImpl::JITCompilationStarted
0:000> g
...

Breakpoint 0 hit
eax=00c133f8 ebx=00000000 ecx=10001218 edx=00000001 esi=002fec74 edi=00000000
eip=10003fc0 esp=002fec64 ebp=002feca4 iopl=0         nv up ei pl nz na po nc
cs=0023  ss=002b  ds=002b  es=002b  fs=0053  gs=002b             efl=00000202
UnitTestSampleProfiler!SampleCallbackImpl::JITCompilationStarted:
10003fc0 55              push    ebp

The debugger is now sitting at the beginning of my profiler's JITCompilationStarted callback. Let's take a look at the parameters.

0:000> dv
           this = 0x00c133f8
     functionID = 0x1e3170
 fIsSafeToBlock = 1

Aha, that's the FunctionID about to get JITted. Now use SOS to see what that function really is.

0:000> !dumpmd 0x1e3170
Method Name: test.Class1.Main(System.String[])
Class: 001e1288
MethodTable: 001e3180
mdToken: 06000001
Module: 001e2d8c
IsJitted: no
m_CodeOrIL: ffffffff

Lots of juicy info here, though the Method Name typically is what helps me the most in my debugging sessions. mdToken tells us the metadata token for this method. MethodTable tells us where another internal CLR data structure is stored that contains information about the class containing the function. In fact, the profiing API's ClassID is simply a MethodTable *. [Note: the "Class: 001e1288" in the output above is very different from the MethodTable, and thus different from the profiling API's ClassID. Don't let the name fool you!] So we could go and inspect a bit further by dumping information about the MethodTable:

0:000> !dumpmt 0x001e3180
EEClass: 001e1288
Module: 001e2d8c
Name: test.Class1
mdToken: 02000002  (C:\proj\HelloWorld\Class1.exe)
BaseSize: 0xc
ComponentSize: 0x0
Number of IFaces in IFaceMap: 0
Slots in VTable: 6

And of course, !dumpmt can be used anytime you come across a ClassID and want more info on it.

IDs and their Dumpers

Now that you see how this works, you'll need to know how the profiling IDs relate to the various SOS commands that dump info on them:

ID	Internal CLR Structure	SOS command
AssemblyID	Assembly *	!DumpAssembly
AppDomainID	AppDomain *	!DumpDomain
ModuleID	Module *	!DumpModule
ClassID	MethodTable *	!DumpMT
ThreadID	Thread *	!Threads (see note)
FunctionID	MethodDesc *	!DumpMD
ObjectID	Object * (i.e., a managed object)	!DumpObject

Note: !Threads takes no arguments, but simply dumps info on all threads that have ever run managed code. If you use "!Threads -special" you get to see other special threads separated out explicitly, including threads that perform GC in server-mode, the finalizer thread, and the debugger helper thread.

More Useful SOS Commands

It would probably be quicker to list what isn't useful! I encourage you to do a !help to see what's included. Here's a sampling of what I commonly use:

!u is a nice SOS analog to the windbg command "u". While the latter gives you a no-frills disassembly, !u works nicely for managed code, including spanning the disassembly from start to finish, and converting metadata tokens to names.

!bpmd lets you place a breakpoint on a managed method. Just specify the module name and the fully-qualified method name. For example:

!bpmd MyModule.exe MyNamespace.MyClass.Foo

If the method hasn't jitted yet, no worries. A "pending" breakpoint is placed. If your profiler performs IL rewriting, then using !bpmd on startup to set a managed breakpoint can be a handy way to break into the debugger just before your instrumented code will run (which, in turn, is typically just after your instrumented code has been jitted). This can help you in reproducing and diagnosing issues your profiler may run into when instrumenting particular functions (due to something interesting about the signature, generics, etc.).

!PrintException: If you use this without arguments you get to see a pretty-printing of the last outstanding managed exception on the thread; or specify a particular Exception object's address.

Ok, that about does it for SOS. Hopefully this info can help you track down problems a little faster, or better yet, perhaps this can help you step through and verify your code before problems arise.

Debugging Your Profiler I: Activation

2007-12-12T04:26:28Z

This is the first of some tips to help you debug your profiler. Note that these tips assume you're using CLR 2.x (see this entry for info on how CLR version numbers map to .NET Framework version numbers). In today's post, I address a frequent question from profiler developers and users: "Why didn't my profiler load?".

Event log

In the Application event log, you'll see entries if the CLR attempts, but fails, to load and initialize your profiler. So this is a nice and easy place to look first, as the message may well make it obvious what went wrong.

Weak link in the chain?

The next step is to carefully retrace this chain to make sure everything is registered properly:

Environment variables --> Registry --> Profiler DLL on File system.

The first link in this chain is to check the environment variables inside the process that should be profiled. If you're running the process from a command-prompt, you can just try a "set co" from the command prompt:

C:\>set co
(blah blah, other vars beginning with "co")

Cor_Enable_Profiling=0x1
COR_PROFILER={C5F90153-B93E-4138-9DB7-EB7156B07C4C}

If your scenario doesn't allow you to just run the process from a command prompt, like say an asp.net scenario, you may want to attach a debugger to the process that's supposed to be profiled, or use IFEO (HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Image File Execution Options) to force a debugger to start when the worker process starts. In the debugger, you can then use "!peb" to view the environment block, which will include the environment variables.

Once you verify Cor_Enable_Profiling and COR_PROFILER are ok, it's time to search the registry for the very same GUID set in your COR_PROFILER environment variable. You should find it at a path like this:

HKEY_LOCAL_MACHINE\SOFTWARE\Classes\CLSID\{C5F90153-B93E-4138-9DB7-EB7156B07C4C}

Note! If you're on a 64 bit box, be aware of the WOW64 redirectors, and ensure you're looking at the proper view of the environment and registry!

If the registry has the GUID value, it's finally time to check out your file system. Go under the InprocServer32 subkey under the GUID:

HKEY_LOCAL_MACHINE\SOFTWARE\Classes\CLSID\{C5F90153-B93E-4138-9DB7-EB7156B07C4C}\InprocServer32

and look at the default value data. It should be a full path to your profiler's DLL. Verify it's accurate. If not, perhaps you didn't properly run regsvr32 against your profiler, or maybe your profiler's DllRegisterServer had problems.

Time for a debugger

If the above investigation indicates everything's ok, then your profiler is properly registered and your environment is properly set up, but something bad must be happening at run time. You'll want symbols for the CLR, which are freely available via Microsoft's symbol server. If you set this environment variable, you can ensure windbg will always use the symbol server:

set _NT_SYMBOL_PATH=srv*C:\MySymbolCache*http://msdl.microsoft.com/download/symbols

Feel free to add more paths (separate them via ";") so you can include your profiler's symbols as well. Now, from a command-prompt that has your Cor_Enable_Profiling and COR_PROFILER variables set, run windbg against the executable you want profiled. The debuggee will inherit the environment, so the profiling environment variables will be propagated to the debuggee.

Once windbg is running, try setting this breakpoint:

bu mscordbc!EEToProfInterfaceImpl::CreateProfiler

Now go! If you hit that breakpoint, that verifies the CLR has determined that a profiler has been requested to load from the environment variables, but the CLR has yet to read the registry. Let's see if your DLL actually gets loaded. You can use

sxe ld NameOfYourProfiler.dll

or even set a breakpoint inside your Profiler DLL's DllMain. Now go, and see if your profiler is getting loaded. If you can verify your profiler's DLL is getting loaded, then you now know your registry is pointing to the proper path, and any static dependencies your profiler has on other DLLs have been resolved. But will your profiler COM object get instantiated properly? Set breakpoints in your class factory (DllGetClassObject) and your profiler COM object's QueryInterface to see if you can spot problems there. For example, if your profiler only works against CLR 1.x, then the CLR's call into your QueryInterface will fail, since you don't implement ICorProfilerCallback2.

If you're still going strong, set a breakpoint in your profiler's Initialize() callback. Failures here are actually a popular cause for activation problems. Inside your Initialize() callback, your profiler is likely calling QueryInterface for the ICorProfilerInfoX interface of your choice, and then calling SetEventMask, and doing other initialization-related tasks, like calling SetEnterLeaveFunctionHooks(2). Do any of these fail? Is your Initialize() callback returning a failure HRESULT?

Hopefully by now you've isolated the failure point. If not, and your Initialize() is happily returning S_OK, then your profiler is apparently loading just fine. At least it is when you're debugging it. :-)

Versions of Microsoft .NET Framework, CLR, and Your Profiler

2007-12-06T20:40:00Z

[Updated 8/13/2008 with the release of Visual Studio 2008 SP1.]

With the many releases of the Microsoft .NET Frameworks and their service packs, it might not be obvious what versions of the Common Language Runtime (CLR) come alongside them and whether your profiler should care. So I'm posting this to help clarify the various versions.

Note: I'm not talking about the Microsoft .NET Compact Framework or Microsoft .NET Micro Framework in this post.

Check it out!

Before I go any further, I invite you to learn more about the recently released Visual Studio 2008 SP1 and Microsoft .NET Framework 3.5 SP1. Some great places to start:

Visual Studio 2008 and Microsoft .NET Framework 3.5:

this post from ScottGu's blog, this post from Soma's blog, or directly at the Visual Studio page http://www.microsoft.com/vstudio.

Visual Studio 2008 SP1 and Microsoft .NET Framework 3.5 SP1:

this post from Soma's blog.

Definitions

Ok, so what's the difference between "Common Language Runtime (CLR)" and "Microsoft .NET Framework"? I think of it as:

CLR + managed libraries and tools = Microsoft .NET Framework

The CLR is the low-level technology (much of it written in unmanaged, native code) that includes the garbage collector, security subsystem, just-in-time compiler, type system, the profiling API (of course :-)), and other similar stuff. Much of this tends to reside in mscorwks.dll.

If you then add onto that list the many rich managed libraries for implementing graphical user interfaces, web services, accessing Windows OS functionality, etc., as well as the managed language compilers and tools, you get the Microsoft .NET Framework.

Disclaimer: These definitions are how I, geek-Dave, keep things straight in my head. I'm not in marketing so the names I'm using might not be perfectly accurate (e.g., I'm probably missing terms like "SDK" or "redistributable package"). Please don't take these as Microsoft Official Definitions.

Versions

You can get the various Microsoft .NET Framework versions via Windows Update, by searching on http://download.microsoft.com, or by installing the corresponding version of Visual Studio. Also, Windows Vista comes with Microsoft .NET Framework 3.0 as an optionally installable component.

Here's how the Microsoft .NET Framework versions >= 2.0 correlate with the CLR versions:

Microsoft .NET Framework version	CLR version	Ships with Visual Studio Version
2.0	2.0	2005
2.0 SP1	2.0 SP1	2008 (via .NET 3.5 install)
3.0	2.0	(comes with Vista)
3.0 SP 1	2.0 SP1	2008 (via .NET 3.5 install)
3.5	2.0 SP1	2008
3.5 SP 1	2.0 SP2	2008 SP1

Note that the latest CLR version at the time of writing this post is CLR 2.0 SP2 (no such thing as CLR 3.x!).

One exciting note here is that Visual Studio 2008 will actually let you target all three of .NET 2.0, .NET 3.0, and .NET 3.5.

Your Profiler

CLR Versions

Your profiler interacts with the CLR Profiling API, so you likely care which CLR version you're interacting with. Knowing that the .NET Framework 2.x/3.x versions are all based on CLR 2.x simplifies the picture for you, as you're assured that the profiling API remains compatible across those versions. However, it's fair to expect that CLR service packs might bring small changes or bug fixes. CLR 2.0 SP1, for example, contains the following profiling API fixes:

SetEnterLeaveFunctionHooks2 returned E_INVALIDARG if any of the specified callback pointers were NULL. For example, one might wish to specify an Enter probe (non-NULL) but not specify a Leave probe (NULL); this was disallowed. Fix: SetEnterLeaveFunctionHooks2 now allows one or more of the callback parameters to be NULL.
Various fixes around IMethodMalloc::Alloc
When a profiler was monitoring Leave calls in order to inspect non-primitive, value-type return values, the profiling API would sometimes specify an invalid value. This has been fixed. (More info about this bug was posted here and here.)

CLR 2.0 SP2 had no fixes or changes of note in the profiling API.

Microsoft .NET Framework Versions

Your profiler may also (optionally) take dependencies on the libraries. For example, if you have an instrumenting profiler that performs IL rewriting on some framework library code, then your profiler should deal gracefully with the cases that the libraries themselves may be different in the various .NET Framework versions. Other than that, your profiler probably doesn't need to care which version of the libraries is in use.

Long Story Short

Although there are several Microsoft .NET Framework versions out there, your CLR 2.x-based profiler should still be fine. Of course, the CLR is under active development (those libraries teams aren't the only ones having fun), so look forward to exciting things for your profiler to take advantage of in the future.