TrakHound Docs MTConnect.NET Configuration Schema

Configuration Schema

Every configuration class and property, generated from the MTConnect.NET source.
MTConnect.NET Docs Menu
This page is generated from the MTConnect.NET source, so it lists everything the code defines, and is checked against the code by the MTConnect.NET tests.

The agent and adapter accept YAML or JSON configuration. The schema below is derived from the source declarations of every option class — the JsonPropertyName / YamlMember.Alias value gives the on-the-wire key, and the /// summary above each property is reproduced verbatim.

Worked example

A minimal agent.config.yaml for an HTTP agent on port 5000:

observationBufferSize: 150000
assetBufferSize: 1000
defaultVersion: "2.5"
enableAgentDevice: true
enableMetrics: true

modules:
  - http:
      port: 5000
      documentFormat: xml

Option classes

AdapterApplicationConfiguration

Configuration for an MTConnect Http Agent Application

Key C# property Type Description
changeToken ChangeToken string An opaque token regenerated each time the configuration is saved, allowing consumers to detect that the configuration has changed.
configurationFileRestartInterval ConfigurationFileRestartInterval int Gets or Sets the minimum time (in seconds) between Adapter restarts when MonitorConfigurationFiles is enabled
deviceKey DeviceKey string The Name or UUID of the Device to create a connection for
enableBuffer EnableBuffer bool Determines whether to send all changes to data or only most recent at the specified Interval
engine Engine Dictionary<string, object> Free-form key/value settings consumed by the adapter engine; keys correspond to engine property names with loosely typed values.
filterDuplicates FilterDuplicates bool Determines whether to filter out duplicate data
id Id string Get a unique identifier for the Adapter
modules Modules IEnumerable<object> The raw, untyped module configuration sections declared for the adapter, each later resolved to a strongly typed configuration on demand.
monitorConfigurationFiles MonitorConfigurationFiles bool Gets or Sets whether Configuration files are monitored. If enabled and a configuration file is changed, the Adapter will restart
outputTimestamps OutputTimestamps bool Determines whether to output Timestamps for each SHDR line
readInterval ReadInterval int The interval (in milliseconds) at which new data is read from the Data Source
serviceAutoStart ServiceAutoStart bool Sets the Service Start Type. True = Auto | False = Manual
serviceName ServiceName string Changes the service name when installing or removing the service. This allows multiple Adapters to run as services on the same machine.
writeInterval WriteInterval int The interval (in milliseconds) at which new data is sent to the Agent

AgentApplicationConfiguration

Configuration for an MTConnect Http Agent Application

Key C# property Type Description
agentUuid AgentUuid string Optional static UUID to assign to the Agent meta-device. Must parse as an RFC 4122 UUID — any format Guid.TryParse accepts (hyphenated xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx, braced, parenthesized, bare-hex, hex-braced) is normalized to the canonical hyphenated form. Surrounding whitespace is trimmed. Malformed, all-zero (Guid.Empty / RFC 4122 nil), or unparseable values are rejected on startup with a warning that reports only the value's length (never the raw content), and the resolver falls through to the next path: (1) validated override, else (2) validated agent.information.json persisted state, else (3) a deterministic UUID v5 derived from ServiceName + machine name so the meta-device UUID survives restarts even in ephemeral-container deployments. Corresponds to AgentDeviceUUID in the cppagent reference implementation. Per MTConnect v2.7 XSD UuidType, the uuid identifies the element "for its entire life" — Header.instanceId is the per-boot discriminator.
configurationFileRestartInterval ConfigurationFileRestartInterval int Gets or Sets the minimum time (in seconds) between Agent restarts when MonitorConfigurationFiles is enabled
devices Devices string The Path to look for the file(s) that represent the Device Information Models to load into the Agent. The path can either be a single file or a directory. The path can be absolute or relative to the executable's directory
durable Durable bool Gets or Sets whether the Agent buffers are durable and retain state after restart
durableBufferPath DurableBufferPath string The base path to the directory to write the File Buffers when 'durable = true'
modules Modules IEnumerable<object> The raw, untyped module configuration sections declared for the agent, each later resolved to a strongly typed configuration on demand.
monitorConfigurationFiles MonitorConfigurationFiles bool Gets or Sets whether Configuration files are monitored. If enabled and a configuration file is changed, the Agent will restart
processors Processors IEnumerable<object> The raw, untyped processor configuration sections declared for the agent's observation/asset processing pipeline.
serviceAutoStart ServiceAutoStart bool Sets the Service Start Type. True = Auto | False = Manual
serviceDisplayName ServiceDisplayName string Changes the display name of the service. This helps with identification when multiple agents on run as services on the same machine.
serviceDisplayName ServiceDescription string Changes the description of the service. This helps with identification when multiple agents on run as services on the same machine.
serviceName ServiceName string Changes the service name when installing or removing the service. This allows multiple agents to run as services on the same machine.
useBufferCompression UseBufferCompression bool Gets or Sets whether the durable Agent buffers use Compression

