PrtgAPI

Author(s)

• lordmilko

Tags

Prtg Sensor Device Group Probe Channel Notification Action Trigger Remove Pause Resume Check Acknowledge PowerShell Setting Property

Cmdlets

Disable-PrtgProgress Enable-PrtgProgress Get-SensorTarget Add-Device Add-Group New-DeviceParameters New-GroupParameters Backup-PrtgConfig Clear-PrtgCache Sync-PrtgConfigFile Restart-PrtgCore Restart-Probe Get-ObjectLog Add-Sensor Get-SensorFactorySource New-SensorParameters Get-SensorHistory Move-Object Set-ObjectPosition Test-ErrorStatus Start-SortPrtgObject Open-PrtgObject Start-AutoDiscovery Copy-Object New-SensorFactoryDefinition Add-NotificationTrigger Set-NotificationTrigger Edit-NotificationTriggerProperty Get-NotificationAction Get-PrtgStatus Get-NotificationTrigger Get-ModificationHistory New-NotificationTriggerParameters Remove-NotificationTrigger Set-ObjectProperty Confirm-Sensor Get-Channel Get-Group Get-Probe Get-ObjectProperty Get-PrtgClient Get-SensorTotals Update-Object Suspend-Object Rename-Object Resume-Object Set-ChannelProperty Remove-Object Get-Device Connect-PrtgServer Disconnect-PrtgServer Get-Sensor New-SearchFilter

Functions

New-Credential Connect-GoPrtgServer Get-GoPrtgServer Install-GoPrtgServer Set-GoPrtgAlias Uninstall-GoPrtgServer Update-GoPrtgCredential

Dependencies

This module has no dependencies.

Release Notes

New Features
----------------

General

* Compatible operations now support specifying multiple Object IDs in a single request (e.g. acknowledging, pausing, modifying properties, etc). Cmdlets of operations that now support specifying multiple Object IDs will now execute in Batch Mode by default, queuing all records received from the pipeline so they can be processed at once via a single API call. All operations that support Batch Mode now execute infinitely faster. Batch Mode can be disabled by specifying -Batch:$false
* Sensor Targets used for creating new sensors including EXE/Advanced Script files, WMI Services and Microsoft SQLv2 database queries can now be resolved from PRTG. Sensor Targets resolved from one object can then be passed assigned to sensor parameter objects and assigned to any device within PRTG.
* Implemented support for retrieving all raw properties (settings) of an object. In C#, these are returned as a dictionary, whereas in PowerShell these are returned as a PSObject

PowerShell

* Implemented new -PassThru parameter on all operation cmdlets that take pipeline input. When specified, the input object to the cmdlet will also be emitted after executing the cmdlet's operation, allowing for mutiple operations to be chained together in a single pipeline
* Implemented new -SourceId parameter to Clone-Object, allowing a single object to be cloned to multiple objects passed in through the pipeline
* PrtgAPI will now automatically resolve any new objects that are created by PrtgAPI cmdlets by default (including Add-Sensor, Add-Device, Add-Group, Add-NotificationTrigger and Clone-Object). Resolution of created objects can be disabled by specifying -Resolve:$false
* PrtgAPI will now show progress when executing a pipeline containing Select-Object surrounded by PrtgAPI cmdlets. PrtgAPI will only show progress when Select-Object is used as the first or second cmdlet in the pipeline. If Select-Object is used at any point beyond the second cmdlet, progress will be disabled for the entirety of the pipeline
* When piping Get-Sensor, Get-Device or Get-Group from parent groups returned by Get-Group, PrtgAPI will now recurse all child groups under the parent group, returning all target objects under the entire object hierarchy. Resolution of objects only under the parent group can be performed by specifying -Recurse:$false

New Methods
---------------

* PrtgClient.AddDevice: create a new device from a set of device parameters
* PrtgClient.AddGroup:: create a new group from a set of group parameters
* PrtgClient.Targets.GetExeXmlFiles: list all files under the Custom Sensors\EXEXML folder of a device's PRTG Probe
* PrtgClient.GetObjectPropertiesRaw: Retrieves all raw properties defined on an object
* PrtgClient.GetObjectProperty: Retrieves a property from a PRTG object as an object of its true type
* PrtgClient.GetObjectProperty<T>: Retrieves a property from a PRTG object cast to its true type
* PrtgClient.Targets.GetWmiServices: list all WMI Services installed on the target device
* PrtgClient.Targets.GetSqlServerQueries: list all files under the Custom Sensors\sql\mssql folder of a device's PRTG Probe

New Cmdlets
---------------

* Add-Device: create a new device from a set of device parameters
* Add-Group: create a new group from a set of group parameters
* New-DeviceParameters: create a set of parameters for creating a new device
* New-GroupParameters: create a set of parameters for creating a new group
* Get-SensorTarget: resolve sensor targets (such as WMI Services or EXE/Script files) that can be used for creating a new sensor

Improvements
----------------

General

