Absolutely. Let’s do this the way a senior engineer would actually think about it in a real industrial system.

---

P/Invoke, native SDK wrapping, and interop adapter design in .NET

When teams first touch native integration in .NET, they often think the problem is:

“How do I write DllImport correctly?”

That matters, but in real systems, that is only the outer shell of the problem.

The real problem is this:

How do you let managed .NET software talk to unstable, low-level, vendor-owned native code without letting that native complexity infect and destabilize the whole application?

That is the real engineering challenge.

In a WPF desktop application controlling industrial hardware, interop is rarely a small technical detail. It is often one of the most dangerous architectural boundaries in the entire system.

---

PART 1 — BIG PICTURE

Why native SDK integration is common in industrial .NET systems

In normal business applications, most dependencies are already nicely packaged for managed ecosystems. You use database drivers, HTTP clients, cloud SDKs, authentication libraries, and the whole stack is already friendly to .NET.

Industrial systems are different.

A WPF desktop app controlling a wafer inspection machine often needs to integrate with things like:

• industrial cameras
• frame grabbers
• motion controllers
• PLC communication libraries
• device communication DLLs
• machine vision toolkits
• native image processing engines
• proprietary hardware SDKs

Those systems usually come from hardware vendors, embedded vendors, or specialized machine-vision vendors. Their world is not centered around .NET. Their world is closer to drivers, firmware, C/C++, DMA buffers, real-time device APIs, and Windows-native integration.

So even if your application is 90% managed C#, that last 10% around device integration may be native, unsafe, stateful, thread-sensitive, and unforgiving.

That is why native SDK integration is so common in industrial .NET systems.

Why hardware vendors often expose C/C++ DLLs instead of clean managed APIs

This is not because they are trying to make your life difficult. It is usually because native APIs are their most universal and lowest-level contract.

A vendor can publish one C API and make it usable from:

• C++
• C#
• Python
• LabVIEW
• Delphi
• MATLAB
• test tools
• old customer software written 15 years ago

Also, many hardware SDKs sit close to:

• drivers
• memory buffers
• interrupt/event systems
• device protocol stacks
• image transport layers
• proprietary processing engines

Those worlds have historically lived in native code.

So the vendor often gives you:

• a DLL
• header files
• constants
• a manual
• a few C or C++ examples
• maybe a thin C# sample that only demonstrates happy-path usage

And then your team must build the real managed integration.

Why interop integration is more than “calling a DLL”

This is the first big mental shift.

A lot of teams underestimate native integration because the first demo looks simple:

• write some DllImport
• call OpenCamera
• call StartAcquisition
• get a callback
• done

But production interop is not just function invocation. It includes:

• signature correctness
• struct layout correctness
• string encoding correctness
• buffer ownership
• handle lifetime
• init/start/stop/close sequencing
• callback lifetime
• callback threading behavior
• error translation
• shutdown ordering
• SDK version quirks
• driver mismatch handling
• diagnostics when native failures do not throw nice managed exceptions

So interop is really not “calling a DLL.”

It is designing and controlling a hazardous runtime boundary.

Why weak interop boundaries create instability across the whole application

This is where systems become fragile.

If native details leak everywhere, then suddenly:

• ViewModels know about IntPtr
• business logic branches on vendor status codes
• workflow classes depend on native structs
• callbacks mutate application state directly from unknown threads
• disposal rules are unclear
• tests require real hardware
• logs are full of meaningless values like -7 and 1051
• nobody really knows who owns the camera handle or when the frame buffer becomes invalid

At that point, the native SDK is no longer isolated. It has effectively become part of your application model.

That is dangerous because native SDKs are usually:

• less safe
• less expressive
• less testable
• more stateful
• more vendor-specific
• more failure-prone than managed code

So if you do not contain that complexity, the whole app becomes unstable.

This happens constantly with:

• camera/image acquisition SDKs
• motion controller libraries
• machine communication DLLs
• native inspection/image processing libraries

The strong engineering move is to treat interop as a containment problem, not merely a syntax problem.

---

PART 2 — WHAT P/INVOKE REALLY IS

What P/Invoke does conceptually

P/Invoke is how managed .NET code calls a function implemented in unmanaged code, usually inside a native DLL.

Conceptually, it is a bridge between two different worlds:

• the managed CLR world
• the unmanaged native world

In ordinary C# code, the runtime understands the types, object lifetime, exceptions, memory model, and execution environment.

In native code, those guarantees change dramatically.

So P/Invoke is not just a function call mechanism. It is a transition between two runtime models.

Managed-to-native call boundary

This boundary matters because the assumptions on one side do not fully apply on the other.

On the managed side, you have things like:

• garbage collection
• type safety
• array bounds checks
• exception propagation
• object lifetime tracking
• a known threading model within your app

On the native side, you may have:

• raw pointers
• manual memory ownership
• SDK-owned buffers
• vendor-defined threading
• callbacks from unmanaged worker threads
• no CLR safety guarantees
• process-level crash potential if memory is misused

That means calling native code is fundamentally different from calling another C# service or helper.

Marshaling at a high level

Marshaling is the process of converting data across the boundary.

Sometimes it is simple:

• int
• double
• IntPtr
• simple blittable structs

Sometimes it is subtle and dangerous:

• strings with ANSI vs UTF-16 differences
• arrays
• output buffers
• packed structs
• fixed-size embedded arrays
• nested structs
• callbacks/delegates
• pointers to memory that must remain valid
• buffers whose ownership rules are not obvious

The danger is that two types may look similar but still not be compatible in practice.

