Export-RjRbXlsx

Exportez des objets depuis des runbooks Azure Automation vers des classeurs Excel natifs stylisés (.xlsx), sans aucune dépendance à des modules externes.

Aperçu

Export-RjRbXlsx est l'assistant standard pour produire des fichiers de rapport Excel (.xlsx) à partir des runbooks de reporting RealmJoin. Il écrit un ou plusieurs tableaux de PSCustomObjects sous la forme d'un classeur Excel natif en utilisant uniquement .NET (System.IO.Compression) — sans ImportExcel, sans automatisation COM, aucun autre module externe n'est requis dans l'environnement Automation.

Disponible depuis RealmJoin.RunbookHelper 0.8.8. La fonction est exportée par le module ; les copies en ligne de code que contenaient les versions antérieures des runbooks ont été supprimées. Les runbooks qui l'utilisent déclarent la version du module en conséquence :

#Requires -Modules @{ModuleName = "RealmJoin.RunbookHelper"; ModuleVersion = "0.8.8" }

Caractéristiques principales:

• Aucune dépendance de module — le classeur est assemblé directement comme un package Open XML via System.IO.Compression.ZipArchive. Cela évite à la fois le coût de démarrage à froid des modules lourds et les conflits d'assembly dans les runbooks de reporting mixtes.
• Sortie stylée, prête à partager — chaque feuille de calcul reçoit un tableau Excel stylé (en-tête bleu marine, lignes zébrées qui suivent le réordonnancement, menus déroulants de filtre), une ligne d'en-tête figée, des largeurs de colonnes calculées et une mise en page d'impression automatique (orientation déterminée à partir de la largeur du contenu, ligne d'en-tête répétée sur chaque page imprimée). Le premier onglet de feuille est coloré en orange RealmJoin.
• Cellules fidèles au type — les nombres .NET deviennent des nombres Excel, Date et heure les valeurs de date et les chaînes ISO-8601 (p. ex. les champs de date Graph) deviennent de vraies dates Excel triables (localisées par le client), et http/https les URL deviennent des liens hypertextes cliquables. Toutes les autres chaînes restent du texte — des valeurs comme les numéros de série ou les IMEI ne sont jamais converties en nombres, et l'injection de formule est impossible.
• Une ou plusieurs feuilles de calcul — envoyez des lignes vers une seule feuille, ou passez un dictionnaire ordonné pour un classeur comportant plusieurs feuilles de calcul, plus une feuille de couverture "Info" facultative.
• Finition du rapport intégrée — règles de mise en forme conditionnelle facultatives pour mettre en évidence les colonnes de statut, barres de données dans les cellules pour les colonnes numériques, texte d'affichage convivial pour les hyperliens et séparateurs de milliers.

Un consommateur typique est un runbook de reporting planifié qui génère des fichiers CSV et XLSX puis les distribue via Send-RjRbReportEmail et/ou Publish-RjRbFilesToStorageContainer.

Prérequis

Rien au-delà de PowerShell lui-même. La fonction n'utilise que des types .NET disponibles dans chaque runtime Azure Automation (System.IO.Compression, System.Text, System.Xmlpour la construction de chaînes sans dépendance). Aucune connexion Graph ou Az n'est requise — la fonction fonctionne uniquement sur des données locales et écrit un fichier local.

Démarrage rapide

L'appel minimal viable transmet les lignes à la fonction et spécifie le chemin de sortie :

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

Cela produit un classeur avec une seule feuille de calcul "Devices" : tableau stylé avec menus déroulants de filtre, ligne d'en-tête figée, colonnes ajustées automatiquement et mise en page d'impression — prêt à être joint à un e-mail de rapport ou téléversé vers un conteneur de stockage.

Paramètres

Jeux de paramètres

La fonction a deux jeux de paramètres :

Jeu de paramètres	Entrée	Cas d'utilisation
SingleSheet (par défaut)	-InputObject (également via le pipeline) + -WorksheetName	Un tableau, une feuille de calcul.
MultiSheet	-Worksheets (dictionnaire ordonné)	Plusieurs tableaux dans des feuilles de calcul distinctes d'un seul classeur.

Requis

Paramètre	Type	Description
Chemin	string	Chemin complet du .xlsx fichier à créer. Un fichier existant est écrasé.

Entrée des données

Paramètre	Type	Jeu de paramètres	Description
InputObject	object[]	SingleSheet	Les lignes à exporter (tableau d'objets ; également accepté via le pipeline). L'ordre des colonnes suit l'ordre des propriétés du premier objet. Les dictionnaires/hashtables sont convertis en objets.
WorksheetName	string	SingleSheet	Nom de la seule feuille de calcul, 31 caractères maximum (voir Noms de feuilles de calcul). Par défaut : Report.
Worksheets	IDictionary	MultiSheet	Dictionnaire ordonné associant nom de feuille de calcul → lignes, par ex. ([ordered]@{ 'Summary' = $summary; 'Details' = $details }). Doit contenir au moins une entrée. Les clés sont des noms de feuilles de calcul, de 31 caractères maximum chacune (voir Noms de feuilles de calcul).

Facultatif — contenu et mise en forme

Paramètre	Type	Défaut	Description
CoverSheet	IDictionary	—	Dictionnaire ordonné rendu sous forme de feuille de couverture "Info" (premier onglet) : une Title clé devient le titre, toutes les autres clés deviennent des lignes étiquette/valeur, par ex. ([ordered]@{ Title = 'Device Report'; Tenant = 'contoso'; Generated = '2026-07-16 08:00 UTC' }).
HighlightRules	object[]	—	Mise en forme conditionnelle pour les colonnes de statut. Tableau de hashtables avec Column (nom d'en-tête), Valeur (texte exact de cellule, insensible à la casse) et Color (Green, Red ou Yellow — les préréglages de mise en évidence Excel classiques). Les règles s'appliquent sur chaque feuille de calcul qui contient la colonne nommée.
DataBarColumns	object[]	—	Noms de colonnes numériques qui obtiennent une barre de données dans la cellule (orange, dégradé du minimum au maximum), par ex. @('DeviceCount'). Les colonnes qui n'existent pas dans une feuille de calcul sont ignorées.
HyperlinkText	IDictionary	—	Nom de colonne → texte affiché pour les cellules de lien hypertexte, par ex. @{ Portal = 'Open in Intune' }. La cellule affiche le texte convivial, la cible du lien reste l'URL complète. Les colonnes sans mappage continuent d'afficher l'URL.
NoHyperlink	interrupteur	désactivé	Ne pas convertir http/https les chaînes URL en liens hypertextes cliquables.
HideGridLines	interrupteur	désactivé	Masquer les lignes de grille de la feuille de calcul à l'extérieur du tableau (les lignes de grille sont conservées par défaut pour la lisibilité ; la feuille de couverture les masque toujours).
UseThousandsSeparator	interrupteur	désactivé	Formater les cellules numériques avec un séparateur de milliers (#,##0 pour les entiers, #,##0.00 pour les décimales — localisé par Excel).

Exemples d'utilisation

Plusieurs feuilles de calcul

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

Les onglets des feuilles de calcul apparaissent dans l'ordre du dictionnaire ; le premier onglet est coloré en orange RealmJoin, les onglets restants en gris neutre.

Feuille de couverture, règles de mise en évidence et barres de données

Le modèle complet de "classeur de rapport" avec une feuille de couverture d'information, des colonnes de statut colorées et des barres de données dans les cellules :

$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')

La feuille de couverture est insérée comme premier onglet nommé "Info", avec le Title titre comme en-tête bleu marine au-dessus d'une ligne d'accent orange et toutes les autres clés comme lignes étiquette/valeur.

Texte convivial pour les hyperliens

Les colonnes URL sont cliquables par défaut et affichent l'URL brute. Mappez une colonne vers un texte d'affichage convivial pour garder le tableau étroit :

$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' }

Combinaison avec les assistants de livraison

Un schéma de bout en bout courant dans les runbooks de reporting : écrire le classeur, puis l'attacher à un e-mail de rapport et/ou le téléverser pour obtenir un lien de téléchargement :

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

# Livraison par e-mail — le classeur compact est idéal comme pièce jointe de secours en cas de limite de taille
Send-RjRbReportEmail `
    -EmailFrom       $emailFrom `
    -EmailTo         $EmailTo `
    -Subject         "Rapport — $(Get-Date -Format 'yyyy-MM-dd')" `
    -MarkdownContent $reportMd `
    -Attachments     @($xlsxPath)

# ...ou livraison via le stockage avec un lien de téléchargement à durée limitée
$uploaded = Publish-RjRbFilesToStorageContainer `
    -FilePaths          $xlsxPath `
    -ContainerName      'reports' `
    -ResourceGroupName  $ResourceGroupName `
    -StorageAccountName $StorageAccountName `
    -AddBlobNamePrefix  $true

Voir Send-RjRbReportEmail et Publish-RjRbFilesToStorageContainer pour la partie livraison de ce modèle.

Gestion des types de cellules

Valeur d'entrée	Rendu comme
Types .NET entiers / à virgule flottante / décimaux	Nombre Excel (éventuellement avec séparateur de milliers via -UseThousandsSeparator). NaN/Infinity retournent au texte.
[datetime]	Vraie date Excel ; les valeurs sans heure obtiennent un format de date, les valeurs avec une composante horaire obtiennent un format date-heure. Localisé par le client affichant.
Chaînes de date ISO-8601 (2026-07-16T08:00:00Z, champs de date Graph typiques)	Analysées et rendues comme de vraies dates Excel triables.
[bool]	Booléen Excel (TRUE/FALSE).
http:// / https:// Chaînes URL	Lien hypertexte cliquable (désactivez avec -NoHyperlink; texte affiché via -HyperlinkText).
Tableaux / collections	Éléments joints avec ; dans une seule cellule de texte.
$null / DBNull	Cellule vide.
Tout le reste	Texte brut. Les espaces de début/de fin sont conservés ; les chaînes ne sont jamais réinterprétées comme des nombres ou des formules.

Comportement et gestion des erreurs

Noms de feuilles de calcul

Les noms de feuilles de calcul sont assainis pour respecter les règles d'Excel : les caractères invalides ([ ] : * ? / \\) sont remplacés, les noms sont tronqués à 31 caractères, les noms vides deviennent Sheet<n>, et les doublons reçoivent un _2, _3, … suffixe.

Conservez des noms de feuilles de calcul d'au plus 31 caractères. Cela s'applique à -WorksheetName et aux clés de -Worksheets, y compris aux valeurs insérées à l'exécution. Les noms plus longs sont tronqués silencieusement, ce qui peut couper la partie significative du nom ou rendre deux noms identiques (le second reçoit alors un _2 suffixe). Choisissez des noms courts et significatifs sans \\ / ? * [ ] :, et utilisez le même nom que le titre du tableau correspondant dans l'onglet Données de sortie du runbook, où l'export vers Excel échoue pour les titres de plus de 31 caractères.

En-têtes de colonne

Les noms d'en-tête proviennent de l'ordre des propriétés du premier objet ligne. Les noms de propriété vides deviennent Column<n>; les noms dupliqués (insensibles à la casse) sont dédupliqués avec un _2, _3, … suffixe, car les colonnes des tableaux Excel doivent être uniques et non vides.

Feuilles de calcul vides

Une feuille de calcul dont l'ensemble des lignes est vide est quand même écrite — elle contient une seule cellule "No data available" et aucun tableau. En revanche, un dictionnaire vide provoque -Worksheets erreur Export-RjRbXlsx: -Worksheets doit contenir au moins une entrée.

Limite de lignes

Excel limite les feuilles de calcul à 1 048 576 lignes. La fonction lance Export-RjRbXlsx: la feuille de calcul '<name>' a <n> lignes - la limite xlsx est de 1048575 lignes de données. avant d'écrire un fichier invalide. Répartissez les exportations très volumineuses sur plusieurs feuilles de calcul ou fournissez-les plutôt en CSV.

Règles de mise en évidence

• Les règles qui font référence à une colonne inexistante dans une feuille de calcul sont ignorées silencieusement pour cette feuille (elles s'appliquent toujours aux autres feuilles qui ont la colonne).
• Une valeur Color inconnue émet Export-RjRbXlsx: couleur de mise en évidence inconnue '<color>' - utilisez Green, Red ou Yellow. Règle ignorée. sous forme d'avertissement et n'ignore que cette règle.

Largeurs de colonne

Les largeurs sont calculées à partir de la longueur de l'en-tête et des 1 000 premières lignes de données (bornées entre 8 et 60 caractères), de sorte que les exportations très volumineuses ne ralentissent pas lors du calcul des largeurs.

Fichier de sortie

Un fichier existant à Chemin est supprimé puis recréé. La fonction ne crée pas les répertoires parents manquants — assurez-vous que le dossier cible existe (par ex. New-Item -ItemType Directory).

Sorties

La fonction ne renvoie rien. Elle écrit le classeur dans Chemin et émet un message verbeux (Export-RjRbXlsx: a écrit <n> feuille(s) de calcul dans <path>) visible lorsque le runbook s'exécute avec -Verbose ou $VerbosePreference = 'Continue'.

Voir aussi

• Send-RjRbReportEmail — remettre le classeur généré en pièce jointe à un e-mail de rapport.
• Publish-RjRbFilesToStorageContainer — téléverser le classeur vers Azure Blob Storage et renvoyer un lien de téléchargement à durée limitée.
• Paramètres de rapport du runbook — configuration centralisée des canaux de livraison du rapport.
• Exemple d'utilisation dans un runbook de production : sync-MFA-secure-users-to-group_scheduled.ps1 — construit un classeur multi-feuilles avec une feuille de couverture "Info".