Fix importing specific version of .NET (#193)

Author: jasongin

Docs/dynamic-invoke.md

@@ -56,6 +56,13 @@ For examples of this scenario, see
     const dotnet = require('node-api-dotnet');
     ```
 
+   To load a specific version of .NET, append the target framework moniker to the module name.
+   A `.js` suffix is required when using ES modules, optional with CommonJS.
+   ```JavaScript
+   import dotnet from 'node-api-dotnet/net6.0.js'
+   ```
+   Currently the supported target frameworks are `net472`, `net6.0`, and `net8.0`.
+
 4. Load one or more .NET packages using the generated `.js` files:
    ```JavaScript
    require('./bin/Example.Package.js');

Docs/node-module.md

@@ -59,15 +59,29 @@ For a minimal example of this scenario, see
     [build it from source](../README-DEV.md).<br>Then get the package from
     `out/pkg/node-api-dotnet-{version}.tgz`.
 
-6. Import the `node-api-dotnet` package in your JavaScript code:
+6. Import the `node-api-dotnet` package in your JavaScript or TypeScript code. The import syntax
+   depends on the [module system](https://nodejs.org/api/esm.html) the current project is using.
+
+   ES modules (TypeScript or JavaScript):
     ```JavaScript
-    const dotnet = require('node-api-dotnet');
+    import dotnet from 'node-api-dotnet';
     ```
-    Or if using ES modules:
+   CommonJS modules (TypeScript):
+    ```TypeScript
+    import * as dotnet from 'node-api-dotnet';
+    ```
+   CommonJS modules (JavaScript):
     ```JavaScript
-    import dotnet from 'node-api-dotnet';
+    const dotnet = require('node-api-dotnet');
     ```
 
+   To load a specific version of .NET, append the target framework moniker to the module name.
+   A `.js` suffix is required when using ES modules, optional with CommonJS.
+   ```JavaScript
+   import dotnet from 'node-api-dotnet/net6.0.js'
+   ```
+   Currently the supported target frameworks are `net472`, `net6.0`, and `net8.0`.
+
 7. Load your .NET module assembly from its path using the `dotnet.require()` function. Also provide
     a hint about type definitions (from the same path):
     ```JavaScript

src/NodeApi.DotNetHost/ManagedHost.cs

@@ -137,6 +137,9 @@ JSValue removeListener(JSCallbackArgs args)
         }
 
         exports.DefineProperties(
+            JSPropertyDescriptor.Accessor("runtimeVersion", ManagedHost.GetRuntimeVersion),
+            JSPropertyDescriptor.Accessor("frameworkMoniker", ManagedHost.GetFrameworkMoniker),
+
             // The require() method loads a .NET assembly that was built to be a Node API module.
             // It uses static binding to the APIs the module specifically exports to JS.
             JSPropertyDescriptor.Function("require", LoadModule),
@@ -164,12 +167,14 @@ JSValue removeListener(JSCallbackArgs args)
 
         // Export the System.Runtime and System.Console assemblies by default.
         LoadAssemblyTypes(typeof(object).Assembly);
-        _loadedAssembliesByName.Add("System.Runtime", typeof(object).Assembly);
+        _loadedAssembliesByName.Add(
+            typeof(object).Assembly.GetName().Name!, typeof(object).Assembly);
 
         if (typeof(Console).Assembly != typeof(object).Assembly)
         {
             LoadAssemblyTypes(typeof(Console).Assembly);
-            _loadedAssembliesByName.Add("System.Console", typeof(Console).Assembly);
+            _loadedAssembliesByName.Add(
+                typeof(Console).Assembly.GetName().Name!, typeof(Console).Assembly);
         }
     }
 
@@ -324,6 +329,22 @@ public static napi_value InitializeModule(napi_env env, napi_value exports)
         return default;
     }
 
+    public static JSValue GetRuntimeVersion(JSCallbackArgs _)
+    {
+        return Environment.Version.ToString();
+    }
+
+    public static JSValue GetFrameworkMoniker(JSCallbackArgs _)
+    {
+        Version runtimeVersion = Environment.Version;
+
+        // For .NET 4 the minor version may be higher, but net472 is the only TFM supported.
+        string tfm = runtimeVersion.Major == 4 ? "net472" :
+            $"net{runtimeVersion.Major}.{runtimeVersion.Minor}";
+
+        return tfm;
+    }
+
     /// <summary>
     /// Loads a .NET assembly that was built to be a Node API module, using static binding to
     /// the APIs the module specifically exports to JS.

src/NodeApi.Generator/TypeDefinitionsGenerator.cs

@@ -377,6 +377,11 @@ public SourceText GenerateTypeDefinitions(bool? autoCamelCase = null)
 
     private bool IsTypeExported(Type type)
     {
+        if (IsExcludedNamespace(type.Namespace))
+        {
+            return false;
+        }
+
         // Types not in the current assembly are not exported from this TS module.
         // (But support mscorlib and System.Runtime forwarding to System.Private.CoreLib.)
         if (type.Assembly != _assembly &&
@@ -626,7 +631,8 @@ private void GenerateClassDefinition(ref SourceBuilder s, Type type)
                 foreach (PropertyInfo property in type.GetProperties(
                     BindingFlags.Public | BindingFlags.Static))
                 {
-                    if (!IsExcludedMember(property))
+                    // Indexed properties are not implemented.
+                    if (!IsExcludedMember(property) && property.GetIndexParameters().Length == 0)
                     {
                         if (isFirstMember) isFirstMember = false; else s++;
                         ExportTypeMember(ref s, property);
@@ -665,7 +671,11 @@ private void GenerateClassDefinition(ref SourceBuilder s, Type type)
             string prefix = (implements.Length == 0 ? $" {implementsKind}" : ",") +
                 (interfaceTypes.Length > 1 ? "\n\t" : " ");
 
-            if (isStreamSubclass &&
+            if (!interfaceType.IsPublic || IsExcludedNamespace(interfaceType.Namespace))
+            {
+                continue;
+            }
+            else if (isStreamSubclass &&
                 (interfaceType.Name == nameof(IDisposable) ||
                 interfaceType.Name == nameof(IAsyncDisposable)))
             {
@@ -725,7 +735,8 @@ private void GenerateClassDefinition(ref SourceBuilder s, Type type)
                 (isStaticClass ? BindingFlags.DeclaredOnly : default) |
                 (type.IsInterface || isGenericTypeDefinition ? default : BindingFlags.Static)))
             {
-                if (!IsExcludedMember(property))
+                // Indexed properties are not implemented.
+                if (!IsExcludedMember(property) && property.GetIndexParameters().Length == 0)
                 {
                     if (isFirstMember) isFirstMember = false; else s++;
                     ExportTypeMember(ref s, property);
@@ -763,7 +774,9 @@ private static bool HasExplicitInterfaceImplementations(Type type, Type interfac
                 type.GetInterfaces().Any((i) => i.Name == typeof(IComparable<>).Name)) ||
                 (interfaceType.Name == "ISpanFormattable" &&
                 (type.Name == "INumberBase`1" ||
-                type.GetInterfaces().Any((i) => i.Name == "INumberBase`1"))))
+                type.GetInterfaces().Any((i) => i.Name == "INumberBase`1"))) ||
+                (interfaceType.Name == "ICollection" &&
+                type.Name == "IProducerConsumerCollection`1"))
             {
                 // TS interfaces cannot extend multiple interfaces that have non-identical methods
                 // with the same name. This is most commonly an issue with IComparable and
@@ -773,10 +786,10 @@ private static bool HasExplicitInterfaceImplementations(Type type, Type interfac
 
             return false;
         }
-        else if (type.Name == "TypeDelegator" && interfaceType.Name == "IReflectableType")
+        else if (interfaceType.Name == "IReflectableType")
         {
-            // Special case: TypeDelegator has an explicit implementation of this interface,
-            // but it isn't detected by reflection due to the runtime type delegation.
+            // Special case: Reflectable types have explicit implementations of this interface,
+            // but they aren't detected by reflection due to the runtime type delegation.
             return true;
         }
 
@@ -823,6 +836,11 @@ private static bool HasExplicitInterfaceImplementations(Type type, Type interfac
             }
         }
 
