Aufgaben-Python/courses/powershell/07_erweiterte_funktionen_und_parameter/index.html

<!DOCTYPE html>
<html lang="de">
<head>
  <link rel="icon" type="image/svg+xml" href="../../../assets/favicon.svg">
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>PS 07: Erweiterte Funktionen &amp; Parameter</title>
  <link rel="stylesheet" href="../../../assets/style.css">
</head>
<body>
  <div class="app-layout">
    <div class="app-main">
      <header>
        <div class="header-container">
          <div class="header-badge">⚡ Skripting &amp; Error-Handling</div>
          <h1>PS 07: Eigene Cmdlets [CmdletBinding()] &amp; Validierung</h1>
          <p>Verwandle einfache PowerShell-Funktionen in vollwertige Enterprise-Cmdlets mit <code>[CmdletBinding()]</code>, robuster Parameter-Validierung, Pipeline-Input und <code>-WhatIf</code> Unterstützung.</p>
        </div>
      </header>

      <main class="container">
        <!-- 1. THEORIE: CMDLETBINDING -->
        <section class="card">
          <h2>💡 1. Das <code>[CmdletBinding()]</code> Attribut</h2>
          <p>Durch das Hinzufügen von <code>[CmdletBinding()]</code> verwandelt PowerShell eine gewöhnliche Funktion in eine <strong>Advanced Function</strong> (Script-Cmdlet). Dadurch stehen automatisch Standard-Parameter wie <code>-Verbose</code>, <code>-Debug</code>, <code>-ErrorAction</code> und <code>-WarningAction</code> zur Verfügung:</p>
          
          <pre><code>function Get-CustomReport {
    [CmdletBinding()]
    param(
        [Parameter(Mandatory = $true, Position = 0)]
        [ValidateNotNullOrEmpty()]
        [string]$ReportName
    )

    Write-Verbose "Erstelle Report '$ReportName'..."
    [PSCustomObject]@{
        Report = $ReportName
        Date   = (Get-Date)
    }
}</code></pre>

          <div class="box box-analogie">
            <div class="box-title">🛡️ Didaktische Analogie: Der Passierschein mit Sicherheitsprüfung</div>
            <p>Parameter-Validierungsattribute wie <code>[ValidateSet()]</code> oder <code>[ValidateRange()]</code> sind deine Türsteher: Ungültige Eingaben werden sofort an der Pforte abgefangen, mit aussagekräftigen Fehlermeldungen abgewiesen und gelangen niemals in deine Geschäftslogik!</p>
          </div>
        </section>

        <!-- 2. PARAMETER-VALIDIERUNG -->
        <section class="card">
          <h2>🛡️ 2. Die wichtigsten Validierungs-Attribute</h2>
          <p>Schütze deine Funktionen vor fehlerhaften Aufrufen mit den bewährten .NET Validierungsattributen:</p>

          <div style="overflow-x: auto; margin: 15px 0;">
            <table style="width: 100%; border-collapse: collapse; font-size: 0.9rem;">
              <thead>
                <tr style="border-bottom: 2px solid var(--border-color); background: var(--bg-subtle);">
                  <th style="padding: 10px;">Attribut</th>
                  <th style="padding: 10px;">Beispiel</th>
                  <th style="padding: 10px;">Wirkung</th>
                </tr>
              </thead>
              <tbody>
                <tr style="border-bottom: 1px solid var(--border-color);">
                  <td style="padding: 10px;"><code>[ValidateSet()]</code></td>
                  <td style="padding: 10px;"><code>[ValidateSet('Dev', 'Test', 'Prod')]</code></td>
                  <td style="padding: 10px;">Erlaubt nur exakt definierte Zeichenketten (inkl. Tab-Completion!).</td>
                </tr>
                <tr style="border-bottom: 1px solid var(--border-color);">
                  <td style="padding: 10px;"><code>[ValidateRange()]</code></td>
                  <td style="padding: 10px;"><code>[ValidateRange(1, 65535)]</code></td>
                  <td style="padding: 10px;">Begrenzt Zahlen auf einen Min/Max-Bereich.</td>
                </tr>
                <tr style="border-bottom: 1px solid var(--border-color);">
                  <td style="padding: 10px;"><code>[ValidateNotNullOrEmpty()]</code></td>
                  <td style="padding: 10px;"><code>[ValidateNotNullOrEmpty()]</code></td>
                  <td style="padding: 10px;">Verhindert Übergabe von <code>$null</code> oder <code>""</code>.</td>
                </tr>
                <tr>
                  <td style="padding: 10px;"><code>[ValidatePattern()]</code></td>
                  <td style="padding: 10px;"><code>[ValidatePattern('^v\d+\.\d+')]</code></td>
                  <td style="padding: 10px;">Prüft das Argument gegen einen Regulären Ausdruck (Regex).</td>
                </tr>
              </tbody>
            </table>
          </div>
        </section>

        <!-- 3. SUPPORTS-SHOULDPROCESS & WHATIF -->
        <section class="card">
          <h2>⚠️ 3. Risikofreie Ausführung mit <code>SupportsShouldProcess</code> &amp; <code>-WhatIf</code></h2>
          <p>Für potenziell destruktive Aktionen (z.B. Neustart von Servern, Löschen von Daten) unterstützt PowerShell <code>-WhatIf</code> und <code>-Confirm</code> out-of-the-box:</p>

          <pre><code>function Restart-CloudServer {
    [CmdletBinding(SupportsShouldProcess = $true)]
    param(
        [Parameter(Mandatory = $true)]
        [string]$ServerName
    )

    if ($PSCmdlet.ShouldProcess($ServerName, "Server neustarten")) {
        Write-Host "Führe echten Neustart von $ServerName durch..."
    }
}

