ConvertTo-Html: HTML-Reports erstellen in PowerShell

    Icon für Report-DashboardMit seinen zahl­reichen Cmdlets erlaubt Power­Shell den Abruf von fast belie­bigen System­infor­mationen. Wenn ein Kom­mando größere Daten­mengen zurück­gibt, dann ist die Aus­gabe auf dem Bild­schirm aber meist sehr unüber­sichtlich. In diesem Fall kann man die Resul­tate für die Ansicht im Browser auf­bereiten.

    PowerShell unterstützt eine ganze Reihe von Optionen, um Daten in verschiedenen Formaten darzustellen. Dazu zählt etwa das Konvertieren zu bzw. aus CSV, die Auf­bereitung mittels Format-List, Formate-Table und Out-GridView oder das Schreiben von XML-Dateien. Mit ConvertTo-Html kommt eine weitere Möglich­keit hinzu.

    Standardmäßig nur rohe Anzeige der Daten

    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.

    Die von ConvertTo-Html produzierte Web-Seite bietet keine ansehnliche Optik.

    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.

    Die Spaltenüberschriften der Tabelle entsprechen den Namen der Attribute, Namen der Hosts erscheinen als FQDN.

    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:

    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 nach dem Anpassen der Eigenschaften mittels Calculated Properties.

    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:

    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.

    Report mit angepasstem title und einer h1-Überschrift

    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.

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

    Report mit einfacher Formatierung durch CSS

    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.

    Listendarstellung von ConvertTo-Html mit dem Parameter -As List

    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.

    Keine Kommentare