This recipe walks through building an MTConnect agent in code, end to end. By the end you have a running process that:
- Holds a Device with a Controller component and a few DataItems.
- Accepts observations.
- Serves
/probe,/current, and/sampleover HTTP on port 5000.
The complete code is small: about 60 lines of C# plus a *.csproj reference.
1. Set Up the Project
Create a new console project and add the meta package:
dotnet new console -o MyAgent
cd MyAgent
dotnet add package MTConnect.NET
The MTConnect.NET meta package transitively pulls every shipped library, including MTConnect.NET-Common, MTConnect.NET-HTTP, and MTConnect.NET-XML.
2. Build the Device
In Program.cs:
using MTConnect.Devices;
using MTConnect.Devices.Components;
using MTConnect.Devices.DataItems;
// Create a Device with a Controller and an Availability data item on each.
var device = new Device
{
Id = "mill-01",
Uuid = "1234-5678-9abc-def0",
Name = "Mill #1",
Type = Device.TypeId,
};
// Attach an AVAILABILITY data item on the Device itself.
var availability = new AvailabilityDataItem(device.Id); // id "mill-01_availability"
device.AddDataItem(availability);
// Attach a Controller with CONTROLLER_MODE and EXECUTION data items.
var controller = new ControllerComponent { Id = "ctrl" };
var mode = new ControllerModeDataItem(controller.Id); // id "ctrl_mode"
var execution = new ExecutionDataItem(controller.Id); // id "ctrl_exec"
controller.AddDataItem(mode);
controller.AddDataItem(execution);
device.AddComponent(controller);
AddComponent and AddDataItem set the parent-pointers automatically — you do not need to populate Container or Parent by hand.
The (parentId) constructors build each DataItem ID as <parentId>_<name>.
3. Create the Agent
The agent is a MTConnectAgentBroker instance — the broker subclass of MTConnectAgent that adds an observation buffer and an asset buffer:
using MTConnect.Agents;
var agent = new MTConnectAgentBroker(
uuid: "agent-uuid-01",
instanceId: (ulong)DateTimeOffset.UtcNow.ToUnixTimeSeconds(),
deviceModelChangeTime: DateTimeOffset.UtcNow.ToUnixTimeMilliseconds(),
initializeAgentDevice: true);
agent.AddDevice(device);
The initializeAgentDevice: true argument auto-registers the self-describing Agent Device that emits agent-introspection observations.
4. Push Observations
A single observation lifecycle:
agent.AddObservation(device.Uuid, availability.Id, "AVAILABLE", DateTime.UtcNow);
agent.AddObservation(device.Uuid, mode.Id, "AUTOMATIC", DateTime.UtcNow);
agent.AddObservation(device.Uuid, execution.Id, "ACTIVE", DateTime.UtcNow);
The second argument is a DataItem key: the DataItem's id, name, or source all resolve.
Omit the timestamp to stamp the observation with the current time.
The agent assigns a monotonically increasing Sequence to each observation as it enters the buffer.
5. Start the HTTP Server
MTConnectHttpServer from MTConnect.NET-HTTP (already transitive through MTConnect.NET) hosts the MTConnect endpoints for an agent broker:
using MTConnect.Configurations;
using MTConnect.Servers.Http;
var httpConfig = new HttpServerConfiguration
{
Port = 5000, // leave Server unset to listen on every interface
IndentOutput = true,
DocumentFormat = "xml",
};
var httpServer = new MTConnectHttpServer(httpConfig, agent);
httpServer.Start();
Console.WriteLine("Agent running at http://localhost:5000/probe");
Console.WriteLine("Press Ctrl-C to exit.");
await Task.Delay(Timeout.Infinite);
6. Hit the Endpoints
In another terminal:
curl -s http://localhost:5000/probe | head -30
curl -s http://localhost:5000/current | head -30
curl -s http://localhost:5000/sample?count=10 | head -30
/probe returns the Device model — Components, Compositions, DataItems — wrapped in a MTConnectDevices envelope.
/current returns the most-recent observation per DataItem.
/sample returns the observation history.
A /probe response looks like:
<MTConnectDevices xmlns="urn:mtconnect.org:MTConnectDevices:2.5">
<Header creationTime="2025-01-01T12:34:56Z" sender="agent-01"
instanceId="1735734896" version="2.5.0.0" assetBufferSize="1000"
assetCount="0" bufferSize="150000"/>
<Devices>
<Device id="mill-01" uuid="1234-5678-9abc-def0" name="Mill #1">
<DataItems>
<DataItem category="EVENT" id="mill-01_availability" name="availability" type="AVAILABILITY"/>
</DataItems>
<Components>
<Controller id="ctrl">
<DataItems>
<DataItem category="EVENT" id="ctrl_mode" name="mode" type="CONTROLLER_MODE"/>
<DataItem category="EVENT" id="ctrl_exec" name="exec" type="EXECUTION"/>
</DataItems>
</Controller>
</Components>
</Device>
</Devices>
</MTConnectDevices>
Device.AddComponent consults MTConnect.Devices.Organizers on insert and creates the Organizer a Component type requires (for example Axes around a Linear).
Controller is the exception: it is added directly under Components, without a Controllers wrapper.
7. Test It
A minimal smoke test using dotnet's built-in HTTP client:
using System.Net.Http;
var http = new HttpClient { BaseAddress = new Uri("http://localhost:5000") };
var probe = await http.GetStringAsync("/probe");
Console.WriteLine(probe);
The HTTP client returns the same XML envelope the agent serves to curl.
What You Have Now
- A running agent with one Device, one Controller, and three EVENT DataItems.
- Observations entering the buffer with monotonic sequence numbers.
- The four MTConnect endpoints (
/probe,/current,/sample,/asset) served over HTTP.
Embedded Agent
Steps 2–5 wire the broker and the HTTP server by hand.
The alternative is to host the full agent application inside your process and plug your data source in as an agent module.
The agent then reads agent.config.yaml, loads the http-server module (and any others) from it, and your module writes observations into the agent directly — no separate SHDR adapter and no TCP hop between adapter and agent.
Pick this shape when the data source is .NET code you control (a PLC poller, a database tail) and you want the standalone agent's configuration, logging, and module set without writing them yourself.
The runnable version lives in examples/MTConnect.NET-Agent-Embedded/:
dotnet run --project examples/MTConnect.NET-Agent-Embedded
In your own project, reference the agent host package:
dotnet add package MTConnect.NET-Applications-Agents
Entry Point
using MTConnect.Applications;
var app = new MTConnectAgentApplication();
app.Run(args, true);
MTConnectAgentApplication is the same host the standalone agent uses.
Run(args, true) reads agent.config.yaml from the working directory, loads the modules listed in it — including module classes in your own assembly — and blocks until shutdown.
The Data-Source Module
using MTConnect.Agents;
using MTConnect.Configurations;
using MTConnect.Devices;
using MTConnect.Devices.Components;
using MTConnect.Devices.DataItems;
using MTConnect.Observations.Events;
public class ModuleConfiguration
{
public string DeviceUuid { get; set; }
public string DeviceName { get; set; }
public string SerialNumber { get; set; }
}
public class Module : MTConnectInputAgentModule
{
public const string ConfigurationTypeId = "datasource"; // matches the key in agent.config.yaml
private readonly ModuleConfiguration _configuration;
public Module(IMTConnectAgentBroker agent, object configuration) : base(agent)
{
Id = "DataSource Module"; // used for logging
_configuration = AgentApplicationConfiguration.GetConfiguration<ModuleConfiguration>(configuration);
}
// Called once at start-up: return the Device to register with the agent.
protected override IDevice OnAddDevice()
{
var device = new Device();
device.Uuid = _configuration.DeviceUuid;
device.Id = _configuration.DeviceName;
device.Name = _configuration.DeviceName;
device.AddDataItem<AvailabilityDataItem>();
var controller = new ControllerComponent { Name = ControllerComponent.NameId };
controller.AddDataItem<EmergencyStopDataItem>();
var path = new PathComponent { Name = PathComponent.NameId };
path.AddDataItem<ExecutionDataItem>();
path.AddDataItem<SystemDataItem>();
controller.AddComponent(path);
device.AddComponent(controller);
var axes = new AxesComponent { Name = AxesComponent.NameId };
foreach (var name in new[] { "X", "Y", "Z" })
{
var axis = new LinearComponent { Name = name };
axis.AddDataItem<PositionDataItem>(PositionDataItem.SubTypes.ACTUAL);
axis.AddDataItem<LoadDataItem>();
axes.AddComponent(axis);
}
device.AddComponent(axes);
return device;
}
// Called every readInterval milliseconds: read the data source and emit observations.
protected override void OnRead()
{
AddValueObservation<AvailabilityDataItem>(Availability.AVAILABLE);
AddValueObservation<ControllerComponent, EmergencyStopDataItem>(EmergencyStop.ARMED);
AddValueObservation<LinearComponent, PositionDataItem>(0.0002, "X", PositionDataItem.SubTypes.ACTUAL);
AddValueObservation<LinearComponent, LoadDataItem>(2, "X");
AddConditionObservation<PathComponent, SystemDataItem>(
MTConnect.Observations.ConditionLevel.WARNING, "404", "This is an Alarm");
}
}
MTConnectInputAgentModule is the base class for modules that produce observations. It has two hooks:
OnAddDevice()— runs once at start-up; the returnedIDeviceis added to the agent and appears in/probe. Building the model in code (rather than loading a staticdevices.xml) suits devices whose shape depends on what the data source reports — variable axis counts, optional sensors, serial numbers read at boot.OnRead()— runs everyreadIntervalmilliseconds.AddValueObservation<TComponent, TDataItem>(value, componentName, subType)finds the DataItem by Component type, Component name, and DataItem type, so the three axes share one call shape and differ only in the axis name.AddConditionObservationdoes the same for CONDITION DataItems.
AgentApplicationConfiguration.GetConfiguration<T> deserializes the module's YAML section into your configuration class.
The Configuration File
modules:
- datasource:
deviceUuid: 7E647B2D-C6A3-40BF-9CE9-FB09834850C9
deviceName: dev-001
serialNumber: 123456
readInterval: 1000
- http-server:
port: 5000
The datasource key matches ConfigurationTypeId; the fields under it map onto ModuleConfiguration, plus the inherited readInterval.
Copy the file to the build output (<None Update="agent.config.yaml"><CopyToOutputDirectory>Always</CopyToOutputDirectory></None> in the *.csproj) so the agent finds it at run time, then check the result with curl http://localhost:5000/probe and curl http://localhost:5000/current.
To publish to MQTT as well, add an mqtt-relay section (see Configure the MQTT Relay).
To package a module as a reusable NuGet package, see Write an Agent Module.
Where to Next
- Add an adapter: see Write an Adapter for the ingestion side.
- Switch to JSON output: set
documentFormat: "json-cppAgent"in the HTTP config andAccept: application/mtconnect+jsonon the request. See JSON-CPPAGENT (v2). - Persist the buffer: set
durable: trueinagent.config.yaml(theIAgentApplicationConfiguration.Durablesetting) when the agent runs underMTConnectAgentApplication, as in Embedded agent. - Run it via YAML: see Configure an Agent for the configuration-driven path that skips writing C# entirely.
- Add an MQTT relay: see Configure the MQTT Relay.