Export-RjRbXlsx

Exporte objetos de runbooks do Azure Automation para livros do Excel nativos com estilo (.xlsx) sem dependências de módulos externos.

Visão geral

Export-RjRbXlsx é o auxiliar padrão para produzir arquivos de relatório do Excel (.xlsx) a partir de runbooks de relatórios do RealmJoin. Ele grava uma ou mais tabelas de PSCustomObjects como uma pasta de trabalho nativa do Excel usando apenas .NET (System.IO.Compression) — sem ImportExcel, sem automação COM, nenhum outro módulo externo é necessário no ambiente do Automation.

Disponível em RealmJoin.RunbookHelper 0.8.8. A função é exportada pelo módulo; as cópias embutidas que versões anteriores do runbook incluíam foram removidas. Os runbooks que a utilizam declaram a versão do módulo em conformidade:

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

Características principais:

• Sem dependências de módulo — a pasta de trabalho é montada diretamente como um pacote Open XML via System.IO.Compression.ZipArchive. Isso evita tanto o custo de inicialização a frio de módulos pesados quanto conflitos de assembly em runbooks de relatórios mistos.
• Saída estilizada, pronta para compartilhar — cada planilha recebe uma tabela Excel estilizada (cabeçalho azul-marinho, linhas zebradas que acompanham a reordenação, menus suspensos de filtro), uma linha de cabeçalho congelada, larguras de coluna calculadas e uma configuração automática de impressão (orientação derivada da largura do conteúdo, linha de cabeçalho repetida em cada página impressa). A primeira guia da planilha é colorida no laranja do RealmJoin.
• Células fiéis ao tipo — números .NET tornam-se números do Excel, DateTime valores e strings ISO-8601 (por exemplo, campos de data do Graph) tornam-se datas reais do Excel, classificáveis (localizadas pelo cliente), e http/https URLs tornam-se hiperlinks clicáveis. Todas as outras strings permanecem texto — valores como números de série ou IMEIs nunca são convertidos em números, e a injeção de fórmulas não é possível.
• De uma ou várias planilhas — encaminhe linhas para uma única planilha ou passe um dicionário ordenado para uma pasta de trabalho com várias planilhas e uma folha de rosto opcional "Info".
• Aprimoramento de relatório integrado — regras opcionais de destaque por formatação condicional para colunas de status, barras de dados na célula para colunas numéricas, texto amigável de exibição de hiperlinks e separadores de milhar.

Um consumidor típico é um runbook de relatórios agendado que gera arquivos CSV e XLSX e depois os entrega por meio de Send-RjRbReportEmail e/ou Publish-RjRbFilesToStorageContainer.

Pré-requisitos

Nada além do próprio PowerShell. A função usa apenas tipos .NET disponíveis em qualquer runtime do Azure Automation (System.IO.Compression, System.Text, System.Xmlconstrução de strings sem StringBuilder). Não é necessária conexão com Graph nem com Az — a função funciona exclusivamente com dados locais e grava um arquivo local.

Início rápido

A chamada mínima viável encaminha as linhas para a função e especifica o caminho de saída:

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

Isso produz uma pasta de trabalho com uma única planilha "Dispositivos": tabela estilizada com menus suspensos de filtro, linha de cabeçalho congelada, colunas com tamanho automático e configuração de impressão — pronta para anexar a um e-mail de relatório ou enviar para um contêiner de armazenamento.

Parâmetros

Conjuntos de parâmetros

A função tem dois conjuntos de parâmetros:

Conjunto de parâmetros	Entrada	Caso de uso
SingleSheet (padrão)	-InputObject (também via pipeline) + -WorksheetName	Uma tabela, uma planilha.
MultiSheet	-Worksheets (dicionário ordenado)	Várias tabelas como planilhas separadas em uma pasta de trabalho.

Obrigatório

Parâmetro	Tipo	Descrição
Caminho	string	Caminho completo do .xlsx arquivo a criar. Um arquivo existente é substituído.

Entrada de dados

