Wie Sie IronWord mit Cursor verwenden
Das Beispielrepository für diese Anleitung liest Lieferantenformulare mit OpenXML SDK-Code, der über Körperelemente iteriert und InnerText liest. Die Umstellung auf IronWord durch das Parsen jedes beschrifteten Werts aus einem Block extrahierten Textes mit einem regulären Ausdruck schlägt fehl. Bei der Kalibrierung hat diese Version 3 von 12 Formularen korrekt gelesen, indem sie fünf Registrierungsnummern mit dem folgenden Etikett verbunden hat und für die vier Tabellenformulare keine Registrierungsnummer zurückgibt.
Cursor basiert auf dem Code von VS Code und bietet ein Agentenmodul neben dem Editor. Zwei seiner Funktionen, die Dokumentationslinks, die der Agent liest, und die Projektrichtlinien, die in .cursor/rules gespeichert sind, bestimmen, ob er IronWord-Code oder Code, der dem OpenXML-Lesemuster folgt, erzeugt. Beide Funktionen erscheinen unten in einem Onboarding-Dienst für Lieferanten, der die von Lieferanten zurückgegebenen DOCX-Formulare liest. Der Dienst extrahiert den Lieferantennamen, die Registrierungsnummer, die Preistablens, und die eingebetteten Logo- und Unterschriftenbilder, und sein Leser wechselt vom OpenXML SDK zu IronWord.
Einzelheiten zu IronWords Lesemethoden finden Sie im Textextraktionsleitfaden und im Bildextraktionsleitfaden.
SchnellstartÖffnen Sie das Repository für die Lieferantenaufnahme und fügen Sie diese Eingabeaufforderung in einen neuen Agent-Chat ein.
@src/SupplierIntake/ @TestData/forms/
Don't write anything until you've fetched https://ironsoftware.com/word/csharp/llms.txt.
Read the extract text and extract images pages it links as well.
Then give Program.cs a dump command that opens one form with IronWord:
`dotnet run --project src/SupplierIntake -- dump <file.docx>`
Have the dump print what IronWord returns for that form:
- The ExtractText result, in quotes.
- Every entry of Paragraphs, with its index.
- Every table cell, with its table, row and column numbers.
- Each extracted image's Width and Height, and the pixel size of the AnyBitmap behind it.
The program should read IRONWORD_LICENSE_KEY itself when it's set.
At startup, assign the key to License.LicenseKey.
Never print the key, and keep environment variables out of the output.
Leave Forms/FormReader.cs and its DocumentFormat.OpenXml reference as they are.
Run the dump on TestData/forms/form-03.docx and show me the output.
Geben Sie den Lizenzschlüssel nicht in einem Chat ein. Der Agent bearbeitet Dateien und führt Shell-Befehle aus, sodass ein eingefügter Schlüssel in jeder Datei, Commit-Nachricht und Build-Log, die er schreibt, exponiert ist. In unseren Tests öffnete und las IronWord jedes Formular ohne einen Schlüssel und warf eine LicensingException nur beim Speichern eines Dokuments. Der Lizenzschlüssel-Leitfaden zeigt, wie man den Schlüssel im Code, in Web.config oder in appsettings.json setzt.
Minimaler Arbeitsablauf (5 Schritte)
- Laden Sie die C# Word-Bibliothek von NuGet herunter
- Fügen Sie unter .cursor/rules eine Projektrichtlinie hinzu, die den Link zur IronWord-Dokumentation enthält.
- Dokumentieren Sie in der Richtlinie, was
ExtractTextauslässt. - Beziehen Sie sich in jeder Anfrage sowohl auf die Leserdatei als auch auf einen Ordner mit zurückgegebenen Formularen.
- Vergleichen Sie jeden extrahierten Wert mit einer bekannten Liste und bestätigen Sie dann jeden Mitgliedsnamen in der API Referenz.
Welches Cursor-Modell sollten Sie für IronWord-Arbeiten verwenden?
Composer ist Cursors eigenes agentisches Modell. Der Modellwähler bietet auch die Grok-Modelle von SpaceXAI, die Cursor mitentwickelt hat, sowie Modelle von OpenAI, Anthropic, Google und anderen Laboren. Der untenstehende Testrun verwendete Grok 4.7.
Wie geben Sie Cursor die IronWord-Dokumentation?
Fügen Sie den Link zur IronWord-Dokumentation in die Anfrage ein oder speichern Sie ihn in einer vom gesamten Team gemeinsam genutzten Regel. IronWords llms.txt listet jeden Leitfaden und die API-Referenz auf, und llms-full.txt fasst 46 Dokumentationsseiten in einer einzigen Datei zusammen. Ab Oktober 2026 fügt Cursor's @-Menü Dateien, Ordner, Terminals, Chats, Git-Diffs und den Browser bei, sodass die IronWord-Dokumentation als Link an den Agenten gelangt.
Der Quickstart-Dump zeigt zwei Verhaltensweisen, die der Extraktionstext-Leitfaden nicht angibt. Für form-03 gab ExtractText die Absätze des Haupttextes in einem einzigen Zeichenfolgen zurück und ließ alle Texte in den zwei Tabellen des Formulars aus.
@src/SupplierIntake/Forms/RegistrationCheck.cs
Answer five questions about IronWord, without editing any files:
1. Does WordDocument.ExtractText include text from table cells?
2. What does it put between paragraphs?
3. Does the Paragraphs collection list the paragraphs inside table cells?
4. What does ExtractImages return, and what element type does the list hold?
5. What unit do the Width and Height of each result use?
Use the documentation at https://ironsoftware.com/word/csharp/llms.txt as your source.
The project rule doesn't count as one.
Check your answers against the form-03 dump from the last turn, where it shows them.
Cite the page each answer comes from.
Where no page states it, say the answer is measured, not documented.
Wie schreiben Sie Projektrichtlinien, die Ihre IronWord-Konventionen kodieren?
Eine Projektrichtlinie ist eine .mdc-Datei, die in .cursor/rules gespeichert und mit dem Repository versioniert wird, sodass jeder Klon sie enthält. Cursor ignoriert einfache .md-Dateien in diesem Ordner, da es ohne Frontmatter nicht bestimmen kann, wann sie geladen werden sollen.
Die unten stehende Regel definiert globs und setzt alwaysApply auf falsch. Cursor lädt sie, wann immer eine Anfrage einen Formularleser oder eine Testdatei enthält, und lässt sie andererseits weg. Speichern Sie sie als .cursor/rules/ironword-forms.mdc.
---
description: IronWord conventions for reading supplier forms
globs: src/SupplierIntake/Forms/**/*.cs, tests/**/*.cs
alwaysApply: false
---
Read and write DOCX files with IronWord only, under these package rules:
- The NuGet package is IronWord.
- Its types come from two namespaces, IronWord and IronWord.Models.
- AnyBitmap comes from IronSoftware.Drawing.
- Don't add DocX, NPOI or any other DOCX package.
- Add no new DocumentFormat.OpenXml code.
- The documentation index is https://ironsoftware.com/word/csharp/llms.txt
Keep license keys out of the code, and handle the key this way:
- Read it at run time from an environment variable named IRONWORD_LICENSE_KEY.
- Never print it.
WordDocument.ExtractText leaves out table cells and runs paragraphs together with no separator.
Use the paragraph and table collections instead:
- Read labeled values one paragraph at a time from doc.Paragraphs.
- Read tables through doc.Tables, Rows and Cells.
- doc.Paragraphs also returns the paragraphs inside table cells.
Table.Rows returns ITableRow, and a row's Cells returns ITableCell.
Two casts are needed:
- Cast a row to TableRow before you pass it to a method that takes a TableRow.
- Cast a cell to TableCell before you call ExtractText on it.
Don't invent IronWord members.
When you're unsure of one, say so and name the page you checked.
Cursor's Regel-Seite besagt, dass Regeln Tab nicht beeinflussen und dass Benutzerrichtlinien nicht auf Inline-Änderungen angewendet werden, sodass Tab- und Inline-Editier-Vorschläge gegen die Richtlinie manuell überprüft werden müssen.
Wie kartieren Sie OpenXML SDK-Aufrufe auf IronWord?
Die Anweisung an das Modell, IronWord zu verwenden, sagt ihm nicht, welcher IronWord-Aufruf welchen OpenXML SDK-Aufruf ersetzt. Eine Tabelle der Gleichwertigkeiten bietet diese Zuordnung.
| OpenXML SDK | IronWord |
|---|---|
WordprocessingDocument.Open | Der WordDocument-Konstruktor, von einem Pfad, Bytes oder einem Stream aus |
| Absatzkörper und ihr innerer Text | Paragraphs, mit ExtractText auf jedem |
| Tabellenkörper, -reihen und -zellen | Tables, Rows und Cells |
| Blip-Elemente und Bildparttröme | ExtractImages, gespeichert über AnyBitmap |
Zwei Zeilen verhalten sich anders als der SDK-Code, den sie ersetzen. Die Absatzliste hält die Absätze innerhalb der Tabellenzellen sowie die Absatzkörper, sodass form-03 15 Einträge zurückgibt, wo der OpenXML SDK-Leser über 5 Absatzkörper iterierte. Die Zellen werden als ITableCell zurückgegeben, die keine Textmethode hat, sodass ein Aufruf ohne den Cast mit CS1061 fehlschlägt.
IronWord verweist nicht auf das DocumentFormat.OpenXml Paket, und ein Projekt, das sowohl IronWord 2026.10.4 als auch DocumentFormat.OpenXml 3.5.1 referenziert, baut und läuft. Die Migration kann daher jeweils ein Leser nacheinander erfolgen. Die Seite zu OpenXML-Konflikten behandelt IronWord-Entwicklungen älter als 2025.7.13.
Diese Zeilen am Ende der Richtlinie hinzuzufügen, fügt die Tabelle jeder Anfrage hinzu, die die Richtlinie lädt.
Translate OpenXML SDK code instead of porting it, with these equivalents:
- WordprocessingDocument.Open becomes new WordDocument(path).
- Body.Elements<Table>() becomes doc.Tables.
- Counting Blip elements becomes doc.ExtractImages().Count.
Save extracted images with ((AnyBitmap)image.Image).SaveAs(path).
Wie planen und führen Sie eine Migration zu IronWord durch?
Drücken Sie Shift+Tab im Chat-Eingabefeld, bis der Planmodus ausgewählt ist, und senden Sie dann die folgende Anfrage. Cursor schreibt seinen Plan in eine bearbeitbare Datei.
@src/SupplierIntake/Forms/ @TestData/forms/expected.csv
Plan the move of FormReader to IronWord so the project can drop DocumentFormat.OpenXml.
Write no code until I approve.
FormReader still reads supplier forms with the OpenXML SDK.
RegistrationCheck already uses IronWord, and the team wants a single DOCX library.
The plan has to cover these points:
- Every OpenXML SDK call, with its IronWord replacement and the file where the call lives.
- How the reader will find the price table.
- How it will find a registration number inside a table.
Keep SupplierForm and the public Read and SaveImages signatures unchanged.
Where something is unclear, state your assumption instead of asking.
Show me the plan when it's ready.
Korrigieren Sie eventuelle Fehler im Plan. Klicken Sie dann entweder auf Erstellen oder wechseln Sie zurück zu Agent und senden Sie diese Anfrage.
@ironword-forms
Carry out the approved plan.
Check the forms output against TestData/forms/expected.csv before and after the move.
A printed row counts as a match when its supplier, registration, items and images columns agree.
Work through it in this order:
1. Run `dotnet run --project src/SupplierIntake -- forms TestData/forms` and count the matches.
2. Migrate FormReader to IronWord.
3. Remove the DocumentFormat.OpenXml package reference.
4. Run dotnet build, then run the forms command again.
Tell me the match count for the OpenXML version and for the IronWord version.
Then show me the diff.
Der @ironword-forms-Hinweis wendet die Regel nach Namen an, unabhängig davon, ob Cursor sie bereits durch seine Globmuster angehängt hat.
Welches Cursor-Feature passt zu jeder Änderung?
Tab vervollständigt eine Bearbeitung, die bereits im Editor sichtbar ist, und Inline-Bearbeitung (Ctrl+K) schreibt eine Auswahl aus einer einzeiligen Anweisung um. Änderungen über mehrere Dateien hinweg oder Änderungen, die einen Build erfordern, gehen zum Agenten. Verwenden Sie den Plan-Modus, wenn es mehr Mühe kostet, eine falsche Änderung rückgängig zu machen, als einen Plan zu schreiben. Ein Cloud-Agent eignet sich für unbeaufsichtigte Arbeiten.
Ein neuer Lieferant liefert formular-13, dessen Preistabelle eine Artikelzelle über zwei Preistufen zusammenführt. Markieren Sie die Schleife, die über die Preiszeilen in FormReader iteriert, drücken Sie Strg+Umschalt+L (Cmd+Umschalt+L auf macOS), um den hervorgehobenen Code in das Chat-Eingabefeld hinzuzufügen, und senden Sie diese Anfrage in Agent.
Make FormReader.Read handle merged cells in the price rows:
- An Item cell that Word merged with the cell above comes back empty.
- For that row, reuse the item name from the previous row.
- Before you read a cell by its column position, check that the row has that many cells.
Then rerun the forms command over TestData/forms.
Tell me how many rows agree with expected.csv, which now lists 13 forms.
Die Zeilenlängenüberprüfung berücksichtigt Zusammenführungen in die andere Richtung. In einer separaten Prüfdatei wurde eine Zelle, die über Spalten zusammengeführt wurde, als eine Zelle zurückgegeben, sodass diese Zeile kürzer war als die anderen.
Wie debuggen Sie Werte, die im extrahierten Text fehlen?
Der Pre-Check des Repositorys liest die Registrierungsnummer mit einem regulären Ausdruck über das Ergebnis von ExtractText.
@src/SupplierIntake/Forms/RegistrationCheck.cs @TestData/forms/
Find out why the pre-check flags 9 of the 13 forms as missing a registration number.
FormReader finds one in all 13, and every number is visible in Word.
Before you edit anything, do these three things:
1. Run the check command on TestData/forms and on TestData/edge, and note what it flags.
2. Run the dump command on one flagged form.
3. Explain what the check reads that FormReader doesn't.
Then fix RegistrationCheck and keep it on IronWord.
Rerun the check on both folders.
Tell me how many forms it flags in TestData/forms and in TestData/edge, before and after the fix.
Die neun Fehler haben zwei Ursachen. In fünf Formularen folgt ein Kontakt-Email-Absatz der Nummer, sodass der Ausdruck GB-0012345Contact erfasst und die Formatprüfung es ablehnt. Die anderen vier speichern die Nummer in einer Firmendatentabelle, wo die Beschriftungszelle Registrierungsnummer ohne Doppelpunkt liest und der Wert in der nächsten Zelle steht. Das individuelle Lesen der Absätze und das Nehmen des Wertes aus der Zelle neben dem Etikett löst beide Probleme.
Welche Teile eines DOCX lässt IronWord aus?
Unsere Untersuchungen zu IronWord 2026.10.4 identifizierten Inhalte, die die Bibliothek nicht an einen Formularleser zurückgibt.
- Kopfzeilen: kein Lesevorgang gibt Kopfzeilentexte zurück, und
ExtractImageslässt Kopfzeilenbilder aus. Die Seiteneinrichtung zeigt die Höhe der Kopfzeile, jedoch keinen ihrer Inhalte. - Inhaltssteuerelemente und Textfelder: ihre Texte fehlen sowohl in den Absätzen als auch im extrahierten Text.
- Verfolgte Änderungen: die Lesevorgänge lassen während des eingeschalteten Verfolgungsmodus eingefügten Text aus.
- Legacy-Dateien: eine Word 97-2003 .doc-Datei wirft „Datei enthält beschädigte Daten“ beim Laden.
- Inline-Bilder ohne Abstandsattribute: ein DOCX, dessen Inline-Bilder distT, distB, distL und distR auslassen, schlägt beim Laden mit einer InvalidOperationException fehl. Python-docx lässt diese Attribute aus.
Schwebende Bilder und Bilder innerhalb von Tabellenzellen werden in Dokumentreihenfolge extrahiert. Wenn Lieferanten Formulare ausfüllen, die mit Inhaltssteuerelementen gebaut wurden, oder die Registrierungsnummer in einer Kopfzeile platzieren, testen Sie diese Formulare, bevor Sie sich auf den Leser verlassen.
Wie schreiben Sie Regressionstests für die Dokumentenlesung?
Tests, die extrahierte Werte mit einer bekannten Liste vergleichen, überprüfen das Ausgabe des Aufnahme-Dienstes, unabhängig von der internen Implementierung des Lesers. Ein Cloud-Agent kann sie in seiner eigenen isolierten VM schreiben. Speichern Sie IRONWORD_LICENSE_KEY zuerst unter Geheimnissen im Cloud-Agents-Dashboard.
@tests/SupplierIntake.Tests/ @TestData/
Write xUnit tests for FormReader and RegistrationCheck.
Each of these needs a test:
- Every row of TestData/forms/expected.csv matches.
- In form-13, both price tiers keep the item name.
- SaveImages writes one PNG per picture, with the pixel sizes listed in the image_sizes column.
- RegistrationCheck passes every form and flags TestData/edge/no-registration.docx.
- Reading TestData/edge/legacy.doc throws a FormatException or a type derived from it.
Copy TestData into the test output and run dotnet test.
Tell me the passed and failed counts.
Die Altdatendateiaussage kann nicht den Ausnahme-Typ von IronWord referenzieren, da er intern ist. Es leitet sich von FormatException ab, sodass eine Aussage, die abgeleitete Typen akzeptiert, wie Assert.ThrowsAny<FormatException> in xUnit, kompiliert und trotzdem fehlschlägt, wenn ein anderer Fehler auftritt.
Der Leitfaden für KI-coding assistants umfasst eine IronWord-Aufgabe, die von Anfang bis Ende gegen geschriebene Passkriterien ausgeführt wird.
Was haben die Aufforderungen in einem realen Lauf erzeugt?
Die sieben Eingabeaufforderungen wurden nacheinander in einem Chat an Cursor gesendet. Das Beispielrepository hielt einen OpenXML SDK-Leser, einen IronWord-Pre-Check, ein leeres xUnit-Projekt, zwölf Formulare mit bekannten Werten und zwei Randdateien.
- Sowohl der OpenXML SDK-Leser als auch der IronWord-Leser, der ihn ersetzt hat, stimmten mit allen 12 Formularen überein.
- IronWord war das einzige DOCX-Paket, das in der App und seinen Tests übrig blieb.
- Mit formular-13 hinzugefügt, stimmte der Leser mit 12 von 13 überein und ließ den Artikelnamen aus der zweiten Preisstufe aus.
- Nach der Änderung der zusammengeführten Zelle stimmte der Leser mit 13 von 13 überein.
- Der Pre-Check hat 9 von den 13 Formularen vor der Korrektur markiert und keine danach. Er hat das Randformular ohne Registrierungsnummer beide Male markiert.
- Alle 21 gespeicherten Bilder hatten ihre angegebenen Pixelgrößen.
- Der form-03-Dump listete 10 Zellen in zwei Tabellen und ein Bild von 108 x 36 Punkten und 144 x 48 Pixel.
- Auf die Frage, was die Dokumentation angibt, antwortete Cursor, ohne Dateien zu ändern.
- Alle 42 Fälle aus sechs Testmethoden bestanden, mit und ohne Lizenzschlüssel.
- In Kopien des endgültigen Codes schlug das Entfernen der zusammengeführten Zellenbehandlung in 2 Fällen fehl. Die Wiederherstellung des alten Pre-Checks schlug in 9 Fällen fehl und das Auslassen eines Bildes pro Formular in 13 Fällen.
- Der Legacy-Dateitest akzeptierte jede Ausnahme und bestand mit der Datei gelöscht. Auf FormatException eingegrenzt, bestand er mit der echten Datei und schlug ohne sie fehl.
- Cursor's erster IronWord-Leser fehlte die Zeilen-Cast und konnte nicht mit CS1503 gebaut werden. Cursor fügte die Cast vor seinem nächsten Build hinzu.
- Jeder Release-Build hatte 0 Warnungen und 0 Fehler, ohne manuelle Änderungen.
- Einige Schritte liefen anders als die Seite. Die Regel fehlte der Zeilen-Cast. Die zusammengeführte Zellenaufforderung forderte keine Überprüfung der Zeilenlänge an, und Cursor fügte keine hinzu. Die Testaufforderung verlangte nur, dass eine Ausnahme geworfen wird. Eingabeaufforderungen, einschließlich @-Erwähnungen, wurden als Text in die Desktop-App eingefügt. Der Plan wurde in Agent genehmigt, nicht mit dem Build-Button. Die Cloud-Agent-Aufforderung wurde lokal im Agent-Modus ausgeführt, ohne eine VM.
Der Claude Code-Leitfaden fügt einen schreibgeschützten Unteragenten hinzu, der jedes IronWord-Mitglied im generierten Code gegen IronWord.xml überprüft. Der ChatGPT Codex-Leitfaden behandelt die Schreibseite und misst, welche Teile eines Word-Dokuments ein Textaustausch verändert.
Das Ablaufprotokoll listet das IronWord-Paket, Modell, Timing und Testmaschine für diese Ergebnisse auf.
Fehlerbehebung
- Text aus DOCX extrahieren wenn ein Wert in einer Tabelle im extrahierten Text fehlt
- Bilder aus DOCX extrahieren wenn gespeicherte Bilder ihre Größen oder ihr Format überprüfen müssen
- IronWord mit DocumentFormat.OpenXml während beide Pakete in einem Projekt während einer Migration referenziert werden
- Verwendung von Lizenzschlüsseln wenn generierter Code beim Speichern eine Lizenzierungsausnahme auslöst
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.