jstott / PrtgAPI

C# library for interfacing with the PRTG HTTP API

PrtgAPI

PrtgAPI is a C# 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. Upon executing a request, PrtgAPI will deserialize the result into an object (Sensor, Device, Probe, etc) that the programmer can further interface with.

Usage

All actions in PrtgAPI revolve around a core class: PrtgRequest

var request = new PrtgRequest("prtg.mycoolsite.com", "username", "password");

When a PrtgRequest is created, it will immediately attempt to retrieve your user's passhash (an alternative to using a password) from your PRTG Server. For added security, your PassHash is then used for all future PRTG Requests made during the life of your program.

For debugging purposes, you are able to use your passhash to PrtgRequest instead of using your password. Simply create a breakpoint after the PrtgRequest constructor call has executed, copy your passhash out of your request object's private passhash property then tell the constructor to use the passhash instead.

var request = new PrtgRequest("prtg.mycoolsite.com", "username", "1234567890", AuthMode.PassHash);

Lists

PrtgAPI provides a series of method overloads for retrieving all sorts of data in a variety of different ways.

To retrieve a list of all sensors, call the GetSensors() method.

var sensors = request.GetSensors();

For groups, call GetGroups(); Devices, call GetDevices(), etc.

Typically however, you'll want to apply one or more filters to limit the number of objects returned (and increase the speed of the HTTP GET request).

//List all sensors in a "down" state.
var downSensors = request.GetSensors(SensorStatus.Down);

//List all devices under probes whose name contains "chicago"
var chicagoProbeDevices = request.GetDevices(Property.Probe, FilterOperator.Contains, "chicago");

//List all sensors under the Device with Object ID 2000.
var childSensors = request.GetSensors(Property.ParentId, "2000");

PrtgAPI methods that return values typically return a List of objects, allowing you to use LINQ to retrieve the values you're really after.

var names = request.GetSensors(SensorStatus.Unknown).Select(s => s.Name).ToList();

Many method parameters are implemented as params, allowing you to specify multiple values just by adding additional commas.

var variousSensors = request.GetSensors(SensorStatus.Down, SensorStatus.Up, SensorStatus.DownAcknowledged);

//Get all Ping sensors for devices whose name contains "dc" on the Perth Office probe.
var filters = new[]
{
    new ContentFilter(Property.Type, "ping"),
    new ContentFilter(Property.Device, FilterOperator.Contains, "dc"),
    new ContentFilter(Property.Probe, "Perth Office")
};

var perthDCPingSensors = request.GetSensors(filters);

Object Settings

Values of object settings can be enumerated and manipulated via two groups of overloaded methods: GetObjectProperty and SetObjectProperty

//Retrieve the name of object with ID 2001
var name = request.GetObjectProperty(2001, BasicObjectSetting.Name);

//Update the name of object with ID 2001
var name = request.SetObjectProperty(2001, BasicObjectSetting.Name, "a brand new name!");

By default, GetObjectProperty will return a string containing the value you requested. If you know for a fact the property is of another type (an enum defined by PrtgAPI, or an integer) you can request GetObjectProperty cast its return value to its "true" data type.

var priorityNum = request.GetObjectProperty<int>(2001, BasicObjectSetting.Priority);
var priorityEnum = request.GetObjectProperty<Priority>(2001, BasicObjectSetting.Priority);

Custom Requests

For those that which to execute custom requests (i.e. those not yet supported by PrtgAPI, or those not known to be supported by PRTG) it is possible to craft custom requests that do whatever you like.

//Return only the "name" and "object ID" properties, limiting the number of results returned to 100.
var parameters = new SensorParameters()
{
    Properties = new[] { Property.Name, Property.ObjId }
    Count = 100
};

var sensors = request.GetSensors(parameters);

PrtgAPI implements a number of built-in parameter types that automatically specify the type of content their requests will retrieve. If you wish to implement your own custom parameters, you can do so by manipulating the base Parameters class.