Why crossing this boundary is different from calling normal C# code

A normal C# call is still inside one runtime, one type system, and one memory safety model.

A native call is different because:

• memory ownership may be manual or ambiguous
• the native side may assume exact struct sizes and packing
• strings may use a different encoding than you expect
• incorrect signatures may corrupt memory silently
• callbacks may arrive on arbitrary threads
• a bug can crash the process, not just fail an operation cleanly

That is why interop code deserves a higher level of engineering discipline than typical application code.

Cost, risk, and correctness implications

Yes, there is some call overhead when crossing into native code. But in most production interop work, performance overhead is not the first problem. The first problem is correctness.

The major risks are usually:

• wrong calling convention
• wrong struct layout
• wrong buffer lifetime
• use-after-free
• delegate collected too early
• callback after dispose
• double release
• invalid state transitions
• unclear thread ownership
• error code misuse

So experienced engineers think like this:

1. make the boundary correct
2. make the ownership explicit
3. make the error behavior observable
4. then optimize hot paths based on actual measurement

---

PART 3 — REAL PROBLEMS IN THIS SYSTEM

Let’s ground this in one concrete example:

A WPF desktop app controlling a wafer inspection machine

This kind of system often uses multiple native SDKs at once.

Controlling cameras through native SDK

A camera SDK might expose functions like:

• initialize SDK
• enumerate cameras
• open camera session
• configure exposure
• configure trigger mode
• register frame callback
• start acquisition
• stop acquisition
• close session

In a demo, this looks manageable.

In production, the difficult questions appear:

• what happens if the network camera disappears mid-run?
• what happens if start is called twice?
• can stop be called while a frame callback is still running?
• does the vendor require all camera calls from the same thread?
• does reconnect require full process reinitialization?
• can two cameras share one SDK instance?

These are not syntax questions. These are operational integration questions.

Acquiring raw image buffers

This is where interop gets serious quickly.

A frame may arrive as:

• IntPtr to raw bytes
• pointer plus metadata struct
• frame handle requiring later release
• callback with an SDK-owned buffer
• separate image and metadata buffers

Now your team must decide:

• do we copy the frame immediately?
• do we pin a managed buffer?
• do we expose a wrapper over native memory?
• who owns the buffer after callback returns?
• how long is the buffer valid?
• is the buffer reused by the SDK?

If you get this wrong, the symptom is not always immediate. You may see:

• occasional corrupted images
• random access violations
• data races under load
• frame content overwritten by later acquisitions
• memory growth from leaked buffers
• unstable behavior only after hours of runtime

Calling machine/device APIs through vendor DLLs

Motion controller SDKs and machine communication DLLs often expose functions like:

• connect
• initialize axis
• home
• enable servo
• move absolute
• stop
• query status
• read alarm word
• reset fault

These APIs are often extremely stateful.

You cannot treat them like stateless utility methods. They have implicit contracts such as:

• connect before initialize
• initialize before enable
• enable before move
• stop before close
• unregister callbacks before shutdown
• call from the same OS thread in certain cases

If your managed wrapper does not model these lifecycle rules clearly, the rest of the application will use the API incorrectly.

Registering callbacks/events from native code

This is one of the highest-risk parts of interop.

Examples include:

• camera frame received callback
• motion alarm callback
• device disconnected callback
• machine status changed callback

The vendor SDK may call your managed delegate:

• from a native worker thread
• from an internal SDK thread
• while holding internal locks
• during shutdown
• after you believe the device is already disposed
• concurrently with other SDK operations

That means your managed callback code is now part of a very delicate runtime interaction.

Receiving native status codes and converting them to .NET behavior

Native SDKs often return things like:

• 0 = success
• -7 = timeout
• -12 = invalid state
• 1051 = device busy
• 2048 = connection lost

That is fine for a native API. It is a terrible application contract.

A WPF application needs to decide things like:

• should timeout throw?
• should connection lost trigger reconnect logic?
• should device busy become an operator warning?
• should invalid state become a workflow validation error?
• should some errors fail fast and others be recoverable?

That is where wrapper design becomes critical.

Why these problems are operationally difficult in production

Because production failures are rarely clean and obvious.

What you see is not:

“The camera struct layout is wrong.”

What you see is:

• the third inspection cycle freezes the UI
• frame callbacks stop after reconnect
• process crashes once every two days
• one device model works, another fails
• shutdown hangs intermittently
• image corruption appears only under high throughput
• error logs show only -7 with no useful context
• bug reproduces only on the machine, never on developer laptops

That is why interop work is operationally difficult. The symptoms appear far away from the true root cause.

---

PART 4 — DESIGNING A SAFE INTEROP BOUNDARY

Why raw DllImport or IntPtr should not leak throughout the app

Because once they leak, the whole codebase becomes coupled to native details.

Then your application layers must reason about:

• raw handles
• pointer validity
• native buffer ownership
• vendor threading quirks
• status code tables
• struct layout assumptions
• shutdown ordering

That is exactly what you want to avoid.

If IntPtr appears in your ViewModels, application services, or workflow orchestration code, your boundary is already too weak.

Creating a dedicated interop layer / adapter boundary

A healthy design usually introduces a contained interop boundary with separate responsibilities:

• a low-level native binding layer
• a safe managed wrapper
• a high-level application-facing adapter

This lets you isolate the unsafe, vendor-specific, unstable pieces.

Keeping native details inside infrastructure code

Interop belongs in infrastructure, not in application or domain logic.

The rest of the system should work with contracts like:

• IMachineCamera
• IMotionController
• IInspectionDeviceSession

