Como Usar o IronWord com o GitHub Copilot

Curtis Chau
Curtis Chau
Atualizado: 19 de outubro de 2026

Um serviço .NET pode gerar declarações mensais de conta como arquivos Word, cada um com um título estilizado, duas linhas de resumo e uma tabela construída a partir de dados. Neste guia, o serviço reside em uma solução do Visual Studio junto com os trabalhos que fornecem seus dados, portanto, qualquer assistente que o modifique deve funcionar dentro da mesma solução.

O GitHub Copilot pode trabalhar nessa solução a partir do Visual Studio ou do VS Code no modo de chat ou agente, de um terminal com Copilot CLI, e do GitHub, onde seu agente na nuvem abre uma solicitação de pull para um problema atribuído a ele. O IronWord constrói o DOCX no código, com execuções de texto estilizadas e tabelas que têm células mescladas e linhas sombreadas. As regras do IronWord são mantidas em arquivos de instruções no repositório, e cada uma dessas superfícies as lê.

O guia de tabela e o guia de estilo de texto cobrem as duas partes da API das quais este guia depende.

Início Rápido
NuGetInstalar com NuGet

PM > Install-Package IronWord

Instale o IronWord executando o comando acima no Console do Gerenciador de Pacotes NuGet, ou procure pelo pacote no Gerenciador de Pacotes NuGet.

Inicie o Copilot CLI a partir do diretório raiz da solução e cole no prompt abaixo. O Copilot Chat no Visual Studio faz referência a um arquivo com #, enquanto o CLI usa @.

Fill in @src/Statements/Documents/StatementBuilder.cs with a public static Build method.
Its signature is Build(Account account, IReadOnlyList<Transaction> transactions, string outputPath).
Add Account and Transaction as small records in the same folder.

Write the DOCX with IronWord, from the IronWord NuGet package.
The types are in the IronWord and IronWord.Models namespaces.

Lay out the statement exactly as @docs/statement-layout.md describes. Three parts need care:
- the bold heading row
- the merged closing-balance cell
- the alternate row shading

Save the file to outputPath, then compile the solution and clear every build error.
Tell me which files you added or changed.
Text

O prompt não nomeia nenhum membro de estilo. O arquivo de instruções específico do caminho abaixo especifica os membros a serem usados.

O Program.cs da solução lê IRONWORD_LICENSE_KEY do ambiente e o atribui a IronWord.License.LicenseKey, então defina a variável antes de iniciar o Copilot. O guia da chave de licença mostra a mesma atribuição e os arquivos de configuração que podem conter a chave.



Como você define convenções do IronWord para o Copilot?

As regras para todo o repositório vão em .github/copilot-instructions.md. Copilot CLI, revisão de código do Copilot, o agente na nuvem e o Copilot Chat em JetBrains IDEs, Visual Studio e VS Code leem esse arquivo, de acordo com a matriz de suporte do GitHub. Visual Studio só o carrega depois que a caixa de seleção de instruções personalizadas é selecionada nas opções do Copilot Chat.

Statement code in this repository follows these rules:

- Statements are DOCX files written with IronWord, from the NuGet package IronWord.
- Import both namespaces, IronWord and IronWord.Models.
- Use no other Word library and no OpenXML SDK code.
- Keep the IronWord version set in Directory.Packages.props, unless the task is upgrading it.
- IRONWORD_LICENSE_KEY holds the license key, and Program.cs reads it there.
- Do not put the key in source, settings files, tests or logs.
- Never print its value, and don't list environment variables.
- docs/statement-layout.md is the layout contract. Do not edit it.
- Propose changes to that layout in your reply instead.
- IronWord's documentation for agents is at https://ironsoftware.com/word/csharp/llms.txt
- An IronWord member is real only when it builds and a saved file shows its effect.
- The documentation, its samples and IronWord.xml list some that do not compile or are not saved.

Statement tests follow these rules:

- Build statements in a temp directory and reopen the saved file with IronWord.
- Compare cell text, values and run styles. Never compare DOCX bytes.
Markdown

Como você dá regras próprias ao código do documento?