AgentConfiguration

Configuration for an MTConnect Agent

Key C# property Type Description
allowEmptyResultForEnumEvents AllowEmptyResultForEnumEvents bool Gets or Sets whether an empty, null, or whitespace-only Result is preserved for Event DataItems whose Type has a controlled vocabulary (for example EXECUTION, CONTROLLER_MODE). Defaults to false, which coerces such Results to UNAVAILABLE. Numeric DataItems (all Samples, and the numeric-typed Events enumerated by the MTConnect Standard SysML) are always coerced regardless of this flag; free-form String Event DataItems (PROGRAM, MESSAGE, TOOL_ID, ASSET_CHANGED, and every other non-vocabulary Type) always preserve the empty Result.
assetBufferSize AssetBufferSize uint The maximum number of assets the agent can hold in its buffer
changeToken ChangeToken string An opaque token regenerated each time the configuration is saved, allowing consumers to detect that the configuration has changed.
convertUnits ConvertUnits bool Gets or Sets the default for Converting Units when adding Observations
defaultVersion DefaultVersionValue string The string form of used for serialization; assigning a parseable version string updates .
deviceValidationLevel DeviceValidationLevel DeviceValidationLevel Gets or Sets the default Device (MTConnectDevices) validation level. 0 = Ignore, 1 = Warning, 2 = Remove, 3 = Strict
enableAgentDevice EnableAgentDevice bool Gets or Sets whether the Agent Device is output
enableMetrics EnableMetrics bool Gets or Sets whether Metrics are captured (ex. ObserationUpdateRate, AssetUpdateRate)
enableValidation EnableValidation bool Gets or Sets whether validation information is output
ignoreObservationCase IgnoreObservationCase bool Gets or Sets the default for Ignoring the case of Observation values
ignoreTimestamps IgnoreTimestamps bool Overwrite timestamps with the agent time. This will correct clock drift but will not give as accurate relative time since it will not take into consideration network latencies. This can be overridden on a per adapter basis.
inputValidationLevel InputValidationLevel InputValidationLevel Gets or Sets the default Input (Observation or Asset) validation level. 0 = Ignore, 1 = Warning, 2 = Remove, 3 = Strict
observationBufferSize ObservationBufferSize uint The maximum number of Observations the agent can hold in its buffer
sender Sender string The value emitted as the Header/@sender attribute on MTConnect response documents (see MTConnect Part 1 §7). When null or empty, falls back to .
timezoneOutput TimeZoneOutput string Sets the TimeZone to use when timestamps are output from the Agent

DataSourceConfiguration

Configuration for an MTConnect Data Source

Key C# property Type Description
readInterval ReadInterval int The interval (in milliseconds) at which new data is read from the Data Source

FileConfiguration

Configuration for Static Files that can served from an Http Server

Key C# property Type Description
location Location string The path to match in the requested URL
path Path string The location of the files on the server (where the Agent is running)

HttpClientConfiguration

Configuration for a MTConnect Http Client

Key C# property Type Description
address Address string The URL address the client MTConnect Agent is located at.
currentOnly CurrentOnly bool Gets or Sets whether the stream requests a Current (true) or a Sample (false)
deviceKey DeviceKey string The Name or UUID of the MTConnect Device
heartbeat Heartbeat int The streaming heartbeat in milliseconds passed to the agent as the heartbeat query parameter on sample long-poll requests. The agent emits an empty document each heartbeat to keep the HTTP connection alive when no observations are produced.
interval Interval int The polling/streaming interval in milliseconds. For polling clients this is the wait between successive current/sample requests; for streaming clients it is the interval query parameter sent to the agent's sample long-poll.
outputConnectionInformation OutputConnectionInformation bool Gets or Sets whether the Connection Information (Host / Port) is output to the Agent to be collected by a client
port Port int The port to connect to the client MTConnect Agent.
useSSL UseSSL bool When true, the client connects to the agent over https://; when false, over http://. Any explicit scheme already present in is rewritten to match this flag.
useStreaming UseStreaming bool Gets or Sets whether the client should use Streaming (true) or Polling (false)

