-
-
Notifications
You must be signed in to change notification settings - Fork 38
Custom Parameters
PrtgAPI supports the creation of a variety different object types, through cloning existing objects, or creating new objects from scratch with well typed or dynamically generated request parameters. For scenarios in which PrtgAPI's built-in facilities do not yet support the object you wish to create, a set of custom parameters may be used to specify the properties to include in the object creation request.
Sensor parameter types that are not yet supported by PrtgAPI can still be added to PRTG via the RawSensorParameters type. RawSensorParameters provides a large level of versatility, ranging from flinging together a collection of parameters for creating a sensor in a fairly specific way to defining whole new sensor parameter types specific to your desired sensor.
When defining sensor parameters for a new sensor type, the first thing you must know is the parameters required to create the sensor. This can be determined by tracing your computer with Fiddler, adding the specified sensor via the PRTG UI and inspecting the parameters under TextView of the URL addsensors5.htm. For example, when an EXE/Script Advanced sensor is added, the sensor parameters are as follows:
name_=XML+Custom+EXE%2FScript+Sensor&parenttags_=C_OS_VMware+parenttag&tags_=xmlexesensor&
priority_=3&exefile_=test.ps1%7Ctest.ps1%7C%7C&exefilelabel=&exeparams_=&environment_=0&
usewindowsauthentication_=0&mutexname_=&timeout_=60&writeresult_=0&intervalgroup=0&
intervalgroup=1&interval_=60%7C60+seconds&errorintervalsdown_=1&inherittriggers=1&
id=2136&sensortype=exexml
Spaces are encoded as plus signs (+), whereas other symbols are encoded as %__. Before beginning, it is recommended to split up and decode your parameters to see what symbols are used in your parameters in case any fields require their values to be written in a certain way. After completing these steps, it can be seen EXE/Script Advanced sensors contain the following parameters
| Name | Value | Description |
|---|---|---|
| name_ | XML Custom EXE/Script Sensor | Sensor Name |
| parenttags_ | C_OS_VMware parenttag | Parent Tags |
| tags_ | xmlexesensor | Tags |
| priority_ | 3 | Priority |
| exefile_ | test.ps1|test.ps1|| | EXE/Script |
| exefilelabel_ | N/A | |
| exeparams_ | Parameters | |
| environment_ | Environment | |
| usewindowsauthentication_ | 0 | Security Context |
| mutexname_ | Mutex Name | |
| timeout_ | 60 | Timeout |
| writeresult_ | 0 | EXE Result |
| intervalgroup | 0 | Inherit Interval |
| intervalgroup | 1 | Inherit Interval |
| interval_ | 60|60 seconds | Scanning Interval |
| errorintervalsdown_ | 1 | If a Sensor Query Fails |
| inherittriggers | 1 | Inherit Triggers (Notifications Tab) |
| id | 2136 | Device ID |
| sensortype | exexml | Sensor Type |
Not all parameters necessarily need to be included in your sensor parameters. id never needs to be defined, as this is determined via the deviceId passed to the AddSensor method. Other parameters such as name_ and inherittriggers are also unnecessary, being defined under the NewSensorParameters base type. You may also find that certain parameters are also unnecessary (parenttags_) or even redundant (multiple intervalgroup instances). Based on how sophisticated you wish to make your custom parameter wrappers, it is up to you to determine that specifying the value of a parameter actually has the desired effect.
It is also worth noting that while it is good practice to specify all values required by a sensor, it is not absolutely required. For any fields not required to create the sensor, PRTG will assign these their default values; as such, while fields like the name, sensor type and EXE file of an EXE/Script Advanced sensor must be specified, the timeout and Windows Authentication mode can probably be ignored if you don't care about them.
The easiest way to create an unsupported sensor is to instantiate a new RawSensorParamaters object, adding the required parameters via the parameters object's indexer.
var parameters = new RawSensorParameters("raw c# sensor", "exexml")
{
Tags = new[] { "xmlexesensor" },
Priority = Priority.Four,
InheritInterval = false,
Interval = ScanningInterval.ThirtySeconds,
IntervalErrorMode = IntervalErrorMode.TwoWarningsThenDown,
InheritTriggers = false,
["exefile_"] = "test.ps1|test.ps1||",
["exeparams_"] = "arg1 arg2 arg3",
["environment_"] = 1,
["usewindowsauthentication_"] = 1,
["mutexname_"] = "testMutex",
["timeout_"] = 70,
["writeresult_"] = 1
};
client.AddSensor(1001, parameters);Parameters common to all objects (such as Priority and Interval) are defined on the base NewSensorParameters type. As such, you can assign type safe values to these properties, without having to worry about the complexities of raw parameter names and values.
Based on your requirements, you can wrap the creation of the custom parameters up in a method accepting just the properties you need to configure as arguments, or even derive a new sensor parameters type that performs all this work in the constructor. If you want to get really crazy however you can add create a whole new type whose property members implement type safety for you.
If you are serious about adding new sensors in a production grade system and believe your custom parameters will be used a lot, in addition to housing your parameters in a type deriving from RawSensorParameters, it is recommended to encapsulate the underlying parameter set via a collection of properties that automatically serialize and deserialize values based on the expected type you would normally use the property with.
PrtgAPI defines the following methods for safely storing and retrieving values from the underlying parameter set
-
GetCustomParameter/SetCustomParameter -
GetCustomParameterInternal/SetCustomParameterInternal -
GetCustomParameterEnumXml/SetCustomParameterEnumXml -
GetCustomParameterBool/SetCustomParameterBool -
GetCustomParameterArray/SetCustomParameterArray
Each method typically contains two overloads, allowing the parameter name to be specified via an ObjectProperty known to PrtgAPI, or via the raw parameter name (where the property is currently unsupported).
The following example shows a custom parameter type for adding EXE/Script Advanced sensors, demonstrating how string, bool, enum and array types can be safely stored and retrieved from the underlying parameter set. A secondary custom class is also defined to encapsulate the logic needed to serialize the exefile_ parameter value into the form expected by PRTG. The ExeFile property is also marked with the RequireValue attribute, which will cause the AddSensor method to throw an exception if it determines the specified property has either been assigned null or string.Empty.
Note that while these parameters choose to represent the ExeFile as a string, one could also use a Generic Sensor Target, eliminating the need to implement the ScriptName wrapper type.
public class ExeXmlRawSensorParameters : RawSensorParameters
{
public ExeXmlRawSensorParameters(string sensorName, string sensorType, string exeFile)
: base(sensorName, sensorType)
{
ExeFile = exeFile;
Tags = new[] {"xmlexesensor"};
//Assign the other properties...
}
public string[] Tags
{
get { return GetCustomParameterArray("tags_", ' '); }
set { SetCustomParameterArray("tags_", value, ' '); }
}
[RequireValue(true)]
public string ExeFile
{
get { return ((ScriptName)GetCustomParameterInternal("exefile_")).Name; }
set { SetCustomParameterInternal("exefile_", new ScriptName(value)); }
}
//Define the other properties...
}
internal class ScriptName
{
public string Name { get; set; }
internal ScriptName(string name)
{
Name = name;
}
public override string ToString()
{
return $"{Name}|{Name}||";
}
}For complete examples on defining sensor parameter types, see ExeXmlSensorParameters and ExeXmlRawSensorParameters.
Sensor parameter types that are not yet supported by PrtgAPI can still be added to PRTG via the -RawParameters parameter of New-SensorParameters. When defining sensor parameters for a new sensor type, the first thing you must know is the parameters required to create the sensor. For information on how to determine this, please see the introduction of the C# section for creating unsupported sensor parameters.
Once you have determined the parameters required to create the specified sensor type, simply define a hashtable mapping each parameter name to its corresponding value.
$table = @{
"name_" = "my raw sensor"
"tags_" = "xmlexesensor"
"priority_" = 4
"exefile_" = "test.ps1|test.ps1||"
"exeparams_" = "arg1 arg2 arg3"
"environment_" = 1
"usewindowsauthentication_" = 1
"mutexname_" = "testMutex"
"timeout_" = 70
"writeresult_" = 1
"intervalgroup" = 0
"interval_" = "30|30 seconds"
"errorintervalsdown_" = 2
"sensortype" = "exexml"
"inherittriggers_" = 0
}
$params = New-SensorParameters $table
Get-Device -Id 1001 | Add-Sensor $paramsWhen constructing unsupported sensor parameters, PrtgAPI will validate that at a minimum the name_ and sensortype parameters have been specified. If either of these is not specified, PrtgAPI will throw an InvalidOperationException specifying the value that was missing.
Note that unlike C#, PowerShell's method of initializing sensor parameters will always completely overwrite the underlying set of custom parameters that would have been created from the RawSensorParameters constructor. As such, all values should be included in the parameters hashtable.
In practice however, it is only necessary to specify values that absolutely require values (such as the name, sensor type and EXE file). If any optional fields are not specified, PRTG will assign these their default values.