[API Proposal]: APIs to expose managed objects to COM

[jkoritzinsky]

Background and motivation

As part of our work to provide a source-generator for COM, we need to provide a mechanism for users to request that code be generated to support passing their types to native code.

API Proposal

namespace System.Runtime.InteropServices.Marshalling;


+ public unsafe interface IComExposedClass
+ {
+     public static abstract ComWrappers.ComInterfaceEntry* ComInterfaceEntries { get; }
+     public static abstract int InterfaceEntriesLength { get; }
+ }

+ public unsafe interface IComExposedDetails
+ {
+     ComWrappers.ComInterfaceEntry* ComInterfaceEntries { get; }
+ 
+     int InterfaceEntriesLength { get; }
+ }

+ [AttributeUsage(AttributeTargets.Class)]
+ public sealed unsafe class ComExposedClassAttribute<T> : Attribute, IComExposedDetails
+     where T : IComExposedClass
+ {
+     public ComWrappers.ComInterfaceEntry* ComInterfaceEntries { get; }
+ 
+     public int InterfaceEntriesLength { get; }
+ }

public interface IIUnknownInterfaceDetailsStrategy
{
+    /// <summary>
+    /// Given a <see cref="RuntimeTypeHandle"/> get the details about the type that are exposed to COM.
+    /// </summary>
+    /// <param name="type">RuntimeTypeHandle instance</param>
+    /// <returns>Details if type is known.</returns>
+    IComExposedDetails? GetComExposedTypeDetails(RuntimeTypeHandle type);
}


+ [AttributeUsage(AttributeTargets.Class, AllowMultiple = true)]
+ public sealed class GeneratedComClassAttribute : Attribute
+ {
+ }


- public abstract class StrategyBasedComWrappers : ComWrappers
+ public class StrategyBasedComWrappers : ComWrappers
{
+     protected override sealed System.Runtime.InteropServices.ComWrappers.ComInterfaceEntry* ComputeVtables(object obj, System.Runtime.InteropServices.CreateComInterfaceFlags flags, out int count);
}

API Usage

[GeneratedComInterface]
[InterfaceType(ComInterfaceType.InterfaceIsIUnknown)]
public partial interface IComInterface1
{
    void Method();
}

[GeneratedComClass]
partial class A : IComInterface1
{
    void IComInterface1.Method()
    {
        Console.WriteLine("--- A.IComInterface1.Method");
    }
}

Examples of how generated code will use these APIs is at https://github.com/AaronRobinsonMSFT/ComObjectRedux/pull/8

Alternative Designs

Alternatively, we considered requiring the user to attribute a ComWrappers-derived type with attributes that point to each class type it should support. This ended up becoming a significantly more expensive design that was less trimmable (both this design and the alternative one are trim-friendly).

Risks

This adds a method to an interface, but we haven't shipped the interface yet.

[ghost]

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

Issue Details

---

Background and motivation

As part of our work to provide a source-generator for COM, we need to provide a mechanism for users to request that code be generated to support passing their types to native code.

API Proposal

namespace System.Runtime.InteropServices.Marshalling;


+ public unsafe interface IComExposedClass
+ {
+     public static abstract ComWrappers.ComInterfaceEntry* ComInterfaceEntries { get; }
+     public static abstract int InterfaceEntriesLength { get; }
+ }

+ public unsafe interface IComExposedDetails
+ {
+     ComWrappers.ComInterfaceEntry* ComInterfaceEntries { get; }
+ 
+     int InterfaceEntriesLength { get; }
+ }

+ [AttributeUsage(AttributeTargets.Class)]
+ public sealed unsafe class ComExposedClassAttribute<T> : Attribute, IComExposedDetails
+     where T : IComExposedClass
+ {
+     public ComWrappers.ComInterfaceEntry* ComInterfaceEntries { get; }
+ 
+     public int InterfaceEntriesLength { get; }
+ }

