[API Proposal]: Move APIs for generated marshalling to different namespace - System.Runtime.Marshalling

[elinor-fung]

Background and motivation

For .NET 7, we added various APIs used for p/invoke source generation:

• LibraryImportAttribute for p/invoke source generation #46822.
• Attributes and Analyzer Diagnostics to support custom struct marshalling in the DllImport Source Generator #46838
• [API Proposal]: Specify supported custom type marshalling features on CustomTypeMarshallerAttribute #66121
• [API Proposal]: Implementations of marshallers using CustomTypeMarshallerAttribute #66623

These were all added to the System.Runtime.InteropServices namespace. We are proposing moving them to a separate namespace for clearer separation and discovery.

API Proposal

-namespace System.Runtime.InteropServices
+namespace System.Runtime.Marshalling
{
    public sealed class LibraryImportAttribute : Attribute { ... }
    public enum StringMarshalling { ... }

    public sealed class NativeMarshallingAttribute : Attribute { ... ]
    public sealed class MarshalUsingAttribute : Attribute { ... }
    public sealed class CustomTypeMarshallerAttribute : Attribute { ... }

    public enum CustomTypeMarshallerDirection { ... }
    public enum CustomTypeMarshallerFeatures { ... ]
    public enum CustomTypeMarshallerKind { ... }

    public unsafe ref struct AnsiStringMarshaller { ... }
    public unsafe ref struct ArrayMarshaller { ... }
    public unsafe ref struct PointerArrayMarshaller { ... }
    public unsafe ref struct Utf16StringMarshaller { ... }
    public unsafe ref struct Utf8StringMarshaller { ... }
}

API Usage

using System.Runtime.Marshalling;

[LibraryImport("NativeLib", StringMarshallingCustomType = typeof(AnsiStringMarshaller))]
internal static partial string Method(string s1, string s2);

Alternative Designs

• Leave LibraryImportAttribute (the triggering attribute for p/invoke source generation) in System.Runtime.InteropServices and only move the new APIs (custom type marshalling attributes, marshaller implementations) that are directly related to marshalling
• Use a sub-namespace under System.Runtime.InteropServices - for example, System.Runtime.InteropServices.Marshalling

Risks

This would be a breaking change between Preview 4 and 5. The new APIs were just exposed in Preview 4 and the source generator itself will not be included for public use until Preview 5. so we do not expect this to be very impactful.

[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

For .NET 7, we added various APIs used for p/invoke source generation:

• LibraryImportAttribute for p/invoke source generation #46822.
• Attributes and Analyzer Diagnostics to support custom struct marshalling in the DllImport Source Generator #46838
• [API Proposal]: Specify supported custom type marshalling features on CustomTypeMarshallerAttribute #66121
• [API Proposal]: Implementations of marshallers using CustomTypeMarshallerAttribute #66623

These were all added to the System.Runtime.InteropServices namespace. We are proposing moving them to a separate namespace for clearer separation and discovery.

API Proposal

-namespace System.Runtime.InteropServices
+namespace System.Runtime.Marshalling
{
    public sealed class LibraryImportAttribute : Attribute { ... }
    public enum StringMarshalling { ... }

    public sealed class NativeMarshallingAttribute : Attribute { ... ]
    public sealed class MarshalUsingAttribute : Attribute { ... }
    public sealed class CustomTypeMarshallerAttribute : Attribute { ... }

    public enum CustomTypeMarshallerDirection { ... }
    public enum CustomTypeMarshallerFeatures { ... ]
    public enum CustomTypeMarshallerKind { ... }

    public unsafe ref struct AnsiStringMarshaller { ... }
    public unsafe ref struct ArrayMarshaller { ... }
    public unsafe ref struct PointerArrayMarshaller { ... }
    public unsafe ref struct Utf16StringMarshaller { ... }
    public unsafe ref struct Utf8StringMarshaller { ... }
}

API Usage

using System.Runtime.Marshalling;

[LibraryImport("NativeLib", StringMarshallingCustomType = typeof(AnsiStringMarshaller))]
internal static partial string Method(string s1, string s2);

Alternative Designs

• Leave LibraryImportAttribute (the triggering attribute for p/invoke source generation) in System.Runtime.InteropServices and only move the new APIs (custom type marshalling attributes, marshaller implementations) that are directly related to marshalling
• Use a sub-namespace under System.Runtime.InteropServices - for example, System.Runtime.InteropServices.Marshalling

Risks

This would be a breaking change between Preview 4 and 5. The new APIs were just exposed in Preview 4 and the source generator itself will not be included for public use until Preview 5. so we do not expect this to be very impactful.

Author:	elinor-fung
Assignees:	-
Labels:	api-suggestion, area-System.Runtime.InteropServices
Milestone:	7.0.0

[elinor-fung]

@AaronRobinsonMSFT @jkoritzinsky I know when we talked before, I was into moving everything - including LibraryImportAttribute, but I'm actually not sure now. As the triggering attribute, it is not directly for marshalling, so I'm not sure it really fits with the rest. Thoughts?

[AaronRobinsonMSFT]

@elinor-fung Agreed on all accounts. I voiced a similar concern to @jkoritzinsky previously. I think we should have a conversation with the API review team and see what some of the API experts think of the concerns.

[terrajobst]

Video

• We'd prefer putting these under InteropServices

namespace System.Runtime.InteropServices
{
    public sealed class LibraryImportAttribute : Attribute { /*...*/ }
    public enum StringMarshalling { /*...*/ }
}

// Was previously also approved for System.Runtime.InteropServices

namespace System.Runtime.InteropServices.Marshalling
{
    public sealed class NativeMarshallingAttribute : Attribute { /*...*/ }
    public sealed class MarshalUsingAttribute : Attribute { /*...*/ }
    public sealed class CustomTypeMarshallerAttribute : Attribute { /*...*/ }

    public enum CustomTypeMarshallerDirection { /*...*/ }
    public enum CustomTypeMarshallerFeatures { /*...*/ }
    public enum CustomTypeMarshallerKind { /*...*/ }

    public unsafe ref struct AnsiStringMarshaller { /*...*/ }
    public unsafe ref struct ArrayMarshaller { /*...*/ }
    public unsafe ref struct PointerArrayMarshaller { /*...*/ }
    public unsafe ref struct Utf16StringMarshaller { /*...*/ }
    public unsafe ref struct Utf8StringMarshaller { /*...*/ }
}