Export-RjRbXlsx

Exporta objetos desde runbooks de Azure Automation a libros de Excel nativos con estilo (.xlsx) sin dependencias de módulos externos.

Descripción general

Export-RjRbXlsx es el asistente estándar para producir archivos de informe de Excel (.xlsx) a partir de runbooks de informes de RealmJoin. Escribe una o más tablas de PSCustomObjects como un libro de Excel nativo usando solo .NET (System.IO.Compression) — no ImportExcel, no automatización COM, no se requiere ningún otro módulo externo en el entorno de Automation.

Aún no forma parte de RealmJoin.RunbookHelper. Export-RjRbXlsx aún no se incluye con el RealmJoin.RunbookHelper módulo — se incluirá con el próximo lanzamiento del módulo. Hasta entonces, la función se duplica en línea en los runbooks que la usan y puede copiarse de allí, por ejemplo de sync-MFA-secure-users-to-group_scheduled.ps1 (región Definiciones de funciones).

Características clave:

• Cero dependencias de módulos — el libro se compone directamente como un paquete Open XML mediante System.IO.Compression.ZipArchive. Esto evita tanto el costo de arranque en frío de módulos pesados como los conflictos de ensamblado en runbooks de informes mixtos.
• Salida con estilo, lista para compartir — cada hoja recibe una tabla de Excel con estilo (encabezado azul marino, filas cebra que se mantienen tras reordenar, menús desplegables de filtro), una fila de encabezado congelada, anchos de columna calculados y una configuración de impresión automática (orientación derivada del ancho del contenido, fila de encabezado repetida en cada página impresa). La pestaña de la primera hoja se colorea en naranja RealmJoin.
• Celdas fieles al tipo — los números de .NET se convierten en números de Excel, DateTime los valores de fecha y las cadenas ISO-8601 (p. ej., campos de fecha de Graph) se convierten en fechas reales de Excel, ordenables (localizadas por el cliente), y http/https las URL se convierten en hipervínculos clicables. Todas las demás cadenas permanecen como texto — valores como números de serie o IMEIs nunca se convierten en números, y no es posible la inyección de fórmulas.
• Una o varias hojas — canaliza filas a una sola hoja, o pasa un diccionario ordenado para un libro con varias hojas de trabajo más una hoja de portada opcional "Info".
• Pulido de informes integrado — reglas opcionales de resaltado de formato condicional para columnas de estado, barras de datos en la celda para columnas numéricas, texto de visualización amistoso para hipervínculos y separadores de miles.

Un consumidor típico es un runbook de informes programado que genera archivos CSV y XLSX y luego los entrega mediante Send-RjRbReportEmail y/o Publish-RjRbFilesToStorageContainer.

Requisitos previos

Ninguna más allá del propio PowerShell. La función solo usa tipos .NET disponibles en cada entorno de Azure Automation (System.IO.Compression, System.Text, System.Xml— sin construcción de cadenas dependiente de `System.Text`/`System.Xml`).

Inicio rápido

La llamada mínima viable canaliza las filas a la función y especifica la ruta de salida:

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

Esto produce un libro con una única hoja "Dispositivos": tabla con estilo con menús desplegables de filtro, fila de encabezado congelada, columnas autoajustadas y configuración de impresión — lista para adjuntar a un correo de informe o cargarla en un contenedor de almacenamiento.

Parámetros

Conjuntos de parámetros

La función tiene dos conjuntos de parámetros:

Conjunto de parámetros	Entrada	Caso de uso
SingleSheet (predeterminado)	-InputObject (también mediante la canalización) + -WorksheetName	Una tabla, una hoja.
MultiSheet	-Worksheets (diccionario ordenado)	Varias tablas como hojas de cálculo separadas en un solo libro.

Requerido

Parámetro	Tipo	Descripción
Ruta	string	Ruta completa del .xlsx archivo que se creará. Un archivo existente se sobrescribe.

Entrada de datos

Parámetro	Tipo	Conjunto de parámetros	Descripción
InputObject	object[]	SingleSheet	Las filas que se exportarán (matriz de objetos; también aceptada mediante la canalización). El orden de las columnas sigue el orden de propiedades del primer objeto. Los diccionarios/tablas hash se convierten en objetos.
WorksheetName	string	SingleSheet	Nombre de la única hoja de cálculo. Predeterminado: Informe.
Worksheets	IDictionary	MultiSheet	Diccionario ordenado de nombre de hoja de cálculo → filas, por ejemplo ([ordered]@{ 'Resumen' = $summary; 'Detalles' = $details }). Debe contener al menos una entrada.

