Cómo usar IronWord con GitHub Copilot
Un servicio .NET puede generar estados de cuenta mensuales como archivos Word, cada uno con un título estilizado, dos líneas de resumen y una tabla construida a partir de datos. En esta guía, el servicio reside en una solución de Visual Studio junto con los trabajos que suministran sus datos, por lo que cualquier asistente que lo modifique debe trabajar dentro de la misma solución.
GitHub Copilot puede trabajar en esa solución desde Visual Studio o VS Code en modo chat o agente, desde un terminal con Copilot CLI, y desde GitHub, donde su agente en la nube abre un pull request para un problema asignado a él. IronWord construye el DOCX en el código, con ejecuciones de texto estilizadas y tablas que tienen celdas combinadas y filas sombreadas. Las reglas de IronWord se mantienen en archivos de instrucciones en el repositorio, y cada una de esas superficies las lee.
La guía de tablas y la guía de estilo de texto cubren las dos partes de la API en las que se basa esta guía.
Inicio rápidoInicie Copilot CLI desde la raíz de la solución y pegue el mensaje a continuación. Copilot Chat en Visual Studio hace referencia a un archivo con #, mientras que el CLI utiliza @.
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.
El mensaje no nombra a ningún miembro de estilo. El archivo de instrucciones específico de la ruta a continuación especifica los miembros a utilizar.
El Program.cs de la solución lee IRONWORD_LICENSE_KEY del entorno y lo asigna a IronWord.License.LicenseKey, así que establezca la variable antes de iniciar Copilot. La guía de claves de licencia muestra la misma asignación y los archivos de configuración que pueden contener la clave.
Flujo de trabajo mínimo (5 pasos)
- Descarga la biblioteca de Word de C# desde NuGet
- Escriba las reglas de IronWord en .github/copilot-instructions.md más un archivo de instrucciones específico de ruta
- Estilice texto en ejecuciones y añada la fila de cierre combinada como una fila separada
- Reabra cada estado guardado y compare sus celdas de tabla con los datos fuente
- Asigne el siguiente cambio al agente en la nube como un problema y verifique la pull request contra la referencia de la API de IronWord
¿Cómo establece las convenciones de IronWord para Copilot?
Las reglas para todo el repositorio van en .github/copilot-instructions.md. Copilot CLI, revisión de código de Copilot, el agente en la nube y Copilot Chat en JetBrains IDEs, Visual Studio y VS Code todos leen ese archivo, según la matriz de soporte de GitHub. Visual Studio lo carga solo después de que se selecciona la casilla de verificación de instrucciones personalizadas en sus opciones de 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.
¿Cómo le da al código del documento sus propias reglas?
Las reglas para algunos carpetas van solo en un archivo específico de ruta como .github/instructions/documents.instructions.md, cuyos patrones applyTo aquí cubren el código del documento y sus pruebas. La documentación del CLI de GitHub dice que el CLI agrega el archivo a una solicitud solo cuando un archivo que está manejando coincide con un patrón listado. En nuestra ejecución, el CLI enumeró los patrones y la ruta del archivo al comienzo de cada sesión, y Copilot leyó el archivo antes de su primera edición.
---
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.
Cada regla en ese archivo se deriva de una compilación, una verificación en memoria o un archivo guardado. La documentación XML enviada enumera ApplyCellStyle en la tabla, pero el compilador rechaza la llamada con CS1061, por lo que el XML solo no muestra si un miembro compila. Una prueba mostró que un relleno establecido a través de la propiedad Shading de una celda nunca se escribió en el archivo guardado, mientras que Zebra escribió un relleno en cada celda.
¿Cómo se construye una tabla de estados a partir de datos CSV?
El código del estado puede fallar en esta etapa sin producir un error. En los archivos guardados, una fila de cierre combinada con MergeCells todavía contenía tres celdas simples, aunque la tabla registró la combinación en memoria. Un título configurado a 18 puntos sin fuente se guardó sin tamaño. Solo una inspección del archivo guardado detecta cualquiera de los problemas.
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.
El fixture contiene cuatro cuentas, con cinco, dos, tres y cero transacciones. En el archivo CSV, las filas de la cuenta de ahorros no están en orden de fecha, y el diseño requiere que la más antigua esté primero.
¿Cómo se prueba un estado de IronWord guardado?
ExtractText en el documento devolvió sus párrafos pero ninguno del texto de la tabla, por lo que una prueba basada en él pasa incluso cuando cada celda está vacía.
Cambie Copilot CLI al modo plan con Shift+Tab antes de enviar este mensaje.
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.
Con un plan primero, puede verificar cómo la suite lee una celda combinada y el estilo de una ejecución antes de que se escriba cualquier afirmación.
¿Cómo se corrige el código de estilo de IronWord que no compila?
La guía de tablas de IronWord estiliza el texto de una celda con un inicializador de objeto en TextContent. Esa muestra no logra compilar con CS0200 porque esas propiedades son de solo lectura.
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.
El compilador informa errores en el encabezado y el monto, y la búsqueda XML enumera los miembros TextStyle que el arreglo utiliza en su lugar.
¿Qué hace que un problema sea en el que el agente de la nube pueda actuar?
El agente en la nube trabaja a partir del título del problema, la descripción y los comentarios existentes, además de cualquier instrucción proporcionada al asignarlo. Según GitHub, los comentarios añadidos después nunca se pasan al agente, por lo que los criterios de finalización pertenecen al cuerpo del 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.
Debido a que la prueba cuenta las celdas coloreadas en un estado conocido, un cambio que colorea toda la columna falla.
¿Por qué fallan las pruebas del agente en la nube en un proyecto de IronWord?
Por defecto, el agente en la nube trabaja en un entorno Linux Ubuntu. IronWord 2026.10.4 envía una biblioteca nativa para linux-x64 dentro del paquete, por lo que una restauración de NuGet en el runner la incluye. El runner no tiene clave de licencia. En una máquina de prueba sin clave, el estado construido en memoria sin error, y cada llamada de guardado en la prueba lanzó una LicensingException cuyo mensaje decía "Licencia de producción requerida". Cada prueba que escribe un archivo falla incluso cuando el código es correcto.
Antes de que Copilot comience a trabajar, GitHub Actions ejecuta el trabajo copilot-setup-steps de .github/workflows/copilot-setup-steps.yml. El flujo de trabajo no se activa hasta que la rama predeterminada contenga ese archivo.
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.
Con la verificación colocada al final, un secreto faltante aún deja una solución restaurada y compilada, además de una línea que identifica el problema.
Guarde la clave como un secreto de Agents: los secretos guardados para Actions, Codespaces o Dependabot no se pasan al agente en la nube. Agregue IRONWORD_LICENSE_KEY en la Configuración del repositorio bajo Seguridad, Secretos y variables, Agents, y el agente lo recibe como una variable de entorno.
¿Qué debes verificar antes de fusionar?
Inicie la revisión con su propia llamada copilot -p, para que se ejecute en una sesión diferente a la que escribió el 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.
¿Qué produjeron los prompts en una ejecución real?
Copilot CLI ejecutó los seis mensajes sin supervisión en una solución de declaración construida para esta guía. Reconstruimos cada commit, volvimos a ejecutar el trabajo y las pruebas, y leímos los archivos DOCX con un script que no usa IronWord.
- El archivo de aviso del compañero causó 3 errores de compilación CS0200 antes del mensaje de estilo y 0 después.
- Solo ese archivo cambió en la corrección del estilo.
- El aviso mantuvo su encabezado en negrita de 14 puntos y el monto en negrita.
- Los 4 estados pasaron la verificación DOCX desde el mensaje CSV en adelante.
- Los 4 saldos de cierre coincidieron con los datos CSV.
- Cada fila de cierre tenía dos celdas, con la etiqueta abarcando dos columnas.
- El título estaba en negrita a 18 puntos.
- La fila del encabezado estaba en negrita.
- Las filas alternaban FFFFFF y F2F2F2.
- Las 3 pruebas de Copilot pasaron.
- Cada prueba leyó la tabla guardada a través de sus filas y celdas.
- El flujo de trabajo de configuración se analizó como YAML, con un trabajo de copilot-setup-steps y la verificación de clave al final.
- La llamada de revisión no cambió ningún archivo y señaló dos lugares en el constructor. Uno llena las celdas de la fila de cierre antes de agregar la fila, como especifica el archivo específico de ruta. El otro usa TableCell.SetContent en lugar de AddChild o AddText.
- Algunos pasos se ejecutaron de manera diferente a lo esperado. La sesión se ejecutó sin cabeza, por lo que el modo plan usó la bandera --plan y la aprobación fue una respuesta escrita. El problema, agente en la nube, secreto de Agents y flujo de trabajo de configuración necesitan un repositorio alojado y no se ejecutaron.
La guía de Cursor delimita su regla de IronWord a patrones de archivo con comodines, como lo hace el archivo de instrucciones específico de la ruta aquí con applyTo. La guía de Google Antigravity publica una página de IronWord para linux-x64, la plataforma en la que se ejecuta el agente en la nube.
La versión de Copilot CLI, el modelo que Auto eligió, la máquina de prueba y la duración de la ejecución aparecen en el registro de ejecución compartido.
Solución de problemas
- Agregar Tabla a DOCX para filas, celdas, bordes y sombreado
- Estilo de Texto en DOCX para fuentes, tamaños y texto en negrita
- Extraer Texto de DOCX para texto de párrafos y extracción por celda de las tablas
- Aplicación de Claves de Licencia para establecer la clave desde el código, Web.config o appsettings.json
- IronWord en Docker para runners y contenedores en Linux
¿Preguntas?
Si tienes alguna pregunta, contacta a support@ironsoftware.com
Curtis Chau tiene una licenciatura en Ciencias de la Computación (Carleton University) y se especializa en el desarrollo front-end con experiencia en Node.js, TypeScript, JavaScript y React. Apasionado por crear interfaces de usuario intuitivas y estéticamente agradables, disfruta trabajando con frameworks modernos y creando manuales bien estructurados y visualmente atractivos.