PowerShell Scripting Introduction
PowerShell Scripting Introduction
Activate Scripts can be written in C#, VB.NET or Powershell. This article outlines the differences and things to be aware of when implementing a PowerShell script.
See "The General scripting guidelines" below for more general information on Activate scripts. You can change the scripting language at the top of the Script window in Activate Administrator.
WARNING: PowerShell scripts that are designed to work interactively on the command line will generally need altering to work successfully in an Activate environment. This article is intended for users with a good understanding of Activate and PowerShell.
This assumes that the associated Activate Service or Task has already been designed and implemented and we are wanting to use PowerShell to complete the provisioning steps.
PowerShell Limitations
PowerShell scripts can generally perform all the functions available with C# or VB.NET. However, Powershell requires the creation of a seperate Execution environment to execute the script. This has a performance hit (Memory and Processor) for every PowerShell script that is run.
High performance Services or Tasks should not use PowerShell.
Native Activate functions are perferred over PowerShell. For example, starting a PowerShell script to simply add a user to a group is 10 times slower that using the Native functions.
PowerShell Integration
When a PowerShell script is executed, Activate automtically adds a number of global variables that the script can use to access the Activate environment.
These are:
| |
|---|---|
Variable | Description |
$Job | The current executing Job. ie. $Job.LogAudit("hello"); |
$Evaluator | The current evaluation context. ie. $Evaluator.WriteLine("Trace output"); $Evaluator.GetObject("=//Roles/Business Roles") |
$System | The root System object. This allow access to the entire Activate Environment. ie. $System.CurrentTime |
$Organisation | The root of the organization. ie. $Organisation.Services["Applications"] |
$CurrentUser | The current user ie. $CurrentUser.DomainName |
$This | The current context for the script |
$$ | The ScriptBase class - this allows access to all methods that are inheritied in standard Activate Scripts. For example, in a standard script LogAudit("Hello"); can be written in PowerShell as $$.LogAudit("Hello"); Note: This is only available in Activate 6.2 or higher. |
PowerShell Commandline scripts
PowerShell scripts that are designed to work interactively on the command line will generally need altering to work successfully in an Activate environment as a script for a Task. The following changes will generally be required.
- Arguments for the script are generally read from $Job.Arguments instead of the command line
- Any user input required will need to be changed to operate non-interactively.
- write-output or other output functions will need to be changed to $Job.LogTrace or $Job.LogAudit if required.
- Logging should be carefully reviewed to prevent performance or database size issues.
- Scripts designed for human interaction often perform a significant amount of logging that is not required.
- The result of the script can be output back into the $Job.Arguments or logged.
- Review any loops and long processes to prevent performance issues on your Activate environment.
The following is a very simple example of adding a user to a group using Powershell within Activate.
#@ps #Available Variables: $Job, $Evaluator, $This, $Organisation, $CurrentUser, $System
$user = $Job.Arguments.GetObject("user")
$group = $Job.Arguments.GetObject("group")
$Job.LogAudit("User = " + $user.Name) $group.Add($user)
Service Scripts
Starting with Activate V6.2 it is also now possible to write Service.CustomScripts as PowerShell scripts. The following is an example and an outline for this script.
#@ps #Available Variables: $Job, $Evaluator, $This, $Organisation, $CurrentUser, $System
Function Create { param($srv) $Job.LogAudit("PS Create Service Instance: " + $srv.Service.Name); }
Function Delete { param($srv) $Job.LogAudit("PS Delete Service Instance: " + $srv.Name); }
Function Update { param($srv, $flags)
}