> 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ó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`) — nenhum `ImportExcel`, nenhuma automação COM, nenhum outro módulo externo é necessário no ambiente de Automação.

{% hint style="info" %}
**Disponível a partir de RealmJoin.RunbookHelper 0.8.8.** A função é exportada pelo módulo; as cópias inline que versões anteriores de runbooks incluíam foram removidas. Runbooks que a usam declaram a versão do módulo de acordo:

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

{% endhint %}

Caraterí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 do Excel estilizada (cabeçalho azul-marinho, linhas em zebra 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 guia da primeira planilha é colorida em laranja RealmJoin.
* **Células fiéis aos tipos** — 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**.
* **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 mais uma folha de rosto opcional "Info".
* **Polimento de relatórios integrado** — regras opcionais de realce com formatação condicional para colunas de status, barras de dados na célula para colunas numéricas, texto de exibição amigável para 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 [Send-RjRbReportEmail](https://docs.realmjoin.com/pt/dev-reference/report-functions/send-rjrbreportemail.md) e/ou [Publish-RjRbFilesToStorageContainer](https://docs.realmjoin.com/pt/dev-reference/report-functions/publish-rjrbfilestostoragecontainer.md).

## Pré-requisitos

Nenhuma, além do próprio PowerShell. A função usa apenas tipos .NET disponíveis em todo runtime do Azure Automation (`System.IO.Compression`, `System.Text`, `System.Xml`-sem construção de strings). 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 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 '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 ajustadas 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 única pasta de trabalho. |

### Obrigatório

| Parâmetro | Tipo     | Descrição                                                                            |
| --------- | -------- | ------------------------------------------------------------------------------------ |
| `Caminho` | `string` | Caminho completo do `.xlsx` arquivo a criar. **Um arquivo existente é sobrescrito.** |

### Entrada de dados

| Parâmetro       | Tipo          | Conjunto de parâmetros | Descrição                                                                                                                                                                                                                                                                        |
| --------------- | ------------- | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `InputObject`   | `object[]`    | `SingleSheet`          | As linhas a exportar (matriz de objetos; também aceitas 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, no máximo 31 caracteres (veja [Nomes de planilhas](#worksheet-names)). 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. As chaves são nomes de planilha, 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 guia): um `Título` a chave se torna o cabeçalho, todas as outras chaves se tornam linhas de rótulo/valor, por exemplo `([ordered]@{ Título = 'Relatório do dispositivo'; Tenant = 'contoso'; Generated = '2026-07-16 08:00 UTC' })`.                            |
| `HighlightRules`        | `object[]`    | —         | Formatação condicional para colunas de status. Matriz de hashtables com `Coluna` (nome do cabeçalho), `Valor` (texto exato da célula, sem distinção de maiúsculas/minúsculas) e `Color` (`Green`, `Red` ou `Yellow` — os predefinidos clássicos de realce 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 de mínimo a máximo), por exemplo `@('DeviceCount')`. As colunas que não existem em uma planilha são ignoradas.                                                                                                                                     |
| `HyperlinkText`         | `IDictionary` | —         | Nome da coluna → texto exibido para células de hiperlink, 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`           | `interruptor` | desligado | Não converter `http/https` strings de URL em hiperlinks clicáveis.                                                                                                                                                                                                                                                                         |
| `HideGridLines`         | `interruptor` | desligado | Ocultar as linhas de grade da planilha fora da tabela (as linhas de grade são mantidas por padrão para legibilidade; a folha de capa sempre as oculta).                                                                                                                                                                                    |
| `UseThousandsSeparator` | `interruptor` | desligado | Formatar células numéricas com separador de milhar (`#,##0` para inteiros, `#,##0.00` para decimais — localizado pelo Excel).                                                                                                                                                                                                              |

## Exemplos de utilização

### Várias planilhas

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

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

### Folha de capa, regras de realce e barras de dados

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

