TinyUa.Client 1.0.0-preview1

TinyUa

<p align="center"> <strong>A lightweight, from-scratch OPC UA client stack for .NET 8</strong> </p>

<p align="center"> <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License: MIT"></a> <a href="https://dotnet.microsoft.com/en-us/download/dotnet/8.0"><img src="https://img.shields.io/badge/.NET-8.0-512BD4.svg" alt=".NET 8"></a> <a href="CONTRIBUTING.md"><img src="https://img.shields.io/badge/contributions-welcome-brightgreen.svg" alt="Contributions Welcome"></a> </p>

TinyUa implements the complete OPC UA binary protocol stack from scratch — binary encoding, four security policies, message chunking, secure channels, and a high-level client with a Fluent API. The core libraries have zero dependency on the OPC Foundation SDK. All cryptography uses only System.Security.Cryptography from .NET 8.

Why TinyUa?

• Zero OPCF SDK dependency in core libraries — fully self-contained binary protocol implementation
• Lightweight — the core stack (Core + Transport + Client) has no external NuGet dependencies
• Modern .NET — targets .NET 8 with nullable reference types and async/await throughout
• Fluent API — intuitive builder pattern for connecting, configuring security, and executing operations
• Comprehensive security — 4 security policies, 3 user token types, auto-generated certificates, auto-discovery of server certificates
• Production-ready features — automatic reconnect with exponential backoff, subscriptions with credit-based flow control, keep-alive monitoring

Features

Protocol (from scratch — OPC UA Part 6 binary protocol)

• Binary encoding/decoding of all OPC UA built-in types
• Message chunking with sign-then-encrypt / verify-before-decrypt pipeline
• Secure channel lifecycle management (Open/Renew/Close)
• Token rotation with current/next/previous ChannelSecurityToken tracking
• PSHA-256 key derivation for symmetric channel keys

Security

User identity tokens: Anonymous, UserName, X509 Certificate

Certificate management:

• Auto-generated self-signed client certificates at runtime
• Auto-discovery of server certificates via GetEndpoints service
• Custom certificate validation callbacks
• DPAPI-encrypted credential persistence (WPF Explorer)

Client

• Fluent Builder API: UaClient.ConnectTo(url).WithSecurity(...).WithUserName(user, pass).BuildAndRunAsync()
• Services: Read, Write, Browse, BrowseNext, CreateSession, ActivateSession, Subscribe, Publish
• Subscriptions: Credit-based flow control (PublishRequest/PublishResponse model), configurable sampling/publishing intervals
• Reconnect: Automatic reconnect with exponential backoff, keep-alive monitoring
• State tracking: ClientState enum (Disconnected → Connecting → Connected → Reconnecting → Disconnecting)
• Error handling: Configurable ErrorMode (Throw or ReturnNull)

Tools

• WPF Explorer — Graphical OPC UA browser with security endpoint discovery and credential persistence
• Console Example — Self-test mode with in-process OPCF reference server
• Benchmarks — BenchmarkDotNet-based performance and crypto primitive benchmarks

Quick Start

Prerequisites

• .NET 8 SDK

Build

git clone https://github.com/YOUR_USER/tinyua.git
cd tinyua
dotnet build TinyUa.sln

Run the self-test

dotnet run --project TinyUa.Example -- selftest

This starts an in-process OPC UA server and runs the client against it — no external server needed.

Minimal code example

using TinyUa.Core.Client;
using TinyUa.Core.Security;

// Connect with security (anonymous)
var client = await UaClient.ConnectTo("opc.tcp://myserver:4840")
    .BuildAndRunAsync();

// Read a value
var result = await client.ReadAsync("ns=2;s=Temperature");
Console.WriteLine($"Temperature: {result.Value}");

await client.DisposeAsync();

// Connect with security + user authentication
var client = await UaClient.ConnectTo("opc.tcp://myserver:4840")
    .WithSecurity("Basic256Sha256")
    .WithUserName("user", "password")
    .BuildAndRunAsync();

// Read a value
var result = await client.ReadAsync("ns=2;s=Temperature");
Console.WriteLine($"Temperature: {result.Value}");

// Browse children
var children = await client.BrowseAsync("ns=2;s=Devices");
foreach (var child in children)
    Console.WriteLine($"  {child.DisplayName}: {child.NodeId}");

// Create a subscription (auto-managed publishing)
var sub = await client.CreateSubscriptionAsync(1000); // 1s interval
// ... monitored items are delivered via callback

await client.DisposeAsync();

Connect without security

var client = await UaClient.ConnectTo("opc.tcp://myserver:4840")
    .BuildAndRunAsync();

Project Structure

Dependency Graph

TinyUa.Core  ─────────────  (zero external deps — pure .NET 8)
  └─ TinyUa.Transport  ───  (references Core)
       └─ TinyUa.Client  ──  (references Transport)
            ├─ TinyUa.Example      (+ OPCF SDK for in-process server)
            ├─ TinyUa.Explorer     (+ WPF, CommunityToolkit.Mvvm, WPF-UI)
            ├─ TinyUa.Benchmarks   (+ BenchmarkDotNet)
            ├─ TinyUa.Client.Tests
            └─ TinyUa.Security.Tests (+ OPCF SDK)

The OPC Foundation SDK (OPCFoundation.NetStandard.Opc.Ua) is used only in test and example projects for reference comparisons. The core libraries and benchmarks are fully self-contained.

Configuration

var options = new UaClientOptions
{
    ApplicationName = "MyApp",
    Timeout = 30000,              // request timeout in ms
    SessionTimeout = 3600000,     // session lifetime in ms
    ChannelLifetime = 3600000,    // secure channel lifetime in ms
    MaxMessageSize = 0,           // 0 = use server default

    Security = new SecurityOptions
    {
        Policy = "Basic256Sha256",          // None, Basic256Sha256, Aes128Sha256RsaOaep, Aes256Sha256RsaPss
        Mode = MessageSecurityMode.SignAndEncrypt,  // None, Sign, SignAndEncrypt
        UserIdentity = new UserIdentityOptions
        {
            Type = UserTokenType.UserName,
            UserName = "user",
            Password = "pass"
        },
        Certificate = new CertificateOptions
        {
            AutoDiscoverServerCertificate = true,   // auto-discover via GetEndpoints
            AutoAcceptServerCertificate = true      // auto-trust (disable in production for custom validation)
        }
    },

    ReconnectMaxRetries = -1,        // -1 = unlimited
    ReconnectInitialDelayMs = 1000,  // start with 1s delay
    ReconnectMaxDelayMs = 30000,     // cap at 30s (exponential backoff)

    ErrorMode = ErrorMode.Throw      // Throw or ReturnNull
};

Logging

// Console logging
var client = await UaClient.ConnectTo("opc.tcp://server:4840")
    .EnableLog(new DelegateLogger((level, msg) => Console.WriteLine($"[{level}] {msg}")))
    .BuildAndRunAsync();

// File logging
var client = await UaClient.ConnectTo("opc.tcp://server:4840")
    .EnableLogFile("tinyua.log", LogLevel.Debug, async: true)
    .BuildAndRunAsync();

Documentation

• Security User Guide — Step-by-step security configuration (Chinese)
• Subscription Internals — Deep dive into OPC UA subscription mechanics (Chinese)
• Contributing Guide — Build, test, and PR instructions

License

This project is licensed under the MIT License — see LICENSE for details.

Acknowledgments

• The OPC Foundation for the OPC UA protocol specification