Tree Creation

Contents

• Object Model
• Tree Creation
  • C#
    • Automatic
    • Manual
    • Progress
  • PowerShell
    • Automatic
    • Manual
• Tree Manipulation

C#

Automatic

The tree of a PRTG Object can be retrieved via the GetTree method.

//Model the tree of the object with ID 1
var tree = client.GetTree(1);

//Model the tree of a specified device
var tree = client.GetTree(device);

GetTree automatically traverses all descendants of the specified object, constructing PrtgNode objects for each item encountered. For large PRTG Trees, this can potentially be quite time consuming. Progress can be monitored by implementing a custom ITreeProgressCallback.

Manual

For creating PRTG Trees for rearranging PRTG Objects, PrtgAPI provides two mechanisms for creating arbitrary PrtgNode objects

• PrtgNode factory methods
• PrtgNodeFactory instance methods

Similar to the Expression class in System.Linq.Expressions, PrtgNode serves as both the base class of all PRTG node types but also defines static factory methods that can be used for generating a new instance of a node type from a specified ITreeValue and optional children.

//Construct a tree where the sensor with ID 2002 is a child of the device with ID 1001
var device = client.GetDevice(1001);
var sensor = client.GetSensor(2002);

var node = PrtgNode.Device(device,
    PrtgNode.Sensor(sensor)
);

PrtgNodeFactory is similar to the SyntaxFactory class found in Roslyn. It is a completely separate type from the more familiar PrtgNode type and is capable of executing API requests and constructing PrtgNode objects for you, all in one go.

//Construct a tree where the sensor with ID 2002 is a child of the device with ID 1001
var factory = new PrtgNodeFactory(client);

var node = factory.Device(1001,
    factory.Sensor(2002)
);

If you wish to retrieve and encapsulate multiple objects at once, PrtgNodeFactory defines simple Property, object overloads for filtering objects by a specified value.

//Create SensorNode objects for all sensors named "Ping"
var node = factory.Sensors(Property.Name, "Ping");

PrtgNodeFactory methods always return at least one object. Methods that retrieve a single object (Sensor, Device, Group, etc) assert that only one object was found, similar to how their equivalent methods on PrtgClient perform (GetSensor, GetDevice, etc).

For methods that perform more advanced filtering that could potentially return a collection of objects, PrtgNodeFactory simply asserts that at least one object was returned. This behavior protects you against creating a tree where mandatory nodes are actually missing.

Progress

Constructing a PrtgNode tree from an entire PRTG Object hierarchy can be an extremely time consuming progress. You can monitor the progress of this process however by defining a custom progress callback for retrieving notifications of progress as PrtgAPI traverses the tree. This is done by defining an implementation of an ITreeProgressCallback.

ITreeProgressCallback defines four members that must be implemented by your type

Name	Description
DepthManager	Tracks the depth at which PrtgAPI has traversed and makes adjustments to the progress output device as required
OnLevelBegin	Called when a new level has begun, specifying the level we're now at and information about the object whose children we'll be retrieving
OnLevelWidthKnown	Called when the total number of items that exist at the current level is finally known
OnProcessValue	Called when the next object at the current level is to be processed

The following provides a simple example of how a progess callback can be used for writing to the console

internal class ConsoleTreeProgressCallback : ITreeProgressCallback
{
    public DepthManager DepthManager { get; } = new DepthManager();

    public void OnLevelBegin(ITreeValue parent, PrtgNodeType parentType, int depth) =>
        WriteLine($"OnLevelBegin: Parent = {parent}, Type = {parentType}, Depth = {depth}");

    public void OnLevelWidthKnown(ITreeValue parent, PrtgNodeType parentType, int width) =>
        WriteLine($"OnWidthKnown: Parent = {parent}, Type = {parentType}, Width = {width}");

    public void OnProcessValue(ITreeValue value) =>
        WriteLine($"OnProcessValue: {value}");

    private void WriteLine(string str)
    {
        var indent = new string(' ', (DepthManager.Depth - 1) * 4);

        Console.WriteLine($"{indent}{str}");
    }
}

Output:

OnLevelBegin: Parent = Root, Type = Group, Depth = 1
OnWidthKnown: Parent = Root, Type = Group, Width = 1
OnProcessValue: Local Probe
    OnLevelBegin: Parent = Local Probe, Type = Probe, Depth = 2
    OnWidthKnown: Parent = Local Probe, Type = Probe, Width = 2
    OnProcessValue: Probe Device
        OnLevelBegin: Parent = Probe Device, Type = Device, Depth = 3
        OnWidthKnown: Parent = Probe Device, Type = Device, Width = 6
        OnProcessValue: System Health
            OnLevelBegin: Parent = System Health, Type = Sensor, Depth = 4
...

PowerShell

Automatic

Manual