UA-.NETStandard/docs/NativeAoT.md

Native AOT

Native AOT (ahead-of-time) compilation publishes an application and the parts of the SDK that it uses as a single native executable. The executable starts quickly and runs without an installed .NET runtime, but it supports only code that the compiler can analyze at publish time. This guide first shows how to publish an application, then describes the test harness that verifies the stack under Native AOT.

Contents

• Publish an application
  • Enable Native AOT
  • Publish and verify the executable
  • Use AOT-compatible features
• Test harness overview
• Prerequisites
  • .NET SDK
  • Platform-Specific Native Toolchain
• Project Structure
  • Why TUnit Instead of NUnit?
  • Test Fixture Pattern
• How to Build and Run
  • 1. Publish the Native AOT Binary
  • 2. Run the Tests
  • Build + Run in a Single Step (Development)
• CI Integration
• Writing New AOT Tests
  • 1. Choose or Create a Test Class
  • 2. Use TUnit Attributes and Assertions
  • 3. Keep Code AOT-Compatible
  • 4. Handle Trimming Warnings
• Troubleshooting
  • 'vswhere.exe' is not recognized on Windows
  • Publish Fails with Linker Errors
  • TypeInitializationException or MissingMetadataException at Runtime
  • Tests Pass Under dotnet test but Fail Under AOT
  • Slow Publish Times
  • IL2104 or Other Trimming Warnings

Publish an application

Enable Native AOT

Install the native toolchain for your platform. Then set PublishAot in the application's project file:

<PropertyGroup>
  <OutputType>Exe</OutputType>
  <TargetFramework>net10.0</TargetFramework>
  <PublishAot>true</PublishAot>
</PropertyGroup>

The stack's Native AOT tests run on net10.0. dotnet build and dotnet run still use the JIT compiler; only dotnet publish compiles the native executable.

Publish and verify the executable

Publish for the runtime identifier of the target platform, such as win-x64, linux-x64, linux-arm64, or osx-arm64:

dotnet publish -c Release -r win-x64

The bin/Release/net10.0/<runtime-identifier>/publish folder then contains one native executable and its symbol file. If the folder instead contains the application's .dll and coreclr.dll, the publish did not use Native AOT. Check that PublishAot applies to the target framework you publish, delete the bin and obj folders, and publish again.

The client and server from Getting started publish this way without trim or AOT warnings. A published application is also a new instance for its certificate stores when PkiRoot depends on the working directory, as in Getting started. Run it from the folder that contains its pki folder, or trust its new certificate again.

Use AOT-compatible features

Fix every trim and AOT warning (IL2026, IL3050, and related codes) that the publish reports for your code. The following features are AOT-compatible:

• Source-generated models and node managers; see Node managers: NativeAOT publishing.
• Source-generated data types; see Source-generated data types.
• The default complex-type builder. The optional Reflection.Emit builder requires the JIT compiler; see Complex types: type builders.
• Hosting with dependency injection; see Dependency injection: Native AOT.
• PubSub; see PubSub: Native AOT.
• The crypto provider model; see Crypto providers.

In your own code, avoid unbounded reflection and runtime code generation; see Keep code AOT-compatible.

Clients and servers run in globalization-invariant mode, which the InvariantGlobalization property enables to make native executables smaller. In this mode a server still selects translations by locale id and falls back to another region of the same language. Arguments in translated texts, such as numbers and dates, use the invariant format for every locale.

Test harness overview

The Opc.Ua.Aot.Tests project verifies that the core OPC UA libraries work correctly when published as a Native AOT binary. The tests cover:

• Encoding, sessions, subscriptions, and monitored items.
• Discovery, security, events, and history.
• Diagnostics, batch operations, and the node cache.
• Complex types, GDS client operations, and client sample patterns.

All tests run inside a single ahead-of-time compiled executable.

The crypto provider model is AOT-compatible and covered by CryptoProviderAotTests; see CryptoProvider. The optional OPCFoundation.NetStandard.Opc.Ua.Security.Pkcs11 package is covered too, by Pkcs11AotTests: although Pkcs11Interop carries no trim or AOT annotations of its own, the ILCompiler analysis produces no warnings for the paths the package uses, so it is marked IsAotCompatible on net10.0. Resolving the token module is native interop, which trimming does not affect.

Prerequisites

.NET SDK

• .NET 10.0 SDK (or later LTS) is required.

Platform-Specific Native Toolchain

Native AOT compilation requires a C/C++ toolchain on the build machine.