Those interfaces should express business or workflow capability, not vendor DLL shape.

Exposing safe, domain-meaningful interfaces to the rest of the application

For example, this is a healthy application-facing interface:

public interface IMachineCamera : IAsyncDisposable
{
    Task ConnectAsync(CancellationToken cancellationToken);
    Task StartAcquisitionAsync(CancellationToken cancellationToken);
    Task StopAcquisitionAsync(CancellationToken cancellationToken);
    IAsyncEnumerable<InspectionFrame> GetFramesAsync(CancellationToken cancellationToken);
}

This is not:

• DllImport shaped
• pointer shaped
• status-code shaped
• vendor-specific

It expresses what the application actually needs.

Likewise:

public interface IMotionController : IAsyncDisposable
{
    Task HomeAxisAsync(string axisName, CancellationToken cancellationToken);
    Task MoveToAsync(string axisName, double position, CancellationToken cancellationToken);
    Task StopAllAsync(CancellationToken cancellationToken);
    Task<MotionStatus> GetStatusAsync(CancellationToken cancellationToken);
}

And:

public interface IInspectionDeviceSession : IAsyncDisposable
{
    Task InitializeAsync(CancellationToken cancellationToken);
    Task<InspectionRunResult> RunInspectionAsync(InspectionRecipe recipe, CancellationToken cancellationToken);
    Task ShutdownAsync(CancellationToken cancellationToken);
}

These contracts let the rest of the app think in device capabilities and workflow concepts, not native implementation details.

Why this architectural boundary matters for maintainability and reliability

Because it gives you protection.

If the vendor SDK changes, or if you switch device vendors, or if you need simulation, or if callback handling changes internally, the rest of the application should remain stable.

Without this boundary:

• interop concerns spread
• testing gets harder
• refactoring becomes dangerous
• vendor lock-in increases
• every workflow change risks destabilizing low-level integration

With this boundary:

• native complexity stays local
• higher layers stay clean
• simulations are possible
• lifetime and error translation are centralized
• operational diagnostics become much clearer

---

PART 5 — LOW-LEVEL WRAPPER VS HIGH-LEVEL ADAPTER

This distinction is extremely important.

Low-level wrapper

A low-level wrapper stays close to the vendor SDK.

Its job is to:

• contain DllImport
• contain raw structs and delegate definitions
• manage handles safely
• perform basic marshaling correctly
• enforce minimal lifecycle correctness
• translate raw failures into technical managed failures

It is still mostly SDK-shaped.

Examples:

• NativeCameraApi
• CameraSdkWrapper

High-level adapter/service

A high-level adapter presents a clean .NET abstraction to the rest of the system.

Its job is to:

• expose domain-meaningful operations
• convert callback models into stable .NET streams/events
• hide vendor-specific status codes
• hide IntPtr
• hide native structs
• integrate with application logging, retry, cancellation, and workflow semantics
• make simulation possible

Examples:

• CameraService
• MachineCameraAdapter

Why these should usually be separate layers

Because they change for different reasons.

The low-level wrapper changes when:

• a signature is wrong
• a struct layout changes
• a vendor DLL version changes
• a callback registration contract changes
• handle release behavior must be adjusted

The high-level adapter changes when:

• the application wants a different abstraction
• frame processing is reworked
• buffering strategy changes
• retry behavior changes
• simulation behavior changes
• workflow semantics change

If you merge them into one giant class, you end up with a messy hybrid that is hard to reason about and hard to test.

What belongs in each layer

NativeCameraApi — DllImport layer

This layer should contain:

• DllImport declarations
• native constants
• native struct layouts
• callback delegate signatures
• calling convention and charset details

It should be intentionally dumb.

CameraSdkWrapper — safe raw wrapper

This layer should contain:

• open/close semantics
• safe handle ownership
• minimal lifecycle enforcement
• delegate lifetime management
• translation from status codes to technical exceptions or wrapper-level results
• thin protection against misuse

It should still feel close to the SDK, but much safer.

CameraService / MachineCameraAdapter — app-facing abstraction

This layer should contain:

• application-friendly methods
• frame streaming contract
• handoff from callback to queue/channel
• reconnect or retry policy if appropriate
• app-level error mapping
• cancellation integration
• logging in business terms
• simulation-compatible interface

That is the layer the rest of the application should depend on.

---

PART 6 — ERROR HANDLING ACROSS NATIVE BOUNDARIES

Native status codes vs .NET exceptions

Native SDKs often use integer return codes because that is portable and language-neutral.

Managed applications typically want one of two things:

• exceptions for unexpected or infrastructure-level failures
• explicit result objects for expected operational failures

The wrapper boundary is where that translation should happen.

When to translate native failures into exceptions

Exceptions make sense when:

• the failure is not part of normal control flow
• the operation cannot continue meaningfully
• the caller is not expected to handle the raw condition directly
• the failure indicates infrastructure or API misuse

Examples:

• DLL not found
• camera open failed unexpectedly during initialization
• invalid handle returned
• callback registration failed
• memory allocation failure on native side
• SDK internal corruption or fatal error

Those are not normal workflow outcomes. They are technical failures.

When to convert them into Result-like domain errors

Result-like outcomes are often better when the failure is expected and meaningful to business or operator flow.

Examples:

• device busy
• axis not homed yet
• machine interlock prevents move
• acquisition timeout that operator may retry
• recipe invalid for current hardware state
• device temporarily offline

These are conditions the application may want to branch on explicitly.

A wrapper may first map the native error into a descriptive technical category, and then a higher layer may convert that into a domain result.