Opcional — Contenido y formato

Parámetro	Tipo	Predeterminado	Descripción
CoverSheet	IDictionary	—	Diccionario ordenado representado como una hoja de portada "Info" (primera pestaña): un Title la clave se convierte en el encabezado, todas las demás claves se convierten en filas etiqueta/valor, por ejemplo ([ordered]@{ Title = 'Informe de dispositivos'; Tenant = 'contoso'; Generated = '2026-07-16 08:00 UTC' }).
HighlightRules	object[]	—	Formato condicional para columnas de estado. Matriz de tablas hash con Column (nombre del encabezado), Valor (texto exacto de la celda, sin distinguir mayúsculas/minúsculas) y Color (Verde, Rojo o Amarillo — los ajustes clásicos de resaltado de Excel). Las reglas se aplican en cada hoja de cálculo que contiene la columna nombrada.
DataBarColumns	object[]	—	Nombres de columnas numéricas que reciben una barra de datos en la celda (naranja, degradado de mínimo a máximo), por ejemplo @('DeviceCount'). Las columnas que no existen en una hoja de cálculo se omiten.
HyperlinkText	IDictionary	—	Nombre de columna → texto mostrado para celdas de hipervínculo, por ejemplo @{ Portal = 'Abrir en Intune' }. La celda muestra el texto amistoso, el destino del enlace sigue siendo la URL completa. Las columnas sin asignación siguen mostrando la URL.
NoHyperlink	switch	off	No convertir http/https cadenas URL en hipervínculos clicables.
HideGridLines	switch	off	Ocultar las líneas de cuadrícula de la hoja fuera de la tabla (las líneas de cuadrícula se conservan de forma predeterminada para facilitar la lectura; la hoja de portada siempre las oculta).
UseThousandsSeparator	switch	off	Dar formato a celdas numéricas con separador de miles (#,##0 para enteros, #,##0.00 para decimales — localizado por Excel).

Ejemplos de uso

Varias hojas de cálculo

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

Las pestañas de las hojas de cálculo aparecen en el orden del diccionario; la primera pestaña se colorea en naranja RealmJoin y las pestañas restantes en gris neutro.

Hoja de portada, reglas de resaltado y barras de datos

El patrón completo de "libro de informes" con una hoja de portada de información, columnas de estado con color y barras de datos en la celda:

$coverSheet = [ordered]@{
    Title             = 'Informe de dispositivos'
    'Tenant'          = $tenantDisplayName
    'Generated (UTC)' = (Get-Date).ToUniversalTime().ToString('yyyy-MM-dd HH:mm')
    'Versión del runbook' = $Version
    'Total de dispositivos'   = "$($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 hoja de portada se inserta como la primera pestaña llamada "Info", con el Title valor como un encabezado azul marino sobre una línea de acento naranja y todas las demás claves como filas etiqueta/valor.

Texto amistoso para hipervínculos

Las columnas URL son clicables de forma predeterminada y muestran la URL en bruto. Asigna una columna a un texto de visualización amistoso para mantener la tabla estrecha:

$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 = 'Abrir en Intune' }

Combinación con los ayudantes de entrega

Un patrón integral común en runbooks de informes: escribir el libro, luego adjuntarlo a un correo de informe y/o cargarlo para obtener un enlace de descarga:

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

# Entrega por correo electrónico — el libro compacto es ideal como adjunto de respaldo cuando hay límite de tamaño
Send-RjRbReportEmail `
    -EmailFrom       $emailFrom `
    -EmailTo         $EmailTo `
    -Subject         "Informe — $(Get-Date -Format 'yyyy-MM-dd')" `
    -MarkdownContent $reportMd `
    -Attachments     @($xlsxPath)

# ...o entrega en almacenamiento con un enlace de descarga con tiempo limitado
$uploaded = Publish-RjRbFilesToStorageContainer `
    -FilePaths          $xlsxPath `
    -ContainerName      'reports' `
    -ResourceGroupName  $ResourceGroupName `
    -StorageAccountName $StorageAccountName `
    -AddBlobNamePrefix  $true

Ver Send-RjRbReportEmail y Publish-RjRbFilesToStorageContainer para la parte de entrega de este patrón.

Manejo del tipo de celda

Valor de entrada	Se renderiza como
Tipos enteros/de punto flotante/decimal de .NET	Número de Excel (opcionalmente con separador de miles mediante -UseThousandsSeparator). NaN/Infinity se trata como texto.
[datetime]	Fecha real de Excel; los valores solo de fecha obtienen un formato de fecha, los valores con componente de hora obtienen un formato de fecha y hora. Localizado por el cliente que lo visualiza.
Cadenas de fecha ISO-8601 (2026-07-16T08:00:00Z, campos de fecha típicos de Graph)	Analizadas y representadas como fechas reales de Excel, ordenables.
[bool]	Booleano de Excel (VERDADERO/FALSO).
http:// / https:// Cadenas URL	Hipervínculo clicable (suprimir con -NoHyperlink; texto mostrado mediante -HyperlinkText).
Matrices / colecciones	Los elementos se unen con ; en una sola celda de texto.
$null / DBNull	Celda vacía.
Todo lo demás	Texto sin formato. Se conserva el espacio en blanco inicial/final; las cadenas nunca se reinterpretan como números o fórmulas.

Comportamiento y tratamiento de errores

Nombres de hojas de cálculo

Los nombres de las hojas de cálculo se sanean para cumplir las reglas de Excel: los caracteres no válidos ([ ] : * ? / \) se reemplazan, los nombres se truncan a 31 caracteres, los nombres vacíos pasan a ser Sheet<n>, y los duplicados obtienen un sufijo _2, _3, ….

Encabezados de columna

Los nombres de encabezado provienen del orden de propiedades del primer objeto de fila. Los nombres de propiedad vacíos pasan a ser Column<n>; los nombres duplicados (sin distinguir mayúsculas/minúsculas) se desduplican con un sufijo _2, _3, …. porque las columnas de tabla de Excel deben ser únicas y no vacías.

Hojas de cálculo vacías

Una hoja de cálculo cuyo conjunto de filas está vacío todavía se escribe — contiene una sola celda "No data available" y ninguna tabla. Sin embargo, un diccionario vacío lanza -Worksheets diccionario, sin embargo, genera Export-RjRbXlsx: -Worksheets debe contener al menos una entrada.

Límite de filas

Excel limita las hojas de cálculo a 1.048.576 filas. La función lanza Export-RjRbXlsx: la hoja de cálculo '<name>' tiene <n> filas - el límite xlsx es de 1048575 filas de datos. antes de escribir un archivo inválido. Divide exportaciones muy grandes en varias hojas de cálculo o entrégalas como CSV en su lugar.

Reglas de resaltado

• Las reglas que hacen referencia a una columna que no existe en una hoja de cálculo se omiten silenciosamente para esa hoja de cálculo (siguen aplicándose a otras hojas de cálculo que sí tienen la columna).
• Un Color valor emite Export-RjRbXlsx: color de resaltado desconocido '<color>' - usa Green, Red o Yellow. Se omite la regla. como advertencia y omite solo esa regla.

Anchos de columna

Los anchos se calculan a partir de la longitud del encabezado y de las primeras 1.000 filas de datos (acotadas entre 8 y 60 caracteres), por lo que las exportaciones muy grandes no se ralentizan en el cálculo del ancho.

Archivo de salida

Un archivo existente en Ruta se elimina y se vuelve a crear. La función no crea directorios principales que falten — asegúrate de que exista la carpeta de destino (p. ej., New-Item -ItemType Directory).

Salida

La función no devuelve nada. Escribe el libro en Ruta y emite un mensaje verbose (Export-RjRbXlsx: escribió <n> hoja(s) en <path>) visible cuando el runbook se ejecuta con -Verbose o $VerbosePreference = 'Continue'.

Véase también

• Send-RjRbReportEmail — entrega el libro generado como adjunto de un correo de informe.
• Publish-RjRbFilesToStorageContainer — sube el libro a Azure Blob Storage y devuelve un enlace de descarga con tiempo limitado.
• Configuración del informe del runbook — configuración central de los canales de entrega de informes.
• Ejemplo de uso en línea: sync-MFA-secure-users-to-group_scheduled.ps1 — el runbook que actualmente contiene la función hasta que se incluya con el módulo.