As regras para algumas pastas vão apenas em um arquivo específico do caminho, como .github/instructions/documents.instructions.md, cujos padrões applyTo aqui cobrem o código do documento e seus testes. A documentação do Copilot CLI do GitHub diz que o CLI adiciona o arquivo a uma solicitação apenas quando um arquivo que está sendo manipulado corresponde a um padrão listado. Em nossa execução, o CLI listou os padrões e caminho do arquivo no início de cada sessão, e o Copilot leu o arquivo antes de sua primeira edição.

---
applyTo: "src/Statements/Documents/**,tests/Statements.Tests/**"
---

The document code and its tests follow these IronWord rules:

- Style text on a Run, with new Run(new TextStyle { ... }) or Run.Style.
- TextContent.IsBold, TextContent.FontSize and Run.FontSize are read-only.
- SaveAs drops a TextStyle assigned to TextContent.Style.
- SaveAs writes a TextStyle's FontSize only when its TextFont is set too.
- Add each body line as its own paragraph with AddParagraph.
- WordDocument.AddText joins its text onto whichever paragraph came last.
- Table.ApplyCellStyle is listed in IronWord.xml but does not compile.
- Style each cell's runs in place of ApplyCellStyle.
- new Table(rows, columns) creates every cell, with zero-based indexes.
- Fill a cell with AddChild or AddText on table[row, column].
- Table.Rows, TableRow.Cells and a TableRow indexer return ITableRow and ITableCell.
- ITableRow and ITableCell have no AddText, AddChild or ExtractText.
- Cast to TableRow or TableCell first.
- SaveAs writes no merge made with Table.MergeCells.
- For a cell that spans two columns, add a new TableRow of two TableCells with AddRow.
- Give the first of those two cells GridSpan = 2.
- Shade alternate rows with Table.Zebra = new ZebraColor(first, second).
- SaveAs writes no fill set through TableCell.Shading.
- With no key set, every save throws LicensingException.
- An in-memory build does not throw it, so it proves nothing about the saved file.
Markdown

Toda regra nesse arquivo é derivada de uma compilação, uma verificação de memória ou um arquivo salvo. A documentação XML enviada lista ApplyCellStyle na tabela, mas o compilador rejeita a chamada com CS1061, então apenas o XML não mostra se um membro é compilável. Uma sondagem mostrou que um preenchimento configurado através da propriedade Shading de uma célula nunca foi escrito no arquivo salvo, enquanto Zebra escreveu um preenchimento em cada célula.

Como você constrói uma tabela de declaração a partir de dados CSV?

O código da declaração pode falhar neste estágio sem gerar um erro. Nos arquivos salvos, uma linha de fechamento mesclada com MergeCells ainda continha três células simples, embora a tabela registrasse a mesclagem em memória. Um título definido para 18 pontos sem fonte foi salvo sem tamanho. Apenas uma inspeção do arquivo salvo detecta qualquer problema.

Rework @src/Statements/Pipeline/StatementJob.cs to write one statement per account, in this order:

1. Read Data/accounts.csv and Data/transactions.csv.
2. Group the transactions by account.
3. Call StatementBuilder.Build once per account.
4. Write <AccountId>.docx into the output folder that StatementJob.Run receives.

That folder is out/statements under the solution root.

The data needs care in a few places:
- Descriptions such as "Rent, September" hold commas.
- Parse quoted fields with a few lines of your own code, and add no CSV package.
- Parse amounts as decimal with the invariant culture.
- An account with no transactions still gets a statement, with its heading and closing rows.

Run the job.
For every statement, print its path, its transaction row count and its closing balance.
Text

A fixture contém quatro contas, com cinco, duas, três e zero transações. No arquivo CSV, as linhas da conta poupança não estão em ordem de data, e o layout requer que a mais antiga venha primeiro.

Como você testa uma declaração IronWord salva?

ExtractText no documento retornou seus parágrafos, mas nenhum dos textos da tabela, portanto, um teste com base nele passa mesmo quando cada célula está vazia.

Alterne o Copilot CLI para o modo de plano com Shift+Tab antes de enviar este prompt.

Plan an xUnit suite in tests/Statements.Tests, and wait for my approval before you write any code.

