ConvertTo-Html: HTML-Reports erstellen in PowerShell

Leitet man den Output eines Kommandos auf dieses Cmdlet über eine Pipe weiter, dann produziert es eine HTML-Seite, die neben einem <title> mit dem Inhalt "HTML TABLE" nur die eigentliche Payload enthält.

Da eine solche Web-Seite keine Formatierung und keine ergänzenden Informationen enthält, sieht sie entsprechend spartanisch und roh aus. Will man daraus einen HTML-Report erzeugen, der diesen Namen verdient, bedarf es einiger Maßnahmen.

Eigenschaften für den Report bearbeiten

Die wichtigste Vorbereitung besteht darin, die Ausgabe eines Kommandos oder eines Scripts so zu filtern, dass sie sich auf einer Seite des Browsers darstellen lässt, ohne dass man horizontal scrollen muss. Diese Aufgabe kann ConvertTo-Html selbst über­nehmen, solange man keine weiter­gehenden Ansprüche stellt.

Folgendes Beispiel ermittelt mit Get-EventLog die letzten 20 Einträge im Systemlog, die nach einem bestimmten Datum geschrieben wurden und leitet sie an ConvertTo-Html weiter. Dieses übernimmt mit dem Parameter Property die gewünschten Eigenschaften in den Bericht:

Get-EventLog -LogName System -after 24.08.2017 -Newest 20 |
ConvertTo-Html -Property EventID, MachineName, Index, Category, EntryType,
Message, Source, InstanceId, TimeGenerated > eventrep.html

Dieses Kommando schreibt die HTML-Ausgabe im in die Datei eventrep.html. Sieht man diese im Browser an, so fällt auf, dass die Spalten­überschriften identisch sind mit den Namen der Eigen­schaften. Diese sind nicht immer aufschlussreich und man könnte überlegen, sie ins Deutsche zu übersetzen.

Hinzu kommt etwa auch noch, dass MachineName den FQDN des Rechners enthält. Wenn sie ohnehin alle der gleichen Domäne angehören, dann kann man hier die Spaltenbreite reduzieren, um den knapp bemessenen Platz besser auszunutzen.

Attribute anpassen mit Calculated Properties

Für diese Aufgabe greift man auf Select-Object zurück, weil dieses Cmdlet den Einsatz von Calculated Properties unterstützt. Mit ihrer Hilfe kann man den Namen von Eigenschaften und ihren Wert ändern:

Get-EventLog -LogName System -after 24.08.2017 -Newest 20 | select EventID, @{Name="Host";Expression={($_.MachineName.split('.'))[0]}}, Index, Category, @{Name="Typ";Expression={$_.EntryType}}, Message, Source, InstanceId, TimeGenerated | ConvertTo-Html > eventrep.html

Dieses Beispiel enthält gleich zwei solcher berechneten Eigenschaften. Der Ausdruck

@{Name="Host";Expression={($_.MachineName.split('.'))[0]}}

teilt den MachineName entlang von '.' als Trennzeichen auf und nimmt das erste Element des Arrays, das aus dieser Operation hervorgeht. Es handelt sich dabei um den Namen des Hosts. Dieses neue Attribut erhält die Bezeichnung "Host".

Die zweite Calculated Property

@{Name="Typ";Expression={$_.EntryType}}

beschränkt sich darauf, den Namen in der Spalten­überschrift von EntryType auf Typ zu ändern.

Report um Metadaten ergänzen

Im nächsten Schritt wird man wahrscheinlich beschreibende Informationen hinzufügen wollen. Dazu gehört etwa ein aufschlussreicher <title> oder eine ebensolche Überschrift. Für beide sieht ConvertTo-Html entsprechende Parameter vor:

$datum = Get-Date -Format "dd.MM.yyyy, HH:mm" Get-EventLog -LogName System -after 24.08.2017 -Newest 20 | select EventID, @{Name="Host";Expression={($_.MachineName.split('.'))[0]}}, Index, Category,EntryType, Message, Source, InstanceId, TimeGenerated | ConvertTo-Html -Title "Report zum Systemlog" `  -PreContent "<h1>Report erzeugt von $env:USERNAME am $datum</h1>" > eventrep.html

Wie man leicht erkennen kann, legt der Parameter Title den <title> im Kopf des Dokuments fest. Mit PreContent kann man sämtliche Inhalte definieren, die vor der eigentlichen Ausgabe des Cmdlets erscheinen sollen.

In unserem Fall ist dies eine Überschrift, die den Namen des Users und das aktuelle Datum plus Uhrzeit enthält. Hier könnte man etwa auch ein Firmenlogo einfügen. PostContent erfüllt den gleichen Zweck unterhalb der Tabelle.

Style-Informationen hinzufügen

Schließlich kann man sich daran machen, den Report ein bisschen hübscher zu gestalten. Erzeugt man solche Berichte öfters, dann erstellt man ein externes Stylesheet und verbindet dieses über den Parameter CssUri mit der HTML-Datei, indem man ihm die URL der CSS-Datei übergibt. Sinnvoll ist dies allerdings nur, wenn man das CSS auf einem allgemein zugänglichen Web-Server ablegen kann.

In den meisten Fällen wird es jedoch einfacher sein, die Formatierung in den <head> des Reports zu übernehmen. Allzu umfangreich werden die Stildefinitionen meist ohnehin nicht ausfallen, nachdem ConvertTo-Html keinerlei class- oder id-Attribute in der Tabelle verwendet.

Falls man mit den Parametern Body, PreContent oder PostContent nicht viel eigenen Inhalt einfügt, dann wird man im Wesentlichen nur die Stile für die Elemente einer Tabelle wie table, tr, th oder td definieren.

Formatierung der Tabelle

Für diese Aufgabe kann man den Parameter Head verwenden, der den Kopf des Dokuments gestaltet. Wenn man sich dafür entscheidet, muss man den gesamten Inhalt des <head>-Elements selbst bereitstellen, also auch den <title>. Der Parameter Title greift in diesem Fall nicht mehr.

$head = "<style> td {width:100px; max-width:300px; background-color:lightgrey;} table {width:100%;} th {font-size:14pt;background-color:yellow;} </style> <title>Report zum Systemlog</title>" $datum = Get-Date -Format "dd.MM.yyyy, HH:mm" Get-EventLog -LogName System -after 24.08.2017 -Newest 20 | select EventID, @{Name="Host";Expression={($_.MachineName.split('.'))[0]}}, Index, Category, @{Name="Typ";Expression={$_.EntryType}}, Message, Source, InstanceId, TimeGenerated | ConvertTo-Html -Head $head ` -PreContent "<h1>Report erzeugt von $env:USERNAME am $datum</h1>" | Out-File ".\eventrep.html"

In diesem Beispiel definieren wir den gesamten Kopfbereich des Dokuments in der Variablen $head und übergeben diese dann an den gleichnamigen Parameter.

Um eine halbwegs günstige Aufteilung der Seitenbreite zu erreichen, kann man für td ein einheitliches Maß festlegen, das für die schmäleren Spalten passt (hier 100px). Zusätzlich verhindert man mit max-width, dass breite Spalten wie etwa jene mit dem Message-Text die halbe Seite belegen. Das klappt aber nicht, wenn man die ursprünglichen Zeilen­umbrüche der Messages mit white-space:pre beibehalten möchte.

Wenn sich die Daten partout nicht in den verfügbaren Spalten der Tabelle unterbringen lassen, kann man mit dem Parameter -As List zur Listenform umschalten. Dabei handelt es sich zwar auch um eine Tabelle, aber die Namen der Attribute stehen nicht oben, sondern links.