Написание нативных аддонов Node.js на C# с .NET Native AOT

Emiliano Montesdeoca — Tue, 21 Apr 2026 00:00:00 +0000

Эта статья переведена автоматически. Оригинальную версию на английском можно найти здесь.

Вот сценарий, который мне нравится: команда, работающая над инструментами .NET, имела нативные аддоны Node.js, написанные на C++ и скомпилированные через node-gyp. Работало. Но для сборки пакета, который никто в команде не трогал напрямую, на каждой машине разработчика требовался Python — причём старая версия Python.

Поэтому они задали вполне разумный вопрос: SDK .NET уже установлен — зачем вообще писать C++?

Ответом стал Native AOT, и результат получился действительно элегантным.

Основная идея

Нативный аддон Node.js — это разделяемая библиотека (.dll на Windows, .so на Linux, .dylib на macOS), которую Node.js может загрузить во время выполнения. Интерфейс называется N-API — стабильный, ABI-совместимый C API. N-API не заботится о том, каким языком создана библиотека — только о том, что она экспортирует нужные символы.

.NET Native AOT может создать именно это. Он компилирует C#-код ahead-of-time в нативную разделяемую библиотеку с произвольными точками входа. В этом весь трюк.

Настройка проекта

Файл проекта минимален:

<Project Sdk="Microsoft.NET.Sdk">
 <PropertyGroup>
 <TargetFramework>net10.0</TargetFramework>
 <PublishAot>true</PublishAot>
 <AllowUnsafeBlocks>true</AllowUnsafeBlocks>
 </PropertyGroup>
</Project>

PublishAot указывает SDK создать разделяемую библиотеку при dotnet publish. AllowUnsafeBlocks нужен для N-API interop с указателями на функции и фиксированными буферами.

Экспорт точки входа

Node.js ожидает, что библиотека экспортирует napi_register_module_v1. В C# это делает [UnmanagedCallersOnly]:

public static unsafe partial class RegistryAddon
{
 [UnmanagedCallersOnly(
 EntryPoint = "napi_register_module_v1",
 CallConvs = [typeof(CallConvCdecl)])]
 public static nint Init(nint env, nint exports)
 {
 Initialize();
 RegisterFunction(env, exports, "readStringValue"u8, &ReadStringValue);
 return exports;
 }
}

Несколько моментов стоит отметить: nint — целое число нативного размера, управляемый эквивалент intptr_t. Суффикс u8 создаёт ReadOnlySpan<byte> с UTF-8 строковым литералом, передаваемым прямо в N-API без выделений памяти под кодировку. А [UnmanagedCallersOnly] экспортирует метод с точно тем именем точки входа, которое ищет Node.js.

Разрешение N-API через хост-процесс

Функции N-API экспортирует сам node.exe, а не отдельная библиотека. Поэтому вместо линковки против чего-либо, они разрешаются против запущенного процесса при старте:

private static void Initialize()
{
 NativeLibrary.SetDllImportResolver(
 System.Reflection.Assembly.GetExecutingAssembly(),
 ResolveDllImport);

 static nint ResolveDllImport(
 string libraryName, Assembly assembly, DllImportSearchPath? searchPath)
 {
 if (libraryName is not "node") return 0;
 return NativeLibrary.GetMainProgramHandle();
 }
}

После этого объявления P/Invoke с [LibraryImport] и сгенерированным маршалингом работают корректно.

Реальная экспортируемая функция

Вот ридер реестра, который они написали:

[UnmanagedCallersOnly(CallConvs = [typeof(CallConvCdecl)])]
private static nint ReadStringValue(nint env, nint info)
{
 try
 {
 var keyPath = GetStringArg(env, info, 0);
 var valueName = GetStringArg(env, info, 1);

 if (keyPath is null || valueName is null)
 {
 ThrowError(env, "Expected two string arguments: keyPath, valueName");
 return 0;
 }

 using var key = Registry.CurrentUser.OpenSubKey(keyPath, writable: false);

 return key?.GetValue(valueName) is string value
 ? CreateString(env, value)
 : GetUndefined(env);
 }
 catch (Exception ex)
 {
 ThrowError(env, $"Registry read failed: {ex.Message}");
 return 0;
 }
}

Важное замечание про try/catch: необработанное исключение в методе [UnmanagedCallersOnly] обрушит хост-процесс. Всегда перехватывайте и передавайте в JavaScript через ThrowError.

Вызов из TypeScript

const registry = require('./native/win32-x64/RegistryAddon.node') as RegistryAddon;
const sdkPath = registry.readStringValue(
 'SOFTWARE\\dotnet\\Setup\\InstalledVersions\\x64\\sdk', 'InstallLocation');

TypeScript → C#, без Python, без C++.

Что получили

Мгновенный выигрыш — опыт контрибьюторов: никакой конкретной версии Python, yarn install работает только с Node.js и .NET SDK. CI-пайплайны также упростились. Производительность сопоставима с реализацией на C++.

Итоги

Команда C# Dev Kit заменила сложность Python/C++ на чистый C#-код, который каждый в команде уже умеет писать и отлаживать. Полный разбор со всеми вспомогательными методами маршалинга строк найдёте в оригинальной статье в блоге .NET.

Interop | The .NET Blog