Every test loads IRONWORD_LICENSE_KEY into the License.LicenseKey property first.
ExtractText leaves out the text inside tables.
Read the statement table through Tables, Rows and Cells instead.
A reopened file reads GridSpan and MergedCells back empty.
The merged label shows up there as a closing row of two cells.

The suite has to prove these points:
- Each account in Data/accounts.csv gets a table of its transactions.
- The table also holds a heading row and that closing row.
- Cell values and the closing balance match the CSV files.
- Every heading run that holds text is bold.
- The title is bold and 18 point.
- CHK-40902 has the heading and closing rows and no others.

Once I approve, write the tests, run dotnet test and tell me the pass and fail counts.
Text

Com um plano primeiro, você pode verificar como o conjunto lê uma célula mesclada e o estilo de uma execução antes que qualquer asserção seja escrita.

Como resolver código de estilo IronWord que não compila?

O guia de tabela do IronWord estiliza o texto de uma célula com um inicializador de objeto em TextContent. Aquele exemplo não compila com CS0200 porque essas propriedades são somente leitura.

A teammate adapted @src/Statements/Documents/OverdraftNotice.cs from IronWord's add-table how-to.
Now the solution no longer builds.

Before you edit anything, work through these steps:
1. Build and quote each compiler error.
2. Open the IronWord.xml file inside the IronWord package in the NuGet cache.
3. List the styling members it gives for TextStyle and Run.

Then rewrite just the styling in that file.
The saved notice must keep its bold 14 point heading and its bold amount.
Rebuild and confirm the error count is zero. Don't touch any other file.
Text

O compilador reporta erros na manchete e no montante, e a pesquisa XML lista os membros TextStyle que a correção usa em vez disso.

O que faz de um problema algo que o agente de nuvem pode atuar?

O agente da nuvem trabalha a partir do título, descrição e comentários existentes do problema, além de quaisquer instruções fornecidas na atribuição. De acordo com o GitHub, comentários adicionados posteriormente nunca são passados ao agente, então os critérios de conclusão pertencem ao corpo do problema.

Title: Show debit amounts in red on statements

The change covers these files and versions:
- Files: src/Statements/Documents/StatementBuilder.cs, tests/Statements.Tests
- IronWord version: the one Directory.Packages.props sets
- Framework: .NET 9

The expected result is this:
- In the Amount column, every negative amount is red (C00000).
- Positive amounts, the heading row and the closing row keep their current color.
- docs/statement-layout.md gains the rule in the pull request text only.

The actual result is that every amount is black.

The constraints are these:
- Keep the Build signature.
- Style the runs as .github/instructions/documents.instructions.md says.
- Add no packages.

The acceptance test is this:
- The current tests still pass.
- A new test reopens CHK-40211.docx and finds red runs in exactly the four debit cells.
Markdown

Como o teste conta células coloridas em uma declaração conhecida, uma alteração que colore toda a coluna o reprova.

Por que os testes do agente na nuvem falham em um projeto IronWord?

Por padrão, o agente na nuvem trabalha em um ambiente Ubuntu Linux. O IronWord 2026.10.4 fornece uma biblioteca nativa para linux-x64 dentro do pacote, então uma restauração NuGet no executor a inclui. O executor não possui uma chave de licença. Em uma máquina de teste sem uma chave, a declaração construída na memória sem erro, e cada chamada de salvamento na sondagem lançou uma LicensingException cuja mensagem dizia "Licença de Produção Requerida". Todo teste que grava um arquivo falha mesmo quando o código está correto.

Antes do Copilot começar a trabalhar, o GitHub Actions executa o trabalho copilot-setup-steps a partir de .github/workflows/copilot-setup-steps.yml. O fluxo de trabalho não é acionado até que o branch padrão contenha esse arquivo.

The cloud agent's Ubuntu runner needs .github/workflows/copilot-setup-steps.yml.
GitHub picks up a single job called copilot-setup-steps, so give the file exactly that job.

Set the job up like this:
- Give it read access to the repository contents.
- Trigger it on workflow_dispatch and on pull requests that touch the file itself.
- Fetch the code and install whichever .NET SDK the projects use.
- Run a restore, then build in Release.