```powershell
$coverSheet = [ordered]@{
    Title             = 'Relatório do dispositivo'
    'Tenant'          = $tenantDisplayName
    'Generated (UTC)' = (Get-Date).ToUniversalTime().ToString('yyyy-MM-dd HH:mm')
    'Runbook version' = $Version
    'Devices total'   = "$($devices.Count)"
}

Export-RjRbXlsx `
    -Worksheets      ([ordered]@{ 'Dispositivos' = $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 capa é inserida como a primeira guia chamada "Info", com o `Título` valor como um cabeçalho em azul-marinho sobre uma linha de destaque laranja e todas as outras chaves como linhas de rótulo/valor.

### Texto amigável para 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 'Dispositivos' -HyperlinkText @{ Portal = 'Abrir no 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 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 por tempo limitado
$uploaded = Publish-RjRbFilesToStorageContainer `
    -FilePaths          $xlsxPath `
    -ContainerName      'reports' `
    -ResourceGroupName  $ResourceGroupName `
    -StorageAccountName $StorageAccountName `
    -AddBlobNamePrefix  $true
```

Consulte [Send-RjRbReportEmail](https://docs.realmjoin.com/pt/dev-reference/report-functions/send-rjrbreportemail.md) e [Publish-RjRbFilesToStorageContainer](https://docs.realmjoin.com/pt/dev-reference/report-functions/publish-rjrbfilestostoragecontainer.md) para o lado de entrega desse padrão.

## Tratamento do tipo de célula

| Valor de entrada                                                                   | Renderizado como                                                                                                                                                                  |
| ---------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Tipos .NET de inteiro/ponto flutuante/decimal                                      | Número do Excel (opcionalmente com separador de milhar via `-UseThousandsSeparator`). `NaN`/`Infinity` recorrem a 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 típicos de data 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`).                                                                                          |
| Matrizes / coleções                                                                | Itens unidos com `;` em uma única célula de texto.                                                                                                                                |
| `$null` / `DBNull`                                                                 | Célula vazia.                                                                                                                                                                     |
| Todo o resto                                                                       | Texto simples. Espaços em branco à esquerda/direita 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 higienizados 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`, `_3`, … sufixo.

{% hint style="warning" %}
**Mantenha os nomes das planilhas com no máximo 31 caracteres.** Isso 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 que o título da tabela correspondente na guia [Dados de saída](https://docs.realmjoin.com/pt/dev-reference/runbook-output-data.md#naming-a-table) do runbook, onde Exportar para Excel falha para títulos maiores que 31 caracteres.
{% endhint %}

### Cabeçalhos de coluna

Os nomes dos cabeçalhos vêm da ordem das propriedades do primeiro objeto da linha. Nomes de propriedade vazios tornam-se `Column<n>`; nomes duplicados (sem distinção entre maiúsculas/minúsculas) são deduplicados com um sufixo `_2`, `_3`, …

### Planilhas vazias

Uma planilha cujo conjunto de linhas está vazio ainda é gravada — ela contém uma única célula "Nenhum dado disponível" e nenhuma tabela. Um dicionário vazio, porém, lança `-Worksheets` dicionário vazio, porém, 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 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 realce

* 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 `Color` valor desconhecido emite `Export-RjRbXlsx: cor de realce desconhecida '<color>' - use Green, Red ou Yellow. Ignorando regra.` como um 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), de modo 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 — 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: gravou <n> planilha(s) em <path>`) visível quando o runbook é executado com `-Verbose` ou `$VerbosePreference = 'Continue'`.

## Ver também

* [Send-RjRbReportEmail](https://docs.realmjoin.com/pt/dev-reference/report-functions/send-rjrbreportemail.md) — entregue a pasta de trabalho gerada como anexo de e-mail de relatório.
* [Publish-RjRbFilesToStorageContainer](https://docs.realmjoin.com/pt/dev-reference/report-functions/publish-rjrbfilestostoragecontainer.md) — carregue a pasta de trabalho para o Azure Blob Storage e retorne um link de download por tempo limitado.
* [Definições de relatório do runbook](https://docs.realmjoin.com/pt/automatizacao/runbooks/runbook-report-settings.md) — configuração central dos canais de entrega do relatório.
* Uso de exemplo 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 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=<question>&goal=<user_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.