public interface IIUnknownInterfaceDetailsStrategy
{
+    /// <summary>
+    /// Given a <see cref="RuntimeTypeHandle"/> get the details about the type that are exposed to COM.
+    /// </summary>
+    /// <param name="type">RuntimeTypeHandle instance</param>
+    /// <returns>Details if type is known.</returns>
+    IComExposedDetails? GetComExposedTypeDetails(RuntimeTypeHandle type);
}


+ [AttributeUsage(AttributeTargets.Class, AllowMultiple = true)]
+ public sealed class GeneratedComClassAttribute : Attribute
+ {
+ }


- public abstract class StrategyBasedComWrappers : ComWrappers
+ public class StrategyBasedComWrappers : ComWrappers
{
+     protected override sealed unsafe object CreateObject(nint externalComObject, CreateObjectFlags flags);
}

API Usage

[GeneratedComInterface]
[InterfaceType(ComInterfaceType.InterfaceIsIUnknown)]
public partial interface IComInterface1
{
    void Method();
}

[GeneratedComClass]
partial class A : IComInterface1
{
    void IComInterface1.Method()
    {
        Console.WriteLine("--- A.IComInterface1.Method");
    }
}

Alternative Designs

Alternatively, we considered requiring the user to attribute a ComWrappers-derived type with attributes that point to each class type it should support. This ended up becoming a significantly more expensive design that was less trimmable (both this design and the alternative one are trim-friendly).

Risks

This adds a method to an interface, but we haven't shipped the interface yet.

Author:	jkoritzinsky
Assignees:	-
Labels:	api-suggestion, area-System.Runtime.InteropServices, source-generator
Milestone:	-

[jkotas]

Is the source generator for COM going to be separate package or is going to be part of netcoreapp?

[jkoritzinsky]

The current plan is for it to be part of netcoreapp.

[bartonjs]

• We rewrote IComExposedDetails to combine the pointer and length into a single member (consequently changing two properties into one method)
  • And then plumbed that through the shape of everything else
• This proposal doesn't address COM activation. Please try to ensure that the shapes of interfaces won't need to change when that feature is added (and frontload that work if it will require changing things).
• There was another suggestion of promoting the "trigger" attributes up to System.Runtime.InteropServices instead of down in Marshalling. If you take that suggestion, keep the CCW and RCW trigger attributes together.

namespace System.Runtime.InteropServices.Marshalling;


 public unsafe interface IComExposedClass
 {
     public static abstract ComWrappers.ComInterfaceEntry* GetComInterfaceEntries(out int count);
 }

 public unsafe interface IComExposedDetails
 {
     ComWrappers.ComInterfaceEntry* GetComInterfaceEntries(out int count);
 }

 [AttributeUsage(AttributeTargets.Class)]
 public sealed unsafe class ComExposedClassAttribute<T> : Attribute, IComExposedDetails
     where T : IComExposedClass
 {
     ComWrappers.ComInterfaceEntry* GetComInterfaceEntries(out int count);
 }

public interface IIUnknownInterfaceDetailsStrategy
{
    /// <summary>
    /// Given a <see cref="RuntimeTypeHandle"/> get the details about the type that are exposed to COM.
    /// </summary>
    /// <param name="type">RuntimeTypeHandle instance</param>
    /// <returns>Details if type is known.</returns>
    IComExposedDetails? GetComExposedTypeDetails(RuntimeTypeHandle type);
}


 [AttributeUsage(AttributeTargets.Class, AllowMultiple = true)]
 public sealed class GeneratedComClassAttribute : Attribute
 {
 }

// No longer declared `abstract`
 public class StrategyBasedComWrappers : ComWrappers
{
     protected override sealed System.Runtime.InteropServices.ComWrappers.ComInterfaceEntry* ComputeVtables(object obj, System.Runtime.InteropServices.CreateComInterfaceFlags flags, out int count);
}