PowerShell

Prerequisites

WhatsUp Gold uses a 32-bit (in other words, "x86") PowerShell engine. Only 32-bit PowerShell snap-ins are supported and 64-bit only snap-ins will not function properly. Snap-ins that work on both 32-bit and 64-bit operating systems are configured for 64-bit systems by default and must be manually configured for 32-bit PowerShell engine to function properly with WhatsUp Gold.

Remote Connection Requirements

Ensure the following are in place for enabling the WhatsUp Gold machine to connect using PowerShell to the destination (polled) device.

• Windows Credentials. Credentials must be used explicitly using the methods and properties provided by the Context object. HTTPS must be used as transport or polled device must be in TrustedHosts list of the machine where WhatsUp Gold is running.
• Domain and hostname. If you use user's default credentials. To use IP address alone, you will need to specify credentials at PowerShell/WinRM login. (For more info see this WinRM troubleshooting help.)
• Enable-PSRemoting. Enable PowerShell remoting on destination (polled) device. For more information see link to MSDN documentation provided.

Monitor Configuration

Configuration fields for this active monitor include:

• Name. Enter a unique name for the active monitor. This name displays in the Monitor Library.
• Description. (Optional) Enter additional information about the monitor. This description displays next to the monitor name in the Monitor Library.
• Timeout (Seconds). Enter the length of time WhatsUp Gold attempts to connect to the selected device.
• Run under device credentials. Enable this check box to execute the script using the Windows credentials for the device.
• Script text. Enter your active monitor code.

Available Monitor Objects and Attributes

PowerShell active monitor scripts have two instantiated session objects available.

• Context. Implementation of the IScriptContext interface. This object provides access to runtime variables and also provides mechanism for returning results to the client. A few useful methods are listed below:
  • object GetProperty(string propertyName) - allows retrieval of context variable values by name.
  • object SetProperty (string propertyName, string propertyValue ) - allows specification of context variable values by name.
  • void SetResult(int resultCode, ResultsString) - allows the script to set a value to indicate success, usually 0 = success and 1 = failure.
• Logger. Implementation of the ILog interface. This object provides the same methods available to C# applications. A few useful methods are listed below:
  • void Error(string message) - Creates an error-specific log entry that includes the message.
  • void Information(string message) - Creates an information-specific log entry that includes the message.
  • void WriteLine(string message) - Creates a generic log entry that includes the message.

Getting or Setting Properties for a Context Object

You can fetch values for context properties using PowerShell active monitor scripts.

Syntax

Property-Value = Context.GetProperty("Property-Name")

Context.SetProperty(" Property-Name "," Property-Value ")

Example

$DeviceIpAddress = $Context.GetProperty("Address")

$Context.SetProperty("Timeout", "180")

Setting Result String and Monitor Status Indicator

The result string you set will be added to the description in the monitor's status change. The status flag you set (0, 1) up/down determines the indicator shown in the State Change Timeline.

# After a successful Get of the deviceIP, Set as result and set success flag ...

$Context.SetResult(0, "Device IP address is: " + $DeviceIpAddress)

Context Object Properties

The following properties can be accessed from the connection object created when running PowerShell Active Monitor Script Syntax Examples.

Context Object Credential Properties

The following credential properties can be set for thePowerShell Active Monitor Script Syntax Examples. These are useful when you need to connect to other services, platforms, or applications after the initial PowerShell connection is made using the active monitor.

Example: Check if Service is Running

Create a PowerShell active monitor that shows status of up only if DNS client is running using stored credentials.

# Device to Poll

$DeviceIpAddress = $Context.GetProperty("Address")

# Set the computer name directly, or...

# $CompName = mydb02.corpnet.example.com (for example)

# ...get it using WMI...

$WmiRes = Invoke-Command -ComputerName $DeviceIpAddress -ScriptBlock { Get-WmiObject Win32_Computersystem }

$CompName = $WMIRes.PSComputerName

# Run command on remote device

$PsResult = Invoke-Command -ComputerName $DeviceName -ScriptBlock { Get-Service | where { $_.Name -match "Dnscache" } }

# Check for condition of 'running'

if ($PsResult.Status -match 'Running') {

$RespondingMessage = "Process '" + $processName + "' running on " + $DeviceIpAddress + " is responding."

$Context.SetResult(0, $RespondingMessage )

} else {

$NotRunningMessage = "Process '" + $processName + "' running on " + $DeviceIpAddress + " is not responding."

$Context.SetResult(1, $NotRunningMessage )

}