Friday, 2 October 2015

Getting Started with foreScript

Getting Started with foreScript

I have been using Powershell for some time now and I think that it is a great addition to the toolset of an IT Professional. However the more I used Powershell, the more I found myself having  to write the same pieces of code over and over again in my scripts. Those pieces of code had to do with:

  • Getting a list of computers to run the script against - You know the drill and that meant using a cmdlet to get a list of computers from either a csv file, or a text file, or the command line.
  •  Getting the information for user authentication - If I wanted to run the script as another user I would end up either prompting for the required credentials, or elevating privileges at run time, or even running Powershell as an administrator.
  • Formatting the output of the Powershell scripts for display purposes - This speaks for itself. I have written quite a few Powershell scripts that have code that is only used for converting the  output  into html.

I could have written a module that would handle all of those issues for me and use that module in every Powershell script that I wrote. However I wanted to do much more than that. I wanted to  create a framework that would support the execution of Powershell scripts.


Enter foreScript

This is something that I have worked on for the past several months and it is written in Powershell and uses some inline C# code. It is called foreScript and it is a GUI based tool that executes Powershell scripts using  a runspacepool.

The foreScript UI

The foreScript framework has the following features:

  • foreScript provides a GUI interface that allows us to retrieve computer objects from several sources and these include an input text box, a text file or a Windows DHCP Server. The computer objects are then passed to the runspacepool via the pipeline as the $ComputerName variable.
  • foreScript provides the capability to do Wake-On-LAN (WOL) using the Windows DHCP Server in either a  local or a remote LAN. foreScript will query the Windows DHCP Server and obtain the list of MAC Addresses in a particular ip subnet and then use these MAC addresses to create WOL packets.
  •  foreScript  supports the use of alternate user  credentials to execute the Powershell scripts. foreScript provides an $FS_Credential variable that can be accessed in the runspaces and this $FS_Credential variable can be passed to  any cmdlet that supports a Credential parameter. foreScript also supports impersonation in the runspace or the combination of the $FS_Credential variable and impersonation.
  •  foreScript expects the  Powershell scripts to return objects and will display the output in either the console or as an HTML report.  The HTML reports are based on templates. foreScript also supports the display of custom objects that are actually C# classes using custom formatters and converters. The custom formatter can be accessed in the runspaces by using the Format-FSTypes function.
  • foreScript uses json for data exchange.
  • foreScript provides a batch mode that can be used to automate the execution of the Powershell script against computer objects. The batch mode uses a csv file as input.

Getting Started

To use an existing Powershell script in foreScript it has to be added to the psscripts.json file in the Config folder. The psscripts.json is read by foreScript at startup and the contents of the file is added to an Observer able Collection that is displayed in the GUI under the Scripts tab.

A sample of the configuration entry for the Get-Diskspace.ps1 Powershell script is as follows:

{      "name": "Hard disk space usage",
       "author": "Nigel Thomas",
       "description": "This script is used to get the hard disk usage on computers.",
       "folder": "computer",
       "file": "Get-Diskspace.ps1",
       "authtype": "credential",
       "template": "FSHardDiskUsage.tpl",
       "callback" : "",
       "warn" : "false"            }

The following table provides an explanation of each attribute in the psscripts.json file:

Attribute
Description
Value
name
The name attribute is used to provide a descriptive name for the Powershell script
A string providing the descriptive name
author
The author attribute is used to provide the name of the person who wrote the script
A string providing the authors name
description
The description attribute is used to provide further details on the actual usage of the script
A string providing the description
folder
The actual folder that the script can be found in. The folder must be created under the PSSCripts folder.
A string providing the name of the actual folder
authtype
The authtype attribute is used to provide the authentication methods that is required by the script.
A string providing one of the following authentication methods:
  •  credential
  • impersonation
  • combined
template
The template attribute is used to provide the name of the HTML based template that will be used to display the output of the Powershell script. If the name of an HTML template is not provided then the output of the Powershell script will be displayed in the console.
A string providing the name of the actual HTML template.
callback
The callback attribute is used to enable the call back button on the foreScript UI and to provide the content that will be displayed on the  call back button.
A string providing the content that will be displayed on the call back button.
warn
The warn attribute is used to alert the person executing the Powershell script that they are about to execute a script that is going to do something  that could have dire consequences. As an example the script could be changing the password for the local administrator account. Do not set the warn attribute to true in scripts that will be run in batch mode.
A string that can be set to either: 
  • true
  • false



The next steps

foreScript can be downloaded from my GitHub repository.  Please feel free to download it and to tell  me what you like and don't like about foreScript. foreScript is still very much a work in progress and I am appreciative of any feedback that will help to improve foreScript.