Node-API for .NET Interoperability

Common errors

• Error: Cannot find module 'node-api-dotnet'

  cause The native module 'node-api-dotnet' could not be found or loaded, often due to compilation issues, incorrect Node.js version, or an architecture mismatch (e.g., x86 vs x64).
  fix Ensure Node.js and npm are up-to-date. Try running `npm rebuild` or `npm install` again. Verify that your system architecture matches the installed package binaries. Check Node-API compatibility matrix if issues persist.

• UnhandledPromiseRejectionWarning: .NET Exception: <Your .NET exception message>

  cause An unhandled exception originated within the invoked .NET code and propagated back to the JavaScript promise chain without being caught.
  fix Implement robust error handling in your .NET code. In JavaScript, always use `.catch()` on promises returned by async .NET operations to handle .NET exceptions gracefully.

• TypeError: Cannot read properties of undefined (reading 'Console') or similar 'Cannot access X of undefined'

  cause The specific .NET namespace (e.g., 'System') or type (e.g., 'Console') was not correctly exposed or accessed from the `node-api-dotnet` module due to incorrect path or casing.
  fix Double-check the exact casing and nesting of the .NET types and namespaces you are trying to access. Consult the generated TypeScript definitions or the .NET API documentation for the correct path.

Warnings

• breaking The project is currently in 'Public Preview' status. This means there may be minor breaking API changes in future releases as the project matures and stabilizes.
  Fix: Always refer to the official documentation and release notes for migration guides and updated API surface when upgrading to new versions.
• gotcha Performance overhead can occur with excessive synchronous calls or marshalling large amounts of data between JavaScript and .NET contexts. Optimize interop boundaries for efficiency.
  Fix: Minimize calls across the boundary, batch operations where possible, and leverage async APIs for long-running .NET tasks to prevent blocking the Node.js event loop and maximize throughput.

Install

• npm install node-api-dotnet npm
• yarn add node-api-dotnet yarn
• pnpm add node-api-dotnet pnpm

Imports

• Node-API .NET root module
  wrong:

  import dotnet from 'node-api-dotnet';

  correct:

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

  The module exports an object containing .NET namespaces as properties. For ESM, use a namespace import (`* as`) to access the full structure. For CommonJS, use `const dotnet = require('node-api-dotnet');`
• System.Console (from .NET)
  wrong:

  import { System } from 'node-api-dotnet'; const Console = System.Console;

  correct:

  import * as dotnet from 'node-api-dotnet'; const Console = dotnet.System.Console;

  Specific .NET types like `System.Console` are exposed as nested properties of the main `node-api-dotnet` module export, not as direct named exports from the top-level module.
• TypeScript types for .NET APIs
  wrong:

  import { System } from 'node-api-dotnet'; // In a type-only context

  correct:

  import type { System } from 'node-api-dotnet';

  While `node-api-dotnet` ships with TypeScript type definitions, use `import type` when only referencing types to ensure the import is optimized away during compilation and doesn't cause runtime errors if the symbol is not a live runtime export.

Quickstart

Demonstrates importing the .NET interop module, calling a static .NET method, accessing a static property, and instantiating/using a .NET class (StringBuilder) from JavaScript with TypeScript.

import * as dotnet from 'node-api-dotnet'; // Using ESM for modern Node.js & TypeScript

// 1. Accessing a static .NET class and method
const Console = dotnet.System.Console;
Console.WriteLine('Hello from .NET via JavaScript!');

// 2. Accessing a static property (e.g., .NET CLR Version)
// System.Environment.Version is a common way to get CLR version in .NET
const clrVersion = dotnet.System.Environment.Version.ToString();
console.log(`\n.NET CLR Version: ${clrVersion}`);

// 3. Creating and using an instance of a .NET class (e.g., System.Text.StringBuilder)
const StringBuilder = dotnet.System.Text.StringBuilder;
const sb = new StringBuilder('Initial string');
sb.Append(' appended from JS!');
sb.Append(`\nCurrent UTC Time: ${new Date().toISOString()}`);
const finalString = sb.ToString();
console.log(`\nStringBuilder output:\n${finalString}`);

// Note: Async operations are also supported, e.g., for File I/O with .NET Tasks.
// This example focuses on synchronous interop for brevity.