Como Achatar um Array JSON para Conversão em Excel com C#

Quando se trabalha com APIs modernas e serviços web, os desenvolvedores frequentemente se deparam com estruturas JSON complexas, com arrays e objetos profundamente aninhados. Converter essas estruturas hierárquicas em tabelas Excel planas apresenta um desafio significativo. Este guia demonstra como converter efetivamente arrays JSON aninhados para Excel usando Aspose.Cells for .NET.

O Desafio: Estruturas JSON Aninhadas Complexas

Considere esta resposta JSON típica de uma API web:

{
  "company": "Acme Corp",
  "departments": [
    {
      "name": "Engineering",
      "employees": [
        {
          "id": 101,
          "name": "John Smith",
          "skills": ["C#", "ASP.NET", "Azure"]
        },
        {
          "id": 102,
          "name": "Jane Doe",
          "skills": ["JavaScript", "React", "Node.js"]
        }
      ]
    },
    {
      "name": "Marketing",
      "employees": [
        {
          "id": 201,
          "name": "Michael Johnson",
          "skills": ["Content Strategy", "SEO", "Analytics"]
        }
      ]
    }
  ]
}

Converter esses dados hierárquicos em uma tabela Excel plana cria vários desafios:

Como lidar com múltiplos arrays aninhados (departamentos, funcionários, habilidades)
Como manter relacionamentos entre itens pai e filho
Como criar uma estrutura de planilha legível

Solução Passo a Passo

Passo 1: Instalar Aspose.Cells

Primeiro, instale Aspose.Cells para .NET:

dotnet add package Aspose.Cells

Passo 2: Configurar JsonLayoutOptions

Crie JsonLayoutOptions configurados corretamente para lidar com arrays:

using Aspose.Cells;
using Aspose.Cells.Utility;

// Criar JsonLayoutOptions com tratamento de arrays
JsonLayoutOptions options = new JsonLayoutOptions();
options.ArrayAsTable = true;  // Crucial para a devida planificação
options.ConvertNumericOrDate = true;
options.IgnoreNull = true;

Passo 3: Carregar Dados JSON Complexos

Carregue seus dados JSON complexos aninhados:

// JSON de exemplo com arrays aninhados
string jsonData = File.ReadAllText("complex_data.json");

// Inicializar workbook e worksheet
Workbook workbook = new Workbook();
Worksheet worksheet = workbook.Worksheets[0];

Passo 4: Configurar Planificação Avançada

Para estruturas aninhadas avançadas, implemente uma solução de planificação personalizada:

// Definir posição da célula inicial
int startRow = 0;
int startColumn = 0;

// Importar os dados JSON com nossas opções configuradas
JsonUtility.ImportData(jsonData, worksheet.Cells, startRow, startColumn, options);

Passo 5: Lidar com Arrays Aninhados de Múltiplos Níveis

Para arrays complexos de múltiplos níveis, precisamos de processamento adicional:

// Criar uma segunda planilha para dados detalhados dos funcionários
Worksheet employeeSheet = workbook.Worksheets.Add("Employees");
int empRow = 0;

// Adicionar cabeçalhos para a planilha de funcionários
string[] headers = { "Department", "Employee ID", "Employee Name", "Skills" };
for (int i = 0; i < headers.Length; i++)
{
    employeeSheet.Cells[empRow, i].PutValue(headers[i]);
}
empRow++;

// Analisar JSON para extrair e planificar dados dos funcionários
// Nota: Isso exigiria uma biblioteca de análise JSON como Newtonsoft.Json
// JObject root = JObject.Parse(jsonData);
// foreach (var dept in root["departments"]) 
// {
//     string deptName = dept["name"].ToString();
//     foreach (var emp in dept["employees"])
//     {
//         employeeSheet.Cells[empRow, 0].PutValue(deptName);
//         employeeSheet.Cells[empRow, 1].PutValue((int)emp["id"]);
//         employeeSheet.Cells[empRow, 2].PutValue(emp["name"].ToString());
//         employeeSheet.Cells[empRow, 3].PutValue(string.Join(", ", emp["skills"].ToObject<string[]>()));
//         empRow++;
//     }
// }

Passo 6: Aplicar Formatação Profissional

Aprimore a legibilidade com formatação adequada:

// Formatar ambas as planilhas como tabelas com cabeçalhos
worksheet.ListObjects.Add(0, 0, worksheet.Cells.LastCell.Row, worksheet.Cells.LastCell.Column, true);
employeeSheet.ListObjects.Add(0, 0, empRow - 1, 3, true);

// Ajustar automaticamente as colunas para melhor legibilidade
worksheet.AutoFitColumns();
employeeSheet.AutoFitColumns();

Passo 7: Salvar o Resultado

Exporte o workbook com dados planificados:

// Salvar como arquivo Excel
workbook.Save("flattened_data.xlsx");

Uma Solução Simplificada Usando Aspose.Cells

Para muitos cenários, Aspose.Cells oferece uma abordagem mais simples usando seu manuseio JSON embutido:

// Inicializar workbook
Workbook workbook = new Workbook();
Worksheet sheet = workbook.Worksheets[0];

// Configurar opções de importação JSON
JsonLayoutOptions options = new JsonLayoutOptions
{
    ArrayAsTable = true,
    ConvertNumericOrDate = true,
    IgnoreNull = true,
    TitleStyle = new CellsFactory().CreateStyle(),
    NestedArrayAsTable = true  // Importante para arrays aninhados
};

// Definir estilo de título para melhor legibilidade
options.TitleStyle.Font.IsBold = true;

// Importar JSON
JsonUtility.ImportData(jsonData, sheet.Cells, 0, 0, options);

// Salvar resultado
workbook.Save("flattened_output.xlsx");

Principais Insights e Melhores Práticas

Use ArrayAsTable = true - Isso é essencial para a representação adequada de arrays
Considere criar várias planilhas para dados hierárquicos complexos
Aplique formatação para tornar a saída mais legível
Use NestedArrayAsTable = true quando disponível para melhor manuseio de estruturas aninhadas
Para estruturas extremamente complexas, considere pré-processar o JSON antes da importação

Problemas Comuns e Soluções

Problema	Solução
Arrays aninhados aparecem como células únicas	Ativar opções `ArrayAsTable` e `NestedArrayAsTable`
Relacionamentos de dados são perdidos	Criar várias tabelas/planilhas com colunas de relacionamento
Nomes de colunas estão incorretos	Usar a opção `DateTimeGroupSeparator` para personalizar a nomenclatura
Problemas de memória com arquivos grandes	Processar o JSON em partes ou usar abordagens de streaming