Preserving low-level technical detail in logs while exposing useful app-level meaning

This is one of the most important responsibilities in wrapper design.

Bad systems lose detail too early and end up with logs like:

• “Camera failed”
• “Move failed”
• “SDK error”

That is useless.

Good wrapper logging preserves details like:

• operation name
• native status code
• device identifier
• current state
• relevant parameters
• SDK-provided last error text
• call sequence context

But the rest of the application should see something more useful, such as:

• “Camera acquisition timed out”
• “Motion move rejected because axis is not homed”
• “Inspection engine initialization failed due to license error”

The idea is:

• logs keep technical truth
• application contract exposes useful meaning

Why error translation is one of the most important interop design responsibilities

Because raw native errors are not a stable language for the rest of your system.

If the rest of the codebase starts checking if (code == -7), your design is already collapsing.

Error translation is what turns vendor-specific, low-level failure details into a clean and durable contract for the rest of the application.

---

PART 7 — OWNERSHIP, LIFETIME, AND CLEANUP

This is where senior engineers start first.

Not syntax. Not performance.

Ownership.

Who owns native handles/resources

Every native resource needs an explicit owner.

Examples:

• camera session handle
• machine connection handle
• inspection engine context
• callback registration token
• frame buffer
• native configuration object

For each one, you want answers to these questions:

• who creates it?
• who releases it?
• when does it become invalid?
• can it be shared?
• is it thread-safe?
• can callbacks still arrive after release starts?
• what happens if initialization partially fails?

If you do not know these answers, the interop layer is not mature enough yet.

Explicit open/init/close/dispose responsibilities

Interop code should prefer explicit lifecycle states such as:

• created
• initialized
• connected/open
• running
• stopping
• closed/disposed

The wrapper should make illegal transitions hard or impossible.

For example:

• starting acquisition twice should not produce undefined behavior
• calling stop after dispose should be safe and idempotent
• callbacks should be unregistered before handle release
• shutdown should not race uncontrolled with new operations

Wrapping native handles safely

When possible, SafeHandle is a strong choice because it centralizes release behavior and reduces accidental misuse.

The key point is not that SafeHandle is magic. The key point is that it encourages a clearer ownership model than raw IntPtr spread everywhere.

Preventing leaks, double release, and invalid reuse

This is where real production bugs live.

Common failures include:

• handle released twice
• stale handle reused after reconnect
• callback fires after close
• frame buffer used after SDK has reclaimed it
• partial initialization fails and leaks native resources
• dispose happens while another thread is still invoking SDK calls

That is why interop design must begin with lifetime rules, not end with them.

Examples

Camera session handle

The wrapper owns the handle. The rest of the app never sees it.

Frame buffer ownership

The wrapper must know whether the frame memory is valid only during callback, until next frame, or until explicit release.

Machine connection object

Connection lifecycle should be encapsulated in one place, not scattered across workflow code.

Callback registration/unregistration

Treat callback registration as a resource with clear lifetime, not just a helper method.

Why interop adapter design must start with lifetime rules

Because most serious interop defects eventually reduce to one of these:

• who owned it?
• who released it?
• who was still using it?
• which thread was allowed to touch it?
• how long was it valid?

That is why lifetime is the first design concern.

---

PART 8 — CALLBACKS, EVENTS, AND THREADING

Native callbacks into managed code

Native SDKs often deliver events by calling back into your code:

• frame received
• alarm raised
• status changed
• device disconnected
• move completed

This is convenient, but it is a very dangerous entry point.

A native callback is not a normal .NET event. It may arrive on threads you do not own and at times you do not expect.

Threading surprises from vendor SDK callbacks

Common surprises include:

• callback arrives on an SDK-owned background thread
• callback arrives while another SDK call is still in progress
• callback arrives serialized under an internal lock
• callback continues briefly during shutdown
• callback ordering is not guaranteed
• callback sometimes reenters application code while state is mid-transition

In WPF, there is an immediate extra danger:

You cannot touch UI-bound state directly from that thread.

Reentrancy risks

Reentrancy is one of the hardest interop bugs to spot.

A typical bad flow looks like this:

• SDK invokes frame callback
• callback logs heavily, updates application state, maybe calls back into the SDK
• meanwhile another operation is stopping the device
• the SDK holds internal locks
• the managed side waits for stop completion
• deadlock or inconsistent state appears

This is exactly why callbacks should be tiny.

Marshaling callback results safely into .NET pipelines or UI-safe flows

The safest pattern is usually:

1. native callback receives raw event
2. callback captures the minimum needed data
3. callback quickly hands off to a queue/channel/thread-safe buffer
4. downstream managed code processes it
5. UI updates happen later on the dispatcher thread

That pattern restores control.

Keeping callbacks small and non-blocking

A strong rule of thumb:

Never do serious work inside a native callback.

Good callback behavior usually means:

• no blocking waits
• no direct UI updates
• no long-running processing
• no heavy disk I/O
• minimal locking
• no complicated workflow branching
• no calling back into the SDK unless the vendor explicitly guarantees it is safe

Examples

Frame received callback

Copy or capture frame data safely, enqueue it, return immediately.

Machine alarm callback

Capture alarm code and timestamp, enqueue a managed notification, let higher layers decide what to do.

Status changed callback

Translate raw status into a small event object and pass it into a controlled managed pipeline.

Why naive callback handling creates deadlocks, race conditions, or crashes

Because callbacks are unmanaged entry points into your managed process.

If you let them directly run application logic, you lose control over:

• threading
• sequencing
• shutdown behavior
• backpressure
• synchronization discipline

