> 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 dos runbooks de relatório do RealmJoin. Ele grava uma ou mais tabelas de `PSCustomObject`s como uma **pasta de trabalho Excel nativa** 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="warning" %} **Ainda não faz parte de RealmJoin.RunbookHelper.** `Export-RjRbXlsx` ainda não é distribuído com o **RealmJoin.RunbookHelper** módulo — ele será incluído com a **próxima versão do módulo**. Até lá, a função é duplicada inline nos runbooks que a utilizam e pode ser copiada de lá, por exemplo de [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) (região *Definições de Função*). {% endhint %} Principais características: * **Zero dependências de módulo** — a pasta de trabalho é montada diretamente como um pacote Open XML por meio de `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ório mistos. * **Saída estilizada e pronta para compartilhar** — cada planilha recebe uma tabela do 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 aba da planilha é colorida em laranja do RealmJoin. * **Células fiéis ao tipo** — números .NET viram números do Excel, `DateTime` values 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 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 **a injeção de fórmulas não é possível**. * **Uma única ou várias planilhas** — envie as linhas para uma única aba ou passe um dicionário ordenado para uma pasta de trabalho com várias planilhas, além de uma folha de capa "Info" opcional. * **Acabamento de relatório embutido** — regras opcionais 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 milhares. 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 Nenhum 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`-sem geração de strings). Nenhuma conexão com Graph ou Az é necessária — a função funciona puramente com dados locais e grava um arquivo local. ## Início rápido A chamada mínima viável envia as linhas para a função e especifica o caminho de saída: ```powershell $devices | Export-RjRbXlsx -Path (Join-Path $env:TEMP 'dispositivos.xlsx') -WorksheetName 'Dispositivos' ``` 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 ajuste 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 única pasta de trabalho. | ### Obrigatório | Parâmetro | Tipo | Descrição | | --------- | -------- | ----------------------------------------------------------------------------------------- | | `Path` | `string` | Caminho completo do `.xlsx` arquivo a ser criado. **Um arquivo existente é sobrescrito.** | ### 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`. | | `Worksheets` | `IDictionary` | `MultiSheet` | Dicionário ordenado de nome da planilha → linhas, por exemplo `([ordered]@{ 'Resumo' = $summary; 'Detalhes' = $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 aba): uma `Title` chave torna-se o cabeçalho, todas as outras chaves tornam-se linhas rótulo/valor, por exemplo `([ordered]@{ Title = 'Relatório de dispositivos'; 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 entre maiúsculas e minúsculas) e `Color` (`Green`, `Red` ou `Yellow` — 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 (gradiente laranja, mínimo a máximo), por exemplo `@('DeviceCount')`. Colunas que não existirem em uma planilha são ignoradas. | | `HyperlinkText` | `IDictionary` | — | Nome da coluna → texto de exibição para células com hyperlink, por exemplo `@{ Portal = 'Abrir no Intune' }`. A célula mostra o texto amigável, o destino do link permanece a URL completa. Colunas sem mapeamento continuam mostrando a URL. | | `NoHyperlink` | `switch` | desligado | Não converter `http/https` strings de URL em hyperlinks clicáveis. | | `HideGridLines` | `switch` | desligado | Ocultar as linhas de grade da planilha fora da tabela (as linhas de grade são mantidas por padrão por legibilidade; a folha de capa sempre as oculta). | | `UseThousandsSeparator` | `switch` | desligado | Formate células numéricas com um separador de milhares (`#,##0` para inteiros, `#,##0.00` para decimais — localizados pelo Excel). | ## Exemplos de uso ### Várias planilhas ```powershell Export-RjRbXlsx ` -Worksheets ([ordered]@{ 'Resumo' = $summaryRows; 'Detalhes' = $detailRows }) ` -Path (Join-Path $env:TEMP 'relatorio.xlsx') ``` As abas das planilhas aparecem na ordem do dicionário; a primeira aba é colorida em laranja do RealmJoin, as demais ficam em cinza neutro. ### Folha de capa, regras de destaque e barras de dados O padrão completo de "pasta de trabalho de relatório" com uma folha de capa de informações, colunas de status coloridas e barras de dados na célula: ```powershell $coverSheet = [ordered]@{ Title = 'Relatório de dispositivos' 'Tenant' = $tenantDisplayName 'Gerado (UTC)' = (Get-Date).ToUniversalTime().ToString('yyyy-MM-dd HH:mm') 'Versão do runbook' = $Version 'Total de dispositivos' = "$($devices.Count)" } Export-RjRbXlsx ` -Worksheets ([ordered]@{ 'Dispositivos' = $devices }) ` -Path (Join-Path $env:TEMP 'relatorio-dispositivos.xlsx') ` -CoverSheet $coverSheet ` -HighlightRules @( @{ Column = 'Compliant'; Value = 'sim'; Color = 'Green' }, @{ Column = 'Compliant'; Value = 'não'; Color = 'Red' } ) ` -DataBarColumns @('AppCount') ``` A folha de capa é inserida como a primeira aba chamada "Info", com o `Title` valor como um cabeçalho azul-marinho sobre uma linha de destaque laranja e todas as outras chaves como linhas rótulo/valor. ### Texto amigável do hyperlink As colunas de URL são clicáveis por padrão e exibem 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 'Dispositivos' -HyperlinkText @{ Portal = 'Abrir no Intune' } ``` ### Combinando com os auxiliares de entrega Um padrão comum de ponta a ponta em runbooks de relatório — grava a pasta de trabalho, depois a anexa a um e-mail de relatório e/ou a envia para obter um link de download: ```powershell $xlsxPath = Join-Path $env:TEMP 'relatorio.xlsx' Export-RjRbXlsx -Worksheets ([ordered]@{ Changes = $changeRows; 'Todos os usuários' = $allUserRows }) ` -Path $xlsxPath -CoverSheet $coverSheet # Entrega por e-mail — a pasta de trabalho compacta é ideal como anexo de contingência para limite de tamanho Send-RjRbReportEmail ` -EmailFrom $emailFrom ` -EmailTo $EmailTo ` -Subject "Relatório — $(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 a parte de entrega desse padrão. ## Tratamento de tipos de célula | Valor de entrada | Renderizado como | | ---------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Tipos .NET inteiros/de ponto flutuante/decimais | Número do Excel (opcionalmente com separador de milhares via `-UseThousandsSeparator`). `NaN`/`Infinity` são tratados como texto. | | `[datetime]` | Data real do Excel; valores apenas de data recebem um formato de data, valores com componente de hora recebem um formato de data e hora. Localizado pelo cliente de visualização. | | 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, ordenáveis. | | `[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. | | Todo o restante | Texto simples. O espaço em branco inicial/final é preservado; 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 obedecer às 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 sufixo ", …". `_2`, `_3`", … ### Cabeçalhos das colunas Os nomes dos cabeçalhos vêm da ordem das propriedades do objeto da primeira linha. Nomes de propriedades vazios tornam-se `Column`; nomes duplicados (sem distinção entre maiúsculas e minúsculas) são desduplicados com um `_2`, `_3`sufixo ", …", porque as colunas de uma 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 "Sem dados disponíveis" e nenhuma tabela. Um `-Worksheets` dicionário, 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 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 referenciam 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 `Color` 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 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 da largura. ### Arquivo de saída Um arquivo existente em `Path` é 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 `Path` 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 um 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 embutido: [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) — o runbook que atualmente contém a função até que ela seja entregue com o módulo. --- # 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.