Wie man IronWord mit GitHub Copilot verwendet

Curtis Chau
Curtis Chau
Aktualisiert: 19. Oktober 2026

Ein .NET-Dienst kann monatliche Kontoauszüge als Word-Dateien generieren, jede mit einem stilvollen Titel, zwei Zusammenfassungszeilen und einer aus Daten erstellten Tabelle. In diesem Leitfaden befindet sich der Dienst in einer Visual Studio-Lösung neben den Jobs, die seine Daten liefern, sodass jeder Assistent, der ihn verändert, innerhalb derselben Lösung arbeiten muss.

GitHub Copilot kann an dieser Lösung aus Visual Studio oder VS Code im Chat- oder Agentenmodus arbeiten, aus einem Terminal mit Copilot CLI und aus GitHub, wo dessen Cloud-Agent einen Pull-Request für ein ihm zugewiesenes Problem öffnet. IronWord erstellt den DOCX im Code, mit stilisierten Textläufen und Tabellen, die zusammengeführte Zellen und schattierte Zeilen haben. Die IronWord-Regeln werden in Anweisungsdateien im Repository gespeichert, und jede dieser Oberflächen liest sie.

Die Tabellenanleitung und die Textstil-Anleitung decken die zwei Teile der API ab, auf die sich dieser Leitfaden stützt.

Schnellstart
NuGetMit NuGet installieren

PM > Install-Package IronWord

Installieren Sie IronWord, indem Sie den obigen Befehl in der NuGet Packet Manager-Konsole ausführen, oder suchen Sie das Paket im NuGet Paket Manager.

Starten Sie Copilot CLI vom Stammverzeichnis der Lösung aus und fügen Sie den unten stehenden Prompt ein. Copilot Chat in Visual Studio referenziert eine Datei mit #, während die CLI @ verwendet.

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

Der Prompt nennt kein Styling-Mitglied. Die unten stehende pfadspezifische Anweisungsdatei spezifiziert die zu verwendenden Mitglieder.

Das Program.cs der Lösung liest IRONWORD_LICENSE_KEY aus der Umgebung und weist es IronWord.License.LicenseKey zu, daher setzen Sie die Variable, bevor Sie Copilot starten. Der Lizenzschlüssel-Leitfaden zeigt dieselbe Zuordnung und die Konfigurationsdateien, die den Schlüssel halten können.



Wie setzen Sie IronWord-Konventionen für Copilot?

Regeln für das gesamte Repository gehören in .github/copilot-instructions.md. Copilot CLI, Copilot-Codeüberprüfung, der Cloud-Agent und Copilot Chat in JetBrains IDEs, Visual Studio und VS Code lesen alle diese Datei, entsprechend GitHubs Support-Matrix. Visual Studio lädt es erst, nachdem das benutzerdefinierte Anweisungen-Kontrollkästchen in seinen Copilot Chat-Optionen ausgewählt ist.

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

Wie geben Sie dem Dokumenten-Code eigene Regeln?

Regeln nur für einige Ordner gehören in eine pfadspezifische Datei wie .github/instructions/documents.instructions.md, deren applyTo-Muster hier den Dokumenten-Code und seine Tests abdecken. Die Dokumentation des GitHub Copilot CLI sagt, dass die CLI die Datei nur zu einer Anfrage hinzufügt, wenn eine Datei, die sie verarbeitet, einem aufgelisteten Muster entspricht. In unserem Lauf listete die CLI die Muster und den Pfad der Datei am Anfang jeder Sitzung auf, und Copilot las die Datei vor seiner ersten Bearbeitung.

---
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

Jede Regel in dieser Datei wird aus einem Build, einem In-Memory-Check oder einer gespeicherten Datei abgeleitet. Die ausgelieferte XML-Dokumentation listet ApplyCellStyle in der Tabelle auf, aber der Compiler lehnt den Aufruf mit CS1061 ab, sodass das XML allein nicht zeigt, ob ein Mitglied kompiliert. Eine Untersuchung zeigte, dass ein Füllen über die Shading-Eigenschaft einer Zelle nie in die gespeicherte Datei geschrieben wurde, während Zebra ein Füllen in jede Zelle schrieb.