IAdapterApplicationConfiguration

Configuration for an MTConnect Adapter

Key C# property Type Description
changeToken ChangeToken string An opaque token that changes whenever the underlying configuration source is reloaded, allowing consumers to detect that the configuration has been replaced.
configurationFileRestartInterval ConfigurationFileRestartInterval int Gets or Sets the minimum time (in seconds) between Adapter restarts when MonitorConfigurationFiles is enabled
deviceKey DeviceKey string The Name or UUID of the Device to create a connection for
enableBuffer EnableBuffer bool Determines whether to send all changes to data or only most recent at the specified Interval
engine Engine Dictionary<string, object> Free-form key/value settings consumed by the adapter engine; keys correspond to engine property names with loosely typed values.
filterDuplicates FilterDuplicates bool Determines whether to filter out duplicate data
id Id string Get a unique identifier for the Adapter
modules Modules IEnumerable<object> The raw, untyped module configuration sections declared for the adapter, each later resolved to a strongly typed configuration on demand.
monitorConfigurationFiles MonitorConfigurationFiles bool Gets or Sets whether Configuration files are monitored. If enabled and a configuration file is changed, the Adapter will restart
outputTimestamps OutputTimestamps bool Determines whether to output Timestamps for each SHDR line
path Path string The file system path the configuration was loaded from, used as the default target when the configuration is saved back to disk.
serviceAutoStart ServiceAutoStart bool Sets the Service Start Type. True = Auto | False = Manual
serviceName ServiceName string Changes the service name when installing or removing the service. This allows multiple Adapters to run as services on the same machine.
writeInterval WriteInterval int The interval (in milliseconds) at which new data is sent to the Agent

IAgentApplicationConfiguration

Configuration for an MTConnect Shdr > Http Agent

Key C# property Type Description
agentUuid AgentUuid string Optional static UUID to assign to the Agent meta-device. Must parse as an RFC 4122 UUID (any Guid.TryParse-accepted format, normalized to the canonical hyphenated form after trimming surrounding whitespace). Malformed, all-zero (Guid.Empty / RFC 4122 nil), or unparseable values log a length-only warning and the resolver falls through to persisted agent.information.json state or a deterministic UUID v5 derived from ServiceName + machine name. Corresponds to AgentDeviceUUID in the cppagent reference implementation.
configurationFileRestartInterval ConfigurationFileRestartInterval int Gets or Sets the minimum time (in seconds) between Agent restarts when MonitorConfigurationFiles is enabled
devices Devices string The Path to look for the file(s) that represent the Device Information Models to load into the Agent. The path can either be a single file or a directory. The path can be absolute or relative to the executable's directory
durable Durable bool Gets or Sets whether the Agent buffers are durable and retain state after restart
durableBufferPath DurableBufferPath string The base path to the directory to write the File Buffers when 'durable = true'
modules Modules IEnumerable<object> The raw, untyped module configuration sections declared for the agent, each later resolved to a strongly typed configuration on demand.
monitorConfigurationFiles MonitorConfigurationFiles bool Gets or Sets whether Configuration files are monitored. If enabled and a configuration file is changed, the Agent will restart
processors Processors IEnumerable<object> The raw, untyped processor configuration sections declared for the agent's observation/asset processing pipeline.
serviceAutoStart ServiceAutoStart bool Sets the Service Start Type. True = Auto | False = Manual
serviceDescription ServiceDescription string Changes the description of the service. This helps with identification when multiple agents on run as services on the same machine.
serviceDisplayName ServiceDisplayName string Changes the display name of the service. This helps with identification when multiple agents on run as services on the same machine.
serviceName ServiceName string Changes the service name when installing or removing the service. This allows multiple agents to run as services on the same machine.
useBufferCompression UseBufferCompression bool Gets or Sets whether the durable Agent buffers use Compression

IAgentConfiguration

Configuration for an MTConnect Agent

