> 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 Exportar objetos de runbooks do Azure Automation para livros do Excel nativos com estilo (.xlsx) sem quaisquer 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ório 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 de Automação. {% 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 continham foram removidas. Runbooks que a utilizam declaram a versão do módulo de acordo: ```powershell #Requires -Modules @{ModuleName = "RealmJoin.RunbookHelper"; ModuleVersion = "0.8.8" } ``` {% endhint %} Principais características: * **Zero 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 fria de módulos pesados quanto conflitos de assembly em runbooks de relatório mistos. * **Saída estilizada, pronta para compartilhar** — cada planilha recebe uma tabela Excel estilizada (cabeçalho azul-marinho, linhas zebrada 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 aba da planilha é colorida em laranja 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 e classificáveis do Excel (localizadas pelo cliente), e `http/https` URLs tornam-se hyperlinks 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 **injeção de fórmulas não é possível**. * **Uma ou várias planilhas** — direcione as linhas para uma única planilha ou passe um dicionário ordenado para uma pasta de trabalho com várias planilhas, além de uma folha de rosto opcional "Info". * **Acabamento de relatório integrado** — regras opcionais de destaque de formatação condicional para colunas de status, barras de dados na célula para colunas numéricas, texto de exibição amigável para hyperlinks e separadores de milhar. Um consumidor típico é um runbook de relatório agendado que gera arquivos CSV e XLSX e depois os entrega via [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 todos os runtimes do Azure Automation (`System.IO.Compression`, `System.Text`, `System.Xml`- construção de strings livre de XML). Nenhuma conexão Graph ou Az é necessária — a função funciona apenas com dados locais e grava um arquivo local. ## Início rápido A chamada mínima viável direciona 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 "Devices": tabela estilizada com menus suspensos de filtro, linha de cabeçalho congelada, colunas redimensionadas automaticamente 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. Dictionaries/hashtables são convertidos em objetos. | | `WorksheetName` | `string` | `SingleSheet` | Nome da única planilha, no máximo 31 caracteres (veja [Nomes de planilhas](#worksheet-names)). Padrão: `Report`. | | `Worksheets` | `IDictionary` | `MultiSheet` | Dicionário ordenado de nome da planilha → linhas, por exemplo: `([ordered]@{ 'Summary' = $summary; 'Details' = $details })`. Deve conter pelo menos uma entrada. As chaves são nomes de planilhas, com no máximo 31 caracteres cada (veja [Nomes de planilhas](#worksheet-names)). | ### 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 aba): 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), `Value` (texto exato da célula, sem distinção de maiúsculas e minúsculas) e `Color` (`Green`, `Red` ou `Yellow` — os predefinidos clássicos de destaque do Excel). As regras são aplicadas em cada planilha que contém 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')`. Colunas que não existem em uma planilha são ignoradas. | | `HyperlinkText` | `IDictionary` | — | Nome da coluna → texto de exibição para células de hyperlink, por exemplo: `@{ Portal = 'Open in Intune' }`. A célula mostra o texto amigável, o destino do link continua sendo a URL completa. Colunas sem mapeamento continuam mostrando a URL. | | `NoHyperlink` | `switch` | off | Não converter `http/https` strings de URL em hyperlinks clicáveis. | | `HideGridLines` | `switch` | off | Oculta as linhas de grade da planilha fora da tabela (as linhas de grade são mantidas por padrão para legibilidade; a planilha de capa sempre as oculta). | | `UseThousandsSeparator` | `switch` | off | Formata células numéricas com separador de milhar (`#,##0` para inteiros, `#,##0.00` para decimais — localizado pelo Excel). | ## Exemplos de uso ### Várias planilhas ```powershell Export-RjRbXlsx ` -Worksheets ([ordered]@{ 'Summary' = $summaryRows; 'Details' = $detailRows }) ` -Path (Join-Path $env:TEMP 'report.xlsx') ``` As abas da planilha aparecem na ordem do dicionário; a primeira aba é colorida em laranja RealmJoin, as abas restantes em cinza neutro. ### Planilha de capa, regras de destaque e barras de dados O padrão completo de "pasta de trabalho de relatório" com uma planilha de capa 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 planilha de capa é inserida como a primeira aba chamada "Info", com o `Título` value 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 hyperlink Colunas de URL são clicáveis por padrão e mostram a URL bruta. Mapeie uma coluna para um texto de exibição amigável 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 comum de ponta a ponta em runbooks de relatório — 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 para limite de tamanho Send-RjRbReportEmail ` -EmailFrom $emailFrom ` -EmailTo $EmailTo ` -Subject "Report — $(Get-Date -Format 'yyyy-MM-dd')" ` -MarkdownContent $reportMd ` -Attachments @($xlsxPath) # ...ou entrega em armazenamento com um link de download com prazo 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 de tipos de células | Valor de entrada | Renderizado como | | ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Tipos .NET inteiros/ponto flutuante/decimais | Número do Excel (opcionalmente com separador de milhar via `-UseThousandsSeparator`). `NaN`/`Infinity` voltam para texto. | | `[datetime]` | Data real do Excel; valores apenas de data recebem formato de data, valores com componente de hora recebem formato de data e hora. Localizado pelo cliente que visualiza. | | Strings de data ISO-8601 (`2026-07-16T08:00:00Z`, campos de data típicos do Graph) | Analisadas e renderizadas como datas reais e classificáveis do Excel. | | `[bool]` | Booleano do Excel (`TRUE`/`FALSE`). | | `http://` / `https://` Strings de URL | Hyperlink 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. | | Tudo o mais | Texto simples. Os espaços em branco no início/fim são preservados; strings nunca são reinterpretadas como números ou fórmulas. | ## Comportamento e tratamento de erros ### Nomes de 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. {% hint style="warning" %} **Mantenha os nomes das planilhas com no máximo 31 caracteres.** Isto se aplica a `-WorksheetName` e às chaves de `-Worksheets`, incluindo valores inseridos em tempo de execução. Nomes mais longos são truncados silenciosamente, o que pode cortar a parte significativa do nome ou tornar dois nomes idênticos (o segundo então recebe um `_2` sufixo). Escolha nomes curtos e significativos sem `\ / ? * [ ] :`, e use o mesmo nome do título da tabela correspondente na aba [Dados de saída](/pt/dev-reference/runbook-output-data.md#naming-a-table) do runbook, onde Export to Excel falha para títulos com mais de 31 caracteres. {% endhint %} ### Cabeçalhos das colunas Os nomes dos cabeçalhos vêm da ordem das propriedades do primeiro objeto da linha. Nomes de propriedade vazios tornam-se `Column`; nomes duplicados (sem distinção de maiúsculas e minúsculas) são desduplicados com um `_2`, `_3`, … sufixo, porque as colunas de tabela do Excel devem ser únicas e não vazias. ### Planilhas vazias Uma planilha cujo conjunto de linhas está vazio ainda é gravada — ela contém uma única célula "No data available" e nenhuma tabela. Um `-Worksheets` dicionário vazio, entretanto, 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 xlsx é de 1048575 linhas de dados.` antes de gravar um arquivo inválido. Divida exportações muito grandes em várias planilhas ou entregue-as como CSV em vez disso. ### 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 desconhecido `Color` valor emite `Export-RjRbXlsx: cor de destaque desconhecida '' - use Green, Red ou Yellow. Ignorando a regra.` como aviso e ignora apenas essa regra. ### Larguras das colunas As larguras são calculadas com base no comprimento do cabeçalho e nas 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 de largura. ### Arquivo de saída Um arquivo existente em `Caminho` é excluído e recriado. A função não cria diretórios pai ausentes — garanta 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: gravou 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 prazo 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) — constrói uma pasta de trabalho com várias planilhas e uma planilha de capa "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 by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` 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 what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. 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.