Como Usar IronXL com GitHub Copilot
Uma solução de relatórios .NET já pode escrever os números corretos em planilhas básicas e ainda receber uma solicitação sobre aparência. O setor financeiro quer suas cores de cabeçalho, separadores de milhares, margens destacadas, uma linha de cabeçalho que permanece fixa enquanto você rola e nomes que outras planilhas podem apontar.
IronXL fornece as chamadas de formatação para fontes, preenchimentos, formatos de números, regras condicionais, congelamento de painéis, larguras de colunas, tabelas e intervalos nomeados. Dois arquivos de instruções comprometidos no repositório registram como essas chamadas se comportam.
Este guia estiliza a saída de um relatório de vendas mensal existente e comprova cada estilo com testes que salvam a planilha, abrem-na novamente e leem todas as configurações de volta. O guia de formatação de células e o guia de formatação condicional documentam as próprias chamadas.
Início RápidoAbra um terminal na raiz da solução, inicie copilot, e envie este prompt. O chat do Visual Studio leva os mesmos dois arquivos como #report-style.md e #ReportStyler.cs.
Read @docs/report-style.md, then fill in @src/FinanceReports/Styling/ReportStyler.cs.
Give it a public static ApplyHouseStyle(WorkBook workbook) method.
It styles the workbook that MonthlySalesReport.Build returns.
IronXL is the IronXL.Excel package.
Styling types are in IronXL.Styles and number formats in IronXL.Formatting.
Keep this first pass to the header row, the data rows and the Total row of the Sales sheet.
Set their fonts, fills, borders, alignment and number formats. The other sections come later.
Find the Total row by the word Total in column A. Don't count on a fixed row number.
1. Call ApplyHouseStyle from Program.cs just before SaveAs.
2. Run the job.
3. Load out/monthly-sales-2026-09.xlsx again.
4. Print the fill and font color of A1 and the FormatString of E2, exactly as IronXL gives them.
O prompt não diz nada sobre como IronXL relata cores e formatos após um recarregamento, porque o arquivo de instrução específico do caminho carrega essas regras.
Defina IRONXL_LICENSE_KEY no ambiente de onde o Copilot começa, e veja o guia de chave de licença para outros lugares para manter a chave. Mantenha-a fora dos prompts e commits. Cada teste aqui carrega uma planilha, então a chave tem que estar presente onde quer que os testes executem.
Fluxo de trabalho mínimo (5 etapas)
- Baixe a biblioteca Excel C# do NuGet
- Registre como o IronXL relata estilos em
.github/copilot-instructions.mde um arquivo específico de caminho.instructions.md - Estilize o cabeçalho, os dados e as linhas de Total, depois adicione regras condicionais, o cabeçalho congelado e os nomes, e dimensione as colunas por último
- Recarregue cada planilha salva em testes e verifique cada estilo, lendo o painel congelado a partir do XML da folha
- Atribua o acompanhamento XLS ao agente de nuvem como um problema e verifique seu pull request contra a referência de API
Onde o Copilot se encaixa em um projeto já no Visual Studio?
Use o Copilot CLI a partir de um terminal, ou modo agente no Visual Studio ou VS Code, para uma mudança de estilização que você deseja acompanhar, já que ele pode construir a solução e executar a tarefa de relatório sozinho. O chat embutido é suficiente para uma mudança de um arquivo. O agente de nuvem no GitHub aceita um problema atribuído e retorna um pull request.
Como você define convenções do IronXL para o Copilot?
Confirme as convenções do IronXL como .github/copilot-instructions.md. Copilot CLI, chat no Visual Studio e VS Code, o agente de nuvem e a revisão de código Copilot todos o leem, então coloque o pacote, a regra de licença e as regras de teste lá.
# Copilot instructions
## Workbooks
- Excel work uses IronXL from the IronXL.Excel NuGet package. Styling types
live in IronXL.Styles, number formats in IronXL.Formatting, and comparison
operators in IronXL.Formatting.Enums. Add no other spreadsheet package and
no Office Interop.
- The IronXL version is pinned in Directory.Packages.props. Leave it alone
unless the task is an upgrade.
- The license key comes from the IRONXL_LICENSE_KEY environment variable,
and the program reads it there. Never put a key in code, settings files,
tests or console output, and don't list environment variables.
- docs/report-style.md is the source for every color, border, format and
name in the monthly sales workbook.
- IronXL documentation is at https://ironsoftware.com/excel/csharp/llms.txt
and https://ironsoftware.com/excel/csharp/skill.md
- Say so whenever you depart from docs/report-style.md, and before you use
an IronXL member you cannot find in IronXL.xml in the NuGet cache.
## Tests
- Build the workbook into a temporary folder, save it, load it again with
WorkBook.Load and assert on what the loaded file reports.
- Never compare workbook bytes and never edit files under TestData.
Como você dá ao código de estilização suas próprias regras?
As regras que importam apenas para o código que define ou verifica estilos vão em .github/instructions/workbook-styling.instructions.md. Seu valor applyTo nomeia duas pastas, separadas por uma vírgula, então as regras alcançam o estilizador e seus testes e ficam de fora das solicitações sobre a importação CSV. A documentação do GitHub diz que o CLI inclui o arquivo apenas quando o Copilot trabalha em um arquivo que corresponda ao glob. Em nossa execução, o Copilot CLI listou o padrão e o caminho do arquivo em cada sessão e disse ao agente para lê-lo antes de alterar o código. O agente abriu antes de sua primeira edição em cada prompt que mudou o código, exceto o segundo, que se baseou na cópia já na sessão.
---
applyTo: "src/FinanceReports/Styling/**,tests/FinanceReports.Tests/**"
---
- IronXL returns colors as lowercase hex. A fill set with "#1F4E78" reads
back as "#1f4e78", so compare colors ignoring case.
- A cell with no fill still reports BackgroundColor "#ffffff". Use
FillPattern (NoFill or SolidForeground) to tell the two apart.
- FormatString only changes how numbers and dates display. A number written
as a string keeps its raw text, its DecimalValue is 0, and SUM skips it.
- Font.Height is the size in points, the number Excel shows.
- Call AutoSizeColumn last. It measures the formatted text in the cell's
font, and on a machine without that font it measures in Arial.
- AddNamedTable and AddNamedRange throw ArgumentException when the name
already exists, and AddConditionalFormatting adds another copy of a rule
on every call. Guard each one so restyling a styled workbook changes nothing.
- IronXL has no getter for freeze panes. Check one by reading the pane
element in the sheet XML.
Execute /instructions em uma sessão CLI para confirmar quais dos dois arquivos estão ativos antes de um prompt longo.
Como o IronXL lê estilos de células após um recarregamento?
Alguns valores que o IronXL devolve após WorkBook.Load diferem do que o código passou. Com o IronXL 2026.10.1, uma fonte definida com "#FFFFFF" é lida de volta como #ffffff, e uma borda definida com "#BFBFBF" como #bfbfbf. A Assert.Equal("#1F4E78", cell.Style.BackgroundColor) falhou contra nossa planilha de referência, e uma comparação que ignora maiúsculas passou. O relatório escreve valores de data, e o IronXL deu a essas células o formato m/d/yy h:mm até o estilizador definir yyyy-mm-dd. Com o #,##0.00, FormattedCellValue retornou 176.366,84 enquanto Text ainda retornou 176366,84157142858, o número subjacente. Uma margem escrita como a string "-0.075" manteve esse texto sob 0.00%, e IsText foi verdadeiro. Um valor de receita escrito como texto manteve a string de formato #,##0.00, então um teste que verifica apenas FormatString passa nessa célula quebrada. A documentação XML enviada com o pacote descreve Font.Height em pixels, mas uma altura de 12 foi salva como tamanho 12.
Como você adiciona formatação condicional, congelamento de painéis e larguras de colunas?
As regras de margem vêm de CreateConditionalFormattingRule, que leva um ComparisonOperator e uma fórmula, e AddConditionalFormatting, que anexa a regra a um intervalo. O cabeçalho congelado é uma chamada, CreateFreezePane(0, 1), onde o primeiro argumento conta colunas congeladas e o segundo conta linhas congeladas, então CreateFreezePane(1, 4) congelou a coluna A e as linhas de 1 a 4. As larguras das colunas vêm de AutoSizeColumn.
Add three more parts of @docs/report-style.md to ApplyHouseStyle.
It lives in @src/FinanceReports/Styling/ReportStyler.cs.
- The margin highlighting. Both rules go on the data rows of column F and stay off the Total row.
- The frozen header row.
- The column widths. Size them as the very last step, after every font, fill and number format.
Run the job and reload the output. Then print:
- the range, operator and formula of each rule, as IronXL reads them
- the pane element in the Sales sheet's XML
- the width of columns A to F
Nosso estilizador de referência dimensionou as colunas por último e obteve larguras de 2.790, 6.988, 3.660, 1.740, 3.430 e 1.792 para as colunas de A a F, em unidades de 1/256 de um caractere que GetColumn(i).Width retornou na nossa execução. Dimensionar primeiro, antes dos formatos, deu 1.587 para Unidades e 3.123 para Receita, muito estreito uma vez que os separadores de milhares apareceram, e 3.635 para a coluna de data, que foi medida contra o formato padrão de data e hora mais longo.
Fontes mudam os números também. Em nossa máquina com Windows, quatro fontes que não estavam instaladas produziram exatamente as larguras do Arial, que eram de 6 a 9 por cento mais largas que as do Calibri. Um teste que fixa larguras exatas, portanto, falha em qualquer executor que não tenha a fonte do relatório.
O painel congelado é escrito como <pane ySplit="1" topLeftCell="A2" activePane="bottomLeft" state="frozen"/> no XML da folha e sobreviveu a um carregamento e salvamento através do IronXL.
IronXL salva cada preenchimento de regra como uma entrada em uma paleta indexada personalizada em xl/styles.xml, e nosso arquivo continha as cores certas, FFC7CE e C6EFCE. Lidas de volta através de PatternFormatting.BackgroundColor, ambas as regras relataram #ffc7ce. O intervalo, o operador, a fórmula e a cor da fonte de cada regra foram lidos corretamente. Apenas o preenchimento precisa do arquivo, embora ler ambas as cores dele permita que um ajudante de teste as cubra.
Como você adiciona tabelas nomeadas e intervalos nomeados?
Os nomes no documento de estilo vêm de duas chamadas. AddNamedTable("SalesData", range, true, TableStyle.TableStyleLight9, true) transforma as linhas de cabeçalho e de dados em uma tabela com botões de filtro. AddNamedRange("TotalRevenue", range, true) dá à célula de Receita da linha Total um nome abrangente no livro que uma fórmula de Resumo pode usar como =TotalRevenue. Após EvaluateAll, essa fórmula retornou o mesmo total da célula que nomeia. FindNamedRange("TotalRevenue") retorna a referência como o texto 'Sales'!$E$38:$E$38 e não um Range. SaveAsNamedTable e SaveAsNamedRange em um Range realizam o mesmo trabalho.
Nenhuma das quatro chamadas verifica um nome existente. Execute o estilizador uma segunda vez em uma planilha que já foi estilizada e AddNamedTable lança ArgumentException com a mensagem "O livro já contém tabela com o nome: SalesData". AddNamedRange faz o mesmo para TotalRevenue, e as duas chamadas SaveAs lançam as mesmas duas exceções. AddConditionalFormatting não lança, e em nosso teste uma segunda execução levou a folha de duas regras de margem para quatro. IronXL também recusou o nome da tabela Sales Table, com uma ArgumentException dizendo que nomes não devem conter espaços.
Finish @src/FinanceReports/Styling/ReportStyler.cs with what's left in @docs/report-style.md.
That's the SalesData table, the TotalRevenue name and the Summary sheet rules.
Column sizing stays the final step.
Finance fixes figures directly in a saved workbook and sends it back for the house style.
So add a restyle <path> command to Program.cs.
It loads the file, calls ApplyHouseStyle and saves the file over itself.
Restyling a file twice has to leave exactly one table, one TotalRevenue name and two margin rules.
Show me that it holds:
1. Run the job once.
2. Make a copy of the output in out/ and restyle that copy twice.
3. After each pass, print the table names, named ranges, rule count and the value of Summary!B2.
Remover as antigas regras de margem com RemoveConditionalFormatting antes de adicionar as novas, ou pular uma regra que a folha já possui, mantém a contagem de regras em dois, e verificar GetNamedTableNames e GetNamedRanges antes de cada adição impede que a segunda passagem lance exceção.
Como você testa estilos do Excel após um recarregamento?
A suíte precisa de alguns ajudantes antes que qualquer teste único seja útil, um para ler o XML da folha e outro para resolver cores de regras, então este prompt começa com /plan. No modo de plano, o Copilot CLI bloqueia edições em arquivos de projeto até você aprovar o plano.
/plan an xUnit suite in tests/FinanceReports.Tests that checks the house style after a reload.
Build the September report into a temp folder, save it and open it again with WorkBook.Load.
Then check each rule in docs/report-style.md against what the reopened file holds.
- Check FillPattern beside every fill color.
- Read the frozen pane from the Sales sheet XML with ZipArchive.
- For the margin rules, read each rule's range, operator and formula through IronXL.
- Resolve each rule's fill and font color from its dxf entry in xl/styles.xml.
- An indexed color there points into the indexedColors list, so follow it.
- Check FormattedCellValue for a sample of cells in every numeric column.
- Add a test that restyles a saved copy twice.
- For the widths, autosize a reloaded copy again and confirm no column moves.
- Never assert an exact column width.
Implement the plan, then run dotnet test.
Por que os valores das células formatadas dependem da cultura?
IronXL formata FormattedCellValue com a cultura .NET atual. A planilha é o mesmo arquivo de qualquer forma, e a string de formato leu #,##0.00 em todas as culturas que tentamos.
- en-CA: Uma célula de receita mostrou 176.366,84.
- de-DE: A mesma célula mostrou 176.366,84.
- fr-FR: A mesma célula mostrou 176 366,84, onde o espaço é um espaço fino que não quebra (U+202F).
Uma margem de -0.075 formatada como 0.00% voltou como -7,50% tanto em de-DE quanto em fr-FR. Text também muda, e DecimalValue não.
A suíte que o Copilot escreveu a partir do prompt /plan compara essas strings diretamente, por exemplo Assert.Equal("47,999.33", ...) na primeira célula de receita. Nós a executamos novamente sob de-DE e depois fr-FR. O teste de estilo da casa falhou ambas as vezes, com 47.999,33 e 47 999,33 como os valores reais, e os outros três testes passaram.
Definir CultureInfo.CurrentCulture para en-US no topo desse teste fez passar novamente para de-DE e fr-FR. Uma planilha carregada com de-DE e lida após a troca para en-US também deu 176.366,84, então a configuração que conta é a que está em vigor quando o teste lê a célula. Fixe a cultura em qualquer teste que compare strings de exibição, ou compare DecimalValue e FormatString em vez disso. O laptop de um colega ou o ambiente do agente de nuvem pode executar com uma cultura diferente da máquina que produziu as strings esperadas.
O que faz de um problema algo que o agente de nuvem pode atuar?
O agente de nuvem recebe o título do problema, a descrição, os comentários já existentes no problema e quaisquer instruções adicionadas na atribuição. O GitHub afirma que não vê comentários postados depois, então todos os requisitos e o teste que fecha o trabalho pertencem ao corpo do problema.
Title: Add an XLS copy of the monthly sales workbook for the ERP import
**Files:** src/FinanceReports/Program.cs, src/FinanceReports/Styling/ReportStyler.cs
**IronXL version:** as pinned in Directory.Packages.props
**Framework:** .NET 9
**Expected:** Each run writes out/monthly-sales-2026-09.xls next to the XLSX,
with the same values and the house style in docs/report-style.md, except the
SalesData table. The TotalRevenue name and Summary!B2 stay.
**Actual:** The ERP import accepts only .xls, and finance converts the file by
hand every month.
**Constraints:** Leave the XLSX output unchanged. Build the XLS workbook with
WorkBook.Create(ExcelFileFormat.XLS) rather than saving the XLSX under a new
extension. In XLS, set every fill before any font color. No new packages.
**Acceptance:** dotnet test passes, plus tests that reopen the .xls and check
the header fill and white header text, the four number formats, the
TotalRevenue name and the operator and formula of both margin rules.
As regras do XLS no problema vêm de medições.
- Tabelas nomeadas:
AddNamedTableeSaveAsNamedTableem um workbook XLS lançam NotSupportedException com "Apenas XLSX suporta tabelas nomeadas." - SaveAs com um caminho .xls: No workbook XLSX estilizado,
SaveAslançou FormulaParseException, e sua mensagem dizia que a faixa nomeada TotalRevenue não existia no workbook atual. - Ordem de preenchimento: O XLS armazena cores em uma paleta compartilhada, e em uma sonda uma fonte de cabeçalho definida para branco antes de serem adicionados três preenchimentos voltou como #ddebf7, o segundo desses preenchimentos, enquanto definir primeiro os preenchimentos manteve-a #ffffff.
- Preenchimentos de regra: Ler o preenchimento de uma regra de margem do arquivo XLS recarregado lançou NullReferenceException, então a linha de aceitação pede o operador e a fórmula de cada regra e não suas cores.
Por que os testes do agente de nuvem falham em um projeto IronXL?
Por padrão, o ambiente do agente executa Ubuntu Linux. Quando todos os testes de estilização falham juntos em um branch que o agente enviou, leia a primeira exceção antes da diferença. Uma LicensingException aponta para a chave de licença.
O agente de nuvem não pode ler segredos de Actions, Codespaces ou Dependabot, então a chave precisa de um segredo de Agentes. Adicione IRONXL_LICENSE_KEY em Configurações, depois Segredos e variáveis, depois Agentes, e o agente a recebe como uma variável de ambiente. Os pull requests do agente pousam no repositório real, então mantenha a proteção de branch e uma aprovação humana ativada.
Por que a estilização falha em planilhas de outras bibliotecas?
Uma planilha do escritório EMEA, escrita por um trabalho Python em openpyxl com o mesmo layout do relatório, lançou InvalidOperationException com "Objeto Nullable deve ter um valor" na primeira configuração de estilo chamada nele, seja essa texto em negrito ou um formato de número. ApplyHouseStyle funcionou em cada planilha que nosso próprio trabalho escreve, o que faz parecer um bug no estilizador quando a causa está no arquivo.
A colleague added tests/FinanceReports.Tests/PartnerWorkbookTests.cs and it fails.
It covers the workbooks the EMEA office sends, which a Python job writes with openpyxl.
It throws InvalidOperationException "Nullable object must have a value".
The exception comes from deep inside the first style setter.
ApplyHouseStyle still passes on our own output.
Before you edit anything, find out what causes it and tell me:
1. Open TestData/partner/emea-2026-09.xlsx and one workbook our job writes with ZipArchive.
2. Compare the fill entries in xl/styles.xml.
3. Try a single style setter on each workbook.
Then fix it at the point where the restyle command and this test load a workbook.
Leave the partner file untouched on disk and add no package.
Run dotnet test when you're done.
O primeiro preenchimento do arquivo do parceiro é <patternFill />, sem o atributo patternType, que o openpyxl 3.1.5 escreve para seu preenchimento padrão. O arquivo do nosso trabalho tem <patternFill patternType="none"/> no mesmo lugar. IronXL carregou o arquivo do parceiro e leu seus valores sem erro. Carregando, salvando através do IronXL e carregando novamente manteve o elemento nu e ainda lançou. Adicionar o atributo ausente a esse elemento na memória e carregar o pacote corrigido, através de WorkBook.Load(Stream) em nossa sonda ou de uma cópia temporária, permitiu que o estilo completo fosse aplicado, e o arquivo no disco permaneceu como o parceiro o enviou.
Manter a correção na etapa de carregamento impede o assistente de capturar a exceção dentro do estilizador, o que ocultaria o problema e deixaria a planilha do parceiro destilizada.
O que você deve verificar antes de fazer o merge?
A documentação do GitHub mostra /review enviado como um prompt copilot -p, então esta revisão pode ser executada de um script antes da mesclagem.
/review the commits on this branch after the first one.
Check them against docs/report-style.md and both instruction files under .github.
Flag any of these:
- a color compared with case-sensitive equality
- an AutoSizeColumn call that runs before a later format or font change
- an AddNamedTable, AddNamedRange or AddConditionalFormatting call with no guard for a second run
- a test that pins an exact column width or compares workbook bytes
- an IronXL member that isn't in IronXL.xml in the NuGet cache
Give each finding its file and line. Don't edit anything.
O prompt nomeia ambos os arquivos de instruções para que as regras de estilização se apliquem à revisão toda e não apenas aos arquivos que o glob corresponde. A revisão de código Copilot no GitHub também suporta o arquivo específico do caminho.
A diferença ainda precisa de uma leitura humana para a única coisa que a revisão e os testes podem perder, que é se os valores mudaram. A estilização deve deixar cada número e data como o relatório escreveu, e cada fórmula exceto Summary!B2, que o documento de estilo move para o nome TotalRevenue. Os totais devem coincidir com o feed CSV.
O que os prompts produziram em uma execução real?
O Copilot CLI recebeu os seis prompts em sequência sem ninguém no teclado. Os primeiros cinco compartilharam uma sessão, com o prompt /plan executado no modo de plano e piloto automático, e /review foi executado como sua própria chamada copilot -p. O alvo era uma solução de relatórios construída para este guia no .NET 9, com uma tarefa de console que escreve a planilha de setembro não estilizada a partir de um feed CSV, um projeto xUnit ainda sem testes, e o documento de estilo. Um commit à frente do prompt do parceiro adicionou a planilha EMEA e o teste falho do colega. Cada figura abaixo vem de reconstruir a solução, reexecutar a tarefa e rodar os testes uma vez que o Copilot tenha terminado. O guia de assistentes de codificação de IA transforma este tipo de verificação em um teste repetível.
- Nosso teste de estilo passou em 23 de 30 verificações após o primeiro prompt, cada cabeçalho, dado e verificação de Total entre elas. Passou em 25 de 30 após as regras, painel e larguras, e 31 de 31 após os nomes e o comando de restilização, com todos os valores ainda correspondendo ao feed CSV.
- Após o segundo prompt, as larguras das colunas corresponderam exatamente ao nosso estilizador de referência, e ambas as regras de margem ficaram em F2:F37.
- Restilizar uma cópia duas vezes deixou uma tabela, um nome TotalRevenue e duas regras de margem, e Summary!B2 ainda retornou 10.977.073,68.
- A suíte planejada passou em 3 de 3 testes. Mudar o dimensionamento de colunas antes dos formatos em uma cópia do código final fez seu teste de largura falhar.
- Após o prompt do parceiro, 4 de 4 testes passaram e uma cópia restilizada do workbook EMEA passou em todas as 32 verificações.
- A chamada
/reviewnão encontrou nenhum dos cinco problemas listados. - Alguns passos foram executados de forma diferente da página. O primeiro prompt também adicionou ambas as regras de margem, que a página deixa para o segundo. Em uma execução anterior, o teste de largura apenas verificou que larguras existiam e passou com colunas dimensionadas primeiro, então o prompt
/planagora pede por uma segunda passagem de redimensionamento automático. O problema, o agente de nuvem, o segredo dos Agentes e a revisão de pull request precisam de um repositório hospedado, então nenhum deles foi executado.
A versão do Copilot CLI, o modelo automático escolhido, o tempo de execução e a máquina de teste são registrados uma vez para cada guia no registro de execução.
Solução de problemas
- Aplicar uma Chave de Licença no IronXL quando um teste lança LicensingException antes que qualquer estilo seja definido
- Formatação Condicional de Excel C# para adicionar, ler e remover regras de margem
- Formatação de Célula de Excel C# para os valores
FormatStringe os formatos embutidos - Redimensionar Automaticamente Linhas e Colunas do Excel para as chamadas de redimensionamento automático e as unidades em que o Excel mede larguras
- Adicionar Tabelas Nomeadas no Excel para estilos de tabela e botões de filtro
Questões?
Se você tiver dúvidas, entre em contato com support@ironsoftware.com
Curtis Chau é bacharel em Ciência da Computação (Universidade Carleton) e se especializa em desenvolvimento front-end, com experiência em Node.js, TypeScript, JavaScript e React. Apaixonado por criar interfaces de usuário intuitivas e esteticamente agradáveis, Curtis gosta de trabalhar com frameworks modernos e criar manuais bem estruturados e visualmente atraentes.