lordmilko/PrtgAPI v0.9.0

PrtgAPI 0.9.0

on GitHub

New Features

General

• PrtgAPI can now be instructed to ignore SSL errors with your PRTG Server. Affects all requests to your PRTG Server for the life of your process. Configured by specifying ignoreSSL in the PrtgClient constructor, or by specifying -IgnoreSSL to Connect-PrtgServer / Set-PrtgClient

  //C#
  var client = new PrtgClient("prtg.example.com", "prtgadmin", "prtgadmin", ignoreSSL: true);

  #PowerShell
  Connect-PrtgServer prtg.example.com -IgnoreSSL

C#

• Implemented a custom IQueryProvider for writing LINQ queries via IQueryable expression trees. Supports parsing any type of expression, regardless of whether or not it can be evaluated server side. For more information see Query

  client.QuerySensors(s => s.Name == "Ping").Take(3).Select(s => s.Name)

PowerShell

• Get-Sensor, Get-Device, Get-Group and Get-Probe now allow specifying dynamic parameters. Any property present on the cmdlet's respective object type can now be used as a parameter. All dynamic parameters allow specifying an array of values

  Get-Sensor -Position 1,2 -ParentId 1001,1002 -Type ping

• Get-Sensor, Get-Device, Get-Group and Get-Probe now support using their ValueFromPipeline properties as name filters as well. A single name can be specified. May contain wildcards

  Get-Sensor -Device dc-1

New Methods

• PrtgClient.GetSensor / Device / Group / Probe / NotificationAction / Schedule / Channel: retrieves and validates that a single sensor, device, group, probe, notification action, schedule or channel with a specified object ID exists. If the specified object does not exist or an ambiguous match is found, an InvalidOperationException is thrown
• PrtgClient.GetChannel / NotificationAction / Schedule: retrieves and validates that single channel, notification action or schedule exists with a specified name. If an object with the specified name does not exist or an ambiguous match is found, an InvalidOperationException is thrown
• PrtgClient.GetObjects: Retrieves uniquely identifiable objects of any type present within the PRTG Configuration File. Includes multiple overloads for synchronous, asynchronous and streaming request methods
• PrtgClient.QuerySensors / Devices / Groups / Probes / Logs: Retrieves sensors, devices, groups, probes and logs via IQueryable LINQ expressions
• Implemented several new PrtgClient.GetLogs overloads that do not require specifying an objectId, as well as several new overloads that allow specifying a custom set of LogParameters
• Implemented new RestartProbe overload. Allows specifying multiple probe IDs

New Cmdlets

• Get-Object: retrieves uniquely identifiable objects of any type present within the PRTG Configuration File, including internal system configuration nodes
• Set-PrtgClient: modifies PrtgClient / PrtgAPI Session properties after a session has been created

Improvements

Object Model

• PRTG objects modelled by PrtgAPI are now divided into three types: IPrtgObject, ISubObject and IEventObject, all deriving from a base type IObject. For information see Object Model
• SensorHistoryData, ChannelHistoryRecord, ModificationEvent and Log now implement IEventObject
• NotificationTrigger and Channel now implement ISubObject
• Implemented new LastValue property on Sensor. Displays the last raw numeric value of the sensor's primary channel
• Schedule objects now display their entire timetables, providing multiple views for inspecting the weekly schedule
• Get-ObjectProperty / Set-ObjectProperty can now pipe from any PrtgObject rather than sensors, devices, groups and probes exclusively
• It is now possible to modify and retrieve Channel Unit properties from sensors, devices, groups and probes
• ContainerSettings now include a Coordinates property that displays the latitude and longitude of the object's Location, if one is set
• ScanningInterval, TriggerChannel and NotificationTypes now implement IEquatable
• ScanningInterval and TriggerChannel now specify a TryParse method
• GetObjectPropertyRaw / Get-ObjectProperty now support specifying to use text mode, allowing option properties to return their setting labels rather than their internal values

Performance

• NotificationAction, NotificationTrigger and TableSettings objects now load Schedule objects lazily when retrieved synchronously. When retrieved asynchronously, PrtgAPI will resolve all schedules immediately, in parallel
• Expanded reflection cache to all instances of property/attribute reflection
• Reduced allocations in XML deserialization engine
• GetChannelsAsync and GetNotificationActionsAsync now execute their secondary request methods in parallel, rather than serially

Search Filters

• SearchFilter objects can now specify a custom FilterMode which specifies the extent to which PrtgAPI should perform additional transformations on the specified value to ensure it is formatted according to the requirements of the specified Property. For more information please see Filters
• New-SearchFilter now has -Illegal and -Raw parameters for specifying the FilterMode. For more information please see Filters

Streaming