+        if (type.BaseType != null && type.BaseType != typeof(object))
+        {
+            return HasExplicitInterfaceImplementations(type.BaseType!, interfaceType);
+        }
+
         return false;
     }
 
@@ -968,6 +986,21 @@ private void EndNamespace(ref SourceBuilder s, Type type)
         }
     }
 
+    private static bool IsExcludedNamespace(string? ns)
+    {
+        // These namespaces contain APIs that are problematic for TS generation.
+        // (Mostly old .NET Framework APIs.)
+        return ns switch
+        {
+            "System.Runtime.InteropServices" or
+            "System.Runtime.Remoting.Messaging" or
+            "System.Runtime.Serialization" or
+            "System.Security.AccessControl" or
+            "System.Security.Policy" => true,
+            _ => false,
+        };
+    }
+
     private static bool IsExcludedMember(PropertyInfo property)
     {
         if (property.PropertyType.IsPointer)

src/NodeApi/Runtime/PooledBuffer.cs

@@ -6,29 +6,43 @@ namespace Microsoft.JavaScript.NodeApi.Runtime;
 
 internal struct PooledBuffer : IDisposable
 {
-    private ArrayPool<byte>? _pool;
-    public static readonly PooledBuffer Empty = new(null, [], 0);
+    public static readonly PooledBuffer Empty = new();
+
+    public PooledBuffer()
+    {
+        Buffer = [];
+        Length = 0;
+    }
 
-    public PooledBuffer(ArrayPool<byte> pool, int length)
-        : this(pool, pool.Rent(length), length) { }
+#if NETFRAMEWORK
 
-    public PooledBuffer(ArrayPool<byte> pool, int length, int bufferMinimumLength)
-        : this(pool, pool.Rent(bufferMinimumLength), length) { }
+    // Avoid a dependency on System.Buffers with .NET Framwork.
+    // It is available as a nuget package, but might not be installed in the application.
+    // In this case the buffer is not actually pooled.
 
-    private PooledBuffer(ArrayPool<byte>? pool, byte[] buffer, int length)
+    public PooledBuffer(int length) : this(length, length) { }
+
+    public PooledBuffer(int length, int bufferMinimumLength)
     {
-        _pool = pool;
-        Buffer = buffer;
+        Buffer = new byte[bufferMinimumLength];
         Length = length;
     }
 
-    public int Length { get; private set; }
+    public readonly void Dispose() { }
 
-    public readonly byte[] Buffer { get; }
+#else
 
-    public readonly Span<byte> Span => Buffer;
+    private ArrayPool<byte>? _pool;
 
-    public readonly ref byte Pin() => ref Span.GetPinnableReference();
+    private PooledBuffer(int length, int bufferMinimumLength)
+        : this(ArrayPool<byte>.Shared, length, bufferMinimumLength) { }
+
+    private PooledBuffer(ArrayPool<byte> pool, int length, int bufferMinimumLength)
+    {
+        _pool = pool;
+        Buffer = pool.Rent(bufferMinimumLength);
+        Length = length;
+    }
 
     public void Dispose()
     {
@@ -39,6 +53,16 @@ public void Dispose()
         }
     }
 
+#endif
+
+    public int Length { get; private set; }
+
+    public readonly byte[] Buffer { get; }
+
+    public readonly Span<byte> Span => Buffer;
+
+    public readonly ref byte Pin() => ref Span.GetPinnableReference();
+
     public static unsafe PooledBuffer FromStringUtf8(string? value)
     {
         if (string.IsNullOrEmpty(value))
@@ -47,15 +71,8 @@ public static unsafe PooledBuffer FromStringUtf8(string? value)
         }
 
         int byteLength = Encoding.UTF8.GetByteCount(value);
-        PooledBuffer buffer = new(ArrayPool<byte>.Shared, byteLength, byteLength + 1);
-
-        fixed (char* pChars = value)
-        fixed (byte* pBuffer = buffer.Buffer)
-        {
-            // The Span<byte> overload of GetBytes() would be nicer, but is not available on .NET 4.
-            Encoding.UTF8.GetBytes(pChars, value!.Length, pBuffer, byteLength);
-            pBuffer[byteLength] = 0;
-        }
+        PooledBuffer buffer = new(byteLength, byteLength + 1);
+        Encoding.UTF8.GetBytes(value, 0, value!.Length, buffer.Buffer, 0);
 
         return buffer;
     }

