# PowerShell
Die Einrichtung eines PowerShell-Agenten kann im Kapitel Automatisierungsagent; [Erstellung & Konfiguration](https://docs.aqua-cloud.io/documentation/de-documentation/~/revisions/jTwnkJ1ie293nfxptIGP/automatisierung/web-client/automatisierungsagent/erstellung-and-konfiguration) nachgelesen werden. Der PowerShell-Agent wird benötigt, um einen Testfall mit PowerShell-Skripten auszuführen.
Um ein PowerShell-Skript zu einem Testfall hinzuzufügen, öffnen Sie den Testfall und navigieren zum Schrittdesigner. Wechseln Sie dann zum Tab 'Automatisierung'.
Wenn Sie PowerShell auswählen, wird automatisch ein PowerShell-Beispielskript eingefügt. Sie können das Beispielskript nutzen, um die Funktionalität, die der PowerShell-Agent bietet, leicht zu verstehen. Anschließend können Sie das Skript weiter anpassen oder es direkt durch andere Skripte ersetzen.
Hier sind einige weitere Informationen über die Objekte und Funktionen, die der PowerShell-Agent für PowerShell-Skripte bereitstellt:
* `variables` – Array von Objekten, die TC-Variablen (und ihre Werte) enthalten, die bei der Ausführung verwendet werden. Name und Wert sind die wichtigsten Eigenschaften jedes Objekts.
* `tempDir` – Zeichenfolge, die den Pfad des temporären Verzeichnisses enthält, in dem die Skriptanhänge gespeichert wurden (falls zutreffend).
* `aquaCallback` – Referenz auf das AquaShellCallbackHelper-Objekt, das verwendet werden kann, um aus dem PowerShell-Skript heraus mit aqua zu kommunizieren. Verfügbar sind Funktionen wie:
* das Senden von Protokollnachrichten an aqua (auch mit Screenshots)
* das Senden von Anhängen an aqua (gespeichert als Anhänge im Ausführungsobjekt)
* das Senden des Ausführungsstatus über AddExecutionData
* das Abrufen von Testausführungsinformationen (IDs von Projekt, Testfall, Testausführung, Testszenario, Testszenarioausführung)
* `StopRequest`-Eigenschaft – wird vom Agenten bei Abbruchanfragen von aqua gesetzt. Langlaufende Skripte sollten dieses Flag periodisch überprüfen und sich schonend beenden, falls es gesetzt ist. Wird nicht innerhalb von 5 Sekunden nach Setzen des Flags gestoppt, führt der Agent einen erzwungenen Stopp des laufenden Skripts durch.
Um NUnit über PowerShell aufzurufen, können Sie Befehle wie folgt verwenden:
```powershell
$output = & $nunitLocation $testDll --test=$testCaseName 2>&1
```
Um exponierte Objekte zu nutzen, muss das PowerShell-Skript ihren Gebrauch durch Ausführen des folgenden Befehls deklarieren:
```powershell
param($variables, $tempDir, $aquaCallback)
```
{% hint style="info" %}
Beachten Sie, dass alle verwendeten Variablen in einem einzigen "param"-Befehl deklariert werden müssen.
{% endhint %}
Beispielskript mit diesen Objekten:
**# Beispiel für ein PowerShell-Skript, das .NET-Objekte und TC-Variablen von aqua verwendet**
{% code overflow="wrap" %}
```powershell
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
}
```
{% endcode %}
**#Request Test Execution information via** **$aquaCallback.GetExecutionInfo()#Returns an object with ProjectId, TestCaseId, TestExecutionId, \[TestScenarioId and TestScenarioExecutionId]**
{% code overflow="wrap" %}
```powershell
$executionInfo = $aquaCallback.GetExecutionInfo()
Write-Output "Project ID: $($executionInfo.ProjectId)" >> script-sample.log
Write-Output "TestCase ID: $($executionInfo.TestCaseId)" >> script-sample.log
Write-Output "Execution ID $($executionInfo.TestExecutionId)" >> script-sample.log
Write-Output "Scenario ID (when run in scenario): $($executionInfo.TestScenarioId)" >> script-sample.log
Write-Output "Scenario Execution ID (when run in scenario): $($executionInfo.TestScenarioExecutionId)" >> script-sample.log
```
{% endcode %}
**# Possible Types of \[aqua.ProcessEngine.WebServiceProxy.ExecutionLogMessageType]**
**# SUTError, ScriptExecutionError, PreparationError, ExecutionError, InformationalInfo, InformationalDebug, InformationalWarn, InformationalSuccess**
{% code overflow="wrap" %}
```powershell
$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");
}
```
{% endcode %}
**# Return status of script execution. One of: Ready, Blocked, Fail, Aborted**** ** return "Ready"
