# Erstellen und Testen eines PowerShell-Projekts

Hier erfährst, du, wie du einen CI-Workflow (Continuous Integration) erstellst, um dein PowerShell-Projekt zu erstellen und zu testen.

> \[!NOTE]
> Auf GitHub Enterprise Server gehostete Runner werden aktuell nicht auf GitHub unterstützt.

## Einführung

In diesem Leitfaden wird gezeigt, wie du PowerShell für CI verwendest. Es beschreibt, wie Sie Pester verwenden, Abhängigkeiten installieren, Ihr Modul testen und auf dem PowerShell-Katalog veröffentlichen.

GitHub-gehostete Runner verfügen über einen Tools-Cache mit vorinstallierter Software, einschließlich PowerShell und Pester.

Eine vollständige Liste der aktuellen Software und der vorinstallierten Versionen von PowerShell und Pester findest du unter [Von GitHub gehostete Runner](/de/enterprise-server@3.22/actions/concepts/runners/github-hosted-runners#preinstalled-software-for-github-owned-images).

## Voraussetzungen

Sie sollten mit YAML und der Syntax für GitHub Actions vertraut sein. Weitere Informationen finden Sie unter [Schreiben von Workflows](/de/enterprise-server@3.22/actions/how-tos/write-workflows).

Du solltest ein grundlegendes Verständnis von PowerShell und Pester haben. Weitere Informationen findest du unter

* [Getting started with PowerShell](https://docs.microsoft.com/powershell/scripting/learn/ps101/01-getting-started) (Erste Schritte mit PowerShell)
* [Pester](https://pester.dev)

### Verwenden von selbstgehosteten Runnern in GitHub Enterprise Server

Wenn du Setupaktionen (z. B. `actions/setup-LANGUAGE`) in GitHub Enterprise Server mit selbst gehosteten Runnern verwendest, musst du eventuell den Toolscache für Runner ohne Internetzugriff einrichten. Weitere Informationen finden Sie unter [Einrichten des Toolcaches auf selbstgehosteten Runnern ohne Internetzugriff](/de/enterprise-server@3.22/admin/managing-github-actions-for-your-enterprise/managing-access-to-actions-from-githubcom/setting-up-the-tool-cache-on-self-hosted-runners-without-internet-access).

## Hinzufügen eines Workflows für Pester

Um deine Tests mit PowerShell und Pester zu automatisieren, kannst du einen Workflow hinzufügen, der jedes Mal ausgeführt wird, wenn eine Änderung an dein Repository gepusht wird. Im folgenden Beispiel wird `Test-Path` verwendet, um zu überprüfen, ob eine Datei namens `resultsfile.log` vorhanden ist.

Diese Datei mit dem Beispielworkflow muss im Verzeichnis `.github/workflows/` deines Repositorys hinzugefügt werden:

```yaml
name: Test PowerShell on Ubuntu
on: push

jobs:
  pester-test:
    name: Pester test
    runs-on: ubuntu-latest
    steps:
      - name: Check out repository code
        uses: actions/checkout@v6
      - name: Perform a Pester test from the command-line
        shell: pwsh
        run: Test-Path resultsfile.log | Should -Be $true
      - name: Perform a Pester test from the Tests.ps1 file
        shell: pwsh
        run: |
          Invoke-Pester Unit.Tests.ps1 -Passthru
```

* `shell: pwsh` konfiguriert den Auftrag für die Verwendung von PowerShell beim Ausführen der `run`-Befehle.

* `run: Test-Path resultsfile.log` überprüft, ob eine Datei namens `resultsfile.log` im Stammverzeichnis des Repositorys vorhanden ist.

* `Should -Be $true` verwendet Pester, um ein erwartetes Ergebnis zu definieren. Wenn das Ergebnis unerwartet ist, GitHub Actions wird dies als fehlgeschlagener Test gekennzeichnet. Beispiel:

  ![Screenshot eines Fehlers bei der Workflow-Ausführung für einen Pester-Test. Der Test meldet „Expected $true, but got $false“ und „Error: Process completed with exit code 1.“](/assets/images/help/repository/actions-failed-pester-test-updated.png)

* `Invoke-Pester Unit.Tests.ps1 -Passthru` verwendet Pester zum Ausführen von Tests, die in einer Datei mit dem Namen `Unit.Tests.ps1` definiert sind. Wenn du beispielsweise den oben beschriebenen Test ausführen möchtest, enthält `Unit.Tests.ps1` Folgendes:

  ```powershell
  Describe "Check results file is present" {
      It "Check results file is present" {
          Test-Path resultsfile.log | Should -Be $true
      }
  }
  ```

## Speicherorte der PowerShell-Module

Die folgende Tabelle beschreibt die Speicherorte verschiedener PowerShell-Module in jedem GitHub-gehosteten Runner.

<div class="ghd-tool rowheaders">

|                                             | Ubuntu                                           | macOS                                             | Windows                                               |
| ------------------------------------------- | ------------------------------------------------ | ------------------------------------------------- | ----------------------------------------------------- |
| **PowerShell-Systemmodule**                 | `/opt/microsoft/powershell/7/Modules/*`          | `/usr/local/microsoft/powershell/7/Modules/*`     | `C:\program files\powershell\7\Modules\*`             |
| **PowerShell-Add-On-Module**                | `/usr/local/share/powershell/Modules/*`          | `/usr/local/share/powershell/Modules/*`           | `C:\Modules\*`                                        |
| **Von Benutzer\*innen installierte Module** | `/home/runner/.local/share/powershell/Modules/*` | `/Users/runner/.local/share/powershell/Modules/*` | `C:\Users\runneradmin\Documents\PowerShell\Modules\*` |

</div>

> \[!NOTE]
> Auf Ubuntu-Läufern werden Azure PowerShell Module in `/usr/share/` anstelle des Standardspeicherorts von PowerShell-Add-On-Modulen (d. h. `/usr/local/share/powershell/Modules/`) gespeichert.

## Installieren von Abhängigkeiten

GitHub-gehostete Runner verfügen über PowerShell 7 und Pester. Sie können `Install-Module` verwenden, um zusätzliche Abhängigkeiten aus dem PowerShell-Katalog zu installieren, bevor Sie Den Code erstellen und testen.

> \[!NOTE]
> Die vorinstallierten Pakete (z. B. Pester), die von GitHub gehosteten Runnern verwendet werden, werden regelmäßig aktualisiert und können erhebliche Änderungen mit sich bringen. Daher wird empfohlen, bei Verwendung von `Install-Module` immer die erforderlichen Paketversionen mit `-MaximumVersion` anzugeben.

Sie können auch Abhängigkeiten zwischenspeichern, um Ihren Workflow zu beschleunigen. Weitere Informationen finden Sie unter [Referenz zum Zwischenspeichern von Abhängigkeiten](/de/enterprise-server@3.22/actions/reference/workflows-and-actions/dependency-caching).

Der folgende Auftrag installiert z. B. die Module `SqlServer` und `PSScriptAnalyzer`:

```yaml
jobs:
  install-dependencies:
    name: Install dependencies
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - name: Install from PSGallery
        shell: pwsh
        run: |
          Set-PSRepository PSGallery -InstallationPolicy Trusted
          Install-Module SqlServer, PSScriptAnalyzer
```

> \[!NOTE]
> Standardmäßig stuft PowerShell keine Repositorys als vertrauenswürdig ein. Beim Installieren von Modulen aus dem PowerShell-Katalog müssen Sie die Installationsrichtlinie für `PSGallery` explizit auf `Trusted` festlegen.

### Abhängigkeiten „cachen“ (zwischenspeichern)

Du kannst PowerShell-Abhängigkeiten mithilfe eines eindeutigen Schlüssels zwischenspeichern, mit dem du die Abhängigkeiten für zukünftige Workflows mit der [`cache`](https://github.com/marketplace/actions/cache)-Aktion wiederherstellen kannst. Weitere Informationen finden Sie unter [Referenz zum Zwischenspeichern von Abhängigkeiten](/de/enterprise-server@3.22/actions/reference/workflows-and-actions/dependency-caching).

PowerShell speichert seine Abhängigkeiten je nach Betriebssystem des Runners an unterschiedlichen Speicherorten. Der für ein Windows-Betriebssystem benötigte `path` Speicherort unterscheidet sich beispielsweise von dem, der im folgenden Ubuntu-Beispiel verwendet wird.

```yaml
steps:
  - uses: actions/checkout@v6
  - name: Setup PowerShell module cache
    id: cacher
    uses: actions/cache@v4
    with:
      path: "~/.local/share/powershell/Modules"
      key: ${{ runner.os }}-SqlServer-PSScriptAnalyzer
  - name: Install required PowerShell modules
    if: steps.cacher.outputs.cache-hit != 'true'
    shell: pwsh
    run: |
      Set-PSRepository PSGallery -InstallationPolicy Trusted
      Install-Module SqlServer, PSScriptAnalyzer -ErrorAction Stop
```

## Testen von Code

Du kannst die gleichen Befehle verwenden, die du auch lokal verwendest, um deinen Code zu bauen und zu testen.

### Linten von Code mit PSScriptAnalyzer

Im folgenden Beispiel wird `PSScriptAnalyzer` installiert und zum Linten aller `ps1`-Dateien im Repository verwendet. Weitere Informationen finden Sie unter [PSScriptAnalyzer auf GitHub](https://github.com/PowerShell/PSScriptAnalyzer).

```yaml
  lint-with-PSScriptAnalyzer:
    name: Install and run PSScriptAnalyzer
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - name: Install PSScriptAnalyzer module
        shell: pwsh
        run: |
          Set-PSRepository PSGallery -InstallationPolicy Trusted
          Install-Module PSScriptAnalyzer -ErrorAction Stop
      - name: Lint with PSScriptAnalyzer
        shell: pwsh
        run: |
          Invoke-ScriptAnalyzer -Path *.ps1 -Recurse -Outvariable issues
          $errors   = $issues.Where({$_.Severity -eq 'Error'})
          $warnings = $issues.Where({$_.Severity -eq 'Warning'})
          if ($errors) {
              Write-Error "There were $($errors.Count) errors and $($warnings.Count) warnings total." -ErrorAction Stop
          } else {
              Write-Output "There were $($errors.Count) errors and $($warnings.Count) warnings total."
          }
```

## Workflow-Daten als Artefakte paketieren

Du kannst Artefakte hochladen, um sie nach Abschluss eines Workflows anzuzeigen. Zum Beispiel kann es notwendig sein, Logdateien, Core Dumps, Testergebnisse oder Screenshots zu speichern. Weitere Informationen finden Sie unter [Speichern und Freigeben von Daten mit Workflowartefakten](/de/enterprise-server@3.22/actions/tutorials/store-and-share-data).

Im folgenden Beispiel wird gezeigt, wie die Aktion `upload-artifact` zum Archivieren von Testergebnissen von `Invoke-Pester` verwendet werden kann. Weitere Informationen finden Sie unter der [`upload-artifact` Aktion](https://github.com/actions/upload-artifact).

```yaml
name: Upload artifact from Ubuntu

on: [push]

jobs:
  upload-pester-results:
    name: Run Pester and upload results
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - name: Test with Pester
        shell: pwsh
        run: Invoke-Pester Unit.Tests.ps1 -Passthru | Export-CliXml -Path Unit.Tests.xml
      - name: Upload test results
        uses: actions/upload-artifact@v3
        with:
          name: ubuntu-Unit-Tests
          path: Unit.Tests.xml
    if: ${{ always() }}
```

Die `always()`-Funktion konfiguriert den Auftrag, um die Verarbeitung auch dann fortzusetzen, wenn Testfehler auftreten. Weitere Informationen finden Sie unter [Auswerten von Ausdrücken in Workflows und Aktionen](/de/enterprise-server@3.22/actions/reference/workflows-and-actions/expressions#always).

## Veröffentlichen auf PowerShell-Katalog

Sie können Ihren Workflow so konfigurieren, dass Ihr PowerShell-Modul in der PowerShell-Katalog veröffentlicht wird, wenn ihre CI-Tests bestehen. Du kannst Geheimnisse verwenden, um Token oder Anmeldeinformationen zu speichern, die zum Veröffentlichen deines Pakets erforderlich sind. Weitere Informationen finden Sie unter [Verwenden von Geheimnissen in GitHub-Aktionen](/de/enterprise-server@3.22/actions/how-tos/write-workflows/choose-what-workflows-do/use-secrets).

Im folgenden Beispiel wird ein Paket erstellt und `Publish-Module` verwendet, um es im PowerShell-Katalog zu veröffentlichen:

```yaml
name: Publish PowerShell Module

on:
  release:
    types: [created]

jobs:
  publish-to-gallery:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - name: Build and publish
        env:
          NUGET_KEY: ${{ secrets.NUGET_KEY }}
        shell: pwsh
        run: |
          ./build.ps1 -Path /tmp/samplemodule
          Publish-Module -Path /tmp/samplemodule -NuGetApiKey $env:NUGET_KEY -Verbose
```