That is why callback handling must be heavily constrained.

---

PART 9 — DATA MARSHALING IN PRACTICE

Simple parameters vs complex structs

Simple primitive parameters are usually straightforward.

But once you get into:

• complex structs
• packed layout
• strings
• arrays
• pointers
• output buffers
• embedded fixed arrays
• binary blobs

The risk level rises quickly.

Strings, arrays, buffers, and binary structs

Interop bugs often hide in details such as:

• is the string ANSI, UTF-8, or UTF-16?
• is the caller expected to allocate the buffer?
• is the struct packed to 1 byte or default alignment?
• are there reserved fields that must be zeroed?
• is the native side expecting exact size/version fields?
• does the struct differ between x86 and x64?
• is the output length returned in bytes or characters?

These are easy to get subtly wrong.

Copying vs pinning vs wrapping

This is not only a performance decision. It is first a correctness decision.

Copying

Copying is often the safest approach when buffer lifetime is short or unclear.

Use it when:

• callback-owned memory may become invalid after return
• the SDK reuses buffers
• correctness matters more than avoiding one copy

Pinning

Pinning lets native code access managed memory without the GC moving it.

This is useful, but it comes with costs:

• pinned objects reduce GC flexibility
• long-lived pinning can hurt heap health
• misuse makes debugging harder

Wrapping native memory

Sometimes you can wrap native memory instead of copying.

That can be good for performance if:

• ownership is crystal clear
• lifetime is well-controlled
• release rules are explicit

It is dangerous if:

• the SDK reclaims or reuses the memory unexpectedly
• the data outlives the callback
• consumers do not understand validity boundaries

When marshaling overhead matters

It matters when:

• frame rates are high
• buffers are large
• operations are repeated frequently
• data is moved in hot paths
• many tiny interop calls happen in tight loops

For example, if you acquire large image frames continuously, repeated copying can absolutely matter.

But experienced engineers still optimize only after the buffer lifetime rules are well understood.

When custom handling is safer than magical automatic marshaling

Automatic marshaling is convenient, but in real systems, explicit handling is often safer for:

• large output buffers
• binary data
• frame memory
• complex structs
• vendor-specific string conventions
• performance-sensitive or correctness-sensitive paths

The mature mindset is:

prefer explicitness over magic when the boundary is risky

Examples

Image frame metadata struct

Make layout explicit, verify field sizes, and test against real device output.

Error message strings

Sometimes it is safer to allocate a buffer and let the SDK fill it, rather than rely on automatic string marshaling.

Command parameter structs

Zero-initialize and fill fields deliberately, especially when the SDK expects size/version metadata.

Raw byte buffers

Decide explicitly whether to copy, pin, or wrap based on lifetime, ownership, and measured performance needs.

---

PART 10 — HOW WE USE THIS IN .NET (PRACTICAL)

Let’s build a realistic layered shape.

1. Thin DllImport layer

using System;
using System.Runtime.InteropServices;

internal static class NativeCameraApi
{
    private const string DllName = "VendorCameraSdk.dll";

    [UnmanagedFunctionPointer(CallingConvention.Cdecl)]
    internal delegate void FrameCallback(
        IntPtr frameBuffer,
        int bufferLength,
        ref NativeFrameInfo frameInfo,
        IntPtr userData);

    [StructLayout(LayoutKind.Sequential)]
    internal struct NativeFrameInfo
    {
        public int Width;
        public int Height;
        public int PixelFormat;
        public long Timestamp;
        public int FrameNumber;
    }

    [DllImport(DllName, CallingConvention = CallingConvention.Cdecl)]
    internal static extern int Camera_Open(int deviceIndex, out CameraSafeHandle handle);

    [DllImport(DllName, CallingConvention = CallingConvention.Cdecl)]
    internal static extern int Camera_Start(CameraSafeHandle handle);

    [DllImport(DllName, CallingConvention = CallingConvention.Cdecl)]
    internal static extern int Camera_Stop(CameraSafeHandle handle);

    [DllImport(DllName, CallingConvention = CallingConvention.Cdecl)]
    internal static extern int Camera_RegisterFrameCallback(
        CameraSafeHandle handle,
        FrameCallback callback,
        IntPtr userData);

    [DllImport(DllName, CallingConvention = CallingConvention.Cdecl)]
    internal static extern int Camera_UnregisterFrameCallback(CameraSafeHandle handle);

    [DllImport(DllName, CallingConvention = CallingConvention.Cdecl)]
    internal static extern int Camera_Close(IntPtr handle);

    [DllImport(DllName, CallingConvention = CallingConvention.Cdecl, CharSet = CharSet.Ansi)]
    internal static extern int Camera_GetLastErrorMessage(
        CameraSafeHandle handle,
        IntPtr buffer,
        int bufferLength);
}

This layer should be boring and low-level. It is not the place for application logic.

2. Safe handle

using System;
using System.Runtime.InteropServices;

internal sealed class CameraSafeHandle : SafeHandle
{
    public CameraSafeHandle() : base(IntPtr.Zero, ownsHandle: true) { }

    public override bool IsInvalid => handle == IntPtr.Zero;

    protected override bool ReleaseHandle()
    {
        return NativeCameraApi.Camera_Close(handle) == 0;
    }
}

This gives us a clearer ownership model than raw IntPtr.

3. Technical error translation helper

using System;
using System.Runtime.InteropServices;

internal sealed class CameraSdkException : Exception
{
    public int StatusCode { get; }

    public CameraSdkException(string message, int statusCode)
        : base(message)
    {
        StatusCode = statusCode;
    }
}