src/node-api-dotnet/index.d.ts

@@ -6,6 +6,17 @@
 // This explicit module declaration enables module members to be merged with imported namespaces.
 declare module 'node-api-dotnet' {
 
+/**
+ * Gets the current .NET runtime version, for example "8.0.1".
+ */
+export const runtimeVersion: string;
+
+/**
+ * Gets the framework monikier corresponding to the current .NET runtime version,
+ * for example "net8.0" or "net472".
+ */
+export const frameworkMoniker: string;
+
 /**
  * Loads a .NET assembly that was built to be a Node API module, using static binding to
  * the APIs the module specifically exports to JS.

src/node-api-dotnet/init.js

@@ -16,18 +16,36 @@ const ridPlatform =
 const ridArch = process.arch === 'ia32' ? 'x86' : process.arch;
 const rid = `${ridPlatform}-${ridArch}`;
 
+const defaultTargetFramework = 'net8.0';
+
+/**
+ * The loaded instance of the .NET Runtime. Only one instance/version may be loaded in the process.
+ */
+let dotnet = undefined;
+
 /**
  * Initializes the Node API .NET host.
- * @param {string} targetFramework Minimum requested .NET version. Must be one of the target
+ * @param {string?} targetFramework Minimum requested .NET version. Must be one of the target
  * framework monikers supported by the Node API .NET package. The actual loaded version of .NET
  * may be higher, if the requested version is not installed.
  * @returns {import('./index')} The Node API .NET host.
  */
 function initialize(targetFramework) {
+  if (!targetFramework) {
+    // Some version was already loaded and no specific version was requested.
+    // Return the already-loaded version.
+    if (dotnet) {
+      return dotnet;
+    }
+
+    targetFramework = defaultTargetFramework;
+  }
+
   const assemblyName = 'Microsoft.JavaScript.NodeApi';
   const nativeHostPath = __dirname + `/${rid}/${assemblyName}.node`;
   const managedHostPath = __dirname + `/${targetFramework}/${assemblyName}.DotNetHost.dll`
 
   const nativeHost = require(nativeHostPath);
-  return nativeHost.initialize(targetFramework, managedHostPath, require);
+  dotnet = nativeHost.initialize(targetFramework, managedHostPath, require);
+  return dotnet;
 }

src/node-api-dotnet/pack.js

@@ -22,7 +22,6 @@ const targetFrameworks = ['net8.0', 'net6.0'];
 if (process.platform === 'win32') targetFrameworks.push('net472');
 
 const aotTargetFramework = 'net8.0';
-const defaultManagedHostTargetFramework = 'net6.0';
 
 const fs = require('fs');
 const path = require('path');
@@ -189,8 +188,7 @@ function copyFile(sourceFilePath, destFilePath) {
 
 function generateTargetFrameworkScriptFiles(packageStageDir) {
   // Generate `index.js` for the default target framework, plus one for each supported target.
-  generateTargetFrameworkScriptFile(
-    path.join(packageStageDir, 'index.js'), defaultManagedHostTargetFramework);
+  generateTargetFrameworkScriptFile(path.join(packageStageDir, 'index.js'));
   for (let tfm of targetFrameworks) {
     generateTargetFrameworkScriptFile(path.join(packageStageDir, tfm + '.js'), tfm);
   }
@@ -199,7 +197,15 @@ function generateTargetFrameworkScriptFiles(packageStageDir) {
 function generateTargetFrameworkScriptFile(filePath, tfm) {
   // Each generated entrypoint script uses `init.js` to request a specific target framework version.
   const js = `const initialize = require('./init');
-module.exports = initialize('${tfm}');
+module.exports = initialize(${tfm ? `'${tfm}'` : ''});
 `;
   fs.writeFileSync(filePath, js);
+
+  // Also generate a `.d.ts` file for each tfm, which just re-exports the default index.
+  if (tfm) {
+    const dts = `import './index';
+export * from 'node-api-dotnet';
+`;
+    fs.writeFileSync(filePath.replace(/\.js$/, '.d.ts'), dts);
+  }
 }