Key C# property Type Description
allowEmptyResultForEnumEvents AllowEmptyResultForEnumEvents bool Gets whether an empty, null, or whitespace-only Result is preserved for Event DataItems whose Type has a controlled vocabulary (for example EXECUTION, CONTROLLER_MODE). When false (the default), such Results are coerced to UNAVAILABLE to satisfy the MTConnect Standard requirement that a controlled-vocabulary Event's Result be a member of the vocabulary. When true, the empty Result is published verbatim, which some implementations rely on for parity with adapters that emit empty values. Numeric DataItems (all Samples, and the numeric-typed Events enumerated by the SysML model) are always coerced regardless of this flag, per the Part 2 "Sample MUST always be reported in float" requirement. Free-form String Event DataItems (PROGRAM, MESSAGE, TOOL_ID, ASSET_CHANGED, and every other non-vocabulary Type) always preserve the empty Result.
assetBufferSize AssetBufferSize uint The maximum number of assets the agent can hold in its buffer
changeToken ChangeToken string An opaque token that changes whenever the underlying configuration source is reloaded, allowing consumers to detect that the configuration has been replaced.
convertUnits ConvertUnits bool Gets the default for Converting Units when adding Observations
defaultVersion DefaultVersion Version Gets the default MTConnect version to output response documents for.
deviceValidationLevel DeviceValidationLevel DeviceValidationLevel Gets or Sets the default Device (MTConnectDevices) validation level. 0 = Ignore, 1 = Warning, 2 = Remove, 3 = Strict
enableAgentDevice EnableAgentDevice bool Gets or Sets whether the Agent Device is output
enableMetrics EnableMetrics bool Gets whether Metrics are captured (ex. ObserationUpdateRate, AssetUpdateRate)
enableValidation EnableValidation bool Gets or Sets whether validation information is output
ignoreObservationCase IgnoreObservationCase bool Gets the default for Ignoring the case of Observation values
ignoreTimestamps IgnoreTimestamps bool Overwrite timestamps with the agent time. This will correct clock drift but will not give as accurate relative time since it will not take into consideration network latencies. This can be overridden on a per adapter basis.
inputValidationLevel InputValidationLevel InputValidationLevel Gets the default Input (Observation or Asset) validation level. 0 = Ignore, 1 = Warning, 2 = Remove, 3 = Strict
observationBufferSize ObservationBufferSize uint The maximum number of Observations the agent can hold in its buffer
path Path string The file system path the configuration was loaded from, used as the default target when the configuration is saved back to disk.
sender Sender string The value emitted as the Header/@sender attribute on MTConnect response documents (see MTConnect Part 1 §7). When null or empty, falls back to .
timeZoneOutput TimeZoneOutput string Sets the TimeZone to use when timestamps are output from the Agent

IDataSourceConfiguration

Configuration for an MTConnect Data Source

Key C# property Type Description
readInterval ReadInterval int The interval (in milliseconds) at which new data is read from the Data Source

IFileConfiguration

Configuration for Static Files that can served from an Http Server

Key C# property Type Description
location Location string The path to match in the requested URL
path Path string The location of the files on the server (where the Agent is running)

IHttpClientConfiguration

Configuration for a MTConnect Http Client

Key C# property Type Description
address Address string The URL address the client MTConnect Agent is located at.
currentOnly CurrentOnly bool Gets or Sets whether the stream requests a Current (true) or a Sample (false)
deviceKey DeviceKey string The Name or UUID of the MTConnect Device
heartbeat Heartbeat int
id Id string The unique identifier for the Adapter
interval Interval int
outputConnectionInformation OutputConnectionInformation bool Gets or Sets whether the Connection Information (Host / Port) is output to the Agent to be collected by a client
port Port int The port to connect to the client MTConnect Agent.
useSSL UseSSL bool
useStreaming UseStreaming bool Gets or Sets whether the client should use Streaming (true) or Polling (false)

IShdrAdapterClientConfiguration

Configuration for an MTConnect SHDR Adapter

Key C# property Type Description
availableOnConnection AvailableOnConnection bool For devices that do not have the ability to provide available events, if yes, this sets the Availability to AVAILABLE upon connection.
convertUnits ConvertUnits bool Adapter setting for data item units conversion in the agent. Assumes the adapter has already done unit conversion. Defaults to global.
ignoreHeartbeatOnChange IgnoreHeartbeatOnChange bool Gets or Sets whether Heartbeat PING requests are not sent if data has been received within the Heartbeat period
ignoreObservationCase IgnoreObservationCase bool Gets or Sets the default for Ignoring the case of Observation values
ignoreTimestamps IgnoreTimestamps bool Overwrite timestamps with the agent time. This will correct clock drift but will not give as accurate relative time since it will not take into consideration network latencies. This can be overridden on a per adapter basis.
outputConnectionInformation OutputConnectionInformation bool Gets or Sets whether the Connection Information (Host / Port) is output to the Agent to be collected by a client

