CLR Activation Debugging

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

1. Build a summary table:

| Process | Log Files | Outcome | Runtime Selected | FOD? | |---------|-----------|---------|-----------------|------| | ... | ... | ... | ... | ... |

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:

| Entry Point | Meaning | |-------------|---------| | _CorExeMain | Managed EXE launch — the binary IS a .NET assembly | | DllGetClassObject. Clsid: {guid} | COM activation — something CoCreated a COM class routed through mscoree.dll | | ClrCreateInstance | Modern (v4+) hosting API | | CorBindToRuntimeEx | Legacy (v1/v2) hosting API — binds the process to one runtime | | ICLRMetaHostPolicy::GetRequestedRuntime | Policy-based hosting API (often called internally after other entry points) | | LoadLibraryShim | Legacy API to load a framework DLL by name |

#### 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.

1. 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
2. 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)

Related skills