# Ausführung:
# Restart-CloudServer -ServerName "srv01" -WhatIf
# Ausgabe: What if: Performing the operation "Server neustarten" on target "srv01".</code></pre>
        </section>

        <!-- 4. CHEAT-SHEET -->
        <section class="card">
          <h2>📑 4. Cheat-Sheet: Advanced Functions</h2>
          <div style="overflow-x: auto;">
            <table style="width: 100%; border-collapse: collapse; font-size: 0.9rem;">
              <thead>
                <tr style="border-bottom: 2px solid var(--border-color); background: var(--bg-subtle);">
                  <th style="padding: 10px;">Klausel</th>
                  <th style="padding: 10px;">Syntax</th>
                  <th style="padding: 10px;">Zweck</th>
                </tr>
              </thead>
              <tbody>
                <tr style="border-bottom: 1px solid var(--border-color);">
                  <td style="padding: 10px;"><code>[CmdletBinding()]</code></td>
                  <td style="padding: 10px;"><code>[CmdletBinding(SupportsShouldProcess)]</code></td>
                  <td style="padding: 10px;">Aktiviert Standard-Cmdlet-Funktionen und <code>$PSCmdlet</code>.</td>
                </tr>
                <tr style="border-bottom: 1px solid var(--border-color);">
                  <td style="padding: 10px;"><code>ValueFromPipeline</code></td>
                  <td style="padding: 10px;"><code>[Parameter(ValueFromPipeline=$true)]</code></td>
                  <td style="padding: 10px;">Ermöglicht Übergabe von Objekten über die Pipeline.</td>
                </tr>
                <tr style="border-bottom: 1px solid var(--border-color);">
                  <td style="padding: 10px;"><code>Switch-Parameter</code></td>
                  <td style="padding: 10px;"><code>[switch]$Detailed</code></td>
                  <td style="padding: 10px;">Boolescher Schalter ohne Argument (<code>-Detailed</code>).</td>
                </tr>
                <tr>
                  <td style="padding: 10px;"><code>ShouldProcess</code></td>
                  <td style="padding: 10px;"><code>$PSCmdlet.ShouldProcess("Ziel", "Aktion")</code></td>
                  <td style="padding: 10px;">Auswertung von <code>-WhatIf</code> und <code>-Confirm</code>.</td>
                </tr>
              </tbody>
            </table>
          </div>
        </section>

        <!-- 5. AUFGABEN CHECKLISTE -->
        <section class="card">
          <h2>🎯 Aufgaben &amp; Checkliste in <code>aufgabe.ps1</code></h2>
          <div class="task-item">
            <input type="checkbox" class="task-checkbox" id="t1">
            <label class="task-label" for="t1"><strong>TODO 1:</strong> <code>Get-EnvironmentConfig</code>: Cmdlet mit <code>[ValidateSet()]</code> und <code>[ValidateRange()]</code> implementieren.</label>
          </div>
          <div class="task-item">
            <input type="checkbox" class="task-checkbox" id="t2">
            <label class="task-label" for="t2"><strong>TODO 2:</strong> <code>Restart-AppService</code>: Cmdlet mit <code>[CmdletBinding(SupportsShouldProcess)]</code> und <code>$PSCmdlet.ShouldProcess</code> bauen.</label>
          </div>
          <div class="task-item">
            <input type="checkbox" class="task-checkbox" id="t3">
            <label class="task-label" for="t3"><strong>TODO 3:</strong> <code>New-UserAccount</code>: Funktion mit Pipeline-Unterstützung und <code>[ValidatePattern()]</code> für E-Mail-Adressen.</label>
          </div>
          <div class="task-item">
            <input type="checkbox" class="task-checkbox" id="t4">
            <label class="task-label" for="t4"><strong>TODO 4:</strong> <code>Get-SystemReport</code>: Funktion mit <code>[switch]$Detailed</code> und <code>[ValidateNotNullOrEmpty()]</code> schreiben.</label>
          </div>

          <div style="margin-top: 25px; display: flex; gap: 12px; flex-wrap: wrap;">
            <a href="../../../workspace.html?course=powershell&track=track_2_skripting_und_errorhandling&chapter=07_erweiterte_funktionen_und_parameter" class="btn" style="background: #0284c7; color: #fff; font-weight: 700;">💻 In Web-IDE öffnen &rarr;</a>
            <a href="../06_schleifen_und_pipeline_durchlaeufe/index.html" class="btn btn-secondary">&larr; Zurück zu PS 06</a>
            <a href="../08_robustes_error_handling_und_try_catch/index.html" class="btn btn-secondary">Weiter zu PS 08 &rarr;</a>
          </div>
        </section>
      </main>
    </div>
  </div>
  <script src="../../../assets/courses_manifest.js"></script>
  <script src="../../../assets/course_sidebar.js"></script>
</body>
</html>