Property Manipulation

lordmilko edited this page Jan 10, 2019 · 52 revisions

Contents

Overview

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

C#

Retrieving Properties

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();
//Retrieve all device properties
var deviceProperties = client.GetDeviceProperties();

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.

Modifying Properties

Properties for all supported 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");
//Change the UpperErrorLimit of the channel with ID 2 on the sensor with ID 1002 to 100
client.SetObjectProperty(1002, 2, ChannelProperty.UpperErrorLimit, 100);

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.ExeName, "newScript.ps1");

When modifying a property with SetObjectProperty, 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. 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")
);

When using SetObjectProperty on channels that use custom units, take into account the unit when specifying your value. e.g. a sensor may have a LastValue in megabytes, however its actual value may be in bytes. You can confirm the numeric value of a channel by referring to the LastValueNumeric property.

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.

Wrapper Types

Certain 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.

Unsupported Properties

For properties not yet supported by PrtgAPI's type system, it is still possible to retrieve such properties via the GetObjectPropertiesRaw method.

//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.

PowerShell

Retrieving Properties

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.sql

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, 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

Modifying Properties

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 90

Even 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.ps1

When modifying a property with SetObjectProperty, 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. 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 8080

Multiple 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 password

PrtgAPI 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 that use custom units, take into account the unit when specifying your value. e.g. a sensor may have a "display value" in megabytes, however its actual value may be in bytes. You can confirm the numeric value of a channel by referring to the LastValue property.

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        : 1169711104

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.

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.

Unsupported Properties

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 -Raw

Get-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.sql

PRTG 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" -Force

Multiple 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.

See Also

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.