[API Proposal]: Respect `ISupportErrorInfo` for `HRESULT` to `Exception` throwing conversion

[AaronRobinsonMSFT]

Background and motivation

See #116917 for motivating example.

The Marshal.ThrowExceptionForHR() API respects IErrorInfo, but doesn't respect ISupportErrorInfo, which means implementing correct COM semantics isn't possible. The motivation here is for source generated COM. Built-in COM support respects ISupportErrorInfo as expected, but source generated COM can't since no public API exists that has the correct semantics.

API Proposal

A QI for ISupportErrorInfo will be performed on the pUnk. If ISupportErrorInfo is supported, the targetIID will then be passed to ISupportErrorInfo::InterfaceSupportsErrorInfo(). This will effectively allow users to then call GetExceptionForHR(int errorCode, IntPtr errorInfo) with the correct errorInfo value. If the interface doesn't support ISupportErrorInfo or the targetIID isn't supported, the errorInfo is thrown away. Throwing away the errorInfo isn't the expected COM behavior, but is the behavior observed by .NET Framework and built-in COM, therefore it will be followed here and documented. See #117438 (comment) for a proposed implementation. The PR for implementing this API should also replace the existing private API called by built-in COM interop.

namespace System.Runtime.InteropServices;

public static partial class Marshal
{
+    public static void ThrowExceptionForHR(int errorCode, Guid targetIID, IntPtr pUnk);
+    public static Exception? GetExceptionForHR(int errorCode, Guid targetIID, IntPtr pUnk);
}

API Usage

From within a source generated COM proxy:

Guid tgtIID = ...
Marshal.ThrowExceptionForHR(errorCode, tgtIID, pUnk);

Alternative Designs

No response

Risks

No response

[dotnet-policy-service]

Tagging subscribers to this area: @dotnet/interop-contrib
See info in area-owners.md if you want to be subscribed.

[AaronRobinsonMSFT]

Below is the implementation in C# for these APIs. On non-Windows we would ignore the targetIID and pUnk arguments.

public static void ThrowExceptionForHR(int errorCode, Guid targetIID, IntPtr pUnk)
{
    if (errorCode < 0)
    {
        throw GetExceptionForHR(errorCode, targetIID, pUnk);
    }
}

[LibraryImport("OleAut32")]
private static partial int GetErrorInfo(uint dwReserved, ref IntPtr ppErrorInfo);

public static Exception? GetExceptionForHR(int errorCode, Guid targetIID, IntPtr pUnk)
{
    if (errorCode >= 0)
    {
        return null;
    }

    const IntPtr NoErrorInfo = -1; // Use -1 to indicate no error info available

    // Normally, we would check if the interface supports IErrorInfo first. However,
    // built-in COM calls GetErrorInfo first to clear the error info, so we follow
    // that pattern here.
    IntPtr errorInfo = NoErrorInfo;
    GetErrorInfo(0, ref errorInfo);
    if (errorInfo == IntPtr.Zero)
    {
        errorInfo = NoErrorInfo;
    }

    // If there is error info and we have a pointer to the interface,
    // we check if it supports ISupportErrorInfo.
    if (errorInfo != NoErrorInfo && pUnk != IntPtr.Zero)
    {
        Guid IID_ISupportErrorInfo = new Guid([
            0x60, 0x3D, 0x0B, 0xDF, // Data1: 0xDF0B3D60 (little-endian)
            0x8F, 0x54,             // Data2: 0x548F (little-endian)
            0x1B, 0x10,             // Data3: 0x101B (little-endian)
            0x8E, 0x65, 0x08, 0x00, 0x2B, 0x2B, 0xD1, 0x19 // Data4: 8 bytes
        ]);

        IntPtr supportErrorInfo = default;
        int hr = Marshal.QueryInterface(pUnk, in IID_ISupportErrorInfo, out supportErrorInfo);
        if (hr == 0)
        {
            // Check if the target interface is supported.
            // ISupportErrorInfo.InterfaceSupportsErrorInfo slot
            hr = ((delegate* unmanaged<IntPtr, Guid*, int>)(*(*(void***)supportErrorInfo + 3)))(supportErrorInfo, &targetIID);
            Marshal.Release(supportErrorInfo);
        }

        // If ISupportErrorInfo isn't supported or the target interface doesn't support IErrorInfo,
        // release the error info and mark it as NoErrorInfo to avoid querying for IErrorInfo again.
        if (hr != 0)
        {
            Marshal.Release(errorInfo);
            errorInfo = NoErrorInfo;
        }
    }

    // If the error info is valid, its lifetime will be handled by GetExceptionForHR().
    return Marshal.GetExceptionForHR(errorCode, errorInfo);
}

[bartonjs]

Video

• targetIID should be named iid for consistency
• Marshal.QueryInterface takes iid as in, here it should, too
• The parameter order here (iid, pUnk) is opposite of QueryInterface, but that is intentional and has value.

namespace System.Runtime.InteropServices;

public static partial class Marshal
{
     public static void ThrowExceptionForHR(int errorCode, in Guid iid, IntPtr pUnk);
     public static Exception? GetExceptionForHR(int errorCode, in Guid iid, IntPtr pUnk);
}