Clr Activation Debugging

CLR Activation Debugging

Diagnose .NET Framework runtime activation issues by analyzing CLR activation logs (CLRLoad logs) produced by the shim (mscoree.dll). These logs record every decision the shim makes when selecting and loading a CLR version.

When to Use

• A process fails to load the CLR at all ("Unable to find a version of the runtime to use")
• The shim picks the wrong CLR version (e.g., v2.0 instead of v4.0)
• Unexpected .NET 3.5 Feature-on-Demand (FOD) install dialogs appear
• FOD dialogs are expected but do NOT appear
• Both CLR v2 and CLR v4 load into the same process, causing failures
• A COM object fails to activate because the shim can't resolve the runtime
• Legacy hosting APIs (CorBindToRuntime) bind to an unexpected version

When Not to Use

• Modern .NET (CoreCLR / .NET 5+) — this skill covers .NET Framework only (the mscoree.dll shim)
• Assembly binding failures — use Fusion logs (fuslogvw.exe), not CLR activation logs
• Runtime crashes after the CLR has loaded — activation succeeded; the problem is elsewhere

Background

The Shim Architecture

The .NET Framework shim has two layers:

• mscoree.dll (the "shell shim") — the public-facing DLL that is the registered InprocServer32 for CLR-hosted COM objects and the entry point for _CorExeMain, legacy APIs, etc.
• mscoreei.dll — the actual shim implementation where the runtime selection logic, logging, and activation decisions live. mscoree.dll forwards into mscoreei.dll.

When reading logs, the caller-name:mscoreei.dll in FOD command lines reflects this — it's mscoreei.dll doing the work.

.NET 3.5 / v2.0.50727 Version Mapping

.NET 2.0, 3.0, and 3.5 all share the same CLR runtime version: v2.0.50727. The "3.0" and "3.5" releases were library additions on top of CLR v2.0. For activation purposes, they are all "v2.0.50727." When the shim resolves to v2.0.50727 or FOD offers to install "NetFx3", it's installing the CLR v2.0 runtime (plus the 3.0/3.5 libraries). Similarly, CLR v4.0 (v4.0.30319) covers all .NET Framework versions from 4.0 through 4.8.x.

.NET 3.5 Availability on Recent Windows

On recent Windows versions (Windows 11 Insider Preview Build 27965 and future platform releases), .NET Framework 3.5 is no longer available as a Windows optional component (Feature-on-Demand). It must be installed from a standalone MSI. This means the FOD dialog (fondue.exe /enable-feature:NetFx3) will not succeed on these systems even if it fires. On Windows 10 and Windows 11 through 25H2, FOD remains available. .NET Framework 3.5 reaches end of support on January 9, 2029.

Shim HRESULT Codes

When the shim fails, it returns specific HRESULTs in the 0x8013xxxx range. These are the errors you'll see from callers (not in the activation logs themselves, which log human-readable messages):

If a user reports one of these HRESULTs (especially 0x80131700), CLR activation logs are the right diagnostic tool.

Prerequisites

CLR activation logging must be enabled to produce log files. If the user doesn't have logs yet, instruct them to enable logging:

Via environment variable (recommended — scoped to current session):

set COMPLUS_CLRLoadLogDir=C:\CLRLoadLogs

Via registry (machine-wide — affects all .NET Framework processes):

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\.NETFramework
  CLRLoadLogDir = "C:\CLRLoadLogs" (REG_SZ)

On 64-bit systems, also set under Wow6432Node if 32-bit processes are involved.

⚠️ The log directory must already exist. The shim will not create it. If it doesn't exist, no logs will be written and there will be no error or indication of failure.

Logs are written as {ProcessName}.CLRLoad{NN}.log (NN = 00–99, one per process instance). Logs cannot be read until the process exits — the file is held open.

After capturing, remove the env var or registry key to stop logging.

Inputs

Workflow

Step 1: Load Reference Material

Try to load the reference files in this order — they contain the detailed log format, decision flow, and CLSID registry documentation:

1. references/log-format.md — Log line format, fields, and all known log message types 2. references/activation-flow.md — The shim's decision tree for runtime selection 3. references/com-activation.md — COM (DllGetClassObject) activation specifics, CLSID registry layout

If reference files are not available, proceed using the inline knowledge below.

Step 2: Survey the Log Files

Get the big picture before diving into any single log:

1. List all log files and group by process name — this shows which executables triggered CLR activation 2. For each process, scan for outcome lines:

• Decided on runtime: vX.Y.Z — successful resolution
• ERROR: — failed resolution
• Launching feature-on-demand — FOD dialog was shown
• Could have launched feature-on-demand — FOD would have fired but was suppressed
• V2.0 Capping is preventing consideration — v4+ was skipped due to capping

grep -l "ERROR:\|Launching feature-on-demand\|Could have launched" *.log
grep -c "Launching feature-on-demand" *.log

