[cDAC] Add IMetaDataImport COM wrapper over MetadataReader for no-fallback mode

[max-charlamb]

Note

This PR description was AI/Copilot-generated.

Summary

Implements a managed [GeneratedComClass] wrapper that adapts System.Reflection.Metadata.MetadataReader to the IMetaDataImport/IMetaDataImport2 COM interfaces. This enables SOS and ClrMD to query metadata in cDAC no-fallback mode where the legacy DAC is unavailable.

Motivation

In cDAC no-fallback mode, ClrDataModule.GetInterface() returned NotHandled for IMetaDataImport QIs when _legacyModulePointer == 0, meaning diagnostic tools couldn't access type/method/field metadata. The cDAC already has access to MetadataReader via the EcmaMetadata contract, so a thin COM wrapper bridges the gap.

Changes

File	Description
IMetaDataImport.cs	Managed [GeneratedComInterface] definitions for IMetaDataImport (62 methods) and IMetaDataImport2 (8 methods) with exact vtable ordering from cor.h
MetadataImportWrapper.cs	[GeneratedComClass] implementation wrapping MetadataReader — ~21 real implementations + ~40 E_NOTIMPL stubs
ClrDataModule.cs	Wire up wrapper in GetInterface() as no-fallback path with thread-safe lazy init and proper COM ref counting
MetadataImportWrapperTests.cs	21 unit tests using synthetic metadata built with MetadataBuilder

Implemented methods

Enum: EnumTypeDefs, EnumInterfaceImpls, EnumTypeRefs, EnumMembers, EnumMethods, EnumFields, EnumCustomAttributes, EnumGenericParams, CloseEnum, CountEnum, ResetEnum

Properties: GetTypeDefProps, GetTypeRefProps, GetMethodProps, GetFieldProps, GetMemberProps, GetInterfaceImplProps, GetNestedClassProps, GetGenericParamProps

Blob/token: GetRVA, GetSigFromToken, GetCustomAttributeByName, IsValidToken

Design decisions

• HCORENUM pattern: Uses GCHandle.Alloc to box a MetadataEnum object, matching the native pattern of opaque enumeration handles
• COM ref counting: Caches the managed wrapper object (not the COM pointer) to avoid ref counting leaks; creates COM interface on demand via StrategyBasedComWrappers
• Thread safety: Uses Interlocked.CompareExchange for lazy wrapper initialization
• Error handling: CatchHR() helper normalizes all exceptions to HRESULT values

Testing

All 1651 cDAC tests pass (1630 existing + 21 new).

[dotnet-policy-service]

Tagging subscribers to this area: @steveisok, @tommcdon, @dotnet/dotnet-diag
See info in area-owners.md if you want to be subscribed.

[Copilot]

Pull request overview

This PR adds a managed COM-compatible IMetaDataImport/IMetaDataImport2 implementation backed by System.Reflection.Metadata.MetadataReader, and wires it into cDAC’s ClrDataModule so diagnostic tools can query metadata when running in no-fallback mode (legacy DAC unavailable).

Changes:

• Introduces generated COM interface definitions for IMetaDataImport and IMetaDataImport2.
• Implements MetadataImportWrapper to adapt MetadataReader to the COM metadata import APIs (with a subset implemented and the rest stubbed).
• Updates ClrDataModule to provide IMetaDataImport in no-fallback mode and adds unit tests validating implemented behaviors.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 5 comments.

File	Description
src/native/managed/cdac/tests/MetadataImportWrapperTests.cs	Adds unit tests that exercise the wrapper’s enumeration and property APIs over synthetic metadata.
src/native/managed/cdac/Microsoft.Diagnostics.DataContractReader.Legacy/MetadataImportWrapper.cs	Implements the COM wrapper over MetadataReader including enum-handle handling and a set of metadata accessors.
src/native/managed/cdac/Microsoft.Diagnostics.DataContractReader.Legacy/IMetaDataImport.cs	Adds managed [GeneratedComInterface] declarations for IMetaDataImport/IMetaDataImport2 with vtable ordering.
src/native/managed/cdac/Microsoft.Diagnostics.DataContractReader.Legacy/ClrDataModule.cs	Hooks IMetaDataImport QI to return the managed wrapper when legacy DAC is unavailable.