Wie bauen Sie eine Auszugstabelle aus CSV-Daten auf?

Der Auszugscode kann in diesem Stadium ohne Fehlermeldung scheitern. In den gespeicherten Dateien enthielt eine mit MergeCells zusammengeführte Abschlusszeile immer noch drei einfache Zellen, obwohl die Tabelle das Zusammenführen im Speicher aufzeichnete. Ein Titel, der auf 18 Punkt ohne Schriftart gesetzt ist, wurde ohne Größe gespeichert. Nur eine Inspektion der gespeicherten Datei entdeckt eines der Probleme.

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

Die Ausstattung enthält vier Konten mit fünf, zwei, drei und null Transaktionen. In der CSV-Datei sind die Zeilen des Sparkontos nicht in Datumssortierung, und das Layout erfordert das älteste zuerst.

Wie testen Sie eine gespeicherte IronWord-Aussage?

ExtractText auf dem Dokument gab seine Absätze zurück, aber keinen der Tabellen-Text, sodass ein darauf basierender Test besteht, auch wenn jede Zelle leer ist.

Schalten Sie Copilot CLI mit Shift+Tab in den Planmodus, bevor Sie diesen Prompt senden.

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

Mit einem Plan zuerst können Sie überprüfen, wie die Suite vor einer Behauptung einen zusammengeführten Zellenlauf und den Stil eines Laufes liest.

Wie beheben Sie nicht kompilierenden IronWord-Stilecode?

IronWords Tabellenanleitung stilisiert den Text einer Zelle mit einem Objektinitialisierer auf TextContent. Dieses Beispiel schlägt mit CS0200 fehl, da diese Eigenschaften schreibgeschützt sind.

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

Der Compiler meldet Fehler auf den Überschrift und die Menge, und das XML-Lookup listet die TextStyle-Mitglieder auf, die die Lösung stattdessen verwendet.

Was macht ein Problem aus, auf das der Cloud-Agent reagieren kann?

Der Cloud-Agent arbeitet aus dem Titel, der Beschreibung und den vorhandenen Kommentaren eines Problems, plus allen bei der Zuweisung bereitgestellten Anweisungen. Gemäß GitHub werden später hinzugefügte Kommentare niemals an den Agenten weitergegeben, daher gehören die Abschließkriterien in den Problembeschreibungstext.

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

Da der Test gefärbte Zellen in einer bekannten Aussage zählt, schlägt eine Änderung, die die gesamte Spalte färbt, fehl.

Warum scheitern die Cloud-Agent-Tests bei einem IronWord-Projekt?

Standardmäßig arbeitet der Cloud-Agent in einer Ubuntu Linux-Umgebung. IronWord 2026.10.4 liefert eine native Bibliothek für linux-x64 innerhalb des Pakets, daher ist sie bei einer NuGet-Wiederherstellung auf dem Runner enthalten. Der Runner hat keinen Lizenzschlüssel. Auf einer Testmaschine ohne Schlüssel baute die Aussage im Speicher ohne Fehler, und jeder Speicherruf in der Untersuchung warf eine LicensingException, deren Nachricht "Produktionslizenz erforderlich" lautete. Jeder Test, der eine Datei schreibt, schlägt fehl, selbst wenn der Code korrekt ist.

Bevor Copilot mit der Arbeit beginnt, führt GitHub Actions den copilot-setup-steps-Job aus .github/workflows/copilot-setup-steps.yml aus. Der Workflow wird nicht ausgelöst, bis der Standardbranch diese Datei enthält.

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

Mit der zuletzt platzierten Prüfung hinterlässt ein fehlendes Geheimnis immer noch eine wiederhergestellte und kompilierte Lösung, plus eine Zeile, die das Problem identifiziert.