Without a license key, every IronWord save throws a LicensingException.
Add a step that checks IRONWORD_LICENSE_KEY, which is an Agents secret.
GitHub documents Agents secrets for the cloud agent's environment.
That includes this workflow when it runs for the agent.
So the check works like this:
- In pull_request and workflow_dispatch runs, it prints a warning and passes.
- In any other run, it exits non-zero with a clear message when the key is empty.

Put that step last, because a failing setup step makes Copilot skip whatever follows it.
Write the file, then show me the finished YAML.
Text

Com a verificação colocada por último, um segredo ausente ainda deixa uma solução restaurada e compilada, além de uma linha que identifica o problema.

Armazene a chave como um segredo de Agentes: segredos salvos para Actions, Codespaces ou Dependabot não são passados para o agente na nuvem. Adicione IRONWORD_LICENSE_KEY nas Configurações do repositório em Segurança, Segredos e variáveis, Agentes, e o agente o recebe como uma variável de ambiente.

O que você deve verificar antes de fazer o merge?

Inicie a revisão com sua própria chamada copilot -p, para que ela seja executada em uma sessão diferente daquela que escreveu o código.

/review every change committed after the first commit on this branch.
Hold every IronWord call up against .github/instructions/documents.instructions.md.
Check it against the XML API documentation in the IronWord NuGet package as well.
List each place they conflict.

Also flag any of these:
- styling set on TextContent instead of on runs
- a table cell filled anywhere but on the cell the table already holds
- a closing row that spans its label with MergeCells instead of GridSpan
- a font size with no TextFont beside it
- a test that reads table data with ExtractText instead of reloading the saved file
- any line that prints IRONWORD_LICENSE_KEY

Tell me what you find, and don't edit any file.
Text

O que os prompts produziram em uma execução real?

O Copilot CLI executou todos os seis prompts sem supervisão em uma solução de declaração construída para este guia. Reconstruímos cada commit, executamos novamente o trabalho e os testes, e lemos os arquivos DOCX com um script que não usa IronWord.

  • O arquivo de aviso do colega causou 3 erros de compilação CS0200 antes do prompt de estilização e 0 depois dele.
  • Apenas esse arquivo foi alterado na correção de estilização.
  • O aviso manteve seu cabeçalho em negrito de 14 pontos e montagem em negrito.
  • Todas as 4 declarações passaram no teste DOCX a partir do prompt de CSV.
  • Todos os 4 saldos finais coincidiram com os dados CSV.
  • Cada linha de fechamento tinha duas células, com o rótulo abrangendo duas colunas.
  • O título estava em negrito em 18 pontos.
  • A linha de cabeçalho estava em negrito.
  • As linhas alternavam FFFFFF e F2F2F2.
  • Os 3 testes do Copilot passaram.
  • Cada teste leu a tabela salva através de suas linhas e células.
  • O fluxo de trabalho de configuração foi analisado como YAML, com um trabalho de passos de configuração de copiloto e a verificação da chave por último.
  • A chamada de revisão não alterou nenhum arquivo e sinalizou dois locais no construtor. Um preenche as células da linha de fechamento antes de adicionar a linha, conforme especificado no arquivo específico do caminho. O outro usa TableCell.SetContent em vez de AddChild ou AddText.
  • Alguns passos foram executados de forma diferente da página. A sessão foi executada sem cabeça, então o modo de plano usou a flag --plan e a aprovação foi uma resposta digitada. O problema, o agente na nuvem, o segredo de Agentes e o fluxo de trabalho de configuração precisam de um repositório hospedado e não foram executados.

O guia do Cursor define seu regulamento do IronWord para padrões de arquivo com globs, assim como o arquivo de instruções específico do caminho faz aqui com applyTo. O guia do Google Antigravity publica uma página IronWord para linux-x64, a plataforma em que o agente na nuvem é executado.

A versão do Copilot CLI, o modelo escolhido por Auto, a máquina de teste e a duração da execução aparecem no registro de execução compartilhada.


Solução de problemas


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.

Leia Mais

Pronto para começar?

Downloads no NuGet 62,392Versão:2026.11recém-lançado