[jkoritzinsky]

You'll likely need to add support for IMetaDataAssemblyImport as well for assembly-level info

[Copilot]

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated 7 comments.

[Copilot]

Pull request overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated 6 comments.

[Copilot]

Pull request overview

Copilot reviewed 10 out of 10 changed files in this pull request and generated 8 comments.

[Copilot]

Pull request overview

Copilot reviewed 10 out of 10 changed files in this pull request and generated 6 comments.

[Copilot]

Pull request overview

Copilot reviewed 10 out of 10 changed files in this pull request and generated 5 comments.

[Copilot]

GetRootModuleImport uses MetadataReader? and then returns/passes it as non-nullable MetadataReader. Since MetadataReader is a struct and IEcmaMetadata.GetMetadata returns MetadataReader?, this won't compile; use reader.Value (after checking reader.HasValue) or restructure to avoid nullable.

Suggested change

	Assert.NotNull(reader);
	return (reader, new MetaDataImportImpl(reader));
	Assert.True(reader.HasValue);
	MetadataReader metadataReader = reader.Value;
	return (metadataReader, new MetaDataImportImpl(metadataReader));

[Copilot]

CreateTestMetadata declares userStringHandle but never uses it. This triggers CS0219 (warning-as-error) and will fail the build; either remove the local or explicitly discard the result (e.g., assign to _).

Suggested change

	UserStringHandle userStringHandle = mb.GetOrAddUserString("Hello, World!");
	_ = mb.GetOrAddUserString("Hello, World!");

[Copilot]

StringConst is described as a string field but is created with the intFieldSig signature. That makes the synthetic metadata inconsistent and can hide issues; use a string field signature blob for StringConst.

Suggested change

	mb.GetOrAddString("StringConst"), intFieldSig);
	mb.GetOrAddString("StringConst"), stringFieldSig);

[Copilot]

CreateWrapper stores the MetadataReaderProvider in a static field and never disposes it. Since MetadataReaderProvider is IDisposable, this retains metadata buffers for the entire test run; consider returning the provider from CreateWrapper and disposing it per-test (or using a fixture implementing IDisposable).

[Copilot]

GetUserString copies charCount characters into the buffer but only writes a null terminator on truncation and treats cchString == charCount as non-truncated. This can return a non-null-terminated buffer and incorrect truncation behavior; treat cchString as including space for the terminator (copy at most cchString-1, always write \0 when cchString>0, and return CLDB_S_TRUNCATION when charCount + 1 > cchString).

