# PowerShell

PowerShell agent exposes several objects available for PowerShell scripts:

* Variables – array of aqua.ProcessEngine.WebServiceProxy.VariableValue objects containing TC variables (and their values) used for execution. Name and Value are the most important properties of VariableValue.
* tempDir – string variable containing path of temporary directory where script attachments have been saved (if applicable).
* aquaCallback – reference to AquaShellCallbackHelper object that can be used to communicate with aqua from PowerShell script. Available functionality includes:
* sending log messages to aqua (also with screenshots)
* sending attachments to aqua (saved as attachments in the execution object)
* StopRequest property  - set by agent on abort requests received from aqua. Long-running scripts should periodically check this flag and stop gently in case when set. If not stop in 5 seconds after the flag is set, the agent does force stop of the running script.

 To call nunit by PowerShell, you can use commands like:

```powershell
$output = & $nunitLocation $testDll --test=$testCaseName 2>&1
```

To use exposed objects, a PowerShell script needs to declare their usage by issuing the following command: 

```powershell
param($variables, $tempDir, $aquaCallback)
```

{% hint style="info" %}
Note, that all used variables must be declared in a single “param” command.
{% endhint %}

Sample script using those objects: 

```powershell
# Sample PowerShell script that uses .NET objects and TC variables from aqua   
param($variables, $tempDir, $aquaCallback)  
$text = new-object System.Text.StringBuilder  
$date = [System.DateTime]::Now  
$text.AppendLine($date.ToLongDateString())  
$text.AppendLine($date.ToLongTimeString())  
echo "$text" > script-sample.log  
foreach ($var in $variables)  
{  
    $varName = $var.Name  
    $varValue = $var.Value  
    echo "Variable: $varName : $varValue" >> script-sample.log  
}
# Possible Types of  [aqua.ProcessEngine.WebServiceProxy.ExecutionLogMessageType]
# SUTError, ScriptExecutionError, PreparationError, ExecutionError, InformationalInfo, InformationalDebug, InformationalWarn, InformationalSuccess  
$aquaCallback.SendMessage("hello, I was sent from script", [aqua.ProcessEngine.WebServiceProxy.ExecutionLogMessageType]::InformationalWarn, "my category");   
$aquaCallback.SendMessageWithScreenshot("and this is Screenshot", "c:\sample.jpg", [aqua.ProcessEngine.WebServiceProxy.ExecutionLogMessageType]::InformationalWarn, "my category");   
dir $tempDir >> script-sample.log  
$aquaCallback.AddExecutionAttachment("script-sample.log"); 
 
while ($true)  
{  
    if ($aquaCallback.StopRequest)  
    {
        $aquaCallback.SendMessage("Aborting on StopRequest", [aqua.ProcessEngine.WebServiceProxy.ExecutionLogMessageType]::InformationalWarn, "my category");   
        return "Aborted"   
    }  
    Start-Sleep -s 10  
    aquaCallback.SendMessage("Looping in PowerShell…", [aqua.ProcessEngine.WebServiceProxy.ExecutionLogMessageType]::InformationalWarn, "my category");   
}  
# Return status of script execution. One of: Ready, Blocked, Fail, Aborted  
return "Ready"  
```

### **Execution Status** <a href="#execution_status" id="execution_status"></a>

PowerShell's automation provides the capability to set an execution status of a given list of parameters that can be updated from time to time. This is helpful if you have a long-running test execution and want to show an intermediate status in aqua, e.g. progress in percent or number of checks performed so far.&#x20;

Sample code how to do this is given below.&#x20;

{% hint style="info" %}
Please note that execution status is only visible in WebClient.
{% endhint %}

```powershell
# sending multiple values as execution status
$attributes = @()
 
$attribute = New-Object aqua.ProcessEngine.WebServiceProxy.ExecutionDataAttribute
$attribute.AttrName = "dummy"
$attribute.AttrType = [aqua.ProcessEngine.WebServiceProxy.ExecutionDataAttributeType] "Integer"
$attribute.AttrValue = "14"
$attributes += $attribute
 
$attribute = New-Object aqua.ProcessEngine.WebServiceProxy.ExecutionDataAttribute
$attribute.AttrName = "dummy2"
$attribute.AttrType = [aqua.ProcessEngine.WebServiceProxy.ExecutionDataAttributeType] "String"
$attribute.AttrValue = "HelloWorld"
$attributes += $attribute
 
# if second parameter is true, execution status is replaced entirely with the given array. In contrast, false does a partial update
$aquaCallback.AddExecutionData($attributes, $true)
 
# sending single value as execution status
# $aquaCallback.AddExecutionDataString(string name, string value)
$aquaCallback.AddExecutionDataString("Progress", "50%")
 
# $aquaCallback.AddExecutionDataInteger(string name, int value)
$aquaCallback.AddExecutionDataInteger("No. of Checks", 50)
 
Two automated steps in aqua are running independent of each other. Thus, you are not able to access data from one automated step in a subsequent step by default. To solve this issue, you can use execution status to hand over some data from one automated step to another.
 
# $aquaCallback.GetAllExecutionAttributesInExecution()
$allAttributes = $aquaCallback.GetAllExecutionAttributesInExecution()
 
# $aquaCallback.GetExecutionAttributeInExecution(string attributeName)
$progress = $aquaCallback.GetExecutionAttributeInExecution("Progress")
 
# $aquaCallback.GetExecutionAttributeValueInExecution(string attributeName)
$noOfChecks = $aquaCallback.GetExecutionAttributeValueInExecution("No. of Checks")
```