TrakHound Docs MTConnect.NET Write an Agent Module

Write an Agent Module

Write a module that sends the Agent's data to a destination the included modules don't cover.
MTConnect.NET Docs Menu

A module is the agent's pluggable extension point. The shipped modules — HTTP server, MQTT broker, MQTT relay, MQTT adapter, SHDR adapter, HTTP adapter — all implement the same IMTConnectAgentModule interface. This recipe shows how to write a custom module so an agent can publish to a destination the shipped modules do not cover (an InfluxDB bucket, a Kafka topic, a Postgres table, a webhook).

By the end you have:

  • A class implementing IMTConnectAgentModule.
  • The module wired into the agent and receiving observations as the agent buffers them.
  • A pattern for declaring the module's config in agent.config.yaml.

1. Set Up the Project

A custom module is a separate class library. Reference MTConnect.NET-Common:

dotnet new classlib -o MyCustomModule
cd MyCustomModule
dotnet add package MTConnect.NET-Common

2. Implement IMTConnectAgentModule

The interface is small. The full surface:

namespace MTConnect.Agents;

public interface IMTConnectAgentModule
{
    string Id { get; }
    void StartBeforeLoad(IMTConnectAgentBroker agent, object configuration);
    void StartAfterLoad(IMTConnectAgentBroker agent, object configuration);
    void Stop();
}

Two lifecycle hooks: StartBeforeLoad runs before the agent has loaded the device model; StartAfterLoad runs after. Most modules use StartAfterLoad because they need to subscribe to observation events that fire once the device model is in place.

A minimal module that prints every observation to the console:

using System;
using MTConnect.Agents;
using MTConnect.Observations;

namespace MyCustomModule;

public class ConsoleSinkModule : IMTConnectAgentModule
{
    public string Id => "console-sink";

    private IMTConnectAgentBroker _agent;
    private ConsoleSinkConfiguration _config;

    public void StartBeforeLoad(IMTConnectAgentBroker agent, object configuration)
    {
        // no-op for this module.
    }

    public void StartAfterLoad(IMTConnectAgentBroker agent, object configuration)
    {
        _agent = agent;
        _config = configuration as ConsoleSinkConfiguration ?? new ConsoleSinkConfiguration();

        _agent.ObservationAdded += OnObservationAdded;
        Console.WriteLine($"[{Id}] Started.  Prefix='{_config.Prefix}'");
    }

    public void Stop()
    {
        if (_agent != null)
        {
            _agent.ObservationAdded -= OnObservationAdded;
            Console.WriteLine($"[{Id}] Stopped.");
        }
    }

    private void OnObservationAdded(object sender, IObservation obs)
    {
        var valueText = obs.GetValue(ValueKeys.Result) ?? Observation.Unavailable;
        Console.WriteLine($"[{Id}] {_config.Prefix} {obs.DataItemId}={valueText} @ {obs.Timestamp:O}");
    }
}

public class ConsoleSinkConfiguration
{
    public string Prefix { get; set; } = ">>";
}

The ObservationAdded event on IMTConnectAgentBroker fires once per observation as it enters the buffer. Other events on the broker:

  • AssetAdded — fires when an Asset enters the asset buffer.
  • AssetRemoved — fires when an Asset is removed.
  • DeviceAdded — fires when a Device is added to the agent's device list.

3. Plug the Module into the Agent

Three integration shapes:

A. Programmatic (In-Process)

When the agent is hosted in a custom executable, instantiate the module after the agent:

var agent = new MTConnectAgentBroker(...);
agent.AddDevice(device);

var module = new ConsoleSinkModule();
module.StartAfterLoad(agent, new ConsoleSinkConfiguration { Prefix = "OBS" });

B. Via the Standalone Agent's YAML Config

The standalone agent loads modules through reflection. Register the assembly with the agent's module loader (drop the assembly into the agent's modules/ directory) and reference the module by Id in agent.config.yaml:

