Dokumentation mit PSWriteWord in der PowerShell
Text to Picture
Veröffentlicht in Ausgabe 04/2024 - PRAXIS
Eine effiziente und aktuelle IT-Dokumentation ist oftmals nicht nur vorteilhaft, sondern auch rechtlich oder durch Unternehmensrichtlinien vorgegeben. Sie dient als fundamentales Werkzeug in verschiedenen Bereichen: Sie erleichtert die Einarbeitung neuer Mitar- beiter, unterstützt die Planung und Erweiterung von Systemen, bildet eine Basis für das Risikomanagement und ermöglicht einen detaillierten Einblick in die gesamte Infrastruktur.
Und wie die Erfahrung lehrt, sind insbesondere Diagramme und Infografiken in der Lage, komplexe Strukturen und Zusammenhänge übersichtlich darzustellen. Da kommt uns die Fähigkeit des PSWriteWord-Moduls, Informationen in Bilder aufzubereiten, gerade recht.
Automatisierung der Dokumentation
Angesichts dieser Herausforderungen und Möglichkeiten stellt sich die Frage, wie sich der Prozess der IT-Dokumentation effizienter gestalten lässt. Einen vielversprechenden Ansatz bietet die Automatisierung der IT-Dokumentation. Hier kommt PSWriteWord [1] ins Spiel, ein leistungsstarkes Tool, das die Erstellung von Word-Dokumenten durch PowerShell ermöglicht – und das ganz ohne die Notwendigkeit, Word selbst installiert zu haben. Das vereinfacht nicht nur den Prozess der IT-Dokumentation, sondern eröffnet auch zahlreiche weitere Anwendungsmöglichkeiten.
Eine effiziente und aktuelle IT-Dokumentation ist oftmals nicht nur vorteilhaft, sondern auch rechtlich oder durch Unternehmensrichtlinien vorgegeben. Sie dient als fundamentales Werkzeug in verschiedenen Bereichen: Sie erleichtert die Einarbeitung neuer Mitar- beiter, unterstützt die Planung und Erweiterung von Systemen, bildet eine Basis für das Risikomanagement und ermöglicht einen detaillierten Einblick in die gesamte Infrastruktur.
Und wie die Erfahrung lehrt, sind insbesondere Diagramme und Infografiken in der Lage, komplexe Strukturen und Zusammenhänge übersichtlich darzustellen. Da kommt uns die Fähigkeit des PSWriteWord-Moduls, Informationen in Bilder aufzubereiten, gerade recht.
Automatisierung der Dokumentation
Angesichts dieser Herausforderungen und Möglichkeiten stellt sich die Frage, wie sich der Prozess der IT-Dokumentation effizienter gestalten lässt. Einen vielversprechenden Ansatz bietet die Automatisierung der IT-Dokumentation. Hier kommt PSWriteWord [1] ins Spiel, ein leistungsstarkes Tool, das die Erstellung von Word-Dokumenten durch PowerShell ermöglicht – und das ganz ohne die Notwendigkeit, Word selbst installiert zu haben. Das vereinfacht nicht nur den Prozess der IT-Dokumentation, sondern eröffnet auch zahlreiche weitere Anwendungsmöglichkeiten.
PSWriteWord bietet eine Vielzahl an Funktionen, die das Erstellen einer Dokumentation effizienter machen. Es erlaubt unter anderem das Einfügen und Bearbeiten von Text, das Erstellen von Tabellen und das Einbinden von Diagrammen und Infografiken – alles automatisiert über Skripte. Ein entscheidender Vorteil der Software ist, dass Microsoft Word nicht installiert sein muss. Dies erleichtert die Integration in verschiedene IT-Umgebungen und reduziert Abhängigkeiten. So kann das Tool ohne Probleme auch auf Servern laufen, die in der Regel nicht über eine Word-Installation verfügen.
Die Software zeigt ihre Stärken insbesondere in der Automatisierung von IT-Dokumentationen. Beispielsweise lassen sich Berichte automatisiert generieren oder bestehende PowerShell-Skripte um Dokumentationserstellung erweitern. Ein interessantes Zusatzmodul ist PS- WinDocumentation, das auf PS-WriteWord basiert und eine komplette Dokumentation des Active Directory erstellen kann. Durch die Integration von automatisierten Diagrammen und Infografiken lässt sich ein umfassender und leicht verständlicher Einblick in die IT-Infrastruktur gewinnen.
Installation und Voraussetzungen
Die Installation von PSWriteWord ist unkompliziert, wobei jedoch einige Voraussetzungen zu beachten sind. Das Modul funktioniert nur auf Windows-Systemen, da .NET Core von der benötigten DLL nicht unterstützt wird. Zudem ist die Verwendung auf PowerShell 5.1 beschränkt. Über eine PowerShell-Konsole installieren Sie das Modul wie folgt:
Install-Module PSWriteWord
Es ist zu beachten, dass PSWriteWord nicht mehr aktiv weiterentwickelt wird. Das Modul ist stabil, voll funktionsfähig und wird aktiv in anderen Projekten verwendet. Der Entwickler fokussiert sich derzeit aber auf das Nachfolgeprojekt PSWriteOffice [2], das neben Word auch Excel und PowerPoint unterstützen soll. PSWriteOffice befindet sich noch in einer frühen Entwicklungsphase und verfügt noch nicht über alle Features von PSWriteWord.
Befehle und Syntax
PSWriteWord umfasst über 100 verschiedene PowerShell-Funktionen. Die Details dazu finden Sie auf der Seite des Publishers [3]. Die wichtigsten Befehle daraus sind die folgenden:
- New-WordDocument: Erzeugt ein neues Word-Dokument. Dies ist der Ausgangspunkt für das Erstellen von Dokumenten mit PSWriteWord.
- Add-WordText: Fügt Text zum Dokument hinzu und ermöglicht umfangreiche Formatierungsoptionen wie etwa Schriftart, Größe und Farbe.
- Add-WordTable: Fügt eine Tabelle zum Dokument hinzu und erlaubt die Definition von Spalten, Zeilen und Inhalten sowie Formatierungsoptionen.
- Add-WordChart: Integriert ein Diagramm in das Dokument. Dieses Unterstützt verschiedene Diagrammtypen und ermöglicht die visuelle Darstellung von Daten.
- Save-WordDocument: Speichert das bearbeitete Word-Dokument. Dieser Befehl schließt den Bearbeitungsprozess ab und sichert alle Änderungen.
Beispiele für Formatierungen
Mithilfe der zuvor genannten Befehle erstellen wir ein Word-Dokument. Zunächst definieren Sie den Speicherpfad für Ihr File:
$docPath = "./<Dateiname>.docx"
Sofern noch nicht erfolgt, importieren Sie das PSWriteWord-Modul:
Import-Module PSWriteWord
Anschließend legen Sie ein neues Word-Dokument an:
$document = New-WordDocument -FilePath $docPath
Darin fügen Sie wie mit dem folgenden Befehl eine Überschrift hinzu:
Add-WordText -WordDocument $document -Text "Meine Überschrift" -FontSize 22 -Bold $true
Eine spezifische Formatierung liefert:
Add-WordText -WordDocument $document -Text "Einfacher Text in Schriftgröße 12" -FontSize 12
Jetzt speichern Sie das Dokument:
Save-WordDocument -WordDocument $document
Um den Erfolg zu prüfen, öffnen Sie das Word-Doc mit:
Invoke-Item $docPath
Damit haben wir ein einfaches Word-Dokument mit einer Überschrift und formatiertem Text angelegt.
Dokumentenlayouts ansprechend gestalten
Die Gestaltung von Layouts in Word-Dokumenten mit PSWriteWord eröffnet vielfältige Möglichkeiten, Informationen ansprechend und übersichtlich darzustellen. So haben Sie etwa die Option, den freien Speicher einer Festplatte mittels Kuchendiagramm abzubilden oder die Ressourcen einer Azure-Ressourcen-gruppe als Tabelle darzustellen. Wir konzentrieren uns im Folgenden beispielhaft auf Diagramme und Tabellen, zwei wesentlichen Elementen für effektive Dokumentationen. Listing 1 zeigt den dokumentierten Code für ein das Erzeugen eines Kuchendiagramms.
Listing 1: Ein Kuchendiagramm zeichnen
# Speicherpfad des Dokuments
$docPath = "./<MeinDokument>.docx"
# Importieren des PSWriteWord-Moduls
Import-Module PSWriteWord
# Erstellen eines neuen Word-Dokuments
$document = New-WordDocument -FilePath $docPath
# Prozesse abfragen und für Pie-Chart vorbereiten
$procs = Get-Process | Group-Object ProcessName
$procNames = $procs.Name
$procCount = foreach ($proc in $procs){ $proc.Count
}
# Hinzufügen des Kuchendiagramms
$params = @{
WordDocument = $document
ChartName = 'Test PieChart'
Names = $procNames
Values = $procCount
ChartLegendPosition = 'Bottom'
ChartLegendOverlay = $false
}
Add-WordPieChart @params
# Speichern des Dokuments
Save-WordDocument -WordDocument $document
# Dokument in Word öffnen
Invoke-Item $docPath
Bild 1 zeigt, wie in diesem Beispiel mit dem Code ein Diagramm entsteht, das die Prozessnamen sowie die Anzahl deren aktiver Instanzen anzeigt. Hierzu importieren wir zunächst das PSWriteWord-Modul und initiieren ein neues Word-Dokument unter einem frei wählbaren Pfad. Anschließend müssen wir die zu visualisierenden Daten vorbereiten.
Für das Cmdlet zur Erzeugung des Diagramms benötigen wir die Parameter "Names" und "Values" (jeweils vom Typ Array). Mit dem Add-WordPieChart-Cmdlet fügen wir das Pie-Chart zum Word-Dokument hinzu und speichern es anschließend.
Das nächste Beispiel in Listing 2 zeigt das Erstellen eines Arrays, das wiederum einzelne PSCustomObjects enthält. Jedes dieser Objekte repräsentiert eine Zeile der Tabelle. Die Eigenschaften dieser Objekte (Spalte1, Spalte2) entsprechen den Spalten der Tabelle.
Listing 2: Eine Tabelle anlegen
# Speicherpfad des Dokuments
$docPath = "./MeinDokument.docx"
# Importieren des PSWriteWord-Moduls
Import-Module PSWriteWord
# Erstellen eines Arrays mit Tabellendaten
$tabellenDaten = @(
[PSCustomObject]@{ Spalte1 = "Wert 1"; Spalte2 = "Wert A" }
[PSCustomObject]@{ Spalte1 = "Wert 2"; Spalte2 = "Wert B" }
[PSCustomObject]@{ Spalte1 = "Wert 3"; Spalte2 = "Wert C" }
)# Hinzufügen der Tabelle zum Dokument
$tableParams = @{
WordDocument = $document
DataTable = $tabellenDaten
Design = 'ColorfulGridAccent1'
}
Add-WordTable @tableParams
# Speichern des Dokuments
Save-WordDocument -WordDocument $document
Anschließend fügen wir die Tabelle in das Word-Dokument ein. Das Add-WordTable-Cmdlet nimmt das Array "$tabellenDaten" entgegen und verwendet es zum Aufbau der Tabelle. Der Parameter "Design = ColorfulGrid" gibt an, dass die Tabelle ein buntes Rasterdesign erhalten soll. Auch hier sichern wir das Dokument mit dem Save-WordDocument-Befehl.
Dokumentation eines ESX-Hosts
Die Dokumentation einer VMware-Umgebung ist ein komplexes Unterfangen, das von der detaillierten Erfassung verschiedener Informationen bis hin zur übersichtlichen Darstellung dieser Daten reicht. Im Folgenden schauen wir uns ein praxisnahes Vorgehen zur Dokumentation eines ESX-Hosts an. Ziel ist es, dass der Anwender lediglich den DNS-Namen des ESX-Hosts sowie die benötigten Anmeldedaten angibt. Neben PSWriteWord verwenden wir hierzu das PowerCLI-Modul. Das Skript soll die folgenden Aufgaben übernehmen:
- Sammeln der Daten: Hostname und IP-Adresse, Betriebssystemversion, Hardwareinformationen, installierte VMs mit ihren Konfigurationen.
- Erstellen des Dokuments mittels PS-WriteWord mit einer Überschrift und Darstellung der jeweiligen Informationen.
- Speichern und Freigeben des Dokuments: Abspeichern des Dokuments sowie Weiterleitung via E-Mail.
Das Skript in Listing 3 sammelt diese Informationen für den darin angegebenen ESX-Host ein.
Listing 3: Dokumentation eines ESX-Hosts
Importieren des VMware PowerCLI Moduls
Import-Module VMware.PowerCLI
# Variablen setzen
$esxHost = "<Name des Hosts oder dessen IP-Adresse>"
$userName = "<Benutzer>"
$password= "<Passwort>"
# Verbindung zum vCenter oder ESX-Host herstellen
Connect-VIServer -Server $esxHost -User $userName -Password $password -Force
# Ersetzen Sie "esx_host_name" mit dem Namen des ESX-Hosts, von dem Sie Daten abrufen möchten
$esxHost = Get-VMHost -Name $esxHost
# Abrufen der Host- und Hardwareinformationen
$hostInfo = @{
Hostname = $esxHost.Name
IPAddress = $esxHost.ExtensionData.
Config.Network.Vnic[0].Spec.Ip.IpAddress
OSVersion = $esxHost.Version
CPU = $esxHost.NumCpu
MemoryGB = $esxHost.MemoryTotalGB
}
$storageInfos = Get-VMHost -Name $esxHost
-PipelineVariable esx |
Get-Datastore |
Select-Object @{N='VMHost';E={$esx.Name}},Name,FreeSpaceMB,CapacityMB
# Abruf der Informationen der auf dem Host installierten VMs
$vmInfo = Get-VM -Location $esxHost | ForEach-Object {
@{
VMName = $_.Name
CPU = $_.NumCpu
MemoryGB = $_.MemoryGB
VMHost = $_.VMHost
PowerState = $_.PowerState
OS = $_.Guest.OSFullName
}
}
# Trennen der Verbindung
Disconnect-VIServer -Server $esxHost -Confirm:$false
Listing 4 erstellt nun das Word-Dokument sowie dessen Inhalte. Wir starten mit einer Überschrift, generieren dann Tabellen zur Abbildung der Host- und VM-Informationen und ergänzen dies abschließend mit einem Diagramm über die CPU-Auslastung. Schließlich speichern wir das Dokument und öffnen es zur Kontrolle. Das Gesamtergebnis zeigt Bild 2.
Listing 4: Visualisierung der VMware-Daten
Code aus Listing 3 zum Sammeln der Daten von ESX-Host und VMs
$wordDocumentPath = "$esxHost.docx"
# Importieren des PSWriteWord-Moduls
Import-Module PSWriteWord
# Erstellen eines neuen Word-Dokuments
$document = New-WordDocument -FilePath $wordDocumentPath
# Hinzufügen einer Überschrift für den Host
Add-WordText -WordDocument $document -Text "ESX-Host Informationen" -FontSize 18 -Bold $true
# Tabelle mit Hostinformationen erstellen
$hostTableData = @($hostInfo)
$hostTableData | Add-WordTable -WordDocument $document -Design ColorfulGridAccent1
# Hinzufügen einer Überschrift für den Host
Add-WordText -WordDocument $document -Text "ESX-Host DataStore Speicher" -FontSize 18 -Bold $true
# Diagramm zur Visualisierung von Host-Speicherressourcen
$pieChartParams = @{
WordDocument = $document
Names = @("Freier Speicher", "Belegter Speicher")
Values = @($storageInfos.FreeSpaceMB,
$storageInfos.CapacityMB)
}
Add-WordPieChart @pieChartParams
# Hinzufügen einer Überschrift für VMs
Add-WordText -WordDocument $document -Text "Liste der VMs" -FontSize 18 -Bold $true
# Tabelle mit VM-Informationen erstellen
$vmTableData = @($vmInfo)
$vmTableData | Add-WordTable -WordDocument $document -Design ColorfulGridAccent1
# Speichern des Dokuments
Save-WordDocument -WordDocument $document
# Öffnen des Dokuments zur Überprüfung
Invoke-Item $wordDocumentPath
Fazit
Die Verwendung von PSWriteWord in Kombination mit der PowerCLI zur Automatisierung der Dokumentation einer VMware-Umgebung zeigt, wie effizient moderne IT-Administration sein kann. PSWriteWord erweist sich dabei als Werkzeug, um komplexe und oft zeitraubende Dokumentationsaufgaben zu vereinfachen. Das Potenzial des Moduls reicht dabei über die reine Dokumentation hinaus. Es kann für eine Vielzahl von Anwendungen eingesetzt werden, von Berichterstattung bis hin zur automatisierten Erstellung von Anleitungen und Handbüchern.
In Anbetracht der Tatsache, dass PS-WriteWord-Modul nicht mehr aktiv weiterentwickelt wird, ist der Ausblick auf das Nachfolgeprojekt PSWriteOffice besonders spannend in Sachen Dokumentation. Dieses Modul verspricht, die Funktionalität auf weitere Office-Produkte wie Excel und PowerPoint auszudehnen, was den Anwendungsbereich noch weiter vergrößert.
(jp)
Link-Codes
[1] PSWriteWord: https://github.com/EvotecIT/PSWriteWord
[2] PSWriteOffice: https://github.com/EvotecIT/PSWriteOffice
[3] Befehle in PSWriteWord: https://evotec.xyz/hub/scripts/pswriteword-powershell-module/