Platform	Requirement
Windows	Visual Studio 2022+ with the Desktop development with C++ workload, or the equivalent Build Tools package.
Linux	clang and zlib1g-dev (Debian/Ubuntu) or the equivalent packages for your distribution.
macOS	Xcode Command Line Tools (xcode-select --install).

See the official Microsoft documentation for full details: https://learn.microsoft.com/en-us/dotnet/core/deploying/native-aot/?tabs=windows%2Cnet8plus

Project Structure

tests/Opc.Ua.Aot.Tests/
├── Opc.Ua.Aot.Tests.csproj   # Project file (PublishAot=true, net10.0)
├── AotServerFixture.cs        # Lightweight AOT-compatible server host
├── AotTestFixture.cs          # Shared fixture: starts server + client session
├── GdsTestFixture.cs          # GDS-specific test fixture
├── EncodingAotTests.cs        # Binary & JSON encoding round-trips
├── DataTypeAotTests.cs        # OPC UA data type verification
├── SessionAotTests.cs         # Session lifecycle & reconnect
├── SubscriptionAotTests.cs    # Subscription create / modify / delete
├── MonitoredItemAotTests.cs   # Monitored item operations
├── DiscoveryAotTests.cs       # Endpoint & server discovery
├── SecurityAotTests.cs        # Security policy negotiation
├── EventsAotTests.cs          # Event subscription & filtering
├── HistoryAotTests.cs         # Historical read operations
├── DiagnosticsAotTests.cs     # Server diagnostics
├── BatchOperationsAotTests.cs # Batch read / write / call
├── NodeCacheAotTests.cs       # Client-side node cache
├── ComplexTypeAotTests.cs     # Complex type loading & serialization
├── GdsClientAotTests.cs       # Global Discovery Server client
├── ClientSamplesAotTests.cs   # End-to-end client sample patterns
├── AotClientSamples.cs        # Helper methods for client samples
├── PubSubAotTests.cs          # Part 14 PubSub publisher / subscriber round-trips
├── WebApiAotFixture.cs        # Kestrel host for REST endpoint round-trips
├── WebApiAotTests.cs          # REST binding (Opc.Ua.Bindings.Https) smoke + Basic auth
└── StubWebApiServer.cs        # IWebApiServer stub backing WebApiAotFixture

Why TUnit Instead of NUnit?

The project uses the TUnit test framework instead of NUnit. TUnit generates test-discovery code at compile time, so this test binary can be published with Native AOT. The repository's NUnit test projects use runtime reflection for discovery instead and are not the Native AOT test path.

Test Fixture Pattern

AotTestFixture implements IAsyncInitializer and IAsyncDisposable from TUnit. It is shared across all test classes via the attribute:

[ClassDataSource<AotTestFixture>(Shared = SharedType.PerTestSession)]

On initialization the fixture:

1. Starts a ReferenceServer in-process using AotServerFixture<T>.
2. Creates a client ApplicationConfiguration programmatically.
3. Connects an ISession to the server over opc.tcp.

Every test class receives the fixture through its primary constructor and reuses the same server and session, keeping the test suite fast.

AotServerFixture<T> is a cut-down, AOT-compatible version of ServerFixture<T> from the NUnit test infrastructure. It avoids transitive references to BenchmarkDotNet, Moq, and other packages that are not AOT-friendly.

How to Build and Run

1. Publish the Native AOT Binary

dotnet publish tests/Opc.Ua.Aot.Tests/Opc.Ua.Aot.Tests.csproj --configuration Release

The publish step compiles the entire application (tests, server, and all referenced OPC UA libraries) into a single native executable. This can take several minutes depending on the machine.

2. Run the Tests

Windows (x64):

./tests/Opc.Ua.Aot.Tests/bin/Release/net10.0/win-x64/publish/Opc.Ua.Aot.Tests.exe

Linux (x64):

./tests/Opc.Ua.Aot.Tests/bin/Release/net10.0/linux-x64/publish/Opc.Ua.Aot.Tests

The executable discovers and runs all tests, producing TUnit console output and writing results to a TestResults directory.

Build + Run in a Single Step (Development)

For iterative development you can combine both commands:

# Windows
dotnet publish tests/Opc.Ua.Aot.Tests/Opc.Ua.Aot.Tests.csproj -c Release && ^
  tests\Opc.Ua.Aot.Tests\bin\Release\net10.0\win-x64\publish\Opc.Ua.Aot.Tests.exe