3. Build a summary table:

Step 3: Analyze Problematic Logs

For each log file with an unexpected outcome, trace the full activation flow. Read the log top-to-bottom and identify:

⚠️ Nested log entries: The shim's own internal calls can trigger additional log entries within an activation sequence that is already being logged. For example, a DllGetClassObject call may internally call ComputeVersionString, which calls FindLatestVersion, each generating log lines. When the FOD check runs ("Checking if feature-on-demand installation would help"), it re-runs the entire version computation — producing a second ComputeVersionString block within the same activation. Don't mistake these nested/re-entrant entries for separate activation attempts.

3a. Entry Point

The first FunctionCall: or MethodCall: line tells you how activation was triggered:

3b. Input Parameters

Immediately after the entry point, the log dumps the version computation inputs:

• `IsLegacyBind`: Is this a legacy (pre-v4) activation path? If 1, the shim uses the single-runtime "legacy" view of the world. Legacy APIs (CorBindToRuntimeEx, DllGetClassObject for legacy COM, LoadLibraryShim, etc.) set this.
• `IsCapped`: If 1, the shim's roll-forward semantics are capped at Whidbey (v2.0.50727) — it will NOT consider v4.0+ when enumerating installed runtimes. This is the mechanism that makes v4 installation non-impactful: legacy codepaths continue to behave as if v4 doesn't exist. On a v4-only machine with no .NET 3.5, a capped enumeration sees no runtimes at all. Capping does NOT prevent loading v4+ if a specific v4 version string is explicitly provided (e.g., via CorBindToRuntimeEx("v4.0.30319", ...) or via config with useLegacyV2RuntimeActivationPolicy).
• `SkuCheckFlags`: Controls SKU (edition) compatibility checking.
• `ShouldEmulateExeLaunch`: Whether to pretend this is an EXE launch for policy purposes.
• `LegacyBindRequired`: Whether a legacy bind is strictly required.

3c. Config File Processing

Look for config file parsing results:

• Parsing config file: {path} — the shim is looking for a .config file
• Config File (Open). Result:00000000 — config file found and opened successfully
• Config File (Open). Result:80070002 — config file not found (HRESULT for ERROR_FILE_NOT_FOUND)
• Found config file: {path} — config was successfully read
• UseLegacyV2RuntimeActivationPolicy is set to {0|1} — whether <startup useLegacyV2RuntimeActivationPolicy="true"> is present. When 1, all runtimes are treated as candidates for legacy codepaths — meaning legacy shim APIs can enumerate and choose v4+. This can be used with multiple <supportedRuntime> entries, with other config options, or even with no <supportedRuntime> entries at all (in which case legacy APIs can simply enumerate v4). Side effect: turns off in-proc SxS with pre-v4 runtimes — locks them out of the process.
• Config file includes SupportedRuntime entry. Version: vX.Y.Z, SKU: {sku} — each <supportedRuntime> found in config

Key insight: If a process has no config file AND is doing a capped legacy bind, the shim has nothing to direct it to v4.0. It will enumerate installed runtimes (capped to ≤v2.0), find nothing if 3.5 isn't installed, and fail. This is by design — v4 is intentionally invisible to these codepaths to keep v4 installation non-impactful.

3d. Version Resolution

• Installed Runtime: vX.Y.Z. VERSION_ARCHITECTURE: N — what's installed on the machine
• {exe} was built with version: vX.Y.Z — version from the binary's PE header (managed assemblies only; native EXEs won't have this)
• Using supportedRuntime: vX.Y.Z — the shim picked a version from the config's <supportedRuntime> list
• FindLatestVersion is returning the following version: vX.Y.Z ... V2.0 Capped: {0|1} — result of policy-based latest-version search
• Default version of the runtime on the machine: vX.Y.Z or (null) — what the shim settled on; (null) means nothing was found
• Decided on runtime: vX.Y.Z — final decision — this is the version that will be loaded

3e. Failure and FOD Path

If version resolution fails:

1. ERROR: Unable to find a version of the runtime to use — the shim found no suitable runtime 2. SEM_FAILCRITICALERRORS is set to {value} — checks the process error mode:

• Value 0: Error dialogs and FOD are ALLOWED
• Nonzero (any bit set, commonly 0x8001): Error dialogs and FOD are SUPPRESSED. The SEM_FAILCRITICALERRORS flag (0x0001) is inherited from the parent process.

3. Checking if feature-on-demand installation would help — the shim re-runs version computation to see if installing .NET 3.5 would resolve the request 4. Then either:

• Launching feature-on-demand installation. CmdLine: "...\fondue.exe" /enable-feature:NetFx3 — FOD dialog shown
• Could have launched feature-on-demand installation if was not opted out. — FOD suppressed because SEM_FAILCRITICALERRORS was set

3f. Multiple Activations in One Process