Parâmetro	Tipo	Conjunto de parâmetros	Descrição
InputObject	object[]	SingleSheet	As linhas a exportar (array de objetos; também aceito via pipeline). A ordem das colunas segue a ordem das propriedades do primeiro objeto. Dicionários/hashtables são convertidos em objetos.
WorksheetName	string	SingleSheet	Nome da única planilha. Padrão: Relatório.
Planilhas	IDictionary	MultiSheet	Dicionário ordenado de nome da planilha → linhas, por exemplo: ([ordered]@{ 'Summary' = $summary; 'Details' = $details }). Deve conter pelo menos uma entrada.

Opcional — Conteúdo e formatação

Parâmetro	Tipo	Padrão	Descrição
CoverSheet	IDictionary	—	Dicionário ordenado renderizado como uma planilha de capa "Info" (primeira guia): uma Título chave torna-se o título, todas as outras chaves tornam-se linhas de rótulo/valor, por exemplo: ([ordered]@{ Title = 'Device Report'; Tenant = 'contoso'; Generated = '2026-07-16 08:00 UTC' }).
HighlightRules	object[]	—	Formatação condicional para colunas de status. Array de hashtables com Column (nome do cabeçalho), Valor (texto exato da célula, sem distinção entre maiúsculas e minúsculas) e Cor (Verde, Vermelho ou Amarelo — as predefinições clássicas de destaque do Excel). As regras são aplicadas em cada planilha que contenha a coluna nomeada.
DataBarColumns	object[]	—	Nomes de colunas numéricas que recebem uma barra de dados na célula (laranja, gradiente do mínimo ao máximo), por exemplo: @('DeviceCount'). As colunas que não existirem em uma planilha são ignoradas.
HyperlinkText	IDictionary	—	Nome da coluna → texto de exibição para células de hiperlink, por exemplo: @{ Portal = 'Open in Intune' }. A célula mostra o texto amigável, o destino do link permanece a URL completa. Colunas sem mapeamento continuam exibindo a URL.
NoHyperlink	switch	desativado	Não converter http/https strings de URL em hiperlinks clicáveis.
HideGridLines	switch	desativado	Ocultar as linhas de grade da planilha fora da tabela (as linhas de grade são mantidas por padrão para facilitar a leitura; a folha de rosto sempre as oculta).
UseThousandsSeparator	switch	desativado	Formatar células numéricas com um separador de milhar (#,##0 para inteiros, #,##0.00 para decimais — localizados pelo Excel).

Exemplos de uso

Múltiplas planilhas

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

As guias das planilhas aparecem na ordem do dicionário; a primeira guia é colorida no laranja do RealmJoin, as guias restantes em cinza neutro.

Folha de rosto, regras de destaque e barras de dados

O padrão completo de "pasta de trabalho de relatório" com uma folha de rosto informativa, colunas de status coloridas e barras de dados na célula:

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

A folha de rosto é inserida como a primeira guia, chamada "Info", com o Título valor como um título azul-marinho sobre uma linha de destaque laranja e todas as outras chaves como linhas de rótulo/valor.

Texto amigável do hiperlink

As colunas de URL são clicáveis por padrão e mostram a URL bruta. Mapeie uma coluna para um texto amigável de exibição para manter a tabela estreita:

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

Combinando com os auxiliares de entrega

Um padrão ponta a ponta comum em runbooks de relatórios — gravar a pasta de trabalho, depois anexá-la a um e-mail de relatório e/ou enviá-la para obter um link de download:

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

# Entrega por e-mail — a pasta de trabalho compacta é ideal como anexo de fallback quando há limite de tamanho
Send-RjRbReportEmail `
    -EmailFrom       $emailFrom `
    -EmailTo         $EmailTo `
    -Subject         "Report — $(Get-Date -Format 'yyyy-MM-dd')" `
    -MarkdownContent $reportMd `
    -Attachments     @($xlsxPath)

# ...ou entrega por armazenamento com um link de download com tempo limitado
$uploaded = Publish-RjRbFilesToStorageContainer `
    -FilePaths          $xlsxPath `
    -ContainerName      'reports' `
    -ResourceGroupName  $ResourceGroupName `
    -StorageAccountName $StorageAccountName `
    -AddBlobNamePrefix  $true

Veja Send-RjRbReportEmail e Publish-RjRbFilesToStorageContainer para o lado de entrega deste padrão.

Tratamento dos tipos de célula

Valor de entrada	Renderizado como
Tipos inteiros/de ponto flutuante/decimais .NET	Número do Excel (opcionalmente com separador de milhar via -UseThousandsSeparator). NaN/Infinity voltam ao texto.
[datetime]	Data real do Excel; valores somente de data recebem um formato de data, valores com componente de hora recebem um formato de data e hora. Localizado pelo cliente que estiver visualizando.
Strings de data ISO-8601 (2026-07-16T08:00:00Z, campos de data típicos do Graph)	Analisadas e renderizadas como datas reais do Excel, classificáveis.
[bool]	Booleano do Excel (TRUE/FALSE).
http:// / https:// strings de URL	Hiperlink clicável (suprima com -NoHyperlink; texto de exibição via -HyperlinkText).
Arrays / coleções	Itens unidos com ; em uma única célula de texto.
$null / DBNull	Célula vazia.
Todo o resto	Texto simples. Os espaços em branco iniciais/finais são preservados; strings nunca são reinterpretadas como números ou fórmulas.

Comportamento e tratamento de erros

Nomes das planilhas

Os nomes das planilhas são sanitizados para cumprir as regras do Excel: caracteres inválidos ([ ] : * ? / \\) são substituídos, os nomes são truncados para 31 caracteres, nomes vazios tornam-se Sheet<n>, e duplicatas recebem um _2, _3sufixo, ….

Cabeçalhos de coluna

Os nomes dos cabeçalhos vêm da ordem das propriedades do primeiro objeto de linha. Nomes de propriedades vazios tornam-se Column<n>; nomes duplicados (sem distinção entre maiúsculas e minúsculas) são deduplicados com um _2, _3sufixo, …, porque as colunas da tabela do Excel devem ser exclusivas e não vazias.

Planilhas vazias

Uma planilha cujo conjunto de linhas está vazio ainda é gravada — ela contém uma única célula "Sem dados disponíveis" e nenhuma tabela. Um -Worksheets dicionário vazio, no entanto, lança Export-RjRbXlsx: -Worksheets deve conter pelo menos uma entrada.

Limite de linhas

O Excel limita as planilhas a 1.048.576 linhas. A função lança Export-RjRbXlsx: a planilha '<name>' tem <n> linhas - o limite do xlsx é 1048575 linhas de dados. antes de gravar um arquivo inválido. Divida exportações muito grandes entre várias planilhas ou entregue-as como CSV.

Regras de destaque

• Regras que fazem referência a uma coluna que não existe em uma planilha são ignoradas silenciosamente para essa planilha (elas ainda se aplicam a outras planilhas que tenham a coluna).
• Um valor desconhecido Cor emite Export-RjRbXlsx: cor de destaque desconhecida '<color>' - use Green, Red ou Yellow. Ignorando regra. como aviso e ignora apenas essa regra.

Larguras de coluna

As larguras são calculadas a partir do comprimento do cabeçalho e das primeiras 1.000 linhas de dados (limitadas entre 8 e 60 caracteres), para que exportações muito grandes não fiquem lentas no cálculo das larguras.

Arquivo de saída

Um arquivo existente em Caminho é excluído e recriado. A função não cria diretórios pai ausentes — certifique-se de que a pasta de destino exista (por exemplo, New-Item -ItemType Directory).

Saídas

A função não retorna nada. Ela grava a pasta de trabalho em Caminho e emite uma mensagem detalhada (Export-RjRbXlsx: escreveu <n> planilha(s) em <path>) visível quando o runbook é executado com -Verbose ou $VerbosePreference = 'Continue'.

Veja também

• Send-RjRbReportEmail — entregue a pasta de trabalho gerada como anexo de e-mail de relatório.
• Publish-RjRbFilesToStorageContainer — envie a pasta de trabalho para Azure Blob Storage e retorne um link de download com tempo limitado.
• Configurações de relatório do runbook — configuração central dos canais de entrega do relatório.
• Exemplo de uso em um runbook de produção: sync-MFA-secure-users-to-group_scheduled.ps1 — cria uma pasta de trabalho com várias planilhas e uma folha de rosto "Info".