internal static class CameraSdkError
{
    public static void ThrowIfFailed(int statusCode, string operation, CameraSafeHandle? handle = null)
    {
        if (statusCode == 0)
            return;

        string detail = TryGetLastError(handle) ?? "No native detail available.";
        throw new CameraSdkException(
            $"{operation} failed. Native status={statusCode}. Detail={detail}",
            statusCode);
    }

    private static string? TryGetLastError(CameraSafeHandle? handle)
    {
        if (handle is null || handle.IsInvalid)
            return null;

        IntPtr buffer = Marshal.AllocHGlobal(512);
        try
        {
            int rc = NativeCameraApi.Camera_GetLastErrorMessage(handle, buffer, 512);
            if (rc != 0)
                return null;

            return Marshal.PtrToStringAnsi(buffer);
        }
        finally
        {
            Marshal.FreeHGlobal(buffer);
        }
    }
}

This layer preserves technical detail rather than dropping it.

4. Safer managed wrapper

using System;

internal sealed class CameraSdkWrapper : IDisposable
{
    private readonly object _sync = new();
    private CameraSafeHandle? _handle;
    private NativeCameraApi.FrameCallback? _callback;
    private bool _disposed;

    public void Open(int deviceIndex)
    {
        lock (_sync)
        {
            ThrowIfDisposed();

            int rc = NativeCameraApi.Camera_Open(deviceIndex, out var handle);
            CameraSdkError.ThrowIfFailed(rc, "Camera_Open");

            _handle = handle;
        }
    }

    public void RegisterFrameCallback(NativeCameraApi.FrameCallback callback)
    {
        lock (_sync)
        {
            ThrowIfDisposed();
            EnsureOpen();

            _callback = callback; // keep delegate alive
            int rc = NativeCameraApi.Camera_RegisterFrameCallback(_handle!, _callback, IntPtr.Zero);
            CameraSdkError.ThrowIfFailed(rc, "Camera_RegisterFrameCallback", _handle);
        }
    }

    public void Start()
    {
        lock (_sync)
        {
            ThrowIfDisposed();
            EnsureOpen();

            int rc = NativeCameraApi.Camera_Start(_handle!);
            CameraSdkError.ThrowIfFailed(rc, "Camera_Start", _handle);
        }
    }

    public void Stop()
    {
        lock (_sync)
        {
            if (_disposed || _handle is null || _handle.IsInvalid)
                return;

            int rc = NativeCameraApi.Camera_Stop(_handle);
            CameraSdkError.ThrowIfFailed(rc, "Camera_Stop", _handle);
        }
    }

    public void Dispose()
    {
        lock (_sync)
        {
            if (_disposed)
                return;

            try
            {
                if (_handle is not null && !_handle.IsInvalid)
                {
                    NativeCameraApi.Camera_UnregisterFrameCallback(_handle);
                    NativeCameraApi.Camera_Stop(_handle);
                    _handle.Dispose();
                }
            }
            finally
            {
                _callback = null;
                _handle = null;
                _disposed = true;
            }
        }
    }

    private void EnsureOpen()
    {
        if (_handle is null || _handle.IsInvalid)
            throw new InvalidOperationException("Camera is not open.");
    }

    private void ThrowIfDisposed()
    {
        ObjectDisposedException.ThrowIf(_disposed, this);
    }
}

This wrapper still knows the SDK well, but it keeps the rough edges local.

5. High-level application-facing adapter

using System;
using System.Collections.Generic;
using System.Runtime.InteropServices;
using System.Threading;
using System.Threading.Channels;
using System.Threading.Tasks;

public sealed record InspectionFrame(
    byte[] Buffer,
    int Width,
    int Height,
    int PixelFormat,
    long Timestamp,
    int FrameNumber);

public interface IMachineCamera : IAsyncDisposable
{
    Task ConnectAsync(CancellationToken cancellationToken);
    Task StartAcquisitionAsync(CancellationToken cancellationToken);
    Task StopAcquisitionAsync(CancellationToken cancellationToken);
    IAsyncEnumerable<InspectionFrame> GetFramesAsync(CancellationToken cancellationToken);
}

public sealed class MachineCameraAdapter : IMachineCamera
{
    private readonly CameraSdkWrapper _sdk;
    private readonly Channel<InspectionFrame> _frames;
    private bool _connected;

    public MachineCameraAdapter(CameraSdkWrapper sdk)
    {
        _sdk = sdk;
        _frames = Channel.CreateBounded<InspectionFrame>(new BoundedChannelOptions(64)
        {
            SingleReader = false,
            SingleWriter = false,
            FullMode = BoundedChannelFullMode.DropOldest
        });
    }

    public Task ConnectAsync(CancellationToken cancellationToken)
    {
        _sdk.Open(deviceIndex: 0);
        _sdk.RegisterFrameCallback(OnFrameReceived);
        _connected = true;
        return Task.CompletedTask;
    }

    public Task StartAcquisitionAsync(CancellationToken cancellationToken)
    {
        EnsureConnected();
        _sdk.Start();
        return Task.CompletedTask;
    }

    public Task StopAcquisitionAsync(CancellationToken cancellationToken)
    {
        if (_connected)
        {
            _sdk.Stop();
        }

        return Task.CompletedTask;
    }

    public IAsyncEnumerable<InspectionFrame> GetFramesAsync(CancellationToken cancellationToken)
        => _frames.Reader.ReadAllAsync(cancellationToken);

    public ValueTask DisposeAsync()
    {
        _sdk.Dispose();
        _frames.Writer.TryComplete();
        return ValueTask.CompletedTask;
    }