A single log can contain multiple activation sequences. Each begins with a new FunctionCall: or MethodCall: entry. A common pattern:

1. First activation via ClrCreateInstance / GetRequestedRuntime → succeeds (loads v4.0 via config) 2. Second activation via DllGetClassObject (COM) → legacy bind, capped → fails

This happens when a native EXE (like link.exe or mt.exe) loads the CLR successfully for its primary work, then a secondary COM activation request (e.g., for diasymreader) triggers a separate legacy resolution that can't find v2.0.

Step 4: Check System State (if needed)

When log analysis points to a registration or configuration issue, check:

CLSID Registration (for COM activation issues):

# Check the CLSID entry
Get-ItemProperty 'Registry::HKCR\CLSID\{guid}'
Get-ItemProperty 'Registry::HKCR\CLSID\{guid}\InprocServer32'
Get-ChildItem 'Registry::HKCR\CLSID\{guid}\InprocServer32' | ForEach-Object {
    Write-Output "--- $($_.PSChildName) ---"
    Get-ItemProperty "Registry::$($_.Name)"
}

Key values under InprocServer32:

• (Default) should be mscoree.dll for CLR-hosted COM objects
• Version subkeys (e.g., 2.0.50727, 4.0.30319) indicate which runtime versions registered this CLSID
• `ImplementedInThisVersion` under a version subkey means that runtime version natively implements the COM class (not via managed interop)
• `Assembly` and `Class` under a version subkey indicate a managed COM interop registration
• `RuntimeVersion` under a version subkey specifies which CLR version should host this object

Installed runtimes:

Get-ChildItem 'Registry::HKLM\SOFTWARE\Microsoft\.NETFramework\policy'