• When streaming serially with a Start of 0, PrtgAPI no longer retrieves the total number of objects that exist before starting streaming. This is now extracted from the initial response
• When specifying a -Count in conjunction with a search filter on any kind of table cmdlet, PrtgAPI will now wrap the request in a new TakeIterator, ensuring as many results are returned as possible, regardless of how the server interprets the expression. For example, the expression Get-Device dc* -Count 2 may return the device "xap-dc-1". This record will be ignored and replaced with another

Parameters

• TableParameters now have new AddFilters / RemoveFilters records. Allows specifying a params of search filters
• TableParameters.SearchFilters is now self initializing. Attempting to perform parameters.SearchFilters.Add(filter) will automatically create the underlying list
• Sensor / Device / Group / Probe / NotificationAction / ScheduleParameters now have a new constructor that takes a params of SearchFilter
• Objects are now ordered by Id and Name by default, rather than Probe

Cmdlets

• Get-Device now explicitly defines a -Host parameter. Allows filtering by one or more Host properties of a device
• New-TriggerParameters now supports piping from a sensor, device, group or probe rather than manually specifying an -Id
• Get-NotificationTrigger now supports specifying an array of -OnNotificationAction or -Type
• Get-ObjectLog now specifies an -Id parameter. Allows filtering by a single specified object ID
• Get-ObjectProperty now specifies a -Text parameter. When specified in conjunction with a -RawProperty, allows returning the label of an option property, rather than its internal numeric value
• If a -Count is specified to Get-SensorHistory without specifying an -EndDate, Get-SensorHistory will dynamically calculate the required end date to retrieve the specified number of items, based on the object's Interval or the specified -Average
• Connect-PrtgServer now allows specifying a -LogLevel
• Get-Sensor no longer streams in parallel. Cancelling a large Get-Sensor request no longer causes a delay in executing the next API request

Debugging

• PrtgClient now defines a LogLevel property, allowing one or more LogLevel flags to be specified indicating the types of records that should be emitted to the LogVerbose event handler. Supported log levels include Request, Trace and Response

Bugfixes

Object Model

