# PowerShell

Der PowerShell-Agent stellt mehrere Objekte für PowerShell-Skripte zur Verfügung:

* variables - Array von aqua.ProcessEngine.WebServiceProxy.VariableValue Objekten, die Testfallvariablen (und ihre Werte) für die Ausführung beinhaltet. Name und Value sind die wichtigsten Eigenschaften für VariableValue
* tempDir - String Variable, die den Pfad des temporären Verzeichnisses enthält, in dem Skriptanhänge gespeichert wurden (wenn vorhanden)
* aquaCallback - Verweis auf das AquaShellCallbackHelper Objekt, dass genutzt werden kann, um mit aqua vom PowerShell-Skript zu kommunizieren. Die verfügbare Funktionalität beinhaltet:
* Senden von Log-Nachrichten nach aqua (auch mit Screenshots)
* Senden von Anhängen nach aqua (gespeichert als Anhänge im Ausführungsobjekt)
* StopRequest Eigenschaft - wird bei Abbruchanfragen, die von aqua erhalten werden, vom Agenten gesetzt. Lang laufende Skripte sollten diesen Flag periodisch überprüfen und langsam stoppen, wenn gesetzt. Wenn nicht nach 5 Sekunden gestoppt wird, nachdem dieser Flag gesetzt wurde, macht der Agent einen Forced Stop des laufenden Skripts.

 Zum Aufrufen von nunit aus PowerShell können Sie einen Befehl nutzen wie:  

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

Um exponierte Objekte zu nutzen, muss das PowerShell-Skript ihre Benutzung deklarieren, indem der folgende Befehl eingegeben wird: 

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

 Beachten Sie, dass alle genutzten Variablen in einem einzelnen "param"-Befehl deklariert werden müssen. Ein Beispielskript, dass diese Objekte benutzt: 

```powershell
# Beispiel PowerShell Skript, dass .NET Objekt
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  
}
# Mögliche Typen von  [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");   
}  
# Gibt den Status der Skriptausführung zurück. Einen von: Ready, Blocked, Fail, Aborted (Bereit, Blockiert, Gescheitert, Abgebrochen)
return "Ready"  
```

### **Execution Status**

In PowerShell haben Sie zusätzlich die Möglichkeit, einen Ausführungsstatus in Form einer Liste von Parametern nach aqua zu senden. Dies hilft in Situationen, wenn die Testausführung sehr lange dauert und Sie einen Zwischenstand in aqua geben möchten, zum Beispiel einen Testfortschritt als Prozent-Wert oder die Anzahl der bereits abgearbeiteten Prüfschritte. Die Informationen sind dann über den aqua WebClient einsehbar. Folgender Beispiel-Code zeigt, wie Sie diesen Ausführungsstatus senden können:

```powershell
# mehrere Werte als Ausführungsstatus auf einmal senden
$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

# ist der zweite Parameter true, dann wird der komplette Ausführungsstatus ersetzt,
# andernfalls werden existierende Werte überschrieben oder noch nicht vorhandene Werte ergänzt
$aquaCallback.AddExecutionData($attributes, $true)

# einzelnen Wert als Ausführungsstatus senden
# $aquaCallback.AddExecutionDataString(string name, string value)
$aquaCallback.AddExecutionDataString("Progress", "50%")

# $aquaCallback.AddExecutionDataInteger(string name, int value)
$aquaCallback.AddExecutionDataInteger("No. of Checks", 50)
```

Zwei PowerShell-Skripte in unterschiedlichen Testschritten sind zunächst unabhängig voneinander und es können keine Daten aus einem Schritt in einem nachfolgenden Schritt aufgegriffen und weiterverwendet werden. Um dieses Problem zu lösen, kann der Ausführungsstatus auch dazu benutzt werden, um Daten aus einem automatisierten Schritt in den nächsten zu überführen und wiederzuverwenden. Die benötigten Methoden sind im Folgenden beschrieben:

```powershell
# $aquaCallback.GetAllExecutionAttributesInExecution()
$allAttributes = $aquaCallback.GetAllExecutionAttributesInExecution()

# $aquaCallback.GetExecutionAttributeInExecution(string attributeName)
$progress = $aquaCallback.GetExecutionAttributeInExecution("Progress")

# $aquaCallback.GetExecutionAttributeValueInExecution(string attributeName)
$noOfChecks = $aquaCallback.GetExecutionAttributeValueInExecution("No. of Checks")
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.aqua-cloud.io/documentation/de-documentation/automatisierung/desktop-client/powershell.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.