Export-RjRbXlsx

Objekte aus Azure Automation Runbooks in formatierte native Excel-Arbeitsmappen (.xlsx) exportieren, ohne externe Modulabhängigkeiten.

Übersicht

Export-RjRbXlsx ist der Standard-Helfer zum Erzeugen von Excel-Reportdateien (.xlsx) aus RealmJoin-Reporting-Runbooks. Es schreibt eine oder mehrere Tabellen von PSCustomObjects als eine native Excel-Arbeitsmappe unter ausschließlicher Verwendung von .NET (System.IO.Compression) — kein ImportExcel, keine COM-Automatisierung, kein anderes externes Modul ist in der Automation-Umgebung erforderlich.

Noch nicht Teil von RealmJoin.RunbookHelper. Export-RjRbXlsx ist noch nicht zusammen mit dem RealmJoin.RunbookHelper Modul ausgeliefert — es wird mit der nächsten Modulveröffentlichungenthalten sein. Bis dahin ist die Funktion in den Runbooks, die sie verwenden, inline dupliziert und kann von dort kopiert werden, zum Beispiel aus sync-MFA-secure-users-to-group_scheduled.ps1 (Region Funktionsdefinitionen).

Wichtige Merkmale:

• Keine Modulabhängigkeiten — die Arbeitsmappe wird direkt als Open-XML-Paket über System.IO.Compression.ZipArchive. Dadurch werden sowohl die Kaltstartkosten schwergewichtiger Module als auch Assembly-Konflikte in gemischten Reporting-Runbooks vermieden.
• Stilvolle, sofort teilbare Ausgabe — jedes Arbeitsblatt erhält eine formatierte Excel-Tabelle (dunkelblauer Kopf, Zebra-Zeilen, die beim erneuten Sortieren erhalten bleiben, Filter-Dropdowns), eine fixierte Kopfzeile, berechnete Spaltenbreiten und eine automatische Druckeinrichtung (Ausrichtung aus der Inhaltsbreite abgeleitet, Kopfzeile auf jeder gedruckten Seite wiederholt). Der Tab des ersten Arbeitsblatts ist in RealmJoin-Orange gefärbt.
• Typentreue Zellen — .NET-Zahlen werden zu Excel-Zahlen, Datum/Uhrzeit Werte und ISO-8601-Strings (z. B. Graph-Datenfelder) werden zu echten, sortierbaren Excel-Daten (vom Client lokalisiert), und http/https URLs werden zu anklickbaren Hyperlinks. Alle anderen Zeichenketten bleiben Text — Werte wie Seriennummern oder IMEIs werden niemals in Zahlen umgewandelt, und eine Formeleinschleusung ist nicht möglich.
• Ein- oder mehrere Arbeitsblätter — Zeilen in ein einzelnes Blatt pipen oder ein geordnetes Dictionary für eine Arbeitsmappe mit mehreren Arbeitsblättern plus einem optionalen "Info"-Deckblatt übergeben.
• Integrierte Berichtspolitur — optionale Hervorhebungsregeln per bedingter Formatierung für Statusspalten, Datenbalken im Zellinhalt für numerische Spalten, freundlicher Hyperlink-Anzeigetext und Tausendertrennzeichen.

Ein typischer Verbraucher ist ein geplantes Reporting-Runbook, das CSV- und XLSX-Dateien erzeugt und sie dann über Send-RjRbReportEmail und/oder Publish-RjRbFilesToStorageContainer.

Voraussetzungen

Nichts außer PowerShell selbst. Die Funktion verwendet nur .NET-Typen, die in jeder Azure Automation-Laufzeit verfügbar sind (System.IO.Compression, System.Text, System.Xml-freier Zeichenkettenaufbau). Keine Graph- oder Az-Verbindung ist erforderlich — die Funktion arbeitet ausschließlich mit lokalen Daten und schreibt eine lokale Datei.

Schnellstart

Der minimal funktionsfähige Aufruf leitet die Zeilen in die Funktion weiter und gibt den Ausgabepfad an:

$devices | Export-RjRbXlsx -Path (Join-Path $env:TEMP 'devices.xlsx') -WorksheetName 'Devices'

