Automation Interface support

The TwinCAT 3 PLC Profiler provides an Automation Interface via which Profiler functions can be controlled programmatically via the TwinCAT Automation Interface (ITcPlcProfiler).

Access to the Automation Interface

The Automation Interface is accessed via the PLC project object in the TwinCAT project tree. The ITcPlcProfiler interface is provided by the PLC project object.

// Zugriff auf das SPS-Projektobjekt
ITcSmTreeItem plcProjectItem = systemManager.LookupTreeItem("TIPC^PlcProject^PlcProject Project");
ITcPlcProfiler profiler = (ITcPlcProfiler)plcProjectItem;

Available commands

The following table describes the Automation Interface commands that are available:

Command	Description
`AddProfiler(string relativePath)`	Adds the PLC Profiler to the PLC project. The relativePath parameter can be used to specify the folder in the project tree. If set to null, the profiler is added to the top level.
`RemoveProfiler()`	Removes the PLC Profiler from the PLC project.
`SetProfiler(bool enabled)`	Activates (true) or deactivates (false) the PLC Profiler.
`AddConfiguration(string name, string json)`	Adds a profiler configuration. The json parameter is optional (null for standard configuration). The JSON format is described in the following section.
`SetActiveConfig(string name)`	Sets the specified configuration as the active configuration.
`GetActiveConfig()`	Returns the name of the currently active configuration.
`StartProfiling()`	Starts the profiler measurement.
`SnapshotProfiling()`	Creates a snapshot of the current measurement. The measured values are saved and the measurement is continued.
`StopProfiling()`	Ends the profiler measurement.
`GetProfilerStatus()`	Returns the current status of the profiler (e.g. 1 = recording active).
`GetResults(string configName, uint format, uint flags)`	Returns the results of the profiler measurement for the specified configuration. The return value is a string array with the file paths of the recording files.

JSON configuration format

When creating a configuration via AddConfiguration, a JSON string describing the configuration can optionally be passed. The following example shows the format:

{
  "AddMeasureMethod": true,
  "ActiveProfilerRecordConfigMode": "Blacklist",
  "List": ["METHOD", "FUNCTION_BLOCK"],
  "ListLibrary": ["tc2_system.F_CmpLibVersion"]
}

The following table describes the available JSON properties:

Property	Type	Description
`AddMeasureMethod`	`bool`	Enables the function that includes a Profiler measurement mark.
`ActiveProfilerRecordConfigMode`	`string`	Specifies the configuration mode: “Blacklist” or “Whitelist”.
`List`	`string[]`	List of element types that are on the blacklist or whitelist (e.g. “PROGRAM”, “METHOD”, “FUNCTION_BLOCK”, “ACTION”).
`ListLibrary`	`string[]`	List of library function blocks in the format “LibraryName.FunctionBlockName”.

C# sample: Profiling via the Automation Interface

The following sample shows the sequence of a profiler measurement via the Automation Interface:

// Zugriff auf das SPS-Projektobjekt
ITcSmTreeItem plcProjectItem = systemManager.LookupTreeItem("TIPC^PlcProject^PlcProject Project");
ITcPlcProfiler profiler = (ITcPlcProfiler)plcProjectItem;

// 1. Profiler hinzufügen
profiler.AddProfiler(null);

// 2. Konfiguration anlegen
profiler.AddConfiguration("MeineKonfiguration", null);

// 3. Konfiguration aktivieren
profiler.SetActiveConfig("MeineKonfiguration");

// 4. SPS-Projekt kompilieren, herunterladen und starten (über TwinCAT Automation Interface)

// 5. Messung starten
profiler.StartProfiling();

// 6. Messung beenden
profiler.StopProfiling();

// 7. Ergebnisse abrufen
string[] results = profiler.GetResults("MeineKonfiguration", 0, 0);

// 8. Profiler entfernen (optional)
profiler.RemoveProfiler();