# Linux / macOS
dotnet publish tests/Opc.Ua.Aot.Tests/Opc.Ua.Aot.Tests.csproj -c Release && \
  ./tests/Opc.Ua.Aot.Tests/bin/Release/net10.0/linux-x64/publish/Opc.Ua.Aot.Tests

Note: dotnet test and dotnet run do not perform AOT compilation. You must use dotnet publish followed by direct execution of the resulting binary.

CI Integration

The GitHub Actions workflow .github/workflows/buildandtest.yml runs AOT jobs on Ubuntu and both Intel and ARM64 macOS; the weekly .github/workflows/nightly.yml run adds Windows. Each platform performs these steps:

1. Checkout the repository.
2. Setup .NET 10.0 SDK.
3. Publish the project with dotnet publish in Release configuration.
4. Execute the platform-specific binary directly.
5. Publish + execute the .Historian and .Mcp companions the same way, keeping results separate.
6. Upload any TestResults artifacts.

The job runs in a separate matrix from the main dotnet test build so that AOT failures are isolated and clearly visible.

Writing New AOT Tests

1. Choose or Create a Test Class

Place AOT tests in tests/Opc.Ua.Aot.Tests/. Each file should focus on a single area (encoding, sessions, etc.). Apply the shared fixture:

[ClassDataSource<AotTestFixture>(Shared = SharedType.PerTestSession)]
public class MyFeatureAotTests(AotTestFixture fixture)
{
    [Test]
    public async Task MyTestAsync()
    {
        // Use fixture.Session, fixture.ServerUrl, etc.
        await Assert.That(fixture.Session.Connected).IsTrue();
    }
}

2. Use TUnit Attributes and Assertions

• Mark tests with [Test] (not NUnit's [Test]—they are different types).
• Use await Assert.That(…) for assertions. TUnit assertions are async.
• Do not reference NUnit, xUnit, or MSTest assemblies.

3. Keep Code AOT-Compatible

• Avoid unbounded reflection. Do not use Type.GetType(), Activator.CreateInstance(), or similar APIs unless the types are statically reachable.
• Avoid dynamic code generation. Reflection.Emit, System.Linq.Expressions.Expression.Compile(), and similar APIs are not supported.
• Prefer concrete generic instantiations. The trimmer must see every generic type combination at compile time.
• Annotate when necessary. Use [DynamicallyAccessedMembers] to declare reflection requirements or [DynamicDependency] to preserve specific dependencies. [RequiresUnreferencedCode] declares trimming incompatibility and warns callers; it does not preserve metadata or make code trim-safe.

4. Handle Trimming Warnings

The project suppresses IL2104 (see the .csproj), which comes from third-party packages that are not yet trim-annotated. For warnings in your own code, fix the root cause rather than suppressing.

Troubleshooting

'vswhere.exe' is not recognized on Windows

The native link step locates the Visual C++ tools with vswhere.exe. If the publish fails with 'vswhere.exe' is not recognized as an internal or external command, add the Visual Studio Installer folder to PATH and publish again:

$env:PATH = "${env:ProgramFiles(x86)}\Microsoft Visual Studio\Installer;$env:PATH"
dotnet publish -c Release -r win-x64

Publish Fails with Linker Errors

Ensure the platform-specific C/C++ toolchain is installed (see Prerequisites). On Windows, verify the Desktop development with C++ workload is present in the Visual Studio Installer.

TypeInitializationException or MissingMetadataException at Runtime

The IL trimmer removed type metadata that is needed at runtime. Common fixes:

• Add [DynamicallyAccessedMembers(DynamicallyAccessedMemberTypes.All)] to parameters or fields that hold types accessed via reflection.
• Add an explicit rd.xml file or [DynamicDependency] attribute to preserve specific types.
• Ensure the type is statically referenced somewhere in the code path.

Tests Pass Under dotnet test but Fail Under AOT

dotnet test runs with JIT and full reflection. Some APIs silently work under JIT but are unsupported in AOT. Compare the stack trace from the AOT binary to identify which API is problematic, then refactor to a trim-safe alternative.

Slow Publish Times

Native AOT compilation is inherently slower than JIT builds because it performs whole-program optimization. On CI this is expected. For local development, consider running the NUnit tests with dotnet test for fast feedback, and reserve AOT publish for final validation.

IL2104 or Other Trimming Warnings

Warnings prefixed with IL come from the IL trimmer/linker. The project suppresses IL2104 for third-party packages. If you see new warnings from OPC UA code, investigate and fix the root cause. Suppress only as a last resort and document the reason in a code comment.