modules:
- console-sink:
    prefix: ">>"

The agent loader matches the YAML key (console-sink) against each module assembly's Id property and constructs a configuration object from the YAML value. The config-binding uses YamlDotNet's case-insensitive convention; Prefix in C# maps from prefix in YAML.

C. As a NuGet Package

Publish the module assembly to a NuGet feed (private or nuget.org). Consumers add it with dotnet add package MyCustomModule and reference the module's Id in their agent.config.yaml.

4. Lifecycle in Detail

  1. agent.config.yaml Module loaderDeclares console-sink
  2. Module loader Custom moduleInstantiates ConsoleSinkModule
  3. Module loader Custom moduleStartBeforeLoad(agent, cfg)
  4. AgentLoads Devices.xml (MTConnectAgentBroker)
  5. Module loader Custom moduleStartAfterLoad(agent, cfg)
  6. Custom module AgentSubscribes to ObservationAdded
  7. For each Observation
  8. Agent Custom moduleObservationAdded
  9. On shutdown
  10. Agent Custom moduleStop()
Work that needs the Device model belongs in StartAfterLoad, which runs once Devices.xml is loaded.

The agent stops every module in reverse-registration order on shutdown. A module's Stop() MUST unsubscribe from events and release any held resources; otherwise the agent leaks resources on every restart of a long-lived process.

5. Production Patterns

Custom modules in production deployments typically:

  • Implement IDisposable (in addition to IMTConnectAgentModule) so they release I/O resources cleanly on shutdown.
  • Buffer outgoing writes so a slow downstream does not back-pressure the agent's observation pipeline. A typical pattern: queue observations in an in-memory channel and flush from a background task.
  • Implement structured logging — wire the module up to the agent's ILogger so errors are visible in the standard log stream.
  • Honor the cancellationToken that the agent passes for graceful shutdown.

A buffered pattern:

private readonly System.Threading.Channels.Channel<IObservation> _queue =
    System.Threading.Channels.Channel.CreateBounded<IObservation>(1000);

public void StartAfterLoad(IMTConnectAgentBroker agent, object configuration)
{
    _agent = agent;
    _agent.ObservationAdded += (_, obs) =>
    {
        // Drop if the queue is full; do not block the agent thread.
        _queue.Writer.TryWrite(obs);
    };
    _ = Task.Run(FlushLoopAsync);
}

private async Task FlushLoopAsync()
{
    await foreach (var obs in _queue.Reader.ReadAllAsync())
    {
        try { await WriteToDownstream(obs); }
        catch (Exception ex) { /* log + retry */ }
    }
}

6. Test the Module

A minimal NUnit test:

using NUnit.Framework;
using MTConnect.Agents;
using MTConnect.Devices;
using MTConnect.Observations;
using MyCustomModule;

[TestFixture]
public class ConsoleSinkModuleTests
{
    [Test]
    public void Module_subscribes_and_emits_on_observation()
    {
        var agent = new MTConnectAgentBroker();
        var device = new Device { Id = "test", Uuid = "test", Name = "Test" };
        device.AddDataItem(new MTConnect.Devices.DataItems.AvailabilityDataItem(device.Id));
        agent.AddDevice(device);

        var module = new ConsoleSinkModule();
        module.StartAfterLoad(agent, new ConsoleSinkConfiguration { Prefix = "TEST" });

        // Capture stdout to assert on the module's output.
        using var sw = new System.IO.StringWriter();
        Console.SetOut(sw);

        agent.AddObservation(device.Uuid, new EventValueObservation
        {
            DataItemId = "test-avail",
            Timestamp = DateTime.UtcNow,
            CDATA = "AVAILABLE",
        });

        Assert.That(sw.ToString(), Does.Contain("TEST"));
        Assert.That(sw.ToString(), Does.Contain("AVAILABLE"));
    }
}

Where to Next