Getting Started

C#

All interactions performed by PrtgAPI are accessed via the PrtgClient class. To create a PrtgClient, specify the server, username and password you wish to connect to PRTG with. All classes in PrtgAPI can be found under the PrtgAPI namespace.

var client = new PrtgClient("prtg.mycoolsite.com", "username", "password");

When called with a password, PrtgAPI will immediately attempt to resolve your PassHash - an alternate authentication scheme used by PRTG. Once your PassHash has been retrieved, your password is discarded.

If you wish to use your PassHash instead of your password, you can instruct the PrtgClient constructor to treat the passworld field as a PassHash by specifying the AuthMode parameter.

var client = new PrtgClient("prtg.example.com", "username", "123456", AuthMode.PassHash);

Depending on the performance of your PRTG install, PRTG may time out while handling a request, causing your program to throw an exception. You can tell PrtgAPI to automatically retry timed out requests by specifying the RetryCount and RetryDelay properties of your PrtgClient.

client.RetryCount = 1;
client.RetryDelay = 3;

You can be notified whenever a request is retried by hooking into the RetryRequest event handler

client.RetryRequest += (sender, args) => {
    Console.WriteLine($"{args.Exception.Message}. Retries remaining: {args.RetriesRemaining}");
};

As the PRTG is stateless, there is no need to dispose of your client after you have finished using it.

To begin retrieving data from PRTG, please see Sensors

PowerShell

To connect to a PRTG Server, call the Connect-PrtgServer cmdlet.

Connect-PrtgServer prtg.mycoolsite.com

You will be prompted to enter your credentials. If you wish to use PrtgAPI in a script you can use the New-Credential cmdlet to create a PSCredential for you

Connect-PrtgServer prtg.mycoolsite.com (New-Credential username password)

If you wish to connect using your PassHash instead of your password, you can specify the -PassHash parameter

Connect-PrtgServer prtg.mycoolsite.com (New-Credential username 1234567890) -PassHash

Once connected to a PRTG Server, you can optionally store your credentials for future use

To view your current client, invoke the Get-PrtgClient cmdlet

C:\> Get-PrtgClient

Server     : prtg.mycoolsite.com
Username   : username
PassHash   : 1234567890
RetryCount : 1
RetryDelay : 3

By default, if a connection times out (such as because PRTG is currently under high load), PrtgAPI will wait 3 seconds before making an additional attempt. The RetryCount and RetryDelay can also be specified when initializing your PrtgClient, or can also be modified afterwards

Connect-PrtgServer prtg.example.com -RetryCount 2

(Get-PrtgClient).RetryDelay = 5

Whenever PrtgAPI retries a request, a message will be sent to the PowerShell warning stream.

By using Get-PrtgClient in conjunction with Connect-PrtgServer, it is possible to allow your script to only re-connect when a session is not active.

if(!(Get-PrtgClient))
{
    Connect-PrtgServer prtg.mycoolsite.com
}

To disconnect from a PRTG Server (clear your PrtgClient) call the Disconnect-PrtgServer cmdlet.

If you attempt to call Connect-PrtgServer when already connected to a PRTG Server, you will get an error. To override this behavior (and connect to a potentially different PRTG Server) invoke Connect-PrtgServer with the -Force parameter.

Connect-PrtgServer prtg.mycoolersite.com -Force

To begin retrieving data from PRTG, see Sensors

See Also

• Sensors
• Devices
• Groups
• Probes
• Channels
• Store Credentials