DSC-Configuration-Compiler/README.md

DSC Configuration Compiler

Ein WinForms-basiertes PowerShell-Tool zum Laden, Kombinieren, Anzeigen und Exportieren von DSC-nahen Konfigurationen auf Basis von psd1-Dateien.

Der Fokus des Projekts liegt auf einem einfachen Template-Workflow:

• Templates aus Ordnern laden
• mehrere Templates zu einer Zielkonfiguration zusammenfuehren
• Parameter und Variablen aufloesen
• die resultierende Struktur im TreeView pruefen
• die zusammengefuehrte Konfiguration wieder als psd1 exportieren

Voraussetzungen

• Windows
• PowerShell mit WinForms-Unterstuetzung
• Schreibzugriff auf %APPDATA%

Das Tool speichert Einstellungen und Logs unterhalb von %APPDATA%\DSC Tool.

Start

Das Projekt kann direkt ueber Compiler.ps1 gestartet werden:

powershell -ExecutionPolicy Bypass -File .\Compiler.ps1

Alternativ:

pwsh -File .\Compiler.ps1

Projektstruktur

.
|-- Compiler.ps1
|-- Functions/
|-- Templates/
`-- Deployments/

• Compiler.ps1: Hauptanwendung, UI, Parser- und Resolver-Logik
• Functions/: zusaetzliche Funktionen fuer Import, Export, Merge und UI-Aktualisierung
• Templates/: wiederverwendbare Konfigurationsbausteine
• Deployments/: exportierte oder vorbereitete Zielkonfigurationen

Bedienung

1. Anwendung starten.
2. Falls noetig ueber Einstellungen -> Ordner waehlen... den Root-Ordner setzen.
3. Templates aus den Kategorien laden.
4. Gewuenschte Templates per Doppelklick zur Auswahl hinzufuegen.
5. Die Auswahl zusammenfuehren.
6. Das Ergebnis im TreeView pruefen.
7. Die zusammengefuehrte Konfiguration als psd1 exportieren.

Import und Export werden ueber den Deployment-Ordner abgewickelt.

Template-Modell

Templates bestehen aus drei optionalen Hauptbereichen:

• Parameters
• Variables
• Resources

Ein vereinfachtes Beispiel:

@{
    Parameters = @{
        DatabasePrefix = @{
            Type = 'string'
            DefaultValue = 'SP'
        }
    }

    Variables = @{
        ConfigDbName = "[concat(parameters('DatabasePrefix'),'_','Farm_Config')]"
    }

    Resources = @{
        NonNodeData = @{
            Services = @{
                Example = @{
                    DatabaseName = "[variables('ConfigDbName')]"
                }
            }
        }
    }
}

Ausdruckssyntax

Die Auswertung ist ARM-inspiriert. Template-Ausdruecke stehen in eckigen Klammern:

"[concat(parameters('Prefix'),'_','Database')]"

Unterstuetzte Referenzen:

• parameters('Name')
• variables('Name')

Zusaetzlich werden aus Rueckwaertskompatibilitaet auch diese Varianten verstanden:

• Parameter('Name')
• Variable('Name')

Unterstuetzte Funktionen:

• concat(...)
• toLower(...)
• toUpper(...)
• substring(...)
• replace(...)
• indexOf(...)
• firstIndexOf(...)
• lastIndexOf(...)

Funktionsnamen werden ohne freie PowerShell-Ausfuehrung ausgewertet. Die psd1-Dateien werden als Daten geparst, nicht als beliebiger Script-Code interpretiert.

Aufloesungsreihenfolge

Die Aufloesung erfolgt in dieser Reihenfolge:

1. Parameterwerte und Defaultwerte
2. Variablen
3. Ressourcenwerte

Zirkulaere Variablenreferenzen werden erkannt und als Fehler behandelt.

Merge-Verhalten

Beim Zusammenfuehren mehrerer Templates werden vorhandene Eintraege rekursiv kombiniert:

• Hashtables werden rekursiv gemerged
• Arrays werden anhand passender Name-Felder zusammengefuehrt
• fehlende Werte aus Templates werden in das Ergebnis uebernommen

Die finale Anzeige im TreeView basiert auf dem zusammengefuehrten und bereits aufgeloesten Modell.

Export

Der Export schreibt die aktuelle TreeView-Struktur wieder in eine psd1-Datei.

Standardziel beim Speichern ist:

Deployments\merged_config.psd1

Hinweise

• Einstellungen werden benutzerbezogen gespeichert.
• Logs werden pro Tag unter %APPDATA%\DSC Tool\Logs geschrieben.
• Templates sollten deklarativ bleiben und nur Daten plus Template-Ausdruecke enthalten.
• Fuer neue Templates wird die ARM-aehnliche Syntax mit parameters() und variables() empfohlen.

Beispielinhalt

Im Repository ist bereits ein groesseres Beispiel enthalten:

• Templates\Service\SharePointServer.psd1

Dieses Template zeigt die Verwendung von:

• Parametern
• Variablen
• verschachtelten Ressourcen
• String-Funktionen wie concat() und substring()

Weiterentwicklung

Sinnvolle naechste Schritte fuer das Projekt sind:

• Tests fuer Parser, Resolver und Merge-Verhalten
• typsicherer Export-Roundtrip
• robustere Initialisierung der Pfade und Settings
• weitere Template-Funktionen nach Bedarf