• ScanningInterval now considers two objects equal if they are both convertable to the same ScanningInterval, regardless of their underlying type
• TriggerChannel now considers two objects equal if they are both convertable to the same TriggerChannel, regardless of their underlying type
• NotificationTypes now considers two objects equal if they are both of the same type, have the same number of triggers of each type and have the same inheritance
• Fixed TriggerChannel objects containing a Channel incorrectly being converted to a StandardTriggerEnum (Fix #27)
• Fixed Notification Triggers failing to resolve channels containing the same name as StandardTriggerChannel values (such as "Total") to Channel objects
• Fixed sensor history records treating speed/volume channels in traffic sensors as having the being channels containing value lookups, resulting in multiple ChannelHistoryRecord objects containing the same name
• Fixed Get-SensorHistory not displaying speed channels of traffic sensors at all
• Fixed DeviceTemplate.GetHashCode not being unchecked

Targets

• ExeFileTarget / SqlServerQueryTarget now return null upon attempting to instantiate a new sensor target from null, instead of returning a new sensor target encapsulating the null value
• ExeFileTarget / SqlServerQueryTarget will now throw upon being instantiated with string.Empty
• Fixed an issue wherein ExeFileTarget.Parse / SqlServerQueryTarget.Parse failed to parse unserialized strings (e.g. ExeFileTarget.Parse("test.ps1"))

Search Filters / Requests

• Fixed bool not serializing properly in search filters
• Fixed bool not serializing property when used as a Parameter value
• Fixed Active, Downtime, TotalDowntime, DownDuration, Favorite, Uptime, TotalUptime, UpDuration, TotalMonitorTime, Interval, LastValue, UpSensors, DownSensors, DownAcknowledgedSensors, PartialDownSensors, WarningSensors, PausedSensors, UnusualSensors, UnknownSensors, TotalSensors, Url, Collapsed, TotalGroups, TotalDevices and Position not filtering properly when used with certain FilterOperator values
• Favorite, NotificationTypes and properties of type string will now prevent you from filtering by certain FilterOperator values by default that PRTG
  is incapable of evaluating. This can be overridden by specifying a custom FilterMode value
• Fixed an issue wherein PrtgAPI would crash when attempting to filter by string.Empty due to PrtgAPI expecting the server version to be included in the response
• Fixed an issue wherein table cmdlets failed to process search filters properly when both specified via -Filter and a parameter that takes pipeline input
• Fixed an issue with geographic lookups no longer resolving in PrtgAPI 18.2.41+ due to a change in how the request must be formatted
• Fixed an issue with GetObjectProperty / Get-ObjectProperty failing to retrieve single properties that include invalid XML characters (Fix #33)
• Fixed several GetDevices / Groups / Probes overloads filtering by string values only instead of allowing filters of any type

Streaming

• Stream methods now clone the source parameters and as such no longer modify
  the Count and Start properties of the original parameters object
• PrtgAPI now supports streaming objects that do not start their indexes at position 0, which would otherwise result in duplicates being returned between the first and second pages of the response
• LogParameters now stipulate that logs start at index 1, rather than index 0
• PageableParameters now report a Page of 0 when Count is 0, instead of crashing
• Fixed an issue wherein specifying a Start offset and a large or unlimited Count would cause PrtgAPI to retrieve too many records, cutting into the records that should have been skipped
• When retrieving the total number of objects that PrtgAPI will stream, PrtgAPI now uses any SearchFilters that have been specified on the parameters, ensuring a more accurate result is calculated

Parameters

• Fixed a bug wherein SensorParameters.Status did not return all Status objects when multiple objects were stored in a single search filter
• SensorParameters.Status no longer crashes if an object not of type PrtgAPI.Status is stored in a filter on Property.Status
• Fixed an issue wherein DynamicSensorParameters would crash upon retrieving no sensor targets for a property that supports targets (such as because the device's probe is disconnected)

Cmdlets

• Fixed an issue wherein Connect-PrtgServer -Progress:$true did not enable progress where it would otherwise be disabled
• Fixed -Count not working properly on Get-Sensor, Get-Device and Get-Group used in conjunction with -Recurse:$true when piping from groups
• Fixed Get-Group not working properly when piping from another group with -Recurse:$true and specifying one or more search filters. i.e. Get-Group -Id 1001 | Get-Group Servers would not find any grandchildren under any children not named "Servers"
• Fixed an issue wherein -Count was sometimes incorrectly handled by Get-SensorHistory when used in conjunction with an -EndDate
• Fixed an issue wherein Get-ObjectLog did not filter properly when specifying a -Count in conjunction with a client side search filter (such as -Name)
• Fixed an issue wherein Restart-PrtgCore did not wait properly with -Wait:$true

Breaking Changes

Object Model

• Channel and Log no longer derive from PrtgObject
• Renamed Log and PrtgObject property Type to DisplayType and property RawType to Type
• The raw type of a Log / PrtgObject (property Type) is now a StringEnum<ObjectType> capable of modelling well known and unknown types
• Renamed DeviceOrGroup property and Property enum value UndefinedSensors to UnknownSensors
• Renamed SensorOrDeviceOrGroupOrProbe property IntervalInherited to InheritInterval
• It is no longer possible to filter by InheritInterval
• Merged type ObjectTable with PrtgObject
• Renamed property LastValue to DisplayLastValue on both Channel and Sensor
• Renamed Channel property LastValueNumeric to LastValue
• Sensor properties Downtime and Uptime now store their values as nullable doubles instead of strings
• Channel property Unit now correctly displays when the PRTG Server language is a language other than English
• Renamed TriggerUnitSize, TriggerVolumeUnitSize and TriggerUnitTime to DataUnit, DataVolumeUnit and TimeUnit respectively
• ContainerSettings properties SSHEngine and VMwareSessionMode are now nullable for compatibility with older versions of PRTG
• Renamed RecordAge.AllTime to RecordAge.All
• TriggerParameters.SubId is now an int? instead of a string
• Renamed RestartProbeProgress to ProbeRestartProgress
• The callback specified to RestartProbe now takes an immutable array of ProbeRestartProgress instead of a List<ProbeRestartProgress>
• The RestartProbe overload taking a single probe ID now only sends a single ProbeRestartProgress object to its callback

Search Filters

• It is no longer possible to filter by string.Empty. This can be overridden by specifying a custom FilterMode

Parameters

• Renamed base Parameters type to BaseParameters
• IParameters.GetParameters() now returns an IDictionary rather than a Dictionary
• ContentParameters.Properties setter is now internal
• Renamed TableParameters.SearchFilter to TableParameters.SearchFilters
• TableParameters.SearchFilters is now a List<SearchFilter> rather than an array. If you attempt to interact with this property before it has been initialized, it will now automatically instantiate, store and return a new list for you

Cmdlets

• Connect-PrtgServer parameter -Progress is now a SwitchParameter rather than a bool. Progress can now be disabled by specifying -Progress:$false rather than -Progress $false
• Renamed Get-ObjectLog parameter -Since to -Period

Accessibility

• ParallelObjectGenerator, SerialObjectGenerator, SensorTypeInternal, CategoryAttribute, ObjectPropertyCategory, Output and ProcessingOption are now internal
• Deleted unused exception type UnknownTypeException

Namespaces

• Moved all sensor targets to namespace PrtgAPI.Targets