# PowerShell

Die Einrichtung eines PowerShell-Agenten kann im Kapitel Automatisierungsagent; [Erstellung & Konfiguration](/documentation/de-documentation/automatisierung/web-client/automatisierungsagent/erstellung-and-konfiguration.md) 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.

<figure><img src="/files/8ZMqnEMgjiqAOWEOrFaH" alt=""><figcaption></figcaption></figure>

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:

<mark style="color:blue;">**# Beispiel für ein PowerShell-Skript, das .NET-Objekte und TC-Variablen von aqua verwendet**</mark>

{% 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 %}

<mark style="color:blue;">**#Request Test Execution information via**</mark> <mark style="color:blue;">**$aquaCallback.GetExecutionInfo()#Returns an object with ProjectId, TestCaseId, TestExecutionId, \[TestScenarioId and TestScenarioExecutionId]**</mark>&#x20;

{% 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 %}

<mark style="color:blue;">**# Possible Types of  \[aqua.ProcessEngine.WebServiceProxy.ExecutionLogMessageType]**</mark>

<mark style="color:blue;">**# SUTError, ScriptExecutionError, PreparationError, ExecutionError, InformationalInfo, InformationalDebug, InformationalWarn, InformationalSuccess**</mark> &#x20;

{% 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 %}

<mark style="color:blue;">**# Return status of script execution. One of: Ready, Blocked, Fail, Aborted**</mark>**&#x20;** return "Ready" &#x20;

<figure><img src="/files/LN50OFkI6VfoaMnyWIzM" alt=""><figcaption></figcaption></figure>


---

# 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/web-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.