Dies erzeugt eine Arbeitsmappe mit einem einzelnen "Devices"-Arbeitsblatt: formatierte Tabelle mit Filter-Dropdowns, fixierter Kopfzeile, automatisch angepassten Spalten und Druckeinrichtung — bereit, einer Bericht-E-Mail angehängt oder in einen Speichercontainer hochgeladen zu werden.

Parameter

Parameter-Sätze

Die Funktion hat zwei Parametersätze:

Parametersatz	Eingabe	Anwendungsfall
SingleSheet (Standard)	-InputObject (auch per Pipeline) + -WorksheetName	Eine Tabelle, ein Arbeitsblatt.
MultiSheet	-Worksheets (geordnetes Dictionary)	Mehrere Tabellen als separate Arbeitsblätter in einer Arbeitsmappe.

Erforderlich

Parameter	Typ	Beschreibung
Pfad	Zeichenfolge	Vollständiger Pfad der .xlsx zu erstellenden Datei. Eine vorhandene Datei wird überschrieben.

Dateneingabe

Parameter	Typ	Parametersatz	Beschreibung
InputObject	object[]	SingleSheet	Die zu exportierenden Zeilen (Array von Objekten; auch per Pipeline akzeptiert). Die Spaltenreihenfolge folgt der Eigenschaftenreihenfolge des ersten Objekts. Dictionaries/Hashtables werden in Objekte umgewandelt.
WorksheetName	Zeichenfolge	SingleSheet	Name des einzelnen Arbeitsblatts. Standard: Report.
Worksheets	IDictionary	MultiSheet	Geordnetes Dictionary von Arbeitsblattname → Zeilen, z. B. ([ordered]@{ 'Summary' = $summary; 'Details' = $details }). Muss mindestens einen Eintrag enthalten.

Optional — Inhalt & Formatierung

