Property Manipulation
PrtgAPI enables retrieving and modifying the properties and settings of sensors, devices, groups, probes and channels in a type safe, reliable manner. PrtgAPI is capable of retrieving all properties of an object and displaying them all at once. For properties not currently supported by PrtgAPI, these properties can still be interacted with via their raw property names.
To view a list of all properties currently supported by PrtgAPI, please install the PowerShell version of PrtgAPI and run one of the following commands, or alternatively click the link on the command to view the online version
Sensor, Device, Group and Probe properties can be retrieved from PRTG using each of their respective Get<object>Properties methods
//Retrieve all sensor properties
var sensorSettings = client.GetSensorProperties(1001);//Retrieve all device properties
var deviceProperties = client.GetDeviceProperties(1002);Either can object ID or existing object reference can be specified
//Retrieve sensor properties for an existing sensor object
var sensorSettings = client.GetSensorProperties(sensor);Certain properties (often fields considered "read-only") can only be retrieved by directly asking for them, and will not be returned in the general queries for all properties present on an object.
//Retrieve the SQL Server Query file of a Microsoft SQL v2 sensor
var query = client.GetObjectProperty(1001, ObjectProperty.SqlServerQuery);Values returned by GetObjectProperty will always be of their true type, as seen in the
members of the SensorSettings/DeviceSettings/GroupSettings/ProbeSettings types returned by Get<object>Properties. If you know the true type of the value you are retrieving, you can instead call GetObjectProperty<T> to have PrtgAPI cast the returned value for you. Attempting to cast a value to an invalid type will generate an exception stating the actual type that was expected.
// InvalidCastException! SensorSettings.HttpRequestMethod
// defines this value as being of type HttpRequestMethod?
var method = client.GetObjectProperty<bool>(2002, ObjectProperty.HttpRequestMethod)When retrieving individual object properties, please note that if your PRTG server is not in English and you attempt to retrieve an individual property that does not exist on the target object, due to limitations of the PRTG API you may receive a deserialization error or the string "(Property does not exist)" in your server's native language.
Note due to the way PrtgAPI retrieves object properties, pluralized property methods (GetSensorProperties, etc) will throw an InvalidOperationException if the current PRTG user has read-only access to the specified object. Singular property methods (GetObjectProperty) can always be used regardless of whether the current user has read or write access.
Channel objects do not have a separate method for retrieving their properties, as these details are included in the standard channel response. For more information on retrieving channels, please see Channels.
Properties for all supported first class object types can be modified using the SetObjectProperty method.
//Change the Windows Domain of the device with ID 1001 to "contoso"
client.SetObjectProperty(1001, ObjectProperty.WindowsDomain, "contoso");As is the case when retrieving properties, Either can object ID or existing object reference can be specified
//Change the Windows Domain a given device to "contoso"
client.SetObjectProperty(device, ObjectProperty.WindowsDomain, "contoso");Channel properties can be modified using the SetChannelProperty method
//Change the UpperErrorLimit of the channel with ID 2 on the sensor with ID 1002 to 100
client.SetChannelProperty(1002, 2, ChannelProperty.UpperErrorLimit, 100);
//Change the LowerErrorLimit of all channels on the sensor with ID 1001
var channels = client.GetChannels(1001);
client.SetChannelProperty(channels, ChannelProperty.LowerErrorLimit, 50);Even properties that appear as "read-only" in PRTG can be modified by SetObjectProperty
//Modify the EXE/Script executed by an EXE/XML Advanced sensor
client.SetObjectProperty(1003, ObjectProperty.ExeFile, "newScript.ps1");When modifying a property with SetObjectProperty or SetChannelProperty, PrtgAPI performs a type lookup of the specified property and verifies that the specified value is convertable to the target type. Type information is derived from the corresponding property returned from one of the Get<object>Properties methods (or in the case of Channels, the type of the property found on the Channel object).
PrtgAPI understands any dependent properties a property may have, and updates the values of these properties as well to make sure the target property takes effect. For example, as the WindowsDomain property of an object is not active unless the InheritWindowsCredentials property is false, PrtgAPI will update the value of this property as well. This extends to multi-level relationships
//Set the database port under the "Credentials for Database Management Systems" section
//to 8080. DBPortMode will also be set to Manual, and InheritDBCredentials will also be
//set to False
client.SetObjectProperty(1001, ObjectProperty.DBPort, 8080);Multiple properties can be specified at once by specifying a collection of PropertyParameter, ChannelParameter or CustomParameter objects
client.SetObjectProperty(
1001,
new PropertyParameter(ObjectProperty.VMwareUserName, "root"),
new PropertyParameter(ObjectProperty.VMwarePassword, "password")
);Note: from PRTG 18.1.38 it is no longer possible to enable channel limits or set an error or warning message without having first set a limit value on at least one limit field (UpperErrorLimit, LowerErrorLimit, UpperWarningLimit or LowerWarningLimit). If PrtgAPI detects you are using version 18.1 or higher it will automatically validate all target channels have an existing limit value when trying to modify the ErrorLimitMessage, WarningLimitMessage or set LimitsEnabled to true. If any channels do not contain a limit value, an InvalidOperationException will be thrown, specifying the IDs of the sensors whose channel was missing a value.
PRTG allows the unit factor of channels to be controlled via the Channel Unit Configuration section found on the Settings page of devices, groups and probes. Based on the current factor that is defined for a channel, this can influence how values are interpreted when modifying channel properties that relate to the channel's unit (e.g. a channel under a device whose a Bytes (Disk) is set to MByte should interpret setting an UpperErrorLimit of 100 differently than a channel under a device whose Bytes (Disk) is set to GByte).
Both PRTG and PrtgAPI work around this issue by specifying the unit factor of a channel when executing a request. Unit factors can be viewed by inspecting the Factor property of Channel objects. While there is absolutely no need for you to utilize this property directly, as a consequence of this behavior it is important to note that
- Modifying the Channel Unit Configuration properties may invalidate the
Factorany descendantChannelobjects you currently hold reference to - When modifying properties that require specifying a unit factor, PrtgAPI will inspect the
Factorof all channels to determine how to construct the request.
As a result, requests like the following
// Don't do this
var channel = client.GetChannel(1001, 1);
client.SetChannelProperty(channel.SensorId, channel.Id, ChannelProperty.UpperErrorLimit, 100);are extremely inefficient, as the Channel object will need to be retrieved again inside of SetChannelProperty. Instead, simply pass the channel objects straight to SetChannelProperty
//Do this instead
var channel = client.GetChannel(1001, 1);
client.SetChannelProperty(channel, ChannelProperty.UpperErrorLimit, 100);When viewing the current values of channels, the DisplayLastValue property will display a string containing the current value in terms of its custom unit. LastValue however will always display the value in terms of its raw underlying unit (e.g. bytes).
C:\> Get-Sensor *mem* | Get-Channel *mem* | fl Name,*Last*
Name : Percent Available Memory
DisplayLastValue : 27 %
LastValue : 27
Name : Available Memory
DisplayLastValue : 1,116 MByte
LastValue : 1169711104Certain properties, such as Scanning Interval, support a range of valid values that can also be customized by the administrator. PrtgAPI defines custom types for representing these values, allowing static values to be accessed via predefined constants, or dynamic values to be used via a cast.
client.SetObjectProperty(1234, ObjectProperty.Interval, ScanningInterval.ThirtySeconds);client.SetObjectProperty(1234, ObjectProperty.Interval, (ScanningInterval) new TimeSpan(0, 0, 30));Note: if a custom scanning interval is specified that is not supported by PRTG, PRTG will automatically select the closest interval to the specified value.
For properties not yet supported by PrtgAPI's type system, it is still possible to retrieve such properties via the GetObjectPropertiesRaw method. As is the case when retrieving supported properties, either an object ID or existing object reference can be specified.
//Retrieve all properties present on the settings page of the probe with ID 3002
var properties = client.GetObjectPropertiesRaw(3002);
Console.WriteLine($"Hello, my name is {properties["name"]}");GetObjectPropertiesRaw returns a dictionary containing all properties present on an object. Object properties can be referred to by their raw property names (with trailing underscores removed). GetObjectPropertiesRaw can also be used for identifying raw property names to potentially use with SetObjectPropertyRaw (see below). Typically, all raw property names (with the exception of inheritance related properties) returned by GetObjectPropertiesRaw will require a trailing underscore in order to directly manipulate them.
Raw properties can also be retrieved via the GetObjectPropertyRaw method. Properties returned by GetObjectPropertyRaw will always be returned as strings, leaving it up to the programmer to parse them. PRTG does not support the retrieval of individual inheritance settings; as such, these settings must be retrieved via GetObjectPropertiesRaw.
var name = client.GetObjectPropertyRaw(1001, "name_");When retrieving option properties, by default PRTG will return the internal numeric value that is used to represent the value. The label of the selected value (as displayed in the PRTG UI) can alternatively be retrieved by specifying text: true
var rights = client.GetObjectPropertyRaw(1001, "sshelevatedrights", true);When retrieving individual object properties, please note that if your PRTG server is not in English and you attempt to retrieve an individual property that does not exist on the target object, due to limitations of the PRTG API you may receive the string "(Property does not exist)" in your server's native language.
Properties can be modified using their raw names via the SetObjectPropertyRaw method.
client.SetObjectPropertyRaw(1001, "name_", "New Name!");Multiple properties can be modified by specifying an array of CustomParameter objects
client.SetObjectPropertyRaw(
1001,
new CustomParameter("name_", "New Name!"),
new CustomParameter("interval_", "60|60 seconds")
);If you prefer to extract raw property details straight from PRTG, this can typically be done by inspecting the "name" and "value" attributes of the properties <input> tag on the Settings page of PRTG.
<input class="text valid" data-rule-required="true" type="text" name="name_"
id="name_" value="dc-1">When modifying raw properties whose values are populated from dropdown lists, the raw value often has to be in the format <value>|<value>||
client.SetObjectPropertyRaw(1001, "sqlquery_", "test.sql|test.sql||")Note: unsupported channel properties cannot be modified.
Properties can be retrieved from Sensors, Devices, Groups and Probes using the Get-ObjectProperty cmdlet
C:\> Get-Sensor -Id 1001 | Get-ObjectProperty
InheritAccess : True
Name : Service: Microsoft Exchange Information Store
ParentTags : {B_Server_Mail}
Tags : {wmiservicesensor, servicesensor}
Priority : Three
InheritChannelUnit :
DebugMode : Discard
...Based on the type of object requested (sensor, device, group or probe) different properties will be returned. Get-ObjectProperty is not required for retrieving Channel settings, as these are automatically included in Channel objects. For more information on retrieving channels, please see Channels.
Certain properties (often fields considered "read-only") can only be retrieved by directly asking for them, and will not be returned in the general queries for all properties present on an object.
C:\> Get-Sensor -Id 1001 | Get-ObjectProperty SqlServerQuery
CalculateUptime.sqlWhen retrieving individual object properties, please note that if your PRTG server is not in English and you attempt to retrieve an individual property that does not exist on the target object, due to limitations of the PRTG API you may receive a deserialization error or the string "(Property does not exist)" in your server's native language.
Note due to the way PrtgAPI retrieves object properties, attempting to retrieve all type safe object properties (by invoking Get-ObjectProperty with no parameters) will cause a non terminating InvalidOperationException exception if the current PRTG user has read-only access to the specified object. Singular property parameter sets (GetObjectProperty -Property) can always be used regardless of whether the current user has read or write access.
Object properties currently supported by PrtgAPI are documented across several PowerShell help articles. For more information, please see the following documents
-
Get-Help SensorSettings- Sensors -
Get-Help ObjectSettings- Devices, Groups and Probes -
Get-Help ChannelSettings- Channels
Properties for Sensors, Devices, Groups and Probes can be modified using the Set-ObjectProperty cmdlet, while Channel properties can be modified using the Set-ChannelProperty cmdlet. By default, these cmdlets operate in batch mode and are also capable of executing in PassThru Mode. For information on batch mode and PassThru Mode, please see Batch Requests and PassThru Requests respectively.
# Set the default scanning interval of sensors under the device with ID 1001
# to 30 seconds
Get-Device -Id 1001 | Set-ObjectProperty Interval 00:00:30# Set the upper error limit of the "Total" channel of all WMI CPU Load sensors to 90
Get-Sensor -Tags wmicpu* | Get-Channel Total | Set-ChannelProperty UpperErrorLimit 90Even properties that appear as "read-only" in PRTG can be modified by Set-ObjectProperty
# Modify the EXE/Script executed by an EXE/XML Advanced sensor
Get-Sensor -Tags xmlexesensor -count 1 | Set-ObjectProperty ExeFile newScript.ps1When modifying a property with Set-ObjectProperty, PrtgAPI performs a type lookup of the specified property and verifies that the specified value is convertable to the target type. Type information is derived from the corresponding property returned from Get-ObjectProperty (or in the case of Channels, the type of the property found on the Channel object returned from Get-Channel).
PrtgAPI understands any dependent properties a property may have, and updates the values of these properties as well to make sure the target property takes effect. For example, as the Interval property of an object is not active unless the InheritInterval property is false, PrtgAPI will update the value of this property as well. This extends to multi-level relationships
# Set the database port under the "Credentials for Database Management Systems" section
# to 8080. "DBPortMode" will also be set to "Manual", and "InheritDBCredentials" will
# also be set to $false
Get-Device -Id 1001 | Set-ObjectProperty DBPort 8080Multiple properties can be specified at once by specifying the target properties as parameter names
# Create a new device and specify its credentials
Get-Probe | Add-Device esxi-1 | Set-ObjectProperty -VMwareUserName root -VMwarePassword passwordPrtgAPI will automatically attempt to coerce the specified value to the property's target type. If the specified value cannot be parsed, PrtgAPI will throw an exception alerting you of the specified and expected type.
When using Set-ChannelProperty on channels containing scaling custom units (e.g. bytes, megabytes, gigabytes, etc) PrtgAPI will automatically ensure the request is executed in terms of the correct unit for the channel. Depending on your application however it is possible you could get tripped up by this. For more information please see Channel Units.
When entering decimal numbers with Set-ChannelProperty it is important the number format matches that of the PRTG Server (determined by your PRTG server language); i.e. if PRTG uses commas to represent decimal places, you too must use commas to represent decimal places. If the correct number format is not used, PRTG will likely truncate the specified value, leading to undesirable results. As PowerShell treats commas as arrays, it is important to indicate to PowerShell your value is not an array, such as by representing it as a string.
# Set the UpperErrorLimit to 1.1 on a PRTG server whose number format
# uses commas as the decimal point
$channel | Set-ChannelProperty -UpperErrorLimit "1,1"If the number format of your operating system does not match the number format of your PRTG server (i.e. a German copy of Windows connecting to an English PRTG server) decimal values will not be serialized correctly. You can bypass this (for both regular objects and channels) by specifying a set of custom parameters. For more information, see this issue.
Note: from PRTG 18.1.38 it is no longer possible to enable channel limits or set an error or warning message without having first set a limit value on at least one limit field (UpperErrorLimit, LowerErrorLimit, UpperWarningLimit or LowerWarningLimit). If PrtgAPI detects you are using version 18.1 or higher it will automatically validate all target channels have an existing limit value when trying to modify the ErrorLimitMessage, WarningLimitMessage or set LimitsEnabled to true. If any channels do not contain a limit value, an InvalidOperationException will be thrown, specifying the IDs of the sensors whose channel was missing a value.
Properties not yet supported by PrtgAPI can still be interacted with via the Raw Parameter Sets of the Get-ObjectProperty and Set-ObjectProperty cmdlets.
# Retrieve all properties present on the settings page of the probe with ID 2002
Get-Probe -Id 2002 | Get-ObjectProperty -RawGet-ObjectProperty -Raw returns a PSObject containing all raw properties present on an object (with trailing underscores removed from all property names). Properties that are not included in the output from GetObjectProperty -Raw can be directly requested by specifying one or more -RawProperty values. If a single -RawProperty is requested, PrtgAPI will simply return the string response from PRTG. If multiple properties are specified however, PrtgAPI will wrap the values of these properties in a PSObject for easier access.
C:\> Get-Sensor *sql* | Get-ObjectProperty -RawProperty name_,sqlquery_
name : Microsoft SQL
sqlquery : test.sqlPRTG does not support the retrieval of individual inheritance properties; as such, these properties must be retrieved via Get-ObjectProperty / Get-ObjectProperty -Raw (for supported and unsupported properties, respectively)
When retrieving option properties, by default PRTG will return the internal numeric value that is used to represent the value. The label of the selected value (as displayed in the PRTG UI) can alternatively be retrieved by specifying -Text
C:\> Get-Probe -Count 1 | Get-ObjectProperty -RawProperty sshelevatedrights -Text
Run the command as the user connecting (default)When retrieving individual object properties, please note that if your PRTG server is not in English and you attempt to retrieve an individual property that does not exist on the target object, due to limitations of the PRTG API you may receive the string "(Property does not exist)" in your server's native language.
Property values can be modified via their raw names by passing the -RawProperty and -RawValue parameters to Set-ObjectProperty
Get-Sensor ping | Set-ObjectProperty -RawProperty name_ -RawValue "Ping"By default, Set-ObjectProperty will warn you when attempting to modify raw properties to ensure you understand that this is a risky operation. This prompt can be bypassed by specifying the -Force parameter
Get-Sensor ping | Set-ObjectProperty -RawProperty name_ -RawValue "Ping" -ForceMultiple raw properties can be modified at once by specifying a hashtable
Get-Sensor ping | Set-ObjectProperty -RawParameters @{
"scheduledependency" = 0
"schedule_" = Get-PrtgSchedule "Weekdays Nine-To-Five*"
}If you prefer to extract raw property details straight from PRTG, this can typically be done by inspecting the "name" and "value" attribute of the properties <input> tag on the Settings page of PRTG.
<input class="text valid" data-rule-required="true" type="text" name="name_"
id="name_" value="dc-1">When modifying raw properties whose values are populated from dropdown lists, the raw value often has to be in the format <value>|<value>||
Get-Sensor -Tags sqlsensor | Set-ObjectProperty -RawProperty sqlquery_ -RawValue "test.sql|test.sql||"Care should be taken when interacting with raw properties (especially properties involving radio buttons), as specifying invalid values can cause minor corruption to PRTG (such as no item being selected). Any corruption that may occur can be easily rectified in the PRTG UI.
Note: unsupported channel properties cannot be modified.