Calling assembly from .NET, Python and C
An AsmSdk shared library is an ordinary Windows DLL, Linux .so or macOS .dylib that follows
its platform's C calling convention, so any language with a C foreign-function interface can
call it. This page covers the three callers the AsmFoundation uses, plus testing.
.NET in the same solution
<!-- App/App.csproj -->
<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<OutputType>Exe</OutputType>
<TargetFramework>net10.0</TargetFramework>
<AllowUnsafeBlocks>true</AllowUnsafeBlocks> <!-- needed by [LibraryImport] source generation -->
</PropertyGroup>
<ItemGroup>
<ProjectReference Include="../Hello/Hello.asmproj" />
</ItemGroup>
</Project>
using System.Runtime.InteropServices;
internal static partial class Native
{
/// <summary>int hello_add(int a, int b), exported by hello.dll, libhello.so or libhello.dylib.</summary>
[LibraryImport("hello", EntryPoint = "hello_add")]
internal static partial int HelloAdd(int a, int b);
}
The .NET project needs nothing else. Every .asmproj carries an implicit PackageReference to
AsmFoundation.Sdk, and the package's buildTransitive targets reach the projects that
reference it. They treat the asm project like a NuGet package with a runtimes/ folder, and
let .NET's own RID rules choose the library.
A portable build (no
RuntimeIdentifier, the default fordotnet build) builds every RID the asm project lists. Each library goes toruntimes/<rid>/native/in the output, andApp.deps.jsonlists them. The .NET host then loads the one for the machine the app runs on, as it does for a package's native libraries. The same fordotnet publish.A RID-specific build (
dotnet build -r linux-arm64, or aRuntimeIdentifierin the.csproj) builds the one RID that serves it best, by the .NET SDK's RID graph, and copies that library flat, besideApp.dll. That is the RID itself when the asm project lists it. Otherwise it is the nearest one the RID falls back to: an asm project that listslinux-arm64serveslinux-musl-arm64, as a package'sruntimes/linux-arm64/would. When none fits, the build stops with ASM0040, which lists what the asm project builds and what the app can use.RuntimeIdentifierson the reference narrows what a portable build carries:<ProjectReference Include="../Hello/Hello.asmproj" RuntimeIdentifiers="linux-x64;win-x64" />A RID the asm project does not list is ASM0012, as with
-r. An asm project that lists no RIDs of its own builds exactly these. A portable build that names none for such a project stops with ASM0010. A RID-specific build needs no list: it builds its own RID.Only shared libraries are copied. A referenced static library, program or object-file project is something an app cannot load. It is skipped with a message, and stays for the asm projects that link it. This includes the static libraries that the .NET SDK adds as transitive references of an asm reference.
The app's own publish options stay with the app.
SelfContained,PublishAot,PublishTrimmed,PublishSingleFileandPublishReadyToRunare not passed on: the asm project builds the same native code either way. That holds on the command line too (dotnet publish -p:PublishAot=true), where NuGet's restore hands them to every project: the asm projects ignore them.Through a class library. An app that reaches the asm project through a C# wrapper (app →
Acme.Crc.Net.csproj→Crc.asmproj) gets the same result. The .NET SDK adds the asm project to the app's references transitively, and the consumer targets build it for the app. The wrapper itself is RID-agnostic, so it is built portable and keeps every RID'sruntimes/copy in its own output. A RID-specific app leaves those out of its output and publish folders, as NuGet leaves out other RIDs' assets.-o:dotnet build App.csproj -o outbuilds the asm projects in their ownbin/folders, andout/gets the copies the app needs. Footgun:-osends every project's output toout/, so a wrapper library in between puts its portableruntimes/copies there as well.dotnet publish -ohas no such effect.No assembly reference is added. The SDK's
GetTargetPathWithTargetPlatformMonikerreturns nothing.Library names:
[LibraryImport("hello")]and[DllImport("hello")]probehello.dllon Windows,libhello.soon Linux andlibhello.dylibon macOS. Use the bare name, and one attribute serves every platform.Platforms: the app runs wherever the asm project has a build. On another platform, the first call throws
DllNotFoundException.A single solution builds both with
dotnet build App.slnx, as long as the.asmprojentry has its type GUID.
Where the binaries go: BinariesCopyPath
Note
Not released yet: on the main branch, a ProjectReference or PackageReference to an
asm program delivers it the same way, with the libraries it links, for a .NET app that
starts it as a helper process. BinariesCopyPath also places the libraries that an asm
program links. See Programs.
By default the asm libraries go where NuGet puts a package's native files: runtimes/<rid>/native/
in a portable build, beside the app in a RID-specific one. BinariesCopyPath puts them
elsewhere, for build and publish alike:
<!-- One reference -->
<ProjectReference Include="../Hello/Hello.asmproj" BinariesCopyPath="native/{rid}" />
<!-- Every asm reference of the project (and its asm packages) -->
<PropertyGroup>
<BinariesCopyPath>RidFolders</BinariesCopyPath>
</PropertyGroup>
| Value | A portable build (every RID) | A build for one RID (-r win-x64) |
|---|---|---|
Auto (the default) |
runtimes/<rid>/native/hello.dll |
hello.dll, beside the app |
Runtimes |
runtimes/<rid>/native/hello.dll |
runtimes/win-x64/native/hello.dll |
AppFolder |
hello.dll, libhello.so, libhello.dylib, beside the app (one RID per OS; see ASM0044 below) |
hello.dll |
RidFolders |
<rid>/hello.dll |
win-x64/hello.dll |
any folder, {rid} optional |
native/{rid} → native/<rid>/hello.dll |
native/{rid} → native/win-x64/hello.dll; native → native/hello.dll |
{rid}is the RID each file was built for. In a build for one RID it is the RID that serves it: alinux-musl-arm64app that gets thelinux-arm64build has it inlinux-arm64/.- A folder without
{rid}holds a file name once. In a portable build,win-x64andwin-arm64both givehello.dll, andlinux-x64,linux-arm64andlinux-musl-x64all givelibhello.so, so such a build stops with ASM0044 before anything is copied. Add{rid}, or narrow the reference'sRuntimeIdentifiersto one RID per OS. The three OSes never collide: their file names differ. - Values: a preset (
Auto,Runtimes,AppFolder,RidFolders, in any letter case), or a folder inside the output: slashes either way, no absolute path, no.., none of< > : " | ? *, and no placeholder but{rid}. Anything else stops with ASM0043, which says where the value was written. - Which value applies, per asm library: the reference's own attribute, then the project's
property, then the choice of a .NET library the asm library comes through, then
Auto. SoBinariesCopyPathon the reference inside a wrapper library, often the only place the asm project is referenced, shapes the app's output as well; the app's own property or reference overrides it. When two libraries in between disagree, ASM0046 warns and the first wins. - Footgun:
RidFoldersin a portable build writesbin/Debug/net10.0/win-x64/, the same folderdotnet build -r win-x64uses for the whole app. Prefernative/{rid}when you also build for one RID.
How the app finds them
No code is needed in the app. Measured with .NET 10 on Windows and Linux:
deps.json: the app'sdeps.jsonlists every asm library withlocalPath, the path it was copied to:runtimeTargetsin a portable app, plainnativeassets in an app for one RID. The .NET host loads from any folder named there, framework-dependent and self-contained alike. A self-contained app ignoresruntimeTargets, and withoutlocalPaththe host keeps only a file name and looks beside the app.- The generated loader: a C# project for .NET 5 or later that puts an asm library
anywhere but the app folder gets
obj/.../AsmNativeLibraryLoader.g.cs. It is a module initializer that adds anAssemblyLoadContext.ResolvingUnmanagedDllhandler, for what reads nodeps.json: NativeAOT, and an app that gets the files through a library without the entries (PrivateAssets="all"below). It runs only after .NET's own probing failed, and after any resolver of yours (NativeLibrary.SetDllImportResolverruns first). It looks for<name>.dll,lib<name>.soorlib<name>.dylibunder the app folder, for this machine's RID, and on musl for thelinux-<arch>build too. Turn it off with<AsmGenerateNativeLibraryLoader>false</AsmGenerateNativeLibraryLoader>; a VB or F# project, or one for an older framework, never gets it.
| Publish kind | How the library in native/ was found |
|---|---|
portable, dotnet build / dotnet run |
deps.json (runtimeTargets + localPath) |
-r <rid>, framework-dependent |
deps.json (native + localPath) |
-r <rid> --self-contained |
deps.json (native + localPath) |
-p:PublishSingleFile=true |
the library stays in its folder beside the bundle |
-p:PublishAot=true |
the generated loader |
PrivateAssets="all": the binaries inside a .NET package
dotnet pack turns a ProjectReference into a package dependency, an asm reference too: a
wrapper library Acme.Calc that references Calc.asmproj depends on the package calc, and
both must be published. With NuGet's own PrivateAssets="all" ("this reference does not flow
to my users"), the wrapper's package carries every RID's library itself, and depends on
nothing:
<ProjectReference Include="../Calc.Native/Calc.Native.asmproj" PrivateAssets="all" />
Acme.Calc.1.0.0.nupkg
lib/net10.0/Acme.Calc.dll
runtimes/win-x64/native/calc.dll
runtimes/linux-x64/native/libcalc.so
runtimes/osx-arm64/native/libcalc.dylib (one per RID of the reference)
buildTransitive/net10.0/Acme.Calc.targets BinariesCopyPath for the package's users
Use it for a library whose asm code is an implementation detail. Keep the dependency when several .NET packages share one asm library: NuGet then ships it once.
Within the solution, an app that references the wrapper by project doesn't get the asm reference (it does not flow). Unless the app has asm references of its own, it doesn't get AsmSdk's targets either. So the app:
- copies what the wrapper hands on: the files where the wrapper's
BinariesCopyPathput them, every RID's (nothing in the app keeps only one); - gets no
deps.jsonentries; - loads the library through the loader generated into the wrapper.
In a single-file publish the files stay beside the bundle. To place them elsewhere, set
BinariesCopyPathon the wrapper's reference.- copies what the wrapper hands on: the files where the wrapper's
Publishing a .NET app
Every publish mode of .NET carries the asm library, the way it carries a NuGet package's native library (measured with the .NET 10 and 11 SDKs, through a project reference and through a package):
dotnet publish … |
Where the asm library goes |
|---|---|
| (portable) | runtimes/<rid>/native/, listed in deps.json |
-r <rid> |
beside the app |
-r <rid> -p:PublishSingleFile=true |
beside the single file |
the same with -p:IncludeNativeLibrariesForSelfExtract=true |
inside the single file; the .NET host extracts it at start, so the file runs alone |
-r <rid> -p:PublishAot=true |
beside the native program, loaded at run time (NativeAOT does not link a shared library in). NativeAOT needs its platform linker, as always: Visual Studio's C++ tools on Windows, clang on Linux, Xcode on macOS |
-r <rid> -p:PublishTrimmed=true |
beside the app; trimming leaves native files alone |
-r linux-x64 -t:PublishContainer |
in the image, beside the app |
The single-file rows rely on the consumer targets, which mark the asm libraries
AssetType=native: the metadata the .NET SDK decides by. "Beside the app" is the default:
with BinariesCopyPath each row puts the library in that folder instead (see above).
A static library inside a NativeAOT program. NativeAOT can link a static library into the
program and call it directly: no library file ships, and nothing is looked up at run time. The
consumer targets leave static libraries alone, so name the library yourself, for the RID being
published, and build it for that RID first (dotnet build Crc.asmproj -c Release -r win-x64):
<ItemGroup Condition="'$(RuntimeIdentifier)' != '' and '$(PublishAot)' == 'true'">
<DirectPInvoke Include="crc" /> <!-- the name in [LibraryImport("crc")] -->
<NativeLibrary Condition="$(RuntimeIdentifier.StartsWith('win-'))"
Include="../Crc/bin/$(Configuration)/freestanding/$(RuntimeIdentifier)/crc.lib" />
<NativeLibrary Condition="!$(RuntimeIdentifier.StartsWith('win-'))"
Include="../Crc/bin/$(Configuration)/freestanding/$(RuntimeIdentifier)/libcrc.a" />
</ItemGroup>
- Declare its entry points with
HIDDEN_FUNCTION. AFUNCTIONin a static library takes its export along into whatever links it, so a Windows program would export it.HIDDEN_FUNCTIONlinks the same and exports nothing (measured on Windows: the program's export table then holds only .NET's own entry; a Linux program exports neither). - A JIT run cannot use it.
dotnet runhas no static library to load and throwsDllNotFoundException; only the published program has the code linked in.
.NET through a package
What a
.csprojgets: a.csprojwith<PackageReference Include="Acme.Crc" />gets the package'sruntimes/<rid>/native/libraries (crc.dll,libcrc.so,libcrc.dylib). NuGet handles them on its own: a portable app gets every RID underruntimes/, and the host picks one. An app built for one RID gets the best match from NuGet's RID graph, copied beside it.What it ignores: the package's
native/folder (static and import libraries) and the asm items in itsbuild/props. These apply only to asm projects.BinariesCopyPath on the PackageReference (or the project's property) moves the package's libraries like a project reference's:
<PackageReference Include="Acme.Crc" Version="1.2.0" BinariesCopyPath="native/{rid}" />An asm package does not depend on AsmFoundation.Sdk, so the work is done by targets inside the package (
buildTransitive/<tfm>/<id>.targets, plain MSBuild, named for that package only): they move NuGet's items, and the .NET SDK itself writes the new place intodeps.jsonaslocalPath. A C# consumer gets a generated loader for NativeAOT, as above. Without the attribute or the property, nothing changes.Wrapper packages: to ship a managed API, make a separate
.csprojpackage (for exampleAcme.Crc.Net) that references the native package and contains the[LibraryImport]declarations. The pair works likeSkiaSharpwith itsSkiaSharp.NativeAssets.*packages. Or put the binaries inside the wrapper's package withPrivateAssets="all"(above).
Example: Shipping to .NET through NuGet packs an assembly library for seven RIDs and its C# wrapper as two packages, and uses them from a program by version.
Marshalling rules
Blittable types cross for free:
int↔int32_t,long↔int64_t,nint↔intptr_t;double↔double;- pointers, and
structs made only of these, with[StructLayout(LayoutKind.Sequential)].
.NET calls with the platform's C convention by default: Microsoft x64 on Windows, System V on Linux and macOS, AAPCS64 on ARM64. Those are the conventions
asmsdk.incandasmsdk-gnu.incfollow, so noCallingConventionis needed.Spans: pass
ReadOnlySpan<byte>as a pointer plus a length. With[LibraryImport], declare the parameter asbyte*and call it insidefixed, or useReadOnlySpan<byte>directly (the source generator pins it).Strings: use
StringMarshalling = StringMarshalling.Utf8forconst char*arguments. The generator allocates a NUL-terminated UTF-8 copy for each call. On hot paths, pass bytes instead.bool: marshal as[MarshalAs(UnmanagedType.U1)](1 byte), or usebyte/intexplicitly. Read only the low byte of a 1-byte bool:ARG1bin x64 code (clon Windows,dilelsewhere),uxtb w0, w0on ARM64.Very short leaf functions:
[SuppressGCTransition]removes the GC mode switch, which costs a few nanoseconds per call and dominates a call that only adds two numbers. It is only for functions that:- run briefly;
- never block;
- never call back into .NET;
- and never take locks.
Every asm leaf that only computes qualifies.
Callbacks: an
[UnmanagedCallersOnly]static method's address (&Method) can be passed to asm as a function pointer. The asm calls it with the platform's C convention. In x64 code, the arguments go inARG1.. and, on Windows,SHADOW_SPACEis reserved.Errors: return status codes, or
-errnostyle values. An exception cannot cross the boundary.
Testing asm code from .NET
A test project is the most productive harness for asm functions: property-based checks, comparison against a C# reference implementation, and fuzzing.
<!-- Hello.Tests/Hello.Tests.csproj -->
<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<TargetFramework>net10.0</TargetFramework>
<AllowUnsafeBlocks>true</AllowUnsafeBlocks>
</PropertyGroup>
<ItemGroup>
<PackageReference Include="xunit.v3" Version="..." />
<PackageReference Include="Microsoft.NET.Test.Sdk" Version="..." />
<ProjectReference Include="../Hello/Hello.asmproj" />
</ItemGroup>
</Project>
- Every platform tests its own build: the test project's portable output carries every RID
of the asm project, as an app's does. The same test run on a Windows, Linux or macOS CI
machine calls that machine's library. A machine whose platform the asm project does not
build gets
DllNotFoundException, so skip the tests there. - Compare against a reference: for every function, write a C# reference implementation and compare outputs on random inputs, including the edge cases: zero length, unaligned pointers, page boundaries, maximum values.
- Memory boundaries: to test that code never reads past the end of a buffer, allocate
the buffer at the end of a page followed by an inaccessible page:
mmapplusmprotecton Linux and macOS,VirtualAllocplusVirtualProtecton Windows, through P/Invoke. A read past the end then crashes the test instead of passing silently.
Example: Testing and measuring from C# tests each code path of an assembly library against a C# reference with xunit, and times it with BenchmarkDotNet.
Python
import ctypes
lib = ctypes.CDLL("./bin/Release/freestanding/linux-x64/libhello.so")
# Windows: ctypes.CDLL(r".\bin\Release\freestanding\win-x64\hello.dll")
lib.hello_add.argtypes = [ctypes.c_int, ctypes.c_int]
lib.hello_add.restype = ctypes.c_int
assert lib.hello_add(40, 2) == 42
- Always set
argtypesandrestype: the defaultrestypeisint, which truncates a 64-bit return. - Buffers: pass arrays as
(ctypes.c_int32 * n)(...),ctypes.create_string_buffer, ornumpy_array.ctypes.data_as(ctypes.POINTER(ctypes.c_int32)). - The GIL:
ctypes.CDLLreleases the GIL around foreign calls, whilectypes.PyDLLkeeps it. For a function that runs only nanoseconds, thectypescall overhead dominates, so batch the work into one call per array. - Distributing: ship one wheel per platform, with the library loaded relative to the
module file. The platform tags:
win_amd64andwin_arm64;manylinux_2_34_x86_64andmanylinux_2_34_aarch64forlibcbuilds (glibc 2.34+), ormanylinux2014_x86_64andmanylinux2014_aarch64forfreestandingones (no glibc requirement);musllinux_1_2_x86_64forlinux-musl-x64;macosx_11_0_x86_64andmacosx_11_0_arm64.
cffi:cffiin ABI mode reads a C header, so theinclude/<name>.hyou ship for C users serves Python too.
Both templates in Writing NASM for AsmSdk were called this way from Python
3.12, and returned the expected values: on Windows 11, on Debian (python:3.12-slim, glibc)
and on Alpine (python:3.12-alpine, musl).
C and other languages
Write a header next to the .inc file (include/hello.h):
#ifndef HELLO_H
#define HELLO_H
#include <stdint.h>
#ifdef __cplusplus
extern "C" {
#endif
int32_t hello_add(int32_t a, int32_t b);
#ifdef __cplusplus
}
#endif
#endif
Linking from C:
- Windows: link the DLL's import library, and put the DLL beside the program:
cl main.c /Iinclude bin\Release\freestanding\win-x64\hello.dll.lib(checked with MSVC 2022). - Linux:
gcc main.c -Iinclude -Lbin/Release/freestanding/linux-x64 -lhello. Run it withLD_LIBRARY_PATHset, or link with-Wl,-rpath,'$ORIGIN'. - macOS:
clang main.c -Iinclude -Lbin/Release/freestanding/osx-arm64 -lhello -Wl,-rpath,@executable_path. The library's install name is@rpath/libhello.dylib, so the program finds it through its own run paths. - A static library links in directly:
libhello.aon Linux and macOS,hello.libon Windows. For GNUldon Linux, its objects must carry.note.GNU-stack, or recent versions warn that the stack is executable.
Rust, Go and Zig bind the same functions through their C FFI (extern "C", cgo,
@cImport).