    private void OnFrameReceived(
        IntPtr frameBuffer,
        int bufferLength,
        ref NativeCameraApi.NativeFrameInfo frameInfo,
        IntPtr userData)
    {
        try
        {
            // Safety-first choice:
            // assume native frame memory is not valid after callback returns.
            var managed = new byte[bufferLength];
            Marshal.Copy(frameBuffer, managed, 0, bufferLength);

            var frame = new InspectionFrame(
                managed,
                frameInfo.Width,
                frameInfo.Height,
                frameInfo.PixelFormat,
                frameInfo.Timestamp,
                frameInfo.FrameNumber);

            _frames.Writer.TryWrite(frame);
        }
        catch
        {
            // Never allow exceptions to escape a native callback.
            // Real code would log carefully and non-blockingly.
        }
    }

    private void EnsureConnected()
    {
        if (!_connected)
            throw new InvalidOperationException("Camera is not connected.");
    }
}

Why this shape matters

Now the UI and application workflow do not need to know about:

• DllImport
• IntPtr
• callback delegate lifetime
• vendor error code tables
• SDK handle ownership

They consume a clean contract and receive regular managed types.

That is the correct direction.

---

PART 11 — COMMON MISTAKES (VERY REALISTIC)

Exposing IntPtr or raw native structs everywhere

Why it happens:

• fast prototype pressure
• “temporary” shortcut
• nobody owns wrapper design

What it causes:

• lifetime confusion
• native leakage into the application model
• hard-to-test code
• widespread unsafe assumptions

Putting DllImport calls directly in business/application code

Why it happens:

• team wants quick progress
• interop looks small at first

What it causes:

• duplicated native handling logic
• no central ownership model
• no proper containment
• painful future refactoring

No lifetime ownership model

Why it happens:

• vendor docs vague
• happy-path development
• disposal added too late

What it causes:

• leaks
• double release
• stale handle usage
• shutdown crashes
• reconnect instability

Blocking inside native callbacks

Why it happens:

• easy place to “just do the work”
• team wants immediate processing

What it causes:

• callback stalls
• frame loss
• hidden deadlocks
• backpressure problems
• bad shutdown behavior

Not isolating thread-affinity issues from SDKs

Why it happens:

• works on developer machine
• thread behavior misunderstood

What it causes:

• UI-thread violations
• race conditions
• intermittent hangs
• impossible-to-reproduce bugs

Weak error mapping: “error -7” everywhere

Why it happens:

• nobody designed the error translation layer
• vendor codes just bubble upward

What it causes:

• useless logs
• confusing operator messages
• duplicated condition checks
• workflow logic polluted by technical codes

Mixing interop code with workflow logic

Why it happens:

• one engineer built both quickly
• layering was never enforced

What it causes:

• god classes
• low cohesion
• difficult simulation
• high-risk changes

No fake/simulation layer for testing

Why it happens:

• hardware dependency accepted as normal
• abstraction added too late

What it causes:

• slow testing
• low confidence
• difficult CI
• poor defect isolation

Assuming vendor docs are fully correct

Why it happens:

• understandable trust

What it causes:

• wrong layout assumptions
• wrong calling conventions
• incorrect lifetime behavior
• long debugging cycles

Experienced engineers respect vendor docs, but they verify against real runtime behavior.

---

PART 12 — TESTABILITY & SIMULATION

Why direct native SDK dependency makes testing hard

If higher-level code directly depends on real native SDK behavior, then testing requires:

• device drivers
• installed DLLs
• hardware connection
• proper runtime environment
• exact timing conditions
• sometimes operator intervention

That is not sustainable for most development and verification work.

Using abstractions to enable simulation/fakes

This is one of the biggest architectural payoffs of clean interop boundaries.

If the application depends on IMachineCamera, IMotionController, and IInspectionDeviceSession, then you can provide:

• fake camera implementations
• simulated frame providers
• simulated motion controllers
• machine state simulators
• deterministic fault injection

Now the application can be tested without real hardware.

Testing higher layers without real hardware

For example, a fake camera might simply push synthetic frames into the same interface used by production code.

A simulated motion controller might:

• pretend to home
• report ready state
• delay move completion
• inject timeout or alarm states

This lets you test:

• workflow sequencing
• timeout behavior
• retry logic
• UI state transitions
• alarm handling
• cancellation and shutdown behavior

without having the real machine attached.

Keeping real interop limited to infrastructure boundaries

That is the key idea.

Only the infrastructure layer should truly depend on:

• vendor DLLs
• DllImport
• native handles
• native structs
• unmanaged callbacks

Higher layers should not care whether the implementation is real or simulated.

How this improves both design and verification

A design that supports simulation is usually a healthier design anyway, because it means native details are truly isolated.

You gain:

• cleaner boundaries
• faster feedback
• better CI possibilities
• easier workflow testing
• safer refactoring
• more confidence in fault handling

---

PART 13 — PERFORMANCE & TRADE-OFFS

Thin wrapper speed vs safer adapter complexity

A thin wrapper is quicker to write and may look more efficient.

A safer adapter adds more code and more layers.

But in long-running industrial systems, the extra structure often pays for itself in:

• correctness
• supportability
• diagnostics
• testability
• resilience

The fastest code path is useless if it creates rare crashes and impossible debugging.

Copying vs pinning

This is one of the classic interop trade-offs.

Copying

Benefits:

• simpler
• safer
• clear ownership
• easier downstream usage

Costs:

• memory allocation
• data copy overhead

Pinning

Benefits:

