> For the complete documentation index, see [llms.txt](https://docs.realmjoin.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.realmjoin.com/pt/dev-reference/report-functions/export-rjrbxlsx.md). # Export-RjRbXlsx ## 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 `PSCustomObject`s 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. {% hint style="info" %} **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: ```powershell #Requires -Modules @{ModuleName = "RealmJoin.RunbookHelper"; ModuleVersion = "0.8.8" } ``` {% endhint %} 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](/pt/dev-reference/report-functions/send-rjrbreportemail.md) e/ou [Publish-RjRbFilesToStorageContainer](/pt/dev-reference/report-functions/publish-rjrbfilestostoragecontainer.md). ## 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.Xml`construçã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: ```powershell $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 ```powershell 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: ```powershell $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: ```powershell $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: ```powershell $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](/pt/dev-reference/report-functions/send-rjrbreportemail.md) e [Publish-RjRbFilesToStorageContainer](/pt/dev-reference/report-functions/publish-rjrbfilestostoragecontainer.md) 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`, e duplicatas recebem um `_2`, `_3`sufixo, …. ### 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`; nomes duplicados (sem distinção entre maiúsculas e minúsculas) são deduplicados com um `_2`, `_3`sufixo, …, 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 '' tem 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 '' - 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 planilha(s) em `) visível quando o runbook é executado com `-Verbose` ou `$VerbosePreference = 'Continue'`. ## Veja também * [Send-RjRbReportEmail](/pt/dev-reference/report-functions/send-rjrbreportemail.md) — entregue a pasta de trabalho gerada como anexo de e-mail de relatório. * [Publish-RjRbFilesToStorageContainer](/pt/dev-reference/report-functions/publish-rjrbfilestostoragecontainer.md) — 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](/pt/automatizacao/runbooks/runbook-report-settings.md) — 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](https://github.com/realmjoin/realmjoin-runbooks/blob/master/org/security/sync-MFA-secure-users-to-group_scheduled.ps1) — cria uma pasta de trabalho com várias planilhas e uma folha de rosto "Info". --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.realmjoin.com/pt/dev-reference/report-functions/export-rjrbxlsx.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.