How to create your own Powershell Cmdlets

A few weeks ago we introduced Unitrends PowerShell Toolkit and how to query any REST API using PowerShell and how to use a limited number of cmdlets that are currently available.

This week I am going to explain how you can create your own PowerShell Cmdlets and extend Unitrends PowerShell Toolkit available commands.

If you go to Modules folder of the Unitrends Toolkit, you will see each Cmdlet has its own .ps1 file. All these files are loaded for your use when you run .\Init.ps1 script.

Let’s start opening and exploring an easy one like Get-UebAlert.ps1 that will return a list of Alerts from the appliance.

function Get-UebAlert {
	param()

	CheckConnection
	$response = UebGet("api/reports/system/alerts")

	$obj = $response.data
	$prop = @('sname','severity','created','message')

	FormatUebResult $obj $prop
}

Each .ps1 file defines a function name that is the name of the cmdlet that we will invoke from command-line and an optional parameter list.

CheckConnection 

This function defined in Helper.ps1 file is used to verify that you have previously connected to an appliance using Connect-UebServer.

$response = UebGet("api/reports/system/alerts")

Here we are using UebGet function defined in Helper.ps1 that will use Invoke-WebRequest to do an HTTP GET operation on the API specified by parameter and will assign result to $response.

$obj = $response.data

Some APIs returns a data object so here we are just saying that the content we want to explore is inside this data property not in the root response object.

$prop = @('sname','severity','created','message')
FormatUebResult $obj $prop

These two lines are used to format the output of the Cmdlet in a table, the object result can have many properties but here we specified the main 4 properties that we want to display in table format.

You can explore all properties using Format-Table * to get all properties from the output of the Cmdlet.

Get-UebAlert|ft *

Creating a new Cmdlet to retrieve numbers of backups per asset

In the previous article we explored how we can calculate the number of backups available for each asset using this PowerShell command:

PS> (Get-UebApi -uri /api/catalog).catalog.instances|Where-Object {$_.app_type -eq "VMware"}|Select-Object database_name, system_name, @{Name="Backups";Expression={$_.backups.count}}

But this command is difficult to remember or reuse, so let’s create a simple Cmdlet Get-BackupSummary that we can run, extend and maintain with additional information in the future.

First thing is to create in Modules folder a new file Get-UebBackupSummary.ps1 and define the function Get-UebBackupSummary

function Get-UebBackupSummary {
	param(	)

	CheckConnection
	
	$response = UebGet("api/catalog")
	$instances = $response.catalog.instances
	
	[array]$vmlist = $null

	foreach($i in $instances){
		$lastbackup = $i.backups | Sort-Object -Property start_date -Descending | Select-Object -First 1

		$Object = New-Object PSObject -Property @{ 
			VM = $i.database_name
			Backups = $i.backups.count
			LastBackup = $lastbackup.start_date
		}

		$vmlist += $Object
	}

	$obj = $vmlist
	$prop = @('VM','Backups','LastBackup')

	FormatUebResult $obj $prop
}

The content of the script is similar to the one we explored before, we are using UebGet function to get data from API “api/catalog” and for each instance available in the catalog we are creating a new PSObject with the information we want to show and saving it to an array list for output.

• VM: is the vm name and is retreived from the instance.database_name
• Backups: is the number of backups available and is calculated from the number of items in the instance backups array.
• LastBackup: is the start_date of the last backup that we get sorting all backups of the instance by start_date property and getting most recent one.

If you save this file and run .\Init.ps1 again you will be able to use the command

PS> Get-UebBackupSummary

VM                Backups LastBackup
--                ------- ----------
SQLSever01		6 	12/30/2015 03:01:08 am
OracleVM01		5 	12/30/2015 03:00:55 am
OracleVM01		6 	12/30/2015 03:00:42 am
Exchange01		8 	12/29/2015 05:34:28 pm
Exchange02		1 	12/29/2015 05:06:13 pm

Upload to GitHub

If you want to share a new script with us, you need to login into github and go to our repository.

If you are not familiar with git commands to branch and commit code, you can go to UI and click in branch combo and enter the name of the new branch you want to create that should be the name of the Cmdlet you created in this case the branch name will be “Get-UebBackupSummary” and click create.

Once you have created the branch you can go to Modules folder and click “New file” file and paste the content of the script there and click commit.

We will review new scripts and merge into the main code.

Next Steps

Next article I will explain how you can extend this simple Cmdlet to add more information and calculate the RPA (Recovery Point Actual) so you can see if your backups are in compliance with your RPO goal.

RPO/RTO compliance and recovery assurance is part of ReliableDR included in Unitrends Enterprise Plus and that you can use for free until end of January 2016 as explained in: VMware ESXi 6.0 Introduced A Changed Block Tracking Bug (2136854) – Why Recovery Testing Is Critical