[API Proposal]: Optional export of UnmanagedCallersOnlyAttribute

[HolographicHat]

Background and motivation

Some funcs are only used for native interop with static libraries and we don't want them exported, so we need a new field to UnmanagedCallersOnlyAttribute to control whether the method is exported.

API Proposal

    [System.AttributeUsageAttribute(System.AttributeTargets.Method, Inherited = false)]
    public sealed class UnmanagedCallersOnlyAttribute : System.Attribute
    {
         public UnmanagedCallersOnlyAttribute() { }
         public System.Type[]? CallConvs;
         public string? EntryPoint;
+        public bool Export = true;
     }

API Usage

[UnmanagedCallersOnly(EntryPoint = "InternalSum", Export = false)]
public static int InternalSum(int a, int b) => a + b;

extern "C" int InternalSum(int a, int b);

extern "C" __declspec(dllexport) capi_get_number() {
    return InternalSum(114, 514);
}

Alternative Designs

No response

Risks

No response

[huoyaoyuan]

The function still needs to be exported from NativeAOT compiler, otherwise the linker can't link it with the import in C++.

The exporting instruction should be passed to the native linker, not NativeAOT compiler. See https://learn.microsoft.com/dotnet/core/deploying/native-aot/interop#linking .

[HolographicHat]

The function still needs to be exported from NativeAOT compiler, otherwise the linker can't link it with the import in C++.

The exporting instruction should be passed to the native linker, not NativeAOT compiler. See learn.microsoft.com/dotnet/core/deploying/native-aot/interop#linking .

Strictly speaking, the purpose of this proposal is to assign a symbol name while preventing its export in the linker output.

// main.cpp, compiled into native.lib
extern "C" int InternalSum(int a, int b);

extern "C" int GetNumberImpl() {
    return InternalSum(114, 514);
}

// Class1.cs
using System.Runtime.InteropServices;

public static partial class Class1 {

    [UnmanagedCallersOnly(EntryPoint = "InternalSum", Export = false)]
    public static int Sum(int a, int b) => a + b;

    [LibraryImport("native")]
    private static partial int GetNumberImpl();

    [UnmanagedCallersOnly(EntryPoint = "ExportedGetNumber")]
    public static int GetNumber() => GetNumberImpl();

}

<Project Sdk="Microsoft.NET.Sdk">
    <!-- ~ ~ -->
    <PropertyGroup>
        <PublishAot>true</PublishAot>
    </PropertyGroup>
    <ItemGroup>
        <DirectPInvoke Include="native"/>
        <NativeLibrary Include="native.lib"/>
    </ItemGroup>
</Project>

Result:

Ref:
https://github.com/HolographicHat/runtime/commit/e7b1476d9db84869bd352d8305db69c97ea3f28e

[huoyaoyuan]

assign a symbol name while preventing its export in the linker output

There are two separate steps. .NET attribute can only control the output .obj file of ilc. The symbol must be present in order to link with native.lib.

The output of native linker is not controllable from .NET. You need to use linker-native way (.DEF file) to specify it.

[HolographicHat]

assign a symbol name while preventing its export in the linker output

There are two separate steps. .NET attribute can only control the output .obj file of ilc. The symbol must be present in order to link with native.lib.

The output of native linker is not controllable from .NET. You need to use linker-native way (.DEF file) to specify it.

https://github.com/HolographicHat/runtime/commit/e7b1476d9db84869bd352d8305db69c97ea3f28e#diff-cbfc0b2a712d55d27b39efb1ee0625e78f2c5ba58fcc9a5f6351241c44134d84R80

https://github.com/HolographicHat/runtime/commit/e7b1476d9db84869bd352d8305db69c97ea3f28e#diff-2d87bd33cc36a7cbe4cc52708e0212f778f3b9b4c3d51890fee89b283c52e86bR29

[huoyaoyuan]

Well I was incorrect. ILC does write the DEF file based on exports.

[jkotas]

You can supply your own exports file (DEF file on Windows) if you want to have fine grained control over what gets exported or if you need to use other advanced exports file features.
 
If we wanted something built-in, we have been exposing this sort of functionality via project file properties, similar to DirectPInvoke/DirectPInvokeList or UnmanagedEntryPointsAssembly exist today.

[HolographicHat]

You can supply your own exports file (DEF file on Windows) if you want to have fine grained control over what gets exported or if you need to use other advanced exports file features. If we wanted something built-in, we have been exposing this sort of functionality via project file properties, similar to DirectPInvoke/DirectPInvokeList or UnmanagedEntryPointsAssembly exist today.

the purpose of this proposal is to assign a symbol name while preventing its export in the linker output.`

If you don't use UnmanagedCallersOnly to specify the symbol name, you cannot export the symbol via a DEF file, as the function name not included in the obj file.
If you use UnmanagedCallersOnly to specify the symbol name, the symbol will be automatically write to $(TargetName).def and exported.

This is unrelated to DirectPInvoke/DirectPInvokeList/UnmanagedEntryPointsAssembly

I know how to remove it before linking just provide a simplify way to do it.

I have implemented a solution for this. May I create a pull request?

[huoyaoyuan]

I have implemented a solution for this. May I create a pull request?

No. This involves public API and must go through the API review process. Pull request can only be accepted after it's approved.

That's also the reason why workarounding with existing feature is recommended, because is available immediately.

[jkotas]

I know how to remove it before linking just provide a simplify way to do it.

A few simple options:

• You can set ExportsFile property to point to your own .DEF file
  or
• You can set (undocumented) IlcExportUnmanagedEntrypoints property to false. It will omit all unmanaged entrypoints from the .DEF file

[HolographicHat]

You can set ExportsFile property to point to your own .DEF file

ilc will override it

A few simple options:
* You can set (undocumented) IlcExportUnmanagedEntrypoints property to false. It will omit all unmanaged entrypoints from the .DEF file

for developers, omitting __declspec(dllexport) in Cxx achieves the desired behavior, whereas in C# it requires relying on undocumented property and manually managing export lists — it's really *simple*?

[AaronRobinsonMSFT]

for developers, omitting __declspec(dllexport) in Cxx achieves the desired behavior, whereas in C# it requires relying on undocumented property and manually managing export lists — it's really simple?

It is neither simple nor cheap when viewed in totality. It involves documentation, tests, new APIs, interaction matrices that need consideration, and of course perpetual ownership.

The calculus for this is going to come down to how many others need this feature and is there another way to achieve it. These relate to one another. If this feature will handle a scenario hit by many, then that may outweight the costs defined above. However, if there are few impacted people and there already exists a way to acheive the solution, it is unlikely to outweight the costs.

I'll place this in Future for now and see if there is more interest. If not, we'll likely close this at a future date.