node-api-dotnet package

Use the node-api-dotnet package to load .NET assemblies into a Node.js application and call public APIs defined in the assemblies.

ES (TS or JS)

import dotnet from 'node-api-dotnet';

CommonJS (TS)

import * as dotnet from 'node-api-dotnet';

CommonJS (JS)

const dotnet = require('node-api-dotnet');

To load a specific version of .NET, append the target framework moniker to the package name:

ES (TS or JS)

import dotnet from 'node-api-dotnet/net8.0';

CommonJS (TS)

import * as dotnet from 'node-api-dotnet/net8.0';

CommonJS (JS)

const dotnet = require('node-api-dotnet/net8.0');

Currently the supported target frameworks are net472, net8.0, and net9.0.

Properties

frameworkMoniker property

const dotnet.frameworkMoniker: string

Gets the framework monikier corresponding to the current .NET runtime version, for example "net8.0" or "net472".

runtimeVersion property

const dotnet.runtimeVersion: string

Gets the current .NET runtime version, for example "8.0.1".

Methods

addListener method

dotnet.addListener(
    event: "resolving",
    listener: (assemblyName: string, assemblyVersion: string, resolve: (string: any) => void) => void,
): void

Adds a listener for the resolving event, which is raised when a .NET assembly requires an additional dependent assembly to be resolved and loaded. The listener may call resolve() to load the requested assembly from a resolved file path. If the listener does not call resolve(), the runtime will then attempt to resolve the assembly by searching in the same application directory as other already-loaded assemblies, if there were any.

• listener: Resolving event listener funciton to be invokved when a .NET assembly is being resolved.

load method

dotnet.load(assemblyNameOrFilePath: string): void

Loads an arbitrary .NET assembly that isn't necessarily designed as a JS module, enabling dynamic invocation of any APIs in the assembly. After loading, types from the assembly are available via namespaces on the main dotnet module.

• assemblyNameOrFilePath: Path to the .NET assembly DLL file, or name of a system assembly.

After loading an assembly, types in the assembly are merged into the .NET namespace hierarchy, with top-level namespaces available as properties on the .NET module. For example, if the assembly defines a type Contoso.Business.Component, it can be accessed as dotnet.Contoso.Business.Component. (.NET core library types can be accessed the same way, for example dotnet.System.Console.)

removeListener method

dotnet.removeListener(
    event: "resolving",
    listener: (assemblyName: string, assemblyVersion: string) => void,
): void

Removes a listener for the resolving event.

require method

dotnet.require(dotnetAssemblyFilePath: string): any

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.

• dotnetAssemblyFilePath: Path to the .NET assembly DLL file.
• Returns: The JavaScript module exported by the assembly. (Type information for the module may be available in a separate generated type-definitions file.)

The .NET assembly must use [JSExport] attributes to export selected types and/or members to JavaScript. These exports do not use .NET namespaces.