IShdrClientConfiguration

Configuration for an MTConnect SHDR Client

Key C# property Type Description
connectionTimeout ConnectionTimeout int The amount of time (in milliseconds) an adapter can be silent before it is disconnected. This is only for legacy adapters that do not support heartbeats. If heartbeats are present, this will be ignored.
deviceKey DeviceKey string The UUID or Name of the device that corresponds to the name of the device in the Devices file.
heartbeat Heartbeat int The Heartbeat interval (in milliseconds) that the TCP Connection will use to maintain a connection when no new data has been sent
hostname Hostname string The host the adapter is located on.
id Id string The unique identifier for the Adapter
port Port int The port to connect to the adapter.
reconnectInterval ReconnectInterval int The amount of time (in milliseconds) between adapter reconnection attempts. This is useful for implementation of high performance adapters where availability needs to be tracked in near-real-time.

ShdrAdapterClientConfiguration

Configuration for an MTConnect SHDR Adapter

Key C# property Type Description
availableOnConnection AvailableOnConnection bool For devices that do not have the ability to provide available events, if TRUE, this sets the Availability to AVAILABLE upon connection.
convertUnits ConvertUnits bool Adapter setting for data item units conversion in the agent. Assumes the adapter has already done unit conversion. Defaults to global.
ignoreHeartbeatOnChange IgnoreHeartbeatOnChange bool Gets or Sets whether Heartbeat PING requests are not sent if data has been received within the Heartbeat period
ignoreObservationCase IgnoreObservationCase bool Gets or Sets the default for Ignoring the case of Observation values
ignoreTimestamps IgnoreTimestamps bool Overwrite timestamps with the agent time. This will correct clock drift but will not give as accurate relative time since it will not take into consideration network latencies. This can be overridden on a per adapter basis.
outputConnectionInformation OutputConnectionInformation bool Gets or Sets whether the Connection Information (Host / Port) is output to the Agent to be collected by a client

ShdrClientConfiguration

Configuration for an MTConnect SHDR Client

Key C# property Type Description
connectionTimeout ConnectionTimeout int The amount of time (in milliseconds) an adapter can be silent before it is disconnected. This is only for legacy adapters that do not support heartbeats. If heartbeats are present, this will be ignored.
deviceKey DeviceKey string The UUID or Name of the device that corresponds to the name of the device in the Devices file.
heartbeat Heartbeat int The Heartbeat interval (in milliseconds) that the TCP Connection will use to maintain a connection when no new data has been sent
hostname Hostname string The host the adapter is located on.
id Id string The unique identifier for the Adapter
port Port int The port to connect to the adapter.
reconnectInterval ReconnectInterval int The amount of time (in milliseconds) between adapter reconnection attempts. This is useful for implementation of high performance adapters where availability needs to be tracked in near-real-time.

PemCertificateConfiguration

Configures a TLS certificate loaded from PEM-encoded files.

Key C# property Type Description
certificateAuthority CertificateAuthority string The path to the PEM file containing the trusted certificate authority chain.
certificatePath CertificatePath string The path to the PEM file containing the server or client certificate.
privateKeyPassword PrivateKeyPassword string The password protecting the private key, when it is encrypted.
privateKeyPath PrivateKeyPath string The path to the PEM file containing the certificate's private key.

PfxCertificateConfiguration

Configures a TLS certificate loaded from a PKCS#12 (PFX) file.

Key C# property Type Description
certificatePassword CertificatePassword string The password protecting the PFX file, when it is encrypted.
certificatePath CertificatePath string The path to the PFX file containing the certificate and its private key.

TlsConfiguration

Configures TLS for an MTConnect endpoint, selecting either a PFX or PEM certificate and its validation options.

Key C# property Type Description
omitCAValidation OmitCAValidation bool Whether certificate-authority chain validation is skipped.
pem Pem PemCertificateConfiguration The PEM certificate configuration, used when is not set.
pfx Pfx PfxCertificateConfiguration The PFX certificate configuration; takes precedence over when set.
verifyClientCertificate VerifyClientCertificate bool Whether the endpoint requires and verifies a client certificate.