Process error mode (why FOD did/didn't fire): The SEM_FAILCRITICALERRORS flag is inherited from the parent process. If a build system or script sets it (or calls SetErrorMode), all child processes inherit it.

Step 5: Diagnose and Report

Produce a clear diagnosis covering:

1. What happened — which process(es) had activation issues and what the symptom was 2. Why it happened — trace through the specific decision path in the shim that led to the outcome 3. What controls the behavior — identify the specific inputs (config file presence, error mode, CLSID registration, capping state) that determined the outcome 4. What changed (if applicable) — if the user says behavior changed, identify which input could have changed (error mode from parent process, config file, CLSID registration, installed runtimes)

Common Scenarios

Unexpected FOD Dialogs

Pattern: DllGetClassObject → IsCapped: 1 → no config file → (null) → SEM_FAILCRITICALERRORS: 0 → FOD launched

Root cause: A native EXE is doing COM activation of a CLSID registered under mscoree.dll. This takes the legacy codepath, which is capped at v2.0. With no config file (and no useLegacyV2RuntimeActivationPolicy), v4 is invisible to this codepath. On a machine without .NET 3.5, there are no runtimes visible, and with SEM_FAILCRITICALERRORS not set, the FOD dialog fires.

Key question: Why did SEM_FAILCRITICALERRORS change? It's inherited from the parent. Different launch methods (script vs. direct invocation, different build systems) produce different error modes. The underlying capped-legacy-bind-on-v4-only-machine failure is always there — it's just that SEM_FAILCRITICALERRORS controls whether it manifests as a visible dialog or a silent failure.

Wrong Runtime Selected

Pattern: supportedRuntime entries in config list multiple versions; the shim picks the first one that's installed. If v2.0 is listed first and .NET 3.5 is installed, v2.0 wins even though v4.0 is also available.

Key insight: Config <supportedRuntime> entries are evaluated in order. First installed match wins.

Both v2 and v4 Loaded

Pattern: Multiple activation sequences in the same process log — one binds v4, another binds v2 (or vice versa). Side-by-side loading of CLR v2 and v4 in the same process IS supported but can cause issues with shared state.

Key insight: Look for separate Decided on runtime lines with different versions in the same log file.

Legacy Runtime Already Bound

Pattern: A legacy codepath succeeds early in the process (e.g., CorBindToRuntimeEx with an explicit v4 version, or config with useLegacyV2RuntimeActivationPolicy). This sets the legacy runtime to v4.0. All subsequent legacy activations — including capped COM activations that would otherwise fail — silently succeed by reusing the already-bound legacy runtime.

Key insight: The ORDER of activations within a process matters. If v4.0 is bound as the legacy runtime first, capped COM activations work. If the capped COM activation happens first (before any legacy runtime is bound), it fails. This means behavior can depend on which component activates first — a race condition in concurrent code can change the outcome.

Common Pitfalls

Validation

Before delivering a diagnosis, verify:

• [ ] All log files with errors or FOD triggers were analyzed (not just the first one)
• [ ] The entry point for each problematic activation was identified
• [ ] The capping and legacy bind state was noted for each activation sequence
• [ ] Config file presence/absence was checked
• [ ] SEM_FAILCRITICALERRORS state was noted for FOD-related issues
• [ ] Multiple activations within a single log were individually traced
• [ ] The diagnosis explains the specific decision path, not just the outcome

CLR Shim Activation Flow Reference

Overview

The CLR shim is the .NET Framework's runtime selection and loading layer. It consists of two DLLs:

• mscoree.dll (the "shell shim") — the public-facing entry point. It is the registered InprocServer32 for CLR-hosted COM objects, the target of _CorExeMain for managed EXE launch, and the DLL that legacy hosting APIs (CorBindToRuntimeEx, etc.) are exported from.
• mscoreei.dll — the actual shim implementation where all the runtime selection logic, logging, activation decisions, and policy evaluation live. mscoree.dll loads and forwards into mscoreei.dll.

The shim supports loading CLR v2.0 and CLR v4.0 side-by-side in the same process (in-proc SxS). Note that .NET 2.0, 3.0, and 3.5 all share CLR v2.0 (v2.0.50727), while .NET 4.0 through 4.8.x all share CLR v4.0 (v4.0.30319).

Key Concepts

The v4 In-Proc SxS Design

.NET 4.0 added the ability for multiple runtimes (v2.0 and v4.0) to coexist in the same process. This required a complete rethinking of the hosting API surface. A new set of APIs — the metahost APIs (defined in metahost.h: ICLRMetaHost, ICLRMetaHostPolicy, ICLRRuntimeInfo) — was introduced with a multi-runtime view of the world. The entire existing mscoree.h API surface became "legacy."

The central design constraint: installing v4 must be non-impactful — it must not change the behavior of any existing component already on the machine.

Legacy Shim APIs vs. Metahost APIs

Metahost APIs (IsLegacyBind: 0): The v4+ hosting APIs. These can enumerate all installed runtimes, target specific versions, and support side-by-side loading. This is the normal path for managed EXE launch (_CorExeMain) and v4+ COM activation.

Legacy shim APIs (IsLegacyBind: 1): The entire pre-v4 API surface. These have a single-runtime-per-process view of the world, because before v4 there could only be one runtime in a process. The legacy API category encompasses:

1. `CorBindToRuntimeEx` and friends — Most flat exports of mscoree.dll defined in mscoree.h (GetCORSystemDirectory, GetCORVersion, LoadLibraryShim, etc.), plus the strong name APIs from strongname.h 2. Pre-v4 COM activation — CoCreateInstance of a CLSID whose latest registration is against a pre-v4 runtime version. This includes new on such a coclass from managed code, or Activator.CreateInstance via Type.GetTypeFromCLSID. 3. Pre-v4 IJW (mixed-mode) activation — Calling into a native export on a pre-v4 mixed-mode assembly 4. Native activation of runtime-provided COM CLSIDs — e.g., CoCreateInstance on ICLRRuntimeHost's CLSID 5. Native activation of managed framework CLSIDs — e.g., CoCreateInstance on System.ArrayList's CLSID (extremely rare)

The Legacy Runtime

Because legacy APIs have a single-runtime view, once any legacy codepath chooses a runtime version, that becomes the legacy runtime for the process (g_pLegacyAPIRuntimeInfo). All subsequent legacy API calls see and use this same runtime for the remainder of the process lifetime. After a version has been chosen by one of these codepaths, that's the version ALL of them see.

If v4.0 is bound as the legacy runtime (through any mechanism — explicit version string, config with useLegacyV2RuntimeActivationPolicy, etc.), all subsequent legacy codepaths will use v4.0.

Whidbey Capping

All legacy shim API codepaths had roll-forward semantics — they would find and use the latest installed runtime. Whidbey capping restricts ("caps") these roll-forward semantics at v2.0 (codename "Whidbey"), meaning by default, none of the legacy codepaths see v4 at all. This is what makes v4 installation non-impactful: existing components using legacy APIs continue to behave exactly as they did before v4 was installed.

When IsCapped: 1 in the logs, the shim will not consider any runtime above v2.0.50727 when enumerating installed runtimes. This has an important and intentional side effect: on a v4-only machine (no .NET 3.5 installed), legacy codepaths see NO runtimes at all — the machine appears to have nothing installed from their perspective.

Capping does NOT prevent loading v4+ if:

• A specific legitimate post-Whidbey version string is explicitly passed to a legacy API (e.g., CorBindToRuntimeEx("v4.0.30319", ...)) — the APIs will happily load it
• A config file <supportedRuntime> explicitly names a v4+ version AND useLegacyV2RuntimeActivationPolicy="true" is set
• The legacy runtime is already bound to v4+ (all subsequent legacy calls reuse it)

useLegacyV2RuntimeActivationPolicy

This config attribute is the primary mechanism for making legacy codepaths see v4. Setting useLegacyV2RuntimeActivationPolicy="true" in the <startup> element tells the shim to treat all runtimes as candidates for legacy API codepaths. It is mostly equivalent to calling `CorBindToRuntimeEx` with the full v4 version string.

It can be used:

• With one or more <supportedRuntime> entries to direct which runtime is chosen
• With other config options
• With no `<supportedRuntime>` entries at all — in which case legacy APIs can simply enumerate and discover v4

<!-- Common usage: direct legacy codepaths to v4.0 -->
<configuration>
  <startup useLegacyV2RuntimeActivationPolicy="true">
    <supportedRuntime version="v4.0"/>
  </startup>
</configuration>

<!-- Also valid: just let legacy APIs enumerate v4 -->
<configuration>
  <startup useLegacyV2RuntimeActivationPolicy="true">
  </startup>
</configuration>

Side effect: Enabling this attribute turns off in-proc SxS with pre-v4 runtimes — it locks them out of the process. The legacy runtime becomes v4, and pre-v4 runtimes cannot load.

Common reasons to use it:

• Loading pre-v4 mixed-mode (IJW) assemblies into v4
• Making legacy API calls (P/Invoke to GetCORSystemDirectory, etc.) return v4 paths
• Ensuring COM activation of managed objects uses the current runtime (v4) instead of falling back to v2

Why it isn't the default: If it were the default, installing v4 would be impactful — it would change behavior of existing components, violating the core design constraint.

Feature-on-Demand (FOD)

When the shim fails to find a runtime, it can trigger installation of .NET 3.5 via Windows Feature-on-Demand. The FOD path:

1. Only activates on Windows 8+ (not on ARM, not in AppX) 2. Re-runs version computation to check if v2.0.50727 would resolve the request 3. If yes, and if the SEM_FAILCRITICALERRORS process error mode flag is NOT set, launches fondue.exe /enable-feature:NetFx3 4. If SEM_FAILCRITICALERRORS IS set, logs "Could have launched..." but does not show the dialog 5. FOD only fires once per process (g_FeatureOnDemandHasBeenLaunched flag)

FOD only supports installing .NET 3.5 (v2.0.50727). It cannot install v4.0+.

⚠️ Recent Windows versions: Starting with Windows 11 Insider Preview Build 27965 and future platform releases, .NET 3.5 is no longer available as a Windows optional component. It must be installed from a standalone MSI. On these systems, the FOD dialog (fondue.exe /enable-feature:NetFx3) will not succeed even if it fires. This change does not affect Windows 10 or Windows 11 through 25H2. .NET Framework 3.5 reaches end of support on January 9, 2029.

SEM_FAILCRITICALERRORS Inheritance

The SEM_FAILCRITICALERRORS flag is part of the process error mode, set via SetErrorMode(). It is inherited by child processes. This means:

• If a build system or script calls SetErrorMode(SEM_FAILCRITICALERRORS), all processes it spawns will have the flag set
• If you launch a process directly from a clean cmd.exe, the flag is typically 0
• This is the most common reason FOD behavior changes between different launch methods

The Version Resolution Decision Tree

This is the order in which ComputeVersionString resolves a runtime version:

1. COMPLUS_OnlyUseLatestCLR=1? (internal testing only — not supported)
   └─ Yes → FindLatestVersion (uncapped) → done

2. Config file has <supportedRuntime> entries?
   └─ Yes → For each entry (in order):
      ├─ Is this version installed? Check SKU compatibility.
      ├─ If IsCapped AND UseLegacyV2RuntimeActivationPolicy=0:
      │   └─ Only consider v2.0.x entries (skip v4.0+)
      ├─ If IsCapped AND UseLegacyV2RuntimeActivationPolicy=1:
      │   └─ Consider ALL entries including v4.0+ (cap is lifted;
      │      chosen runtime becomes the legacy runtime)
      └─ First installed match wins → done

2b. UseLegacyV2RuntimeActivationPolicy=1 but NO <supportedRuntime> entries?
   └─ Legacy APIs can enumerate all installed runtimes (cap lifted)
      → Falls through to FindLatestVersion (uncapped)

3. Config file has <requiredRuntime> element? (legacy v1.0/v1.1)
   └─ Yes → Use that version → done

4. COMPLUS_Version environment variable set?
   └─ Yes → Use that version → done

5. Host provided a default version?
   └─ Yes → Use that version → done

6. Legacy runtime already bound (g_pLegacyAPIRuntimeInfo != NULL)?
   └─ Yes → Use that version → done

7. Binary has a PE header version (managed assemblies only)?
   └─ Yes → Use that version → done

8. None of the above?
   └─ FindLatestVersion (respects capping)
      ├─ If capped: enumerate installed runtimes ≤v2.0.50727
      ├─ If uncapped: enumerate all installed runtimes
      └─ Return highest match, or (null) if none found

If resolution returns (null) → runtime not found → enter error/FOD path.

Entry Point Details

_CorExeMain (Managed EXE Launch)

1. OS loader recognizes .NET PE header, calls _CorExeMain 2. Shim reads PE header for built-with version 3. Looks for {exe}.config for <supportedRuntime> entries 4. IsLegacyBind: 0, IsCapped: 0 (normal modern bind) 5. Follows decision tree above 6. Loads runtime, transfers control to managed entry point

DllGetClassObject (COM Activation)

This is the most complex path and the most common source of activation issues.

1. Something calls CoCreateInstance for a CLSID registered under mscoree.dll 2. Shim looks up the CLSID in the registry:

• HKCR\CLSID\{guid}\InprocServer32 → checks if (Default) is mscoree.dll
• Enumerates version subkeys (e.g., 2.0.50727, 4.0.30319)
• Reads RuntimeVersion, Assembly, Class, ImplementedInThisVersion from subkeys

3. Determines if this is a legacy or modern COM object:

• If CLSID has only old version subkeys or is a known framework COM object → legacy path
• Legacy path sets IsLegacyBind: 1, IsCapped: 1

4. Version resolution follows the decision tree 5. If the legacy runtime is already bound, reuses it (skips the entire search)

Critical implication: For native EXEs doing COM activation, if no config file exists and the legacy runtime is not already bound, a capped legacy bind will enumerate only ≤v2.0 runtimes. On a machine without .NET 3.5, this finds nothing and triggers the error/FOD path.

CorBindToRuntimeEx (Legacy Hosting)

1. Caller specifies a version (or NULL for default) 2. If version is NULL, uses FindLatestVersion (respects capping) 3. If version specified, attempts to load that exact version 4. On success, sets g_pLegacyAPIRuntimeInfo (the process-global legacy runtime) 5. Subsequent calls must match the same runtime or fail with CLR_E_SHIM_LEGACYRUNTIMEALREADYBOUND

LoadLibraryShim (Legacy DLL Loading)

1. Loads a framework DLL by name (e.g., diasymreader.dll) 2. If version specified, loads from that runtime's directory 3. If no version, uses legacy runtime if bound, otherwise finds latest

Config File Resolution

The shim looks for config files at:

1. Activation config: Set via COMPLUS_ApplicationMigrationRuntimeActivationConfigPath (rare) 2. Host config: Provided by hosting API caller (rare) 3. App config: {exe_path}.config (most common)

Config for legacy codepaths

To make legacy shim API codepaths (including capped COM activation) see v4.0:

<?xml version="1.0"?>
<configuration>
  <startup useLegacyV2RuntimeActivationPolicy="true">
    <supportedRuntime version="v4.0"/>
  </startup>
</configuration>

`useLegacyV2RuntimeActivationPolicy="true"` is the key piece — it tells the shim to treat all runtimes as candidates for legacy codepaths, lifting the Whidbey cap. The <supportedRuntime> element directs which version is chosen, but even without it, the attribute alone allows legacy APIs to enumerate v4.

Without useLegacyV2RuntimeActivationPolicy, rolling forward to v4 via <supportedRuntime> works fine for the primary EXE load (which uses the metahost path), but legacy codepaths (COM activation, P/Invoke to mscoree.h APIs, etc.) remain capped and will still look for v2.0.

Trade-off: Setting useLegacyV2RuntimeActivationPolicy="true" turns off in-proc SxS with pre-v4 runtimes. This is usually acceptable for build tools and utilities, but should be considered for applications that need to host both v2 and v4.

Environment Variables That Affect Activation

COM Activation Through the CLR Shim — Reference

How COM Objects End Up in mscoree.dll

When a COM object is implemented in managed code (or is a CLR-internal component like diasymreader), its InprocServer32 registry entry points to mscoree.dll. When CoCreateInstance is called for such a CLSID, the OS loads mscoree.dll and calls its DllGetClassObject.

The shim then must determine: 1. Which CLR version should host this COM object 2. Whether the CLR is already loaded in this process 3. Whether to use legacy or modern activation

CLSID Registry Layout

HKCR\CLSID\{guid}
│   (Default) = "Friendly Name"
│   MasterCLSID = "{other-guid}"    (optional, for redirected CLSIDs)
│
└── InprocServer32
    │   (Default) = "C:\Windows\System32\mscoree.dll"
    │   ThreadingModel = "Both"
    │
    ├── 2.0.50727                    (version subkey — CLR v2 registration)
    │   │   (Default) = "2.0.50727"
    │   │   Assembly = "FullAssemblyName"       (managed interop)
    │   │   Class = "Namespace.ClassName"       (managed interop)
    │   │   RuntimeVersion = "v2.0.50727"       (which CLR to load)
    │   └── ImplementedInThisVersion = ""       (native CLR component, not interop)
    │
    └── 4.0.30319                    (version subkey — CLR v4 registration)
        │   (Default) = "4.0.30319"
        │   Assembly = "FullAssemblyName"
        │   Class = "Namespace.ClassName"
        │   RuntimeVersion = "v4.0.30319"
        └── ImplementedInThisVersion = ""

Key Registry Values

`(Default)` under InprocServer32: Must be mscoree.dll (or full path) for the shim to handle it.

Version subkeys (e.g., 2.0.50727, 4.0.30319): Each subkey represents a CLR version that registered this CLSID. The shim uses these to determine which runtime version(s) can host the object.

`RuntimeVersion`: The CLR version to load for this object. Read from the highest applicable version subkey.

`Assembly` and `Class`: For managed COM interop — the managed assembly and type that implement the COM object. If present, the CLR loads this assembly and creates the managed type.

`ImplementedInThisVersion`: When this value exists (even if empty), it marks the COM class as a native CLR component — something implemented inside the runtime itself (like the metadata APIs, symbol readers, etc.), not a managed interop object. The shim handles these differently from managed COM.

`SupportedRuntimeVersions` (directly under InprocServer32): Semicolon-delimited list of runtime versions. Acts like a <supportedRuntime> list in a config file. Example: v2.0.50727;v4.0.30319.

`MasterCLSID`: If present on the CLSID key, redirects to another CLSID for version lookup purposes. Used for COM objects that have been superseded.

The DllGetClassObject Decision Flow

DllGetClassObject(rclsid, riid, ppv)
│
├─ 1. Is this an AppX process with a disallowed CLSID? → E_NOTIMPL
│
├─ 2. Is this CLSID cached in g_pCVMList?
│     └─ Yes → Call cached DllGetClassObject directly → done
│
├─ 3. Try LoadUnmanagedCOMObject() — handles non-CLR objects
│     └─ Success → done (no CLR involved)
│
├─ 4. Classify the CLSID:
│     ├─ IsClrHostedLegacyComObject()? → Legacy COM object
│     ├─ IsCLSIDImplementedInFrameworkAssembly()? → Framework assembly COM
│     └─ Neither → Modern managed COM
│
├─ 5. Determine activation path:
│     │
│     ├─ MODERN PATH (not legacy, not framework):
│     │   └─ GetClassObjectForManagedType()
│     │       ├─ Uses ICLRMetaHostPolicy with METAHOST_POLICY_HIGHCOMPAT
│     │       ├─ IsLegacyBind: 0, IsCapped: 0
│     │       └─ Config file + version subkeys guide runtime selection
│     │
│     └─ LEGACY PATH (legacy or framework COM):
│         └─ RequestRuntimeDll()
│             ├─ Sets IsLegacyBind: 1, IsCapped: 1
│             ├─ Sets fLatestVersion: TRUE (find latest within cap)
│             ├─ If g_pLegacyAPIRuntimeInfo already set → use it directly
│             └─ Otherwise → ComputeVersionString → FindLatestVersion (capped)
│
└─ 6. Load the CLR, get class factory, return object

Why Native Build Tools Trigger COM Activation

Native tools like link.exe, mt.exe, CL.exe are not .NET applications, but they may use COM objects that are implemented inside the CLR:

• Diasymreader ({E5CB7A31-7512-11D2-89CE-0080C792E5D8}): Debug symbol writer/reader, used by tools that produce or consume PDB files
• SymBinder ({0A29FF9E-7F9C-4437-8B11-F424491E3931}): Symbol binder for debug information
• ALink ({B79B0ACD-F5CD-409B-B5A5-A16244610B92}): Assembly linker

These COM objects have InprocServer32 = mscoree.dll and go through the full shim activation path. Because they're activated via DllGetClassObject (not via a managed EXE launch), they take the legacy COM path with IsCapped: 1.

The Legacy Runtime Binding Order Problem

The order of activations within a process determines behavior:

Scenario A: Primary load first, COM activation second (common for link.exe, CL.exe)

1. ClrCreateInstance → ICLRMetaHostPolicy::GetRequestedRuntime
   → Config says supportedRuntime v4.0 → Loads v4.0 → Success
   → g_pLegacyAPIRuntimeInfo may or may not be set yet

2. DllGetClassObject for diasymreader
   → Legacy bind, IsCapped: 1
   → If g_pLegacyAPIRuntimeInfo is set to v4.0 → uses v4.0 → OK
   → If NOT set → FindLatestVersion (capped to v2.0) → fails on machines without 3.5

Scenario B: COM activation is the ONLY activation (common for mt.exe)

1. DllGetClassObject for diasymreader
   → Legacy bind, IsCapped: 1
   → No legacy runtime bound yet
   → No config file
   → FindLatestVersion (capped to v2.0) → (null) → ERROR → FOD

Scenario C: Legacy hosting API sets the runtime first

1. CorBindToRuntimeEx(v4.0) → binds g_pLegacyAPIRuntimeInfo to v4.0
2. DllGetClassObject for anything → legacy bind → uses g_pLegacyAPIRuntimeInfo (v4.0) → OK

Diagnosing CLSID Issues

Check the CLSID registration

$clsid = '{E5CB7A31-7512-11D2-89CE-0080C792E5D8}'

# Main CLSID entry
Get-ItemProperty "Registry::HKCR\CLSID\$clsid" -ErrorAction SilentlyContinue

# InprocServer32 (should be mscoree.dll)
Get-ItemProperty "Registry::HKCR\CLSID\$clsid\InprocServer32" -ErrorAction SilentlyContinue

# Version subkeys — what runtimes registered this CLSID?
Get-ChildItem "Registry::HKCR\CLSID\$clsid\InprocServer32" -ErrorAction SilentlyContinue |
    ForEach-Object {
        Write-Output "`n--- $($_.PSChildName) ---"
        Get-ItemProperty "Registry::$($_.Name)" -ErrorAction SilentlyContinue
    }

What to look for

Registration corruption from build races

If a build process registers/unregisters COM objects (e.g., via regasm.exe), concurrent registrations can corrupt CLSID entries:

• A version subkey may be deleted or partially written
• Assembly/Class values may be missing or point to the wrong type
• RuntimeVersion may be incorrect

Check for partial registrations by verifying that all expected values exist under each version subkey.

CLR Activation Log Format Reference

Enabling Logging

Set one of:

• Environment variable: COMPLUS_CLRLoadLogDir=C:\path\to\logdir
• Registry: HKLM\SOFTWARE\Microsoft\.NETFramework\CLRLoadLogDir (REG_SZ)
• On 64-bit, also HKLM\SOFTWARE\Wow6432Node\Microsoft\.NETFramework\CLRLoadLogDir for 32-bit processes

⚠️ The log directory must already exist. The shim will not create it. If it doesn't exist, no logs will be written and there will be no error or indication of failure.

Logs are written by mscoreei.dll (the shim implementation DLL loaded by mscoree.dll). They are written while the process runs and cannot be opened until the process exits.

File Naming

{ProcessName}.CLRLoad{NN}.log

• {ProcessName} = the EXE name (e.g., mt.exe, csc.exe, MSBuild.exe)
• {NN} = sequence number 00–99 (increments if the previous file exists, one per process instance)
• Multiple log files for the same EXE indicate multiple process invocations

Line Format

Every line in the log follows this format:

ThreadID,TickCount.Milliseconds,Message

• ThreadID: OS thread ID (decimal) that produced the log entry
• TickCount.Milliseconds: Time in GetTickCount() units — seconds since system boot, with millisecond precision. Useful for ordering events and measuring elapsed time within and across logs.
• Message: The log message (see below)

Header Lines

The first three lines of every log are:

{tid},{tick},CLR Loading log for {full_path_to_exe}
{tid},{tick},Log started at {time} on {date}
{tid},{tick},-----------------------------------

The process path in the first line identifies exactly which binary triggered CLR activation.

Log Message Reference

Entry Points

Version Computation

Config File Processing

Runtime Selection Outcomes

Errors and FOD

Process Lifecycle

Runtime Info Queries

Well-Known CLSIDs

These CLSIDs frequently appear in COM activation logs:

Well-Known IIDs

SEM_FAILCRITICALERRORS Values

The SEM_FAILCRITICALERRORS is set to {value} line reports the result of SetErrorMode(0) (which returns the previous mode). Common values:

Any nonzero value where bit 0 (SEM_FAILCRITICALERRORS = 0x0001) is set will suppress the FOD dialog.

Nested / Re-Entrant Log Entries

Log entries within a single activation sequence can include the shim's own internal calls into its own APIs. This creates nested blocks that can be confusing if you don't expect them:

• A DllGetClassObject call internally triggers ComputeVersionString, which may call FindLatestVersion — all generating log lines within the same sequence
• When the FOD check runs ("Checking if feature-on-demand installation would help"), it re-runs the entire version computation — producing a second Input values for ComputeVersionString block. This is the shim asking "if .NET 3.5 were installed, would that resolve this request?"
• A GetRequestedRuntime call may internally trigger GetFileVersion and config parsing

The key to reading these is: watch for the major entry point lines (FunctionCall:, MethodCall:) to distinguish top-level activations from internal re-entrant calls.

.NET 3.5 / v2.0.50727 Version Mapping

In the logs, all version strings refer to the CLR runtime version, not the .NET Framework marketing version:

.NET 2.0, 3.0, and 3.5 all share CLR v2.0 — the "3.0" and "3.5" releases added libraries on top of the same runtime. When the shim resolves to v2.0.50727 or FOD offers to install "NetFx3", it's all about CLR v2.0.

Shim HRESULT Codes

These HRESULTs are returned by the shim to callers. They don't appear in the activation logs themselves (which use human-readable messages), but knowing them helps connect caller-side errors to activation log analysis: