Comment utiliser IronWord avec Cursor
Le dépôt exemple pour ce guide lit les formulaires fournisseurs avec le code OpenXML SDK qui itère sur les éléments du corps et lit le texte intérieur. Déplacer ce lecteur vers IronWord en analysant chaque valeur étiquetée à partir d'un bloc de texte extrait avec une expression régulière échoue. Lors de l'étalonnage, cette version a lu correctement 3 des 12 formulaires, en raccordant cinq numéros d'enregistrement à l'étiquette suivante et en ne retournant aucun numéro d'enregistrement pour les quatre formulaires de tableau.
Cursor est construit sur la base de code de VS Code et fournit un agent à côté de l'éditeur. Deux de ses fonctionnalités, les liens de documentation que l'agent lit et les règles de projet engagées dans .cursor/rules, déterminent s'il produit du code IronWord ou du code suivant le modèle de lecteur OpenXML. Les deux fonctionnalités apparaissent ci-dessous dans un service d'intégration fournisseur qui lit les formulaires DOCX retournés par les fournisseurs. Le service extrait le nom du fournisseur, le numéro d'enregistrement, le tableau de liste de prix et les images intégrées du logo et de la signature, et son lecteur passe de l'OpenXML SDK à IronWord.
Pour plus de détails sur les méthodes de lecture d'IronWord, voir le guide d'extraction de texte et le guide d'extraction d'images.
Démarrage rapideAvec le dépôt d'accueil fournisseur ouvert, collez cette invite dans une nouvelle discussion d'Agent.
@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.
N'entrez pas la clé de licence dans une discussion. L'agent édite des fichiers et exécute des commandes shell, donc une clé collée est exposée à chaque fichier, message de commit et journal de build qu'il écrit. Dans nos tests, IronWord a ouvert et lu chaque formulaire sans clé et a lancé une LicensingException seulement lors de la sauvegarde d'un document. Le guide de la clé de licence montre comment définir la clé dans le code, dans Web.config ou dans appsettings.json.
Flux de travail minimal (5 étapes)
- Téléchargez la bibliothèque C# Word depuis NuGet
- Ajoutez une règle de projet sous .cursor/rules qui contient le lien de documentation d'IronWord
- Documentez dans la règle ce que
ExtractTextomet - Référez-vous au fichier lecteur et à un dossier de formulaires retournés dans chaque requête
- Comparez chaque valeur extraite avec une liste connue, puis confirmez chaque nom de membre dans le référence API
Quel modèle Cursor devez-vous utiliser pour le travail IronWord ?
Composer est le propre modèle agentique de Cursor. Le sélecteur de modèle offre également les modèles Grok de SpaceXAI, que Cursor a co-développés, ainsi que des modèles d'OpenAI, Anthropic, Google et d'autres laboratoires. Le test réalisé ci-dessous a utilisé Grok 4.7.
Comment fournissez-vous la documentation IronWord à Cursor ?
Incluez le lien de documentation d'IronWord dans la requête, ou stockez-le dans une règle partagée par toute l'équipe. Le llms.txt d'IronWord répertorie chaque guide et la référence API, et le llms-full.txt condense 46 pages de documentation en un seul fichier. En octobre 2026, le menu @ de Cursor attache des fichiers, dossiers, terminaux, discussions, Git diffs et le navigateur, donc la documentation IronWord va à l'agent sous forme de lien.
Le vidage Quickstart montre deux comportements que le guide d'extraction de texte ne mentionne pas. Pour le formulaire-03, ExtractText a retourné le texte du paragraphe du corps concaténé en une seule chaîne et omis tout le texte dans les deux tableaux du formulaire.
@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.
Comment écrivez-vous des règles de projet qui encodent vos conventions IronWord ?
Une règle de projet est un fichier .mdc stocké dans .cursor/rules et versionné avec le dépôt, donc chaque clone l'inclut. Cursor ignore les fichiers .md simples dans ce dossier car, sans frontmatter, il ne peut pas déterminer quand les charger.
La règle ci-dessous définit globs et définit alwaysApply à false. Cursor le charge chaque fois qu'une requête inclut un lecteur de formulaire ou un fichier de test, et l'ommet sinon. Sauvegardez-le sous .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.
La page des règles de Cursor indique que les règles n'affectent pas l'onglet et que les règles utilisateur ne sont pas appliquées aux éditions en ligne, donc les suggestions d'édition en ligne et onglet nécessitent une vérification manuelle contre la règle.
Comment mappez-vous les appels OpenXML SDK à IronWord ?
Indiquer au modèle d'utiliser IronWord ne lui indique pas quel appel IronWord remplace chaque appel OpenXML SDK. Un tableau d'équivalences fournit cette correspondance.
| OpenXML SDK | IronWord |
|---|---|
WordprocessingDocument.Open | Le constructeur WordDocument, à partir d'un chemin, d'octets ou d'un flux |
| Paragraphes du corps et leur texte intérieur | Paragraphs, avec ExtractText sur chacun |
| Tables du corps, lignes et cellules | Tables, Rows et Cells |
| Éléments blip et flux de la partie image | ExtractImages, enregistré à travers AnyBitmap |
Deux lignes se comportent différemment du code SDK qu'elles remplacent. La liste des paragraphes contient les paragraphes à l'intérieur des cellules du tableau ainsi que les paragraphes du corps, donc le formulaire-03 retourne 15 entrées là où le lecteur OpenXML SDK a itéré sur 5 paragraphes du corps. Les cellules sont retournées en tant qu'ITableCell, qui n'a pas de méthode texte, donc un appel sans casting échoue à se construire avec CS1061.
IronWord ne référence pas le package DocumentFormat.OpenXml et un projet qui référence à la fois IronWord 2026.10.4 et DocumentFormat.OpenXml 3.5.1 est construit et exécuté. La migration peut donc avancer un lecteur à la fois. La page de conflit OpenXML couvre les builds IronWord plus anciens que 2025.7.13.
Ajouter ces lignes à la fin de la règle met le tableau dans chaque demande qui charge la règle.
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).
Comment planifiez-vous et exécutez-vous une migration vers IronWord ?
Appuyez sur Maj+Tab dans la saisie de chat jusqu'à ce que le mode Plan soit sélectionné, puis envoyez la demande ci-dessous. Cursor écrit son plan dans un fichier modifiable.
@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.
Corrigez les erreurs dans le plan. Puis cliquez sur Construire ou revenez à Agent et envoyez cette demande.
@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.
La mention @ironword-forms applique la règle par nom, que Cursor l'ait déjà attachée ou non via ses globs.
Quel élément de Cursor convient à chaque changement ?
Tab complète une édition déjà visible dans l'éditeur, et l'édition en ligne (Ctrl+K) réécrit une sélection à partir d'une instruction en une phrase. Les changements à travers plusieurs fichiers, ou ceux qui nécessitent une construction, vont à Agent. Utilisez le mode Plan lorsque le retour en arrière d'un changement incorrect demande plus d'effort que d'écrire un plan. Un Agent Cloud convient aux travaux non surveillés.
Un nouveau fournisseur retourne le formulaire-13, dont le tableau des prix fusionne une cellule d'article à travers deux niveaux de prix. Mettez en surbrillance la boucle qui itère sur les lignes de prix dans FormReader, pressez Ctrl+Shift+L (Cmd+Shift+L sur macOS) pour ajouter le code en surbrillance à l'entrée de discussion, et envoyez cette demande à l'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.
La vérification de la longueur de ligne aborde les fusions dans l'autre sens. Dans un fichier de sonde séparé, une cellule fusionnée à travers les colonnes a été retournée comme une seule cellule, donc cette ligne était plus courte que les autres.
Comment déboguer les valeurs manquantes dans le texte extrait ?
Le précontrôle du dépôt lit le numéro d'enregistrement avec une expression régulière sur le résultat de 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.
Les neuf échecs ont deux causes. Dans cinq formulaires, un paragraphe d'email de contact suit le numéro, donc l'expression capture GB-0012345Contact et la vérification de format la rejette. Les quatre autres stockent le numéro dans un tableau de détails de la société, où la cellule d'étiquette lit Numéro d'enregistrement sans deux-points et la valeur est dans la cellule suivante. Lire les paragraphes individuellement et prendre la valeur de la cellule à côté de l'étiquette résout les deux problèmes.
Quelles parties d'un DOCX IronWord laisse-t-il de côté ?
Nos sondes contre IronWord 2026.10.4 ont identifié du contenu que la bibliothèque ne retourne pas à un lecteur de formulaire.
- En-têtes : aucune lecture ne retourne le texte de l'en-tête, et
ExtractImagesomet les images d'en-tête. La configuration de la page expose la hauteur de l'en-tête mais aucun de son contenu. - Contrôles de contenu et zones de texte : leur texte est absent à la fois des paragraphes et du texte extrait.
- Modifications suivies : les lectures omettent le texte inséré lorsque le suivi était activé.
- Fichiers hérités : un fichier .doc Word 97-2003 déclenche "Le fichier contient des données corrompues" au chargement.
- Images en ligne sans attributs d'espacement : un DOCX dont les images en ligne omettent distT, distB, distL et distR ne parvient pas à se charger avec une InvalidOperationException. python-docx omits these attributes.
Les images flottantes et les images à l'intérieur des cellules de tableau sont extraites, dans l'ordre du document. Si des fournisseurs complètent des formulaires créés avec des contrôles de contenu, ou placent le numéro d'enregistrement dans un en-tête, testez ces formulaires avant de vous fier au lecteur.
Comment écrivez-vous des tests de régression pour la lecture de documents ?
Les tests qui comparent les valeurs extraites à une liste connue vérifient la sortie du service d'admission, indépendamment de l'implémentation interne du lecteur. Un Agent Cloud peut les écrire dans sa propre machine virtuelle isolée. Stockez IRONWORD_LICENSE_KEY sous secrets dans le tableau de bord Cloud Agents en premier.
@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.
L'assertion de fichier hérité ne peut pas référencer le type d'exception d'IronWord car il est interne. Il dérive de FormatException, donc une assertion qui accepte des types dérivés, tel que Assert.ThrowsAny<FormatException> dans xUnit, compile et échoue toujours lorsqu'une erreur différente est lancée.
Le guide des assistants de codage AI inclut une tâche IronWord exécutée de bout en bout contre des critères de passation écrits.
Qu'est-ce que les messages ont produit lors d'une réelle exécution ?
Les sept invites ont été envoyées à Cursor dans l'ordre dans une seule discussion. Le dépôt exemple contenait un lecteur OpenXML SDK, une pré-vérification IronWord, un projet xUnit vide, douze formulaires avec des valeurs connues, et deux fichiers de bord.
- Le lecteur OpenXML SDK et le lecteur IronWord qui l'a remplacé ont chacun correspondu à tous les 12 formulaires.
- IronWord était le seul package DOCX restant dans l'application et ses tests.
- Avec le formulaire-13 ajouté, le lecteur a correspondu à 12 sur 13 et a abandonné le nom de l'élément du deuxième niveau de prix.
- Après le changement de cellule fusionnée, le lecteur a correspondu à 13 sur 13.
- La pré-vérification a signalé 9 des 13 formulaires avant le correctif et aucun après. Elle a signalé le formulaire de bord sans numéro d'enregistrement les deux fois.
- Toutes les 21 images sauvegardées avaient leurs tailles de pixels listées.
- Le vidage de formulaire-03 a listé 10 cellules dans deux tableaux et une image de 108 par 36 points et 144 par 48 pixels.
- Demandé ce que la documentation indique, Cursor a répondu sans changer aucun fichier.
- Tous les 42 cas de six méthodes de test ont passé, avec et sans clé de licence.
- Dans des copies du code final, enlever la gestion de cellules fusionnées a échoué 2 cas. Restaurer l'ancienne pré-vérification a échoué 9, et sauter une image par formulaire a échoué 13.
- Le test de fichier hérité a accepté toute exception et est passé avec le fichier supprimé. Réduit à FormatException, il est passé avec le vrai fichier et a échoué sans lui.
- Le premier lecteur IronWord de Cursor manquait le casting de ligne et a échoué à se construire avec CS1503. Cursor a ajouté le casting avant sa prochaine construction.
- Chaque build Release avait 0 avertissements et 0 erreurs, sans modification manuelle.
- Certaines étapes ont été exécutées différemment de la page. La règle manquait du casting de ligne. L'invite de cellule fusionnée ne demandait pas de vérification de la longueur de ligne, et Cursor n'en a ajouté aucune. L'invite de test nécessitait seulement qu'une exception soit lancée. Les invites, @ mentions incluses, ont été collées dans l'application de bureau sous forme de texte. Le plan a été approuvé dans Agent, pas avec le bouton Construire. L'invite de Cloud Agent s'est exécutée localement en mode Agent, sans une VM.
Le guide Claude Code ajoute un sous-agent en lecture seule qui vérifie chaque membre IronWord dans le code généré par rapport à IronWord.xml. Le guide ChatGPT Codex couvre l'écriture et mesure quelles parties d'un document Word un remplacement de texte change.
Le rapport d'exécution liste le package IronWord, le modèle, le timing et la machine de test pour ces résultats.
Dépannage
- Extraire le texte d'un DOCX lorsqu'une valeur à l'intérieur d'un tableau est manquante dans le texte extrait
- Extraire des images d'un DOCX lorsque des images sauvegardées nécessitent que leurs tailles ou formats soient vérifiés
- IronWord avec DocumentFormat.OpenXml tandis que les deux packages sont référencés dans un projet pendant une migration
- Utilisation des clés de licence lorsque le code généré lance une exception de licence lors de l'enregistrement
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.