Comment utiliser IronWord avec GitHub Copilot
Un service .NET peut générer des relevés de compte mensuels sous forme de fichiers Word, chacun avec un titre stylisé, deux lignes récapitulatives et un tableau construit à partir de données. Dans ce guide, le service réside dans une solution Visual Studio aux côtés des travaux qui fournissent ses données, donc tout assistant qui le modifie doit fonctionner au sein de la même solution.
GitHub Copilot peut travailler sur cette solution depuis Visual Studio ou VS Code en mode chat ou agent, depuis un terminal avec Copilot CLI, et depuis GitHub, où son agent cloud ouvre une demande de tirage pour un problème qui lui est attribué. IronWord construit le DOCX en code, avec des exécutions de texte stylisées et des tableaux ayant des cellules fusionnées et des lignes ombrées. Les règles d'IronWord sont conservées dans des fichiers d'instructions dans le dépôt, et chacune de ces surfaces les lit.
Le guide des tableaux et le guide de style de texte couvrent les deux parties de l'API sur lesquelles ce guide repose.
Démarrage rapideDémarrez Copilot CLI depuis la racine de la solution et collez l'invite ci-dessous. Copilot Chat dans Visual Studio fait référence à un fichier avec #, tandis que le CLI utilise @.
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.
L'invite ne nomme aucun membre de style. Le fichier d'instructions spécifique au chemin ci-dessous spécifie les membres à utiliser.
Le Program.cs de la solution lit IRONWORD_LICENSE_KEY de l'environnement et l'assigne à IronWord.License.LicenseKey, alors définissez la variable avant de démarrer Copilot. Le guide des clés de licence montre le même affectation et les fichiers de configuration qui peuvent contenir la clé.
Flux de travail minimal (5 étapes)
- Téléchargez la bibliothèque C# Word depuis NuGet
- Écrivez les règles d'IronWord dans .github/copilot-instructions.md plus un fichier d'instructions spécifique au chemin
- Stylisez le texte sur les exécutions et ajoutez la ligne de fermeture fusionnée en tant que ligne distincte
- Rouvrez chaque relevé enregistré et comparez les cellules du tableau avec les données sources
- Attribuez le prochain changement à l'agent cloud en tant que problème et vérifiez la demande de tirage par rapport à la référence API d'IronWord
Comment définir les conventions IronWord pour Copilot ?
Les règles pour l'ensemble du dépôt se retrouvent dans .github/copilot-instructions.md. Copilot CLI, la révision de code Copilot, l'agent cloud et Copilot Chat dans les IDEs JetBrains, Visual Studio et VS Code lisent tous ce fichier, selon la matrice de support de GitHub. Visual Studio ne le charge qu'après que la case des instructions personnalisées a été sélectionnée dans ses options 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.
Comment donner ses propres règles au code du document ?
Les règles pour certains dossiers seulement se trouvent dans un fichier spécifique au chemin tel que .github/instructions/documents.instructions.md, dont les motifs applyTo ici couvrent le code de document et ses tests. La documentation CLI de GitHub pour Copilot dit que le CLI n'ajoute le fichier à une demande que lorsqu'un fichier qu'il gère correspond à un motif listé. Dans notre exécution, le CLI a listé les motifs et le chemin du fichier au début de chaque session, et Copilot a lu le fichier avant sa première modification.
---
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.
Chaque règle dans ce fichier est dérivée d'une construction, d'un contrôle en mémoire ou d'un fichier enregistré. La documentation XML livrée liste ApplyCellStyle sur la table, mais le compilateur rejette l'appel avec CS1061, donc le seul XML ne montre pas si un membre compile. Une sonde a montré qu'un remplissage paramétré via la propriété Shading d'une cellule n'était jamais écrit dans le fichier enregistré, tandis que Zebra écrivait un remplissage à chaque cellule.
Comment construire un tableau de relevés à partir de données CSV ?
Le code du relevé peut échouer à ce stade sans produire d'erreur. Dans les fichiers enregistrés, une ligne de fermeture fusionnée avec MergeCells contenait encore trois cellules simples, bien que le tableau ait enregistré la fusion en mémoire. Un titre défini à 18 points sans police a été enregistré sans taille. Seule une inspection du fichier enregistré détecte l'un ou l'autre problème.
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.
La fixture contient quatre comptes, avec cinq, deux, trois et zéro transactions. Dans le fichier CSV, les lignes du compte épargne ne sont pas par ordre de date, et la présentation nécessite le plus ancien en premier.
Comment tester un relevé IronWord enregistré ?
ExtractText sur le document a retourné ses paragraphes mais aucun texte de tableau, donc un test basé là-dessus passe même si chaque cellule est vide.
Passez Copilot CLI en mode plan avec Shift+Tab avant d'envoyer cette invite.
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.
Avec un plan d'abord, vous pouvez vérifier comment la suite lit une cellule fusionnée et le style d'une exécution avant que toute assertion ne soit écrite.
Comment corriger du code de style IronWord qui ne compile pas ?
Le guide des tableaux d'IronWord stylise le texte d'une cellule avec un initialiseur d'objet sur TextContent. Cet échantillon échoue à construire avec CS0200 parce que ces propriétés sont en lecture seule.
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.
Le compilateur rapporte des erreurs sur l'en-tête et le montant, et la recherche XML liste les membres TextStyle que la correction utilise à la place.
Qu'est-ce qui rend un problème sur lequel l'agent cloud peut agir ?
L'agent cloud fonctionne à partir du titre, de la description et des commentaires existants du problème, plus toutes instructions fournies lors de l'attribution. Selon GitHub, les commentaires ajoutés plus tard ne sont jamais transmis à l'agent, donc les critères de complétion appartiennent au corps du problème.
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.
Parce que le test compte les cellules colorées dans une déclaration connue, un changement qui colore toute la colonne échoue.
Pourquoi les tests de l'agent cloud échouent-ils sur un projet IronWord ?
Par défaut, l'agent cloud travaille dans un environnement Ubuntu Linux. IronWord 2026.10.4 livre une bibliothèque native pour linux-x64 à l'intérieur du package, donc un restauration NuGet sur le coureur l'inclut. Le coureur n'a pas de clé de licence. Sur une machine de test sans clé, la déclaration construite en mémoire sans erreur, et chaque appel d'enregistrement dans la sonde a lancé une LicensingException dont le message disait "Licence de production requise". Chaque test qui écrit un fichier échoue même lorsque le code est correct.
Avant que Copilot ne commence à travailler, GitHub Actions exécute le job copilot-setup-steps depuis .github/workflows/copilot-setup-steps.yml. Le flux de travail n'est pas déclenché tant que la branche par défaut ne contient pas ce fichier.
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.
Avec le contrôle placé en dernier, un secret manquant laisse toujours une solution restaurée et compilée, plus une ligne qui identifie le problème.
Stockez la clé en tant que secret Agents : les secrets enregistrés pour Actions, Codespaces ou Dependabot ne sont pas transmis à l'agent cloud. Ajoutez IRONWORD_LICENSE_KEY dans les Paramètres du dépôt sous Sécurité, Secrets et variables, Agents, et l'agent la reçoit comme une variable d'environnement.
Que faut-il vérifier avant de fusionner ?
Commencez la revue par son propre appel copilot -p, donc il s'exécute dans une session différente de celle qui a écrit le code.
/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'est-ce que les messages ont produit lors d'une réelle exécution ?
Copilot CLI a exécuté les six invites non assistées sur une solution de relevé construite pour ce guide. Nous avons reconstruit chaque commit, relancé le travail et les tests, et lu les fichiers DOCX avec un script qui n'utilise pas IronWord.
- Le fichier de notification du coéquipier a causé 3 erreurs de construction CS0200 avant l'invite de style et 0 après.
- Seul ce fichier a changé dans la correction de style.
- La notification a conservé son en-tête gras de 14 points et son montant en gras.
- Les 4 relevés ont passé la vérification DOCX à partir de l'invite CSV.
- Les 4 soldes de clôture correspondent aux données CSV.
- Chaque ligne de clôture avait deux cellules, avec l'étiquette s'étendant sur deux colonnes.
- Le titre était en gras à 18 points.
- La ligne d'en-tête était en gras.
- Les lignes alternaient FFFFFF et F2F2F2.
- Les 3 tests de Copilot ont réussi.
- Chaque test a lu le tableau enregistré à travers ses lignes et ses cellules.
- Le flux de travail de configuration a été analysé en tant que YAML, avec un job copilot-setup-steps et le contrôle de la clé en dernier.
- L'appel de révision n'a changé aucun fichier et a signalé deux endroits dans le générateur. L'un remplit les cellules de la ligne de clôture avant d'ajouter la ligne, comme le fichier spécifique au chemin le spécifie. L'autre utilise TableCell.SetContent au lieu d'AddChild ou AddText.
- Certaines étapes ont été exécutées différemment de la page. La session a été exécutée sans interface graphique, donc le mode plan a utilisé le drapeau --plan et l'approbation était une réponse tapée. Le problème, l'agent cloud, le secret Agents et le flux de travail de configuration ont besoin d'un dépôt hébergé et ne se sont pas exécutés.
Le guide de Cursor restreint sa règle IronWord aux motifs de fichiers avec des globs, comme le fait ici le fichier d'instructions spécifique au chemin avec applyTo. Le guide Google Antigravity publie une page IronWord pour linux-x64, la plate-forme sur laquelle l'agent cloud fonctionne.
La version de Copilot CLI, le modèle qu'Auto a choisi, la machine de test et la durée d'exécution apparaissent dans le rapport de course partagé.
Dépannage
- Ajouter un tableau au DOCX pour les lignes, les cellules, les bordures et l'ombrage
- Styliser le texte dans un DOCX pour les polices, les tailles et le texte en gras
- Extraire le texte du DOCX pour le texte du paragraphe et l'extraction par cellule des tableaux
- Appliquer des clés de licence pour définir la clé depuis le code, Web.config ou appsettings.json
- IronWord dans Docker pour les coureurs Linux et les conteneurs
Des questions ?
Si vous avez des questions, contactez support@ironsoftware.com
Curtis Chau détient un baccalauréat en informatique (Université de Carleton) et se spécialise dans le développement front-end avec expertise en Node.js, TypeScript, JavaScript et React. Passionné par la création d'interfaces utilisateur intuitives et esthétiquement plaisantes, Curtis aime travailler avec des frameworks modernes et créer des manuels bien structurés et visuellement attrayants.