Speichern Sie den Schlüssel als ein Agents-Geheimnis: Geheimnisse, die für Actions, Codespaces oder Dependabot gespeichert sind, werden nicht an den Cloud-Agenten weitergegeben. Fügen Sie IRONWORD_LICENSE_KEY in den Einstellungen des Repositorys unter Sicherheit, Geheimnisse und Variablen, Agents, hinzu, und der Agent erhält es als Umgebungsvariable.

Was sollten Sie prüfen, bevor Sie zusammenführen?

Starten Sie die Überprüfung mit ihrem eigenen copilot -p-Aufruf, sodass sie in einer anderen Sitzung läuft als die, die den Code geschrieben hat.

/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

Was haben die Aufforderungen in einem realen Lauf erzeugt?

Copilot CLI führte alle sechs Prompts unbeaufsichtigt auf einer für diesen Leitfaden gebauten Statement-Lösung aus. Wir bauten jedes Commit neu, führten den Job und die Tests erneut durch und lasen die DOCX-Dateien mit einem Skript, das IronWord nicht verwendet.

  • Die Mitteilungsdatei des Teamkollegen verursachte 3 CS0200 Build-Fehler vor dem Styling-Prompt und 0 danach.
  • Nur diese Datei änderte sich in der Styling-Korrektur.
  • Die Mitteilung behielt ihre fette 14 Punkt Überschrift und fette Menge.
  • Alle 4 Aussagen bestanden den DOCX-Check ab dem CSV-Prompt.
  • Alle 4 Abschlussbilanzen stimmten mit den CSV-Daten überein.
  • Jede Abschlusszeile hatte zwei Zellen, mit dem Etikett über zwei Spalten gespannt.
  • Der Titel war fett bei 18 Punkt.
  • Die Überschriftszeile war fett.
  • Zeilen wechselten zwischen FFFFFF und F2F2F2.
  • Copilots 3 Tests bestanden.
  • Jeder Test las die gespeicherte Tabelle durch ihre Reihen und Zellen.
  • Der Setup-Workflow wurde als YAML geparst, mit einem copilot-setup-steps-Job und dem Schlüssel-Check zuletzt.
  • Der Überprüfungsaufruf änderte keine Datei und markierte zwei Stellen im Builder. Einer füllt die Zellen der Abschlusszeile, bevor die Zeile hinzugefügt wird, wie es die pfadspezifische Datei spezifiziert. Der andere verwendet TableCell.SetContent anstelle von AddChild oder AddText.
  • Einige Schritte liefen anders als die Seite. Die Sitzung lief kopflos, also benutzte der Planmodus das --plan-Flag, und die Genehmigung war eine getippte Antwort. Das Problem, der Cloud-Agent, das Agents-Geheimnis und der Setup-Workflow benötigen ein gehostetes Repository und wurden nicht ausgeführt.

Die Cursor-Anleitung beschränkt ihre IronWord-Regel auf Dateimuster mit Globs, wie es die pfadspezifische Anweisungsdatei hier mit applyTo tut. Die Google Antigravity-Anleitung veröffentlicht eine IronWord-Seite für linux-x64, die Plattform, auf der der Cloud-Agent läuft.

Die Copilot CLI-Version, das Modell, das Auto gewählt hat, die Testmaschine und die Dauer des Laufs erscheinen im gemeinsamen Laufprotokoll.


Fehlerbehebung


Fragen?

Wenn Sie Fragen haben, wenden Sie sich an support@ironsoftware.com.

Curtis Chau hat einen Bachelor-Abschluss in Informatik von der Carleton University und ist spezialisiert auf Frontend-Entwicklung mit Expertise in Node.js, TypeScript, JavaScript und React. Leidenschaftlich widmet er sich der Erstellung intuitiver und ästhetisch ansprechender Benutzerschnittstellen und arbeitet gerne mit modernen Frameworks sowie der Erstellung gut strukturierter, optisch ansprechender Handbücher.

Mehr lesen

Bereit loszulegen?

NuGet-Downloads 62,392Version:2026.11gerade veröffentlicht