Suggested change

	int copyChars = Math.Min(charCount, (int)cchString);
	new ReadOnlySpan<char>(dataPtr, copyChars).CopyTo(new Span<char>(szString, copyChars));
	if ((uint)charCount > cchString)
	{
	szString[cchString - 1] = '\0';
	int destinationCapacity = (int)cchString - 1;
	int copyChars = Math.Min(charCount, destinationCapacity);
	new ReadOnlySpan<char>(dataPtr, copyChars).CopyTo(new Span<char>(szString, copyChars));
	szString[copyChars] = '\0';
	if ((uint)charCount + 1 > cchString)
	{

[Copilot]

Pull request overview

Copilot reviewed 11 out of 11 changed files in this pull request and generated 1 comment.

[Copilot]

Changing CopyStringToBuffer from void to bool is a breaking change for any external callers of this public helper. If this API is consumed outside this assembly/package, consider preserving the original void signature (and adding a new overload/optional out parameter for truncation) to avoid breaking binary/source compatibility.

[Copilot]

Pull request overview

Copilot reviewed 10 out of 10 changed files in this pull request and generated 6 comments.

[Copilot]

CountEnum uses _cdacEnumHandles.ContainsKey(hEnum) and then dereferences the GCHandle via GetEnum(hEnum). If another thread calls CloseEnum between those operations, the handle can be freed and GCHandle.Target access may throw (unhandled here). Consider using a single atomic lookup and wrapping GetEnum in a try/catch (or otherwise ensuring the handle can’t be freed concurrently).

[Copilot]

ResetEnum has the same race as CountEnum: ContainsKey followed by GetEnum(hEnum) can observe a handle that gets freed concurrently by CloseEnum, potentially throwing before you can return an HRESULT. Consider an atomic lookup pattern and exception-to-HRESULT handling here as well.

[Copilot]

GetUserString copies up to cchString characters and only writes a null terminator when charCount > cchString. If the buffer size is intended to include the terminator (as with other *Props APIs), the copy should reserve 1 char for \0 and treat charCount >= cchString as truncation; otherwise callers can get a non-null-terminated buffer when charCount == cchString.

Suggested change

	int copyChars = Math.Min(charCount, (int)cchString);
	new ReadOnlySpan<char>(dataPtr, copyChars).CopyTo(new Span<char>(szString, copyChars));
	if ((uint)charCount > cchString)
	{
	szString[cchString - 1] = '\0';
	int copyChars = Math.Min(charCount, (int)cchString - 1);
	new ReadOnlySpan<char>(dataPtr, copyChars).CopyTo(new Span<char>(szString, copyChars));
	szString[copyChars] = '\0';
	if ((uint)charCount >= cchString)
	{

[Copilot]

using System.Runtime.CompilerServices; is currently unused in this file; please remove it to avoid build warnings/noise.

[max-charlamb]

This seems correct.

[Copilot]

reader is a MetadataReader? (nullable struct). Passing it directly into new MetaDataImportImpl(reader, legacyImport) will not compile; unwrap it after the null-check (e.g., reader.Value / GetValueOrDefault()).

Suggested change

	wrapper = new MetaDataImportImpl(reader, legacyImport);
	wrapper = new MetaDataImportImpl(reader.Value, legacyImport);

[max-charlamb]

This seems correct.

[Copilot]

Pull request overview

Copilot reviewed 11 out of 11 changed files in this pull request and generated 6 comments.

[Copilot]

If EcmaMetadata.GetMetadata fails (reader is null) but the legacy module pointer can still provide IMetaDataImport, this currently returns NotHandled and the QI fails even in fallback mode. Consider falling back to returning the legacy IMetaDataImport COM pointer when reader is unavailable, preserving the previous behavior for legacy-capable scenarios.

Suggested change

	return CustomQueryInterfaceResult.NotHandled;
	{
	if (legacyImport is null)
	return CustomQueryInterfaceResult.NotHandled;
	ppv = (nint)ComInterfaceMarshaller<IMetaDataImport>.ConvertToUnmanaged(legacyImport);
	return CustomQueryInterfaceResult.Handled;
	}

[Copilot]

GetTypeDefProps currently masks off the token type (td & 0x00FFFFFF) and always treats the input as a TypeDef RID. Native RegMeta returns S_FALSE for non-TypeDef tokens and has special handling for mdTypeDefNil (0). To match expected COM semantics and avoid returning incorrect data for wrong token kinds, validate TypeFromToken(td) and handle td==0 explicitly before reading metadata.

Suggested change

	{
	{
	if (td == 0)
	return HResults.S_FALSE;
	if ((td & 0xFF000000) != (uint)CorTokenType.mdtTypeDef)
	return HResults.S_FALSE;

[Copilot]

GetTypeRefProps also ignores the token type by masking to a RID and unconditionally reading the TypeRef table. Native RegMeta returns S_FALSE for non-TypeRef tokens and treats mdTypeRefNil (0) as a special case (empty name, length=1, scope=nil). Add token-kind validation and nil-token handling to avoid returning the wrong name/scope for unexpected tokens.

Suggested change

	TypeReferenceHandle refHandle = MetadataTokens.TypeReferenceHandle((int)(tr & 0x00FFFFFF));
	TypeReference typeRef = _reader.GetTypeReference(refHandle);
	string fullName = GetTypeRefFullName(typeRef);
	bool truncated = OutputBufferHelpers.CopyStringToBuffer(szName, cchName, pchName, fullName);
	if (ptkResolutionScope is not null)
	{
	EntityHandle scope = typeRef.ResolutionScope;
	*ptkResolutionScope = scope.IsNil ? 0 : (uint)MetadataTokens.GetToken(scope);
	}
	hr = truncated ? CorDbgHResults.CLDB_S_TRUNCATION : HResults.S_OK;
	const uint MdTypeRefNil = 0;
	const uint TypeRefTokenType = 0x01000000;
	if (tr == MdTypeRefNil)
	{
	bool truncated = OutputBufferHelpers.CopyStringToBuffer(szName, cchName, pchName, string.Empty);
	if (ptkResolutionScope is not null)
	{
	*ptkResolutionScope = 0;
	}
	hr = truncated ? CorDbgHResults.CLDB_S_TRUNCATION : HResults.S_FALSE;
	}
	else if ((tr & 0xFF000000) != TypeRefTokenType)
	{
	hr = HResults.S_FALSE;
	}
	else
	{
	TypeReferenceHandle refHandle = MetadataTokens.TypeReferenceHandle((int)(tr & 0x00FFFFFF));
	TypeReference typeRef = _reader.GetTypeReference(refHandle);
	string fullName = GetTypeRefFullName(typeRef);
	bool truncated = OutputBufferHelpers.CopyStringToBuffer(szName, cchName, pchName, fullName);
	if (ptkResolutionScope is not null)
	{
	EntityHandle scope = typeRef.ResolutionScope;
	*ptkResolutionScope = scope.IsNil ? 0 : (uint)MetadataTokens.GetToken(scope);
	}
	hr = truncated ? CorDbgHResults.CLDB_S_TRUNCATION : HResults.S_OK;
	}

[Copilot]

GetMethodProps constructs a MethodDefinitionHandle from (mb & 0x00FFFFFF) without validating that mb is a MethodDef token or handling mdMethodDefNil. In native RegMeta these APIs return S_FALSE for wrong token types. Without validation, passing a non-MethodDef token can return unrelated method data instead of failing. Consider validating the token kind up front (and similarly for GetFieldProps/GetMemberRefProps/etc.).

Suggested change

	int hr = HResults.S_OK;
	try
	{
	MethodDefinitionHandle methodHandle = MetadataTokens.MethodDefinitionHandle((int)(mb & 0x00FFFFFF));
	MethodDefinition methodDef = _reader.GetMethodDefinition(methodHandle);
	string name = _reader.GetString(methodDef.Name);
	bool truncated = OutputBufferHelpers.CopyStringToBuffer(szMethod, cchMethod, pchMethod, name);
	if (pClass is not null)
	*pClass = MapGlobalParentToken((uint)MetadataTokens.GetToken(methodDef.GetDeclaringType()));
	if (pdwAttr is not null)
	*pdwAttr = (uint)methodDef.Attributes;
	if (ppvSigBlob is not null || pcbSigBlob is not null)
	{
	BlobHandle sigHandle = methodDef.Signature;
	BlobReader blobReader = _reader.GetBlobReader(sigHandle);
	if (ppvSigBlob is not null)
	*ppvSigBlob = blobReader.StartPointer;
	if (pcbSigBlob is not null)
	*pcbSigBlob = (uint)blobReader.Length;
	}
	if (pulCodeRVA is not null)
	*pulCodeRVA = (uint)methodDef.RelativeVirtualAddress;
	if (pdwImplFlags is not null)
	*pdwImplFlags = (uint)methodDef.ImplAttributes;
	hr = truncated ? CorDbgHResults.CLDB_S_TRUNCATION : HResults.S_OK;
	const uint MethodDefTokenType = 0x06000000;
	int hr = HResults.S_OK;
	try
	{
	if ((mb & 0xFF000000) != MethodDefTokenType || (mb & 0x00FFFFFF) == 0)
	{
	hr = HResults.S_FALSE;
	}
	else
	{
	MethodDefinitionHandle methodHandle = MetadataTokens.MethodDefinitionHandle((int)(mb & 0x00FFFFFF));
	MethodDefinition methodDef = _reader.GetMethodDefinition(methodHandle);
	string name = _reader.GetString(methodDef.Name);
	bool truncated = OutputBufferHelpers.CopyStringToBuffer(szMethod, cchMethod, pchMethod, name);
	if (pClass is not null)
	*pClass = MapGlobalParentToken((uint)MetadataTokens.GetToken(methodDef.GetDeclaringType()));
	if (pdwAttr is not null)
	*pdwAttr = (uint)methodDef.Attributes;
	if (ppvSigBlob is not null || pcbSigBlob is not null)
	{
	BlobHandle sigHandle = methodDef.Signature;
	BlobReader blobReader = _reader.GetBlobReader(sigHandle);
	if (ppvSigBlob is not null)
	*ppvSigBlob = blobReader.StartPointer;
	if (pcbSigBlob is not null)
	*pcbSigBlob = (uint)blobReader.Length;
	}
	if (pulCodeRVA is not null)
	*pulCodeRVA = (uint)methodDef.RelativeVirtualAddress;
	if (pdwImplFlags is not null)
	*pdwImplFlags = (uint)methodDef.ImplAttributes;
	hr = truncated ? CorDbgHResults.CLDB_S_TRUNCATION : HResults.S_OK;
	}

[Copilot]

The comment says each layout entry stores a "ridOfField", but the code writes the full FieldDef token (MetadataTokens.GetToken). This is correct behavior for COR_FIELD_OFFSET, but the comment is misleading—update it to refer to the FieldDef token to avoid confusion.

Suggested change

	// Each entry is {ridOfField (uint), ulOffset (uint)}
	// Each entry is {FieldDef token (uint), ulOffset (uint)}

[Copilot]

CreateWrapper stores MetadataReaderProvider in a static field and overwrites it per test without disposing the previous instance. Since MetadataReaderProvider holds unmanaged resources, this leaks one provider per test method in this class. Consider disposing the previous provider before overwriting, or using an xUnit fixture/IDisposable pattern so each test disposes its provider deterministically.

[github-actions]

🤖 Copilot Code Review — PR #127028

Note

This review was generated by Copilot (Claude Opus 4.6), with additional perspectives from GPT-5.3-Codex and Claude Haiku 4.5.

Holistic Assessment

Motivation: This PR implements a managed MetaDataImportImpl wrapper backed by System.Reflection.Metadata.MetadataReader for the cDAC, replacing legacy DAC QI-based fallback for IMetaDataImport/IMetaDataImport2/IMetaDataAssemblyImport. This is well-motivated — it moves metadata reading into managed code with the standard MetadataReader API, with comprehensive #if DEBUG parity validation against the legacy implementation.

Approach: Sound. The implementation covers the most-used IMetaDataImport methods with managed MetadataReader while 54 less-commonly-used methods delegate to the legacy DAC. The COM interop changes to return IMetaDataImport2 vtables address a known ClrMD vtable-boundary issue. The #if DEBUG cross-validation blocks are an excellent technique for ensuring semantic parity.

Summary: ⚠️ Needs Human Review. The implementation is well-structured and largely correct. Two items need human attention: (1) lazy initialization of shared lookup dictionaries using ??= is technically racy per the project's own thread-safety rules (the SKILL.md says "??= operator is not thread-safe"), and (2) the GetUserString implementation doesn't null-terminate non-truncated output, which may differ from some callers' expectations. Neither is a definitive blocker, but both warrant human judgment.

---

Detailed Findings

⚠️ Non-atomic lazy initialization with ??= — Thread-safety inconsistency

_interfaceImplToTypeDef and _paramToMethod use ??= for lazy init (MetaDataImportImpl.cs:554, 1336):

_interfaceImplToTypeDef ??= BuildInterfaceImplLookup();
_paramToMethod ??= BuildParamToMethodLookup();

Similarly _metaDataImportImpl in ClrDataModule.cs:107 (which has an explicit comment acknowledging the race).

While reference-type assignments are atomic in .NET and the worst case is benign duplicate initialization, this is inconsistent with the explicit ConcurrentDictionary used for _cdacEnumHandles (line 29). The comment on line 28 states "COM objects may be called from multiple threads". Per dotnet/runtime review conventions, ??= is flagged as not thread-safe — consider Interlocked.CompareExchange for consistency with the stated threading model. (Flagged by all three models — advisory, not merge-blocking)

⚠️ GetUserString doesn't null-terminate non-truncated output — Verify native parity

In MetaDataImportImpl.cs:1221-1232, when szString is provided and the buffer is large enough, character data is copied but no null terminator is appended. A null terminator is only written when the output is truncated (line 1229: szString[cchString - 1] = '\0').

This may be correct for the #US heap semantics (callers should use pchString for the length), but if any consumer relies on null-termination of the non-truncated output, this would be a behavioral difference from the native implementation. The #if DEBUG validation only checks pchString, not the buffer contents. A human reviewer familiar with the native GetUserString contract should confirm. (Low confidence — flagged for verification)

💡 GetAssemblyFromScope always returns 0x20000001 — Minor edge case

MetaDataImportImpl.cs:1652-1655 unconditionally returns the assembly token:

if (ptkAssembly is not null)
    *ptkAssembly = 0x20000001;

Native RegMeta returns CLDB_E_RECORD_NOTFOUND when the Assembly table is empty (netmodules). In practice, all cDAC-loaded modules have assemblies, making this a non-issue for real-world usage. Documenting this assumption with a comment would be beneficial. (Flagged by GPT-5.3-Codex — follow-up, not blocking)

💡 Enum handle TOCTOU — Defensive programming suggestion

GetEnum (MetaDataImportImpl.cs:77) checks ContainsKey then calls GCHandle.FromIntPtr, while CloseEnum can TryRemove and Free the handle between these operations. This is only exploitable if a caller uses and closes the same enum from different threads concurrently (a caller API violation). The native implementation has the same characteristic. Consider using TryGetValue on _cdacEnumHandles as a one-step check+retrieve pattern if the dictionary value can carry meaning, but this is minor. (Flagged by Claude Haiku 4.5 — follow-up, not blocking)

✅ COM interop reference counting — Correctly balanced

In ClrDataModule.cs:91-96: Marshal.QueryInterface → AddRef'd pointer → ComInterfaceMarshaller.ConvertToManaged creates RCW → Marshal.Release balances the ref count. In ClrDataModule.cs:111: ConvertToUnmanaged returns an AddRef'd pointer → returned as ppv, which is the correct COM QI contract (callee AddRefs before returning).

✅ GetUserString raw heap access — Correct boundary validation

The implementation (MetaDataImportImpl.cs:1188-1250) correctly: reads from raw #US heap via MetadataPointer to match native behavior; validates blob fits within remaining heap; rejects even-sized blobs (missing terminal byte) as corrupt; calculates charCount = (blobSize - 1) / sizeof(char). This is a careful re-implementation of the native RegMeta behavior.

✅ CopyStringToBuffer truncation reporting — Correct

The void → bool return change in OutputBufferHelpers.CopyStringToBuffer correctly reports truncation via strSpan.Length + 1 > bufferSize, properly accounting for the null terminator. All callers correctly propagate CLDB_S_TRUNCATION when truncated.

✅ #if DEBUG parity validation — Comprehensive

Every implemented method includes #if DEBUG blocks that call the legacy implementation and compare results field-by-field, including byte-level blob comparison via ValidateBlobsEqual. The ValidateHResult extension method with AllowDivergentFailures mode is a pragmatic approach. This is excellent engineering for a reimplementation.

✅ MapGlobalParentToken — Correct native parity fix

The helper (MetaDataImportImpl.cs:1702-1706) maps TypeDef RID 1 (<Module>) to mdTypeDefNil (0), matching native RegMeta behavior for GetMethodProps, GetFieldProps, and GetMemberRefProps. Test coverage confirms this at line 860 (GetMethodProps_GlobalMethod_ReturnsMdTypeDefNil).

✅ Test coverage — Good breadth

35+ unit tests cover all implemented methods, edge cases (invalid tokens, not-found records, buffer truncation), pagination, dispatch routing (GetMemberProps), constants with and without values, and string constants returning character counts. 3 dump-based integration tests verify against real module metadata. The _testProvider field pattern correctly prevents GC collection of pinned metadata memory during tests.

Generated by Code Review for issue #127028 · ◷