* Improved deserialization performance by 100%
* PrtgAPI will now throw much more informative exception messages when failing to deserialize enum members
* RestartCore / RestartProbe (C#) and RestartPrtgCore / RestartProbe (PowerShell) now support waiting for the specified targets to restart before completing. C# methods provide a progress callback to allow monitoring or aborting the wait request
* Implemented support for creating WMI Service sensors
* PrtgAPI will now automatically resolve any DescriptionAttribute defined on an enum used in a set of custom request parameters
* If an IEnumerable is assigned to a SearchFilter, PrtgAPI will now iterate over the collection constructing a filter for each item
* Increased default maximum number of items returned by ContentParameters from 50,000 to unlimited
* ContainerSettings and SensorSettings ToString now returns the object's Name

Object Properties

* Implemented support for retrieving and modifying Hostv4, Hostv6, ServiceUrl, AutoDiscoveryMode, AutoDiscoverySchedule and Comments
* Implemented Host property alias for Hostv4
* Implemented support for modifying and retrieving Microsoft SQL v2 sensor properties
* Implemented support for retrieving a device's IPVersion. IPVersion is automatically updated upon setting Hostv4 or Hostv6
* Implemented support for modifying all password related fields. Settings objects now contain Has- properties (HasWindowsPassword, HasLinuxPassword, etc) to indicate whether these values have explicitly been set on the target object
* Get-ObjectProperty parameter -RawProperty can now take multiple property names. If a single property is specified, its value is returned as a string. If multiple properties are specified, a PSObject containing all property values is returned
* Implemented new -Raw parameter for Get-ObjectProperty. If specified, Get-ObjectProperty will return all raw properties defined on the object
* Implemented new -Property parameter on Get-ObjectProperty. Allows specifying a single property to retrieve.

C#

* Implemented support for specifying a SortDirection on TableParameters
* Methods that support streaming (and do not do any filtering) now take an optional argument specifying whether the request should be executed serially

PowerShell

* Probes will now show their Condition (Connected / Disconnected) by default when shown in table view instead of their Status (Up / Paused)
* Devices will now show their Host by default when shown in table view
* Sensors, Devices, Groups and Probes now order their output according to their position under their parent object as shown in the PRTG UI
* Get-Channel now supports filtering based on an array of Channel IDs
* PrtgAPI objects now show their Name property in progress records displayed by inter-cmdlet progress
* Implemented support for cloning NotificationTrigger objects with Clone-Object. Equivalent to piping to New-TriggerParameters followed by Add-Trigger
* When adding a new sensor Add-Sensor will now automatically remove any spaces PRTG erroneously adds around the new sensor name
* Cmdlets will now show inter-cmdlet progress when piping from a single variable inside a nested pipeline

Bugfixes
------------

General

* PrtgAPI will now validate the response returned from PRTG when attempting to resolve an address for use with ObjectProperty.Location

C#

* Fixed a bug wherein RenameObject did not rename probes properly
* Fixed Parameter.SortBy not working due to a missing ParameterTypeAttribute

PowerShell

* Fixed several scenarios wherein progress records would not complete after the execution of multiple PrtgAPI cmdlets chained together
* Install-GoPrtgServer no longer emits output when creating the PowerShell profile when it did not previously exist
* Fixed a bug wherein -Status parameter did not properly work when attempting to filter devices, groups and probes
* Fixed New-SensorParameters including the sensor type in the CustomParameters list, resulting in the sensor type being specified twice in the API request
* Fixed Set-ChannelProperty Manual parameter set not displaying cmdlet target properly when invoked with -WhatIf
* Fixed a bug wherein inter-cmdlet progress would not be enabled by default after updating your GoPrtg credential with Update-GoPrtgCredential

Breaking Changes
--------------------

General

* Renamed ExeName object property to ExeFile on both enum ObjectProperty and ExeXmlSensorParameters
* Split settings property SSHElevationUser into SSHElevationSuUser and SSHElevationSudoUser properties
* Changed SensorSettings.DependentObjectId from string to int?

C#

* Moved Priority property to base NewSensorParameters class. NewSensorParameters constructor now requires a Priority be specified, with RawSensorParameters including Priority as an optional argument. If Priority is not specified to RawSensorParameters, a default priority of Three will be used

PowerShell

* Combined Clone-Sensor, Clone-Device and Clone-Group into single Clone-Object cmdlet
* Renamed -StartIndex parameter of New-SensorFactoryDefinition to -StartId
* Renamed -Name and -Value properties of New-SensorParameters to -First and -Second. Meaning of these parameters is dependent on the type of sensor parameters being generated
* Renamed -Item parameter of New-SensorFactoryDefinition to -Sensor

---

PrtgAPI is a C#/PowerShell library that abstracts away the complexity of interfacing with the PRTG HTTP API.

PrtgAPI implements a collection of methods and enumerations that help create and execute the varying HTTP GET requests required to interface with PRTG. All responses from PRTG are automatically deserialized by PrtgAPI and formatted appropriately when output to the pipeline (when using PowerShell)

All cmdlets in PrtgAPI support some level of piping, allowing you to directly chain multiple cmdlets together, further filtering search results as you go.

PrtgAPI supports a number of undocumented features, including manipulating notification triggers, and viewing and editing channel properties (error limits, etc).

PrtgAPI includes full Cmdlet Comment/XmlDoc documentation. Detailed information on any cmdlet can be found within PowerShell by running Get-Help <cmdlet> or Get-Help <cmdlet> -Full

For examples and usage scenarios, please see the Project Site.