Parameter	Typ	Standard	Beschreibung
CoverSheet	IDictionary	—	Geordnetes Dictionary, dargestellt als „Info“-Deckblatt (erster Tab): ein Titel Schlüssel wird zur Überschrift, alle anderen Schlüssel werden zu Bezeichner/Wert-Zeilen, z. B. ([ordered]@{ Title = 'Device Report'; Tenant = 'contoso'; Generated = '2026-07-16 08:00 UTC' }).
HighlightRules	object[]	—	Bedingte Formatierung für Statusspalten. Array von Hashtables mit Column (Spaltenüberschrift), Wert (exakter Zelltext, groß-/kleinschreibungsunabhängig) und Color (Green, Red oder Yellow — den klassischen Excel-Hervorhebungsvoreinstellungen). Regeln werden auf jedem Arbeitsblatt angewendet, das die benannte Spalte enthält.
DataBarColumns	object[]	—	Numerische Spaltennamen, die einen Datenbalken im Zellinhalt erhalten (orange, Verlauf von Minimum zu Maximum), z. B. @('DeviceCount'). Spalten, die auf einem Arbeitsblatt nicht vorhanden sind, werden übersprungen.
HyperlinkText	IDictionary	—	Spaltenname → Anzeigetext für Hyperlink-Zellen, z. B. @{ Portal = 'Open in Intune' }. Die Zelle zeigt den freundlichen Text, das Linkziel bleibt die vollständige URL. Spalten ohne Zuordnung zeigen weiterhin die URL an.
NoHyperlink	Schalter	aus	Nicht konvertieren http/https URL-Strings in anklickbare Hyperlinks.
HideGridLines	Schalter	aus	Die Gitternetzlinien des Arbeitsblatts außerhalb der Tabelle ausblenden (zur besseren Lesbarkeit sind Gitternetzlinien standardmäßig aktiviert; das Deckblatt blendet sie immer aus).
UseThousandsSeparator	Schalter	aus	Numerische Zellen mit einem Tausendertrennzeichen formatieren (#,##0 für Ganzzahlen, #,##0.00 für Dezimalzahlen — von Excel lokalisiert).

Verwendungsbeispiele

Mehrere Arbeitsblätter

Export-RjRbXlsx `
    -Worksheets ([ordered]@{ 'Summary' = $summaryRows; 'Details' = $detailRows }) `
    -Path (Join-Path $env:TEMP 'report.xlsx')

Die Tabs der Arbeitsblätter erscheinen in Dictionary-Reihenfolge; der erste Tab ist in RealmJoin-Orange gefärbt, die übrigen Tabs in neutralem Grau.

Deckblatt, Hervorhebungsregeln und Datenbalken

Das vollständige „Berichtsarbeitsmappen“-Muster mit Info-Deckblatt, farbigen Statusspalten und Datenbalken im Zellinhalt:

$coverSheet = [ordered]@{
    Title             = 'Device Report'
    'Tenant'          = $tenantDisplayName
    'Generated (UTC)' = (Get-Date).ToUniversalTime().ToString('yyyy-MM-dd HH:mm')
    'Runbook version' = $Version
    'Devices total'   = "$($devices.Count)"
}

Export-RjRbXlsx `
    -Worksheets      ([ordered]@{ 'Devices' = $devices }) `
    -Path            (Join-Path $env:TEMP 'device-report.xlsx') `
    -CoverSheet      $coverSheet `
    -HighlightRules  @(
        @{ Column = 'Compliant'; Value = 'yes'; Color = 'Green' },
        @{ Column = 'Compliant'; Value = 'no';  Color = 'Red' }
    ) `
    -DataBarColumns  @('AppCount')

Das Deckblatt wird als erster Tab mit dem Namen „Info“ eingefügt, mit dem Titel Wert als dunkelblauer Überschrift über einer orangefarbenen Akzentlinie und allen anderen Schlüsseln als Bezeichner/Wert-Zeilen.

Freundlicher Hyperlink-Text

URL-Spalten sind standardmäßig anklickbar und zeigen die rohe URL an. Ordnen Sie einer Spalte einen freundlichen Anzeigetext zu, um die Tabelle schmal zu halten:

$rows = $devices | Select-Object DeviceName, SerialNumber, @{
    n = 'Portal'
    e = { "https://intune.microsoft.com/#view/Microsoft_Intune_Devices/DeviceSettingsMenuBlade/~/overview/mdmDeviceId/$($_.id)" }
}

$rows | Export-RjRbXlsx -Path $xlsxPath -WorksheetName 'Devices' -HyperlinkText @{ Portal = 'Open in Intune' }

Kombination mit den Zustellhilfen

Ein gängiges End-to-End-Muster in Reporting-Runbooks — die Arbeitsmappe schreiben, dann an eine Bericht-E-Mail anhängen und/oder für einen Download-Link hochladen:

$xlsxPath = Join-Path $env:TEMP 'report.xlsx'
Export-RjRbXlsx -Worksheets ([ordered]@{ Changes = $changeRows; 'All Users' = $allUserRows }) `
    -Path $xlsxPath -CoverSheet $coverSheet

# E-Mail-Zustellung — die kompakte Arbeitsmappe ist ideal als Fallback-Anhang bei Größenbeschränkungen
Send-RjRbReportEmail `
    -EmailFrom       $emailFrom `
    -EmailTo         $EmailTo `
    -Subject         "Bericht — $(Get-Date -Format 'yyyy-MM-dd')" `
    -MarkdownContent $reportMd `
    -Attachments     @($xlsxPath)

# ...oder Zustellung über Speicher mit einem zeitlich begrenzten Download-Link
$uploaded = Publish-RjRbFilesToStorageContainer `
    -FilePaths          $xlsxPath `
    -ContainerName      'reports' `
    -ResourceGroupName  $ResourceGroupName `
    -StorageAccountName $StorageAccountName `
    -AddBlobNamePrefix  $true

Siehe Send-RjRbReportEmail und Publish-RjRbFilesToStorageContainer für die Zustellseite dieses Musters.

Behandlung der Zelltypen

Eingabewert	Wird dargestellt als
.NET-Ganzzahl-/Fließkomma-/Dezimaltypen	Excel-Zahl (optional mit Tausendertrennzeichen via -UseThousandsSeparator). NaN/Infinity werden als Text behandelt.
[datetime]	Echte Excel-Datumsangabe; datumsbezogene Werte erhalten ein Datumsformat, Werte mit Uhrzeitanteil erhalten ein Datum-Uhrzeit-Format. Vom Anzeigclient lokalisiert.
ISO-8601-Datumsstrings (2026-07-16T08:00:00Z, typische Graph-Datenfelder)	Analysiert und als echte, sortierbare Excel-Daten dargestellt.
[bool]	Excel-Boolean (TRUE/FALSE).
http:// / https:// URL-Strings	Anklickbarer Hyperlink (unterdrücken mit -NoHyperlink; Anzeigetext via -HyperlinkText).
Arrays / Sammlungen	Elemente verbunden mit ; zu einer Textzelle.
$null / DBNull	Leere Zelle.
Alles andere	Klartext. Führende/nachfolgende Leerzeichen bleiben erhalten; Zeichenketten werden niemals als Zahlen oder Formeln neu interpretiert.

Verhalten & Fehlerbehandlung

Arbeitsblattnamen

Arbeitsblattnamen werden bereinigt, um den Regeln von Excel zu entsprechen: ungültige Zeichen ([ ] : * ? / \\) werden ersetzt, Namen werden auf 31 Zeichen gekürzt, leere Namen werden zu Sheet<n>, und Duplikate erhalten ein _2, _3, …-Suffix.

Spaltenüberschriften

Überschriftennamen stammen aus der Eigenschaftenreihenfolge des ersten Zeilenobjekts. Leere Eigenschaftsnamen werden zu Column<n>; doppelte Namen (groß-/kleinschreibungsunabhängig) werden mit einem _2, _3, …-Suffix dedupliziert, weil Excel-Tabellenspalten eindeutig und nicht leer sein müssen.

Leere Arbeitsblätter

Ein Arbeitsblatt, dessen Zeilenmenge leer ist, wird trotzdem geschrieben — es enthält eine einzelne Zelle „No data available“ und keine Tabelle. Ein leeres -Worksheets Dictionary löst jedoch Export-RjRbXlsx: -Worksheets muss mindestens einen Eintrag enthalten.

Zeilenlimit

Excel begrenzt Arbeitsblätter auf 1.048.576 Zeilen. Die Funktion löst Export-RjRbXlsx: Arbeitsblatt '<name>' hat <n> Zeilen - das xlsx-Limit sind 1048575 Datenzeilen. vor dem Schreiben einer ungültigen Datei aus. Sehr große Exporte sollten auf mehrere Arbeitsblätter aufgeteilt oder stattdessen als CSV bereitgestellt werden.

Hervorhebungsregeln

• Regeln, die auf eine Spalte verweisen, die auf einem Arbeitsblatt nicht existiert, werden für dieses Arbeitsblatt stillschweigend übersprungen (sie gelten weiterhin für andere Arbeitsblätter, die die Spalte haben).
• Ein unbekannter Color Wert erzeugt Export-RjRbXlsx: unbekannte Hervorhebungsfarbe '<color>' - verwende Green, Red oder Yellow. Regel wird übersprungen. als Warnung und überspringt nur diese Regel.

Spaltenbreiten

Breiten werden aus der Überschriftenlänge und den ersten 1.000 Datenzeilen berechnet (begrenzt auf 8 bis 60 Zeichen), sodass sehr große Exporte die Breitenberechnung nicht verlangsamen.

Ausgabedatei

Eine vorhandene Datei unter Pfad wird gelöscht und neu erstellt. Die Funktion erstellt fehlende übergeordnete Verzeichnisse nicht — stellen Sie sicher, dass der Zielordner existiert (z. B. New-Item -ItemType Directory).

Ausgaben

Die Funktion gibt nichts zurück. Sie schreibt die Arbeitsmappe nach Pfad und gibt eine ausführliche Meldung aus (Export-RjRbXlsx: wrote <n> worksheet(s) to <path>) sichtbar, wenn das Runbook mit -Verbose oder $VerbosePreference = 'Continue'.

Siehe auch

• Send-RjRbReportEmail — die erzeugte Arbeitsmappe als Bericht-E-Mail-Anhang ausliefern.
• Publish-RjRbFilesToStorageContainer — die Arbeitsmappe in Azure Blob Storage hochladen und einen zeitlich begrenzten Download-Link zurückgeben.
• Runbook-Berichtseinstellungen — zentrale Konfiguration der Berichtszustellkanäle.
• Beispiel für die Inline-Verwendung: sync-MFA-secure-users-to-group_scheduled.ps1 — das Runbook, das die Funktion derzeit enthält, bis sie mit dem Modul ausgeliefert wird.