• avoids copying
• useful for high-throughput transfer scenarios

Costs:

• more complex lifetime rules
• can interfere with GC efficiency
• easier to misuse

In practice, experienced engineers often start with copying unless measurement proves it is too expensive and the SDK lifetime contract is trustworthy enough to optimize further.

Direct native calls vs buffered/queued handoff

Direct immediate handling may reduce one handoff step, but it also increases risk:

• callback thread does too much
• UI coupling appears
• backpressure becomes messy
• shutdown sequencing gets harder

A queued or buffered handoff adds some structure, but it often makes the system more stable and observable.

Exposing native semantics vs translating to cleaner app contracts

If you expose native semantics directly, you reduce wrapper effort now but increase coupling forever.

If you translate to cleaner app contracts, you do more design work now but get a more durable codebase.

Senior engineers usually choose the latter unless there is a strong reason not to.

Simplicity vs robustness

This is the real trade-off.

A raw wrapper may feel simple from a code-count perspective.

A layered adapter may feel larger.

But in production, the layered version is often simpler operationally because:

• errors are clearer
• ownership is clearer
• testing is easier
• support is easier
• device changes are less disruptive

Experienced engineers choose the kind of simplicity that survives production.

---

PART 14 — DEBUGGING INTEROP IN PRODUCTION

How interop failures typically appear

Interop failures often show up as ugly symptoms:

• random crashes
• AccessViolationException
• corrupted images
• callbacks silently stopping
• leaked memory or handles
• hangs during shutdown
• device state becoming inconsistent
• failures only on one machine or one SDK version

These are hard because the symptom and root cause are often far apart.

Why logs at the wrapper boundary matter so much

The wrapper boundary is where technical truth is still available.

That is where logs should capture things like:

• operation name
• native status code
• handle/session identity
• key parameters
• lifecycle state
• callback registration/unregistration
• start/stop/open/close transitions
• timing information
• SDK version if available
• driver version if available

Without that, debugging becomes guesswork.

How to investigate whether a bug lives in managed code, wrapper code, or vendor SDK behavior

A practical diagnostic mindset usually looks like this:

1. Reconstruct the sequence

What happened before failure?

• init
• connect
• callback register
• start
• frame flow
• stop
• unregister
• close

Did the order look valid?

2. Check ownership assumptions

Was a handle used after dispose? Was a buffer read after callback returned? Did a reconnect reuse stale state?

3. Check threading assumptions

Which thread invoked the callback? Did callback logic touch UI? Did shutdown race with callback delivery?

4. Check signature and layout correctness

Is the calling convention right? Is the struct size correct? Are x64 assumptions correct? Did a DLL update change a field?

5. Compare against vendor examples

Does the same failure occur with the vendor sample? Does it depend on SDK version or hardware model?

6. Isolate the boundary

Can the issue be reproduced with a minimal focused wrapper test? Can the high-level application logic be removed from the experiment?

That methodical approach is how senior engineers debug interop systems without getting lost in guesswork.

---

PART 15 — SENIOR ENGINEER MENTAL MODEL

An experienced engineer does not think of native integration as a normal library dependency.

They think of it as a hazardous boundary.

That mindset changes everything.

How experienced engineers think of native integration as a hazardous boundary that must be tightly controlled

They assume:

• vendor code may be imperfect
• docs may be incomplete
• callbacks may behave badly
• resource ownership is critical
• shutdown is dangerous
• threading is rarely as friendly as hoped
• bugs may appear only under real hardware conditions and long runtimes

So they control the boundary tightly.

How to design stable interop layers that protect the rest of the codebase

They create layers that:

• isolate DllImport
• isolate native structs
• isolate raw status codes
• isolate handles
• isolate callback behavior
• expose clean managed contracts outward

That way, the rest of the application stays mostly normal .NET code.

How to reason about ownership, lifetime, error translation, and callback safety first

Before getting excited about fancy abstractions, they ask:

• who owns this handle?
• when is it valid?
• who disposes it?
• can callback arrive after shutdown starts?
• what thread are callbacks on?
• which failures are technical and which are operational?
• where should translation happen?

That is the right order of thinking.

How to keep native complexity local while exposing clean .NET abstractions

They do not let the app become vendor-shaped.

They let the interop layer absorb the ugliness and expose contracts like:

• IMachineCamera
• IMotionController
• IInspectionDeviceSession

That keeps the rest of the codebase stable and testable.

How to design wrappers that survive years of production use and vendor quirks

A wrapper that survives years of production use usually has these characteristics:

• strict containment of native details
• explicit ownership and disposal rules
• small, safe callback handling
• strong logging at the boundary
• clear error translation
• support for simulation and fakes
• minimal leakage of vendor-specific semantics
• conservative assumptions about buffer lifetime and threading
• defensive handling of partial failures and shutdown races

That is the difference between “it works in the demo” and “it survives real factory use.”

---

Final takeaway

P/Invoke is only the doorway.

The real engineering problem is what happens around that doorway:

• resource ownership
• lifetime rules
• callback safety
• marshaling correctness
• error translation
• thread control
• boundary containment
• operational diagnostics

In real industrial .NET systems, especially WPF apps controlling hardware, the best engineers do not try to make native integration feel casual.

They treat it with respect.

They contain it. They model it carefully. They translate it deliberately. They log it thoroughly. They keep the rest of the application clean.

That is how you build interop layers that survive production.

If you want, next I can turn this into a deeper production-grade code walkthrough for IMachineCamera and IMotionController, including SafeHandle, callback lifetime, queue handoff, shutdown sequencing, and fake/simulator design.