{"id":3883,"date":"2026-04-20T20:14:04","date_gmt":"2026-04-20T20:14:04","guid":{"rendered":"https:\/\/rssfeedtelegrambot.bnaya.co.il\/index.php\/2026\/04\/20\/writing-node-js-addons-with-net-native-aot\/"},"modified":"2026-04-20T20:14:04","modified_gmt":"2026-04-20T20:14:04","slug":"writing-node-js-addons-with-net-native-aot","status":"publish","type":"post","link":"https:\/\/rssfeedtelegrambot.bnaya.co.il\/index.php\/2026\/04\/20\/writing-node-js-addons-with-net-native-aot\/","title":{"rendered":"Writing Node.js addons with .NET Native AOT"},"content":{"rendered":"

C# Dev Kit<\/a> is a VS Code extension. Like all VS Code extensions, its front end is TypeScript running in Node.js. For certain platform-specific tasks, such as reading the Windows Registry, we\u2019ve historically used native Node.js addons written in C++, which are compiled via node-gyp<\/a> during installation to the developer\u2019s workspace.<\/p>\n

This works, but it comes with overhead. Using node-gyp to build these particular packages requires an old version of Python to be installed on every developer\u2019s machine. For a team that works on .NET tooling, this requirement added complexity and friction. New contributors had to set up tools they\u2019d never touch directly, and CI pipelines needed to provision and maintain them, which slowed down builds and added yet another set of dependencies to keep up to date over time.<\/p>\n

The C# Dev Kit team already has the .NET SDK installed, so why not use C# and Native AOT to streamline our engineering systems?<\/p>\n

How Node.js addons work<\/h2>\n

A Node.js native addon is a shared library (.dll<\/code> on Windows, .so<\/code> on Linux, .dylib<\/code> on macOS) that exports a specific entry point. When Node.js loads such a library, it calls the function napi_register_module_v1<\/code>. The addon registers any functions it provides, and from that point on, JavaScript treats it like any other module.<\/p>\n

The interface that makes this possible is N-API<\/a> (also called Node-API) \u2013 a stable, ABI-compatible C API for building addons. N-API doesn\u2019t care what language produced the shared library, only that it exports the right symbols and calls the right functions. This makes Native AOT a viable option because it can produce shared libraries with arbitrary native entry points, which is all N-API needs.<\/p>\n

Throughout the rest of this post, let\u2019s look at the key parts of a small Native AOT Node.js addon that can read a string value from the registry. To keep things simple, we\u2019ll put all the code in one class, though you could easily factor things out to be reusable.<\/p>\n

The project file<\/h2>\n

The project file is minimal:<\/p>\n

<Project Sdk=\"Microsoft.NET.Sdk\">\r\n  <PropertyGroup>\r\n    <TargetFramework>net10.0<\/TargetFramework>\r\n    <PublishAot>true<\/PublishAot>\r\n    <AllowUnsafeBlocks>true<\/AllowUnsafeBlocks>\r\n  <\/PropertyGroup>\r\n<\/Project><\/code><\/pre>\n
PublishAot<\/code><\/a> tells the SDK to produce a shared library when the project is published. AllowUnsafeBlocks<\/code> is needed because the N-API interop involves function pointers and fixed buffers.<\/p>\n
The module entry point<\/h2>\n
Node.js expects the shared library to export napi_register_module_v1<\/code>. In C#, we can do this with [UnmanagedCallersOnly]<\/code><\/a>:<\/p>\n
public static unsafe partial class RegistryAddon\r\n{\r\n    [UnmanagedCallersOnly(\r\n        EntryPoint = \"napi_register_module_v1\",\r\n        CallConvs = [typeof(CallConvCdecl)])]\r\n    public static nint Init(nint env, nint exports)\r\n    {\r\n        Initialize();\r\n\r\n        RegisterFunction(\r\n            env,\r\n            exports,\r\n            \"readStringValue\"u8,\r\n            &ReadStringValue);\r\n\r\n        \/\/ Register additional functions...\r\n\r\n        return exports;\r\n    }\r\n}<\/code><\/pre>\n
A few C# features are doing work here. nint<\/code><\/a> is a native-sized integer \u2014 the managed equivalent of intptr_t<\/code> \u2013 used to pass around N-API handles. The u8<\/code> suffix<\/a> produces a ReadOnlySpan<byte><\/code> containing a UTF-8 string literal, which we pass directly to N-API without any encoding or allocation. And [UnmanagedCallersOnly]<\/code> tells the AOT compiler to export the method with the specified entry point name and calling convention, making it callable from native code.<\/p>\n
Each call to RegisterFunction<\/code> attaches a C# function pointer to a named property on the JavaScript exports<\/code> object, so that calling addon.readStringValue(...)<\/code> in JavaScript invokes the corresponding C# method directly, in-process.<\/p>\n
Calling N-API from .NET<\/h2>\n
N-API functions are exported by node.exe<\/code> itself, so rather than linking against a separate library, we need to resolve them against the host process. We declare our P\/Invoke methods using [LibraryImport]<\/code><\/a> with \"node\"<\/code> as the library name, and then register a custom resolver via NativeLibrary.SetDllImportResolver<\/code><\/a> that redirects to the host process at runtime:<\/p>\n
private static void Initialize()\r\n{\r\n    NativeLibrary.SetDllImportResolver(\r\n        System.Reflection.Assembly.GetExecutingAssembly(),\r\n        ResolveDllImport);\r\n\r\n    static nint ResolveDllImport(\r\n        string libraryName,\r\n        Assembly assembly,\r\n        DllImportSearchPath? searchPath)\r\n    {\r\n        if (libraryName is not \"node\")\r\n            return 0;\r\n\r\n        return NativeLibrary.GetMainProgramHandle();\r\n    }\r\n}<\/code><\/pre>\n
With this resolver in place, the runtime knows to look up all \"node\"<\/code> imports from the host process, and the N-API P\/Invoke declarations work without any additional configuration:<\/p>\n
private static partial class NativeMethods\r\n{\r\n    [LibraryImport(\"node\", EntryPoint = \"napi_create_string_utf8\")]\r\n    internal static partial Status CreateStringUtf8(\r\n        nint env, ReadOnlySpan<byte> str, nuint length, out nint result);\r\n\r\n    [LibraryImport(\"node\", EntryPoint = \"napi_create_function\")]\r\n    internal static unsafe partial Status CreateFunction(\r\n        nint env, ReadOnlySpan<byte> utf8name, nuint length,\r\n        delegate* unmanaged[Cdecl]<nint, nint, nint> cb,\r\n        nint data, out nint result);\r\n\r\n    [LibraryImport(\"node\", EntryPoint = \"napi_get_cb_info\")]\r\n    internal static unsafe partial Status GetCallbackInfo(\r\n        nint env, nint cbinfo, ref nuint argc,\r\n        Span<nint> argv, nint* thisArg, nint* data);\r\n\r\n    \/\/ ... other N-API functions as needed\r\n}<\/code><\/pre>\n
For each registered function we must register a native function as a named property on the exports object:<\/p>\n
private static unsafe void RegisterFunction(\r\n    nint env, nint exports, ReadOnlySpan<byte> name,\r\n    delegate* unmanaged[Cdecl]<nint, nint, nint> callback)\r\n{\r\n    NativeMethods.CreateFunction(env, name, (nuint)name.Length, callback, 0, out nint fn);\r\n    NativeMethods.SetNamedProperty(env, exports, name, fn);\r\n}<\/code><\/pre>\n
The source-generated [LibraryImport]<\/code> handles the marshalling. ReadOnlySpan<byte><\/code> maps cleanly to const char*<\/code>, function pointers are passed through directly, and the generated code is trimming-compatible out of the box.<\/p>\n
Marshalling strings<\/h2>\n
Most of the interop work comes down to moving strings between JavaScript and .NET. N-API uses UTF-8, so the conversion is straightforward, though it does require a buffer. Here\u2019s a helper that reads a string argument passed from JavaScript:<\/p>\n
private static unsafe string? GetStringArg(nint env, nint cbinfo, int index)\r\n{\r\n    nuint argc = (nuint)(index + 1);\r\n    Span<nint> argv = stackalloc nint[index + 1];\r\n    NativeMethods.GetCallbackInfo(env, cbinfo, ref argc, argv, null, null);\r\n\r\n    if ((int)argc <= index)\r\n        return null;\r\n\r\n    \/\/ Ask N-API for the UTF-8 byte length\r\n    NativeMethods.GetValueStringUtf8(env, argv[index], null, 0, out nuint len);\r\n\r\n    \/\/ Allocate a buffer\r\n    int bufLen = (int)len + 1;\r\n    byte[]? rented = null;\r\n    Span<byte> buf = bufLen <= 512\r\n        ? stackalloc byte[bufLen]\r\n        : (rented = ArrayPool<byte>.Shared.Rent(bufLen));\r\n\r\n    try\r\n    {\r\n        fixed (byte* pBuf = buf)\r\n            NativeMethods.GetValueStringUtf8(env, argv[index], pBuf, len + 1, out _);\r\n\r\n        return Encoding.UTF8.GetString(buf[..(int)len]);\r\n    }\r\n    finally\r\n    {\r\n        if (rented is not null)\r\n            ArrayPool<byte>.Shared.Return(rented);\r\n    }\r\n}<\/code><\/pre>\n
This code asks N-API for the byte length, allocates a buffer (on the stack for small strings, from the pool for larger ones), reads the bytes, then decodes to a .NET string<\/code>.<\/p>\n
Returning a string to JavaScript is the same process in reverse. We encode a .NET string into a UTF-8 buffer and pass it to napi_create_string_utf8<\/code>:<\/p>\n
private static nint CreateString(nint env, string value)\r\n{\r\n    int byteCount = Encoding.UTF8.GetByteCount(value);\r\n\r\n    byte[]? rented = null;\r\n    Span<byte> buf = byteCount <= 512\r\n        ? stackalloc byte[byteCount]\r\n        : (rented = ArrayPool<byte>.Shared.Rent(byteCount));\r\n\r\n    try\r\n    {\r\n        Encoding.UTF8.GetBytes(value, buf);\r\n        NativeMethods.CreateStringUtf8(\r\n            env, buf[..byteCount], (nuint)byteCount, out nint result);\r\n        return result;\r\n    }\r\n    finally\r\n    {\r\n        if (rented is not null)\r\n            ArrayPool<byte>.Shared.Return(rented);\r\n    }\r\n}<\/code><\/pre>\n
Both directions use Span<T><\/code>, stackalloc<\/code>, and ArrayPool<\/code> to avoid heap allocations for typical string sizes. Once you have these helpers in place, you can write exported functions without thinking much about marshalling values.<\/p>\n
Implementing an exported function<\/h2>\n
With the N-API plumbing in place, implementing an actual exported function is straightforward. Here\u2019s one that reads a value from the Windows Registry and returns it to JavaScript as a string:<\/p>\n
[UnmanagedCallersOnly(CallConvs = [typeof(CallConvCdecl)])]\r\nprivate static nint ReadStringValue(nint env, nint info)\r\n{\r\n    try\r\n    {\r\n        var keyPath = GetStringArg(env, info, 0);\r\n        var valueName = GetStringArg(env, info, 1);\r\n\r\n        if (keyPath is null || valueName is null)\r\n        {\r\n            ThrowError(env, \"Expected two string arguments: keyPath, valueName\");\r\n            return 0;\r\n        }\r\n\r\n        using var key = Registry.CurrentUser.OpenSubKey(\r\n            keyPath,\r\n            writable: false);\r\n\r\n        return key?.GetValue(valueName) is string value\r\n            ? CreateString(env, value)\r\n            : GetUndefined(env);\r\n    }\r\n    catch (Exception ex)\r\n    {\r\n        ThrowError(env, $\"Registry read failed: {ex.Message}\");\r\n        return 0;\r\n    }\r\n}<\/code><\/pre>\n
The structure is the same for every exported function. Read any arguments to the function first. Here we read string arguments with GetStringArg<\/code>. Then, do the work using normal .NET APIs, and finally return a result via CreateString<\/code> or similar. One thing to be careful about is exception handling \u2013 an unhandled exception in an [UnmanagedCallersOnly]<\/code> method will crash the host process. We catch exceptions and forward them to JavaScript via ThrowError<\/code>, which causes a standard JavaScript Error<\/code> to be thrown on the calling side.<\/p>\n
This example also shows why native addons are useful in the first place. Node.js doesn\u2019t have built-in access to the Windows Registry, so a native addon lets us use Microsoft.Win32.Registry<\/code> from .NET and expose the result to JavaScript with minimal ceremony.<\/p>\n
Calling our function from TypeScript<\/h2>\n
First, we must produce a platform-specific shared library. Running dotnet publish<\/code> produces a native library appropriate for your operating system (for example, RegistryAddon.dll<\/code> on Windows, libRegistryAddon.so<\/code> on Linux, or libRegistryAddon.dylib<\/code> on macOS). By convention, Node.js treats paths ending with .node<\/code> as native addons, so we rename this output file to MyNativeAddon.node<\/code>.<\/p>\n
We declare a TypeScript interface for our module, through which we expose type-safe access to our module\u2019s functions:<\/p>\n
interface RegistryAddon {\r\n    readStringValue(keyPath: string, valueName: string): string | undefined;\r\n\r\n    \/\/ Declare additional functions...\r\n}<\/code><\/pre>\n
From there, loading it in TypeScript is a standard require()<\/code> call:<\/p>\n
\/\/ Load our native module\r\nconst registry = require('.\/native\/win32-x64\/RegistryAddon.node') as RegistryAddon\r\n\r\n\/\/ Call our native function\r\nconst sdkPath = registry.readStringValue(\r\n    'SOFTWARE\\dotnet\\Setup\\InstalledVersions\\x64\\sdk', 'InstallLocation')<\/code><\/pre>\n
And with that, we\u2019re done! We can call from TypeScript into native code that was written in C#. While this particular registry addon is Windows-only, the same Native AOT and N-API approach works equally well on Windows, Linux, and macOS.<\/p>\n
What about existing libraries?<\/h2>\n
There is an existing project, node-api-dotnet<\/a>, that provides a higher-level framework for .NET\/JavaScript interop. It handles a lot of the boilerplate and supports richer scenarios. For our use case, we only needed a handful of functions, and the thin N-API wrapper gave us full control over the interop layer without bringing in additional dependencies. If you need to expose entire .NET classes or handle callbacks from JavaScript into .NET, a library like that is worth considering.<\/p>\n
What we gained<\/h2>\n
The immediate, practical benefit was simplifying our contributor experience. Anyone who wants to develop in our repo no longer needs a specific Python version. yarn install<\/code> works with just Node.js, C++ tooling and the .NET SDK, which are tools we already require for development. Our CI pipelines are simpler as well.<\/p>\n
Performance has been comparable to the C++ implementation. Native AOT produces optimized native code, and for the kind of work these functions do \u2013 string marshalling, registry access \u2013 there\u2019s no meaningful difference in practice. The .NET runtime does bring a garbage collector and a slightly larger memory footprint, but in a long-running VS Code extension process this is negligible.<\/p>\n
Looking ahead, this opens up some interesting possibilities. We currently run substantial .NET workloads in a separate process, communicating over a pipe. With Native AOT producing shared libraries that load directly into the Node.js process, we could potentially host some of that logic in-process, avoiding the serialization and process-management overhead. That\u2019s a longer-term exploration, but the foundation is now in place.<\/p>\n
A footnote<\/h2>\n
When the idea of using Native AOT first arose, no one on the team had direct experience of integrating native code with Node.js. Even though we have experience with Native AOT, the prospect of learning N-API\u2019s C calling conventions and wiring up the interop might have seemed daunting enough to put the whole idea on the back burner. GitHub Copilot allowed us to get a working proof-of-concept running very quickly, at which point the idea seemed promising enough to pursue. It\u2019s been a fantastic tool for exploring ideas that we wouldn\u2019t previously have had the time for. It\u2019s improving our products, and the team\u2019s quality of life.<\/p>\n
Summary<\/h2>\n
Native AOT increases the number of places you can run your .NET code. In this case, it allowed us to consolidate our tooling around fewer technologies and streamline our developer experience, particularly for onboarding new developers to the codebase.<\/p>\n
If you\u2019re running in Node.js, or in any other environment that can load native code, consider using Native AOT to produce that code. It allows you to write your native code in a language with memory safety, a rich standard library, and modern tooling. And if you\u2019re not very familiar with native coding, you might be surprised to learn just how simple it can be to wire this all up (especially if you have a Copilot to help).<\/p>\n
The post Writing Node.js addons with .NET Native AOT<\/a> appeared first on .NET Blog<\/a>.<\/p>","protected":false},"excerpt":{"rendered":"
C# Dev Kit is a VS Code extension. Like all VS Code extensions, its front end is TypeScript running in […]<\/p>\n","protected":false},"author":1,"featured_media":94,"comment_status":"","ping_status":"","sticky":false,"template":"","format":"standard","meta":{"site-sidebar-layout":"default","site-content-layout":"","ast-site-content-layout":"","site-content-style":"default","site-sidebar-style":"default","ast-global-header-display":"","ast-banner-title-visibility":"","ast-main-header-display":"","ast-hfb-above-header-display":"","ast-hfb-below-header-display":"","ast-hfb-mobile-header-display":"","site-post-title":"","ast-breadcrumbs-content":"","ast-featured-img":"","footer-sml-layout":"","theme-transparent-header-meta":"","adv-header-id-meta":"","stick-header-meta":"","header-above-stick-meta":"","header-main-stick-meta":"","header-below-stick-meta":"","astra-migrate-meta-layouts":"default","ast-page-background-enabled":"default","ast-page-background-meta":{"desktop":{"background-color":"var(--ast-global-color-4)","background-image":"","background-repeat":"repeat","background-position":"center center","background-size":"auto","background-attachment":"scroll","background-type":"","background-media":"","overlay-type":"","overlay-color":"","overlay-opacity":"","overlay-gradient":""},"tablet":{"background-color":"","background-image":"","background-repeat":"repeat","background-position":"center center","background-size":"auto","background-attachment":"scroll","background-type":"","background-media":"","overlay-type":"","overlay-color":"","overlay-opacity":"","overlay-gradient":""},"mobile":{"background-color":"","background-image":"","background-repeat":"repeat","background-position":"center center","background-size":"auto","background-attachment":"scroll","background-type":"","background-media":"","overlay-type":"","overlay-color":"","overlay-opacity":"","overlay-gradient":""}},"ast-content-background-meta":{"desktop":{"background-color":"var(--ast-global-color-5)","background-image":"","background-repeat":"repeat","background-position":"center center","background-size":"auto","background-attachment":"scroll","background-type":"","background-media":"","overlay-type":"","overlay-color":"","overlay-opacity":"","overlay-gradient":""},"tablet":{"background-color":"var(--ast-global-color-5)","background-image":"","background-repeat":"repeat","background-position":"center center","background-size":"auto","background-attachment":"scroll","background-type":"","background-media":"","overlay-type":"","overlay-color":"","overlay-opacity":"","overlay-gradient":""},"mobile":{"background-color":"var(--ast-global-color-5)","background-image":"","background-repeat":"repeat","background-position":"center center","background-size":"auto","background-attachment":"scroll","background-type":"","background-media":"","overlay-type":"","overlay-color":"","overlay-opacity":"","overlay-gradient":""}},"footnotes":""},"categories":[7],"tags":[],"class_list":["post-3883","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-dotnet"],"_links":{"self":[{"href":"https:\/\/rssfeedtelegrambot.bnaya.co.il\/index.php\/wp-json\/wp\/v2\/posts\/3883","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/rssfeedtelegrambot.bnaya.co.il\/index.php\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/rssfeedtelegrambot.bnaya.co.il\/index.php\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/rssfeedtelegrambot.bnaya.co.il\/index.php\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/rssfeedtelegrambot.bnaya.co.il\/index.php\/wp-json\/wp\/v2\/comments?post=3883"}],"version-history":[{"count":0,"href":"https:\/\/rssfeedtelegrambot.bnaya.co.il\/index.php\/wp-json\/wp\/v2\/posts\/3883\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/rssfeedtelegrambot.bnaya.co.il\/index.php\/wp-json\/wp\/v2\/media\/94"}],"wp:attachment":[{"href":"https:\/\/rssfeedtelegrambot.bnaya.co.il\/index.php\/wp-json\/wp\/v2\/media?parent=3883"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/rssfeedtelegrambot.bnaya.co.il\/index.php\/wp-json\/wp\/v2\/categories?post=3883"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/rssfeedtelegrambot.bnaya.co.il\/index.php\/wp-json\/wp\/v2\/tags?post=3883"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}