# 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

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

```xml
<!-- 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
<?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

| Variable | Effect |
|----------|--------|
| `COMPLUS_CLRLoadLogDir` | Directory for activation logs (**must already exist**; no error if missing) |
| `COMPLUS_Version` | Force a specific runtime version |
| `COMPLUS_DefaultVersion` | Default version for FindLatestVersion |
| `COMPLUS_Fod` | If 0, disable FOD entirely |
| `COMPLUS_FodConservativeMode` | If 1, only log FOD commands (don't execute) when error dialogs suppressed |
| `COMPLUS_ErrorDialog` | Override SEM_FAILCRITICALERRORS for error dialog display |
| `COMPLUS_ApplicationMigrationRuntimeActivationConfigPath` | Override config file path |
| `COMPLUS_OnlyUseLatestCLR` | ⚠️ **Internal testing only — not supported.** If 1, ignores capping and uses latest installed runtime. Do not use in production. |

# 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

```powershell
$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

| Observation | Meaning |
|-------------|---------|
| Only a `4.0.30319` subkey exists, no `2.0.50727` | .NET 3.5 was never installed (no v2 registration). Capped legacy binds will fail. |
| Both `2.0.50727` and `4.0.30319` subkeys exist | Both runtimes have registered this CLSID. Capped binds can use v2, uncapped can use v4. |
| `ImplementedInThisVersion` is present | This is a native CLR component (not managed interop). |
| `Assembly` and `Class` are present | This is a managed COM interop registration. |
| `SupportedRuntimeVersions` exists | Acts as an inline supportedRuntime list (semicolon-delimited). |
| `InprocServer32\(Default)` is NOT mscoree.dll | This CLSID is not CLR-hosted — shim is not involved. |

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

| Message | Meaning |
|---------|---------|
| `FunctionCall: _CorExeMain` | Managed EXE launch — the OS loader recognized a .NET assembly |
| `FunctionCall: DllGetClassObject. Clsid: {guid}, Iid: {iid}` | COM activation — CoCreateInstance routed through mscoree.dll |
| `FunctionCall: ClrCreateInstance, Clsid: {guid}, Iid: {iid}` | Modern v4+ hosting API entry |
| `LegacyFunctionCall: CorBindToRuntimeEx. Version: {ver}, BuildFlavor: {flavor}, Flags: {hex}` | Legacy v1/v2 hosting API binding |
| `LegacyFunctionCall: LoadLibraryShim. DllName: {dll}, Version: {ver}` | Legacy API to load a framework DLL |
| `LegacyFunctionCall: GetFileVersion. Filename: {path}` | Shim reading PE version from a binary |
| `MethodCall: ICLRMetaHostPolicy::GetRequestedRuntime. Version: {ver}, Metahost Policy Flags: {hex}, Binary: {path}` | Policy-based runtime request |
| `MethodCall: ICLRRuntimeInfo::GetInterface. Clsid: {guid}, Iid: {iid}` | Requesting an interface from a loaded runtime |

### Version Computation

| Message | Meaning |
|---------|---------|
| `Input values for ComputeVersionString follow this line` | Start of a version resolution block |
| `IsLegacyBind is: {0\|1}` | Whether this is a legacy (pre-v4) activation path |
| `IsCapped is {0\|1}` | Whether enumeration is restricted to ≤v2.0.50727 |
| `SkuCheckFlags are {value}` | SKU compatibility check mode |
| `ShouldEmulateExeLaunch is {0\|1}` | Whether to use EXE launch policies |
| `LegacyBindRequired is {0\|1}` | Whether legacy binding is strictly required |
| `Installed Runtime: vX.Y.Z. VERSION_ARCHITECTURE: N` | A runtime version found installed on the machine |

### Config File Processing

| Message | Meaning |
|---------|---------|
| `Parsing config file: {path}` | Looking for an application config file |
| `Config File (Open). Result:00000000` | Config file found and opened successfully |
| `Config File (Open). Result:80070002` | Config file **not found** (ERROR_FILE_NOT_FOUND) |
| `Config File (Read). Result:00000000` | Config file read successfully |
| `Found config file: {path}` | Config file successfully parsed |
| `UseLegacyV2RuntimeActivationPolicy is set to {0\|1}` | Value of `<startup useLegacyV2RuntimeActivationPolicy="true\|false">` |
| `Config file includes SupportedRuntime entry. Version: {ver}, SKU: {sku}` | A `<supportedRuntime>` element from the config |
| `Found a supportedRuntime tag in the config file` | At least one `<supportedRuntime>` was present |

### Runtime Selection Outcomes

| Message | Meaning |
|---------|---------|
| `Using supportedRuntime: vX.Y.Z` | Shim selected this version from config's `<supportedRuntime>` list |
| `{exe} was built with version: vX.Y.Z` | PE header version from a managed binary |
| `FindLatestVersion is returning the following version: vX.Y.Z Input VERSION_ARCHITECTURE: N, V2.0 Capped: {0\|1}` | Result of policy-based latest-version search |
| `Default version of the runtime on the machine: vX.Y.Z` | Resolved default version |
| `Default version of the runtime on the machine: (null)` | **No runtime found** — resolution failed |
| `Decided on runtime: vX.Y.Z` | **Final decision** — this version will be loaded |
| `Runtime has been loaded. Version: vX.Y.Z` | CLR successfully loaded into the process |
| `V2.0 Capping is preventing consideration of a newer runtime` | A v4+ runtime was skipped because capping is active |

### Errors and FOD

| Message | Meaning |
|---------|---------|
| `ERROR: Unable to find a version of the runtime to use.` | Version resolution failed completely |
| `ERROR: Version vX.Y.Z is not present on the machine.` | A specific requested version is not installed |
| `SEM_FAILCRITICALERRORS is set to {value}` | Process error mode check before showing dialogs. 0 = dialogs allowed. Nonzero = dialogs suppressed. |
| `Checking if feature-on-demand installation would help` | Shim is re-running version computation to check if installing .NET 3.5 would help |
| `Launching feature-on-demand installation. CmdLine: {cmd}` | **FOD dialog is being shown** — fondue.exe is launched |
| `Could have launched feature-on-demand installation if was not opted out. CmdLine: {cmd}` | FOD was suppressed because SEM_FAILCRITICALERRORS is set |

### Process Lifecycle

| Message | Meaning |
|---------|---------|
| `FunctionCall: OnShimDllMainCalled. Reason: {code}` | DllMain callback (1=PROCESS_ATTACH, 0=PROCESS_DETACH, 2=THREAD_ATTACH, 3=THREAD_DETACH) |
| `FunctionCall: RealDllMain. Reason: {code}` | Actual DllMain processing |
| `LegacyFunctionCall: CorExitProcess. Code: {exit_code}` | Process exiting through legacy API |

### Runtime Info Queries

| Message | Meaning |
|---------|---------|
| `MethodCall: ICLRRuntimeInfo::GetVersionString. Version: vX.Y.Z` | Querying runtime version |
| `MethodCall: ICLRRuntimeInfo::GetRuntimeDirectory. Version: vX.Y.Z` | Querying runtime install path |
| `MethodCall: ICLRRuntimeInfo::LoadLibrary. Name: {dll}. Version: vX.Y.Z` | Loading a framework DLL |

## Well-Known CLSIDs

These CLSIDs frequently appear in COM activation logs:

| CLSID | Name | Notes |
|-------|------|-------|
| `{E5CB7A31-7512-11D2-89CE-0080C792E5D8}` | CorSymWriter_SxS / CLR Meta Data | Debug symbol writer — common trigger for legacy COM activation in native build tools |
| `{0A29FF9E-7F9C-4437-8B11-F424491E3931}` | NDP SymBinder | Debug symbol binder |
| `{9280188D-0E8E-4867-B30C-7FA83884E8DE}` | CLRMetaHost | ICLRMetaHost — the v4+ entry point for hosting |
| `{2EBCD49A-1B47-4A61-B13A-4A03701E594B}` | CLRMetaHostPolicy | ICLRMetaHostPolicy — policy-based hosting |
| `{CB2F6723-AB3A-11D2-9C40-00C04FA30A3E}` | CorRuntimeHost | Legacy v1/v2 hosting |
| `{F7721072-BF57-476D-89F8-A7625D27683A}` | CLRStrongName | Strong name APIs |
| `{B79B0ACD-F5CD-409B-B5A5-A16244610B92}` | ALink | Assembly linker |

## Well-Known IIDs

| IID | Interface |
|-----|-----------|
| `{00000001-0000-0000-C000-000000000046}` | IClassFactory |
| `{D332DB9E-B9B3-4125-8207-A14884F53216}` | ICLRMetaHost |
| `{E2190695-77B2-492E-8E14-C4B3A7FDD593}` | ICLRMetaHostPolicy |
| `{BD39D1D2-BA2F-486A-89B0-B4B0CB466891}` | ICLRRuntimeInfo |
| `{31BCFCE2-DAFB-11D2-9F81-00C04F79A0A3}` | IMetaDataDispenserEx |
| `{CB2F6722-AB3A-11D2-9C40-00C04FA30A3E}` | ICorRuntimeHost |
| `{07C4E752-3CBA-4A07-9943-B5F206382178}` | ICLRRuntimeHost |

## SEM_FAILCRITICALERRORS Values

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

| Value | Hex | Flags Set | FOD Allowed? |
|-------|-----|-----------|-------------|
| 0 | 0x0000 | None | **Yes** |
| 1 | 0x0001 | SEM_FAILCRITICALERRORS | No |
| 32769 | 0x8001 | SEM_FAILCRITICALERRORS + SEM_NOGPFAULTERRORBOX | No |
| 32768 | 0x8000 | SEM_NOGPFAULTERRORBOX only | **Yes** (only SEM_FAILCRITICALERRORS bit matters) |

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:

| Runtime Version String | CLR Version | .NET Framework Versions |
|----------------------|-------------|------------------------|
| `v1.0.3705` | CLR 1.0 | .NET Framework 1.0 |
| `v1.1.4322` | CLR 1.1 | .NET Framework 1.1 |
| `v2.0.50727` | CLR 2.0 | .NET Framework 2.0, 3.0, 3.5 |
| `v4.0.30319` | CLR 4.0 | .NET Framework 4.0 through 4.8.x |

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

| HRESULT | Symbol | Meaning |
|---------|--------|---------|
| `0x80131700` | `CLR_E_SHIM_RUNTIMELOAD` | Cannot find or load a suitable runtime. The most common shim error — corresponds to "ERROR: Unable to find a version of the runtime to use" in logs. |
| `0x80131701` | `CLR_E_SHIM_RUNTIMEEXPORT` | Found a runtime but failed to get a required export or interface. |
| `0x80131702` | `CLR_E_SHIM_INSTALLROOT` | .NET Framework install root missing or invalid in registry. |
| `0x80131703` | `CLR_E_SHIM_INSTALLCOMP` | A required installation component is missing. |
| `0x80131704` | `CLR_E_SHIM_LEGACYRUNTIMEALREADYBOUND` | A different runtime is already bound as the legacy runtime — a legacy API tried to bind to a conflicting version. |
| `0x80131705` | `CLR_E_SHIM_SHUTDOWNINPROGRESS` | The shim is shutting down. |