Cómo usar IronWord con Cursor

Curtis Chau
Curtis Chau
Actualizado: 19 de octubre de 2026

El repositorio de ejemplo para esta guía lee formularios de proveedores con código OpenXML SDK que itera sobre elementos del cuerpo y lee InnerText. Mover ese lector a IronWord haciendo un análisis de cada valor etiquetado de un bloque de texto extraído con una expresión regular falla. En la calibración, esa versión leyó 3 de 12 formularios correctamente, uniendo cinco números de registro a la etiqueta siguiente y sin devolver número de registro para los cuatro formularios de tabla.

Cursor está construido sobre la base de código de VS Code y proporciona un agente junto al editor. Dos de sus características, los enlaces de documentación que el agente lee y las reglas del proyecto comprometidas en .cursor/rules, determinan si produce código de IronWord o código que sigue el patrón del lector OpenXML. Ambas características aparecen más abajo en un servicio de incorporación de proveedores que lee los formularios DOCX devueltos por los proveedores. El servicio extrae el nombre del proveedor, el número de registro, la tabla de lista de precios y las imágenes del logo y la firma integradas, y su lector pasa del OpenXML SDK a IronWord.

Para obtener detalles sobre los métodos de lectura de IronWord, consulta la guía de extracción de texto y la guía de extracción de imágenes.

Inicio rápido
NuGetInstalar con NuGet

PM > Install-Package IronWord

Instale IronWord ejecutando el comando arriba en la Consola del Administrador de Paquetes NuGet, o busque el paquete en el Administrador de Paquetes NuGet.

Con el repositorio de entrada de proveedores abierto, pega este mensaje en un nuevo chat del Agente.

@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.
Text

No ingreses la clave de licencia en un chat. El agente edita archivos y ejecuta comandos de shell, por lo que una clave pegada se expone a cada archivo, mensaje de commit y registro de compilación que escribe. En nuestras pruebas, IronWord abrió y leyó cada formulario sin una clave y arrojó una LicensingException solo al guardar un documento. La guía de clave de licencia muestra cómo configurar la clave en el código, en Web.config o en appsettings.json.



¿Qué modelo de Cursor deberías usar para trabajar con IronWord?

Composer es el modelo agente propio de Cursor. El selector de modelos también ofrece los modelos Grok de SpaceXAI, que Cursor co-desarrolló, y modelos de OpenAI, Anthropic, Google y otros laboratorios. La prueba a continuación utilizó Grok 4.7.

¿Cómo proporcionas a Cursor la documentación de IronWord?

Incluye el enlace de documentación de IronWord en la solicitud, o guárdalo en una regla compartida por todo el equipo. El llms.txt de IronWord enumera cada guía y la referencia de API, y llms-full.txt condensa 46 páginas de documentación en un solo archivo. A partir de octubre de 2026, el menú @ de Cursor adjunta archivos, carpetas, terminales, chats, diferencias de Git y el navegador, por lo que la documentación de IronWord va al agente como un enlace.

El volcado de Quickstart muestra dos comportamientos que la guía de extracción de texto no menciona. Para form-03, ExtractText devolvió el texto del párrafo del cuerpo concatenado en una cadena y omitió todo el texto en las dos tablas del formulario.

@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.
Text

¿Cómo escribes reglas de proyecto que codifican tus convenciones de IronWord?

Una regla de proyecto es un archivo .mdc almacenado en .cursor/rules y versionado con el repositorio, por lo que cada clon lo incluye. Cursor ignora los archivos .md simples en esa carpeta porque, sin frontmatter, no puede determinar cuándo cargarlos.

La regla a continuación define globs y establece alwaysApply en falso. Cursor la carga siempre que una solicitud incluya un lector de formularios o un archivo de prueba, y la omite de lo contrario. Guárdala como .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.
Markdown
Por favor, tenga en cuenta: Cursor también lee AGENTS.md, en la raíz o en cualquier subcarpeta. Ese archivo no tiene frontmatter ni patrones de archivo, por lo que la regla de IronWord, que depende de sus globs, pertenece a .cursor/rules.

La página de reglas de Cursor indica que las reglas no afectan a Tab y que las reglas del usuario no se aplican a las ediciones en línea, por lo que Tab y las sugerencias de edición en línea necesitan una verificación manual contra la regla.

¿Cómo mapeas las llamadas de OpenXML SDK a IronWord?

Instruir al modelo para usar IronWord no le indica qué llamada de IronWord reemplaza a cada llamada de OpenXML SDK. Una tabla de equivalentes proporciona ese mapeo.

OpenXML SDKIronWord
WordprocessingDocument.OpenEl constructor WordDocument, desde una ruta, bytes o un flujo.
Párrafos del cuerpo y su texto interno.Paragraphs, con ExtractText en cada uno.
Tablas del cuerpo, filas y celdasTables, Rows y Cells
Elementos Blip y flujos de parte de imagen.ExtractImages, guardado a través de AnyBitmap.

Dos filas se comportan de manera diferente al código del SDK que reemplazan. La lista de párrafos contiene los párrafos dentro de las celdas de la tabla así como los párrafos del cuerpo, por lo que form-03 devuelve 15 entradas donde el lector OpenXML SDK iteró sobre 5 párrafos del cuerpo. Las celdas se devuelven como ITableCell, que no tiene método de texto, por lo que una llamada sin el casting falla al compilar con CS1061.

IronWord no hace referencia al paquete DocumentFormat.OpenXml, y un proyecto que hace referencia tanto a IronWord 2026.10.4 como a DocumentFormat.OpenXml 3.5.1 compila y se ejecuta. La migración puede, por lo tanto, proceder un lector a la vez. La página de conflictos de OpenXML cubre compilaciones de IronWord anteriores a 2025.7.13.

Agregar estas líneas al final de la regla pone la tabla en cada solicitud que carga la regla.

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).
Markdown

¿Cómo planificas y ejecutas una migración a IronWord?

Presione Shift+Tab en la entrada del chat hasta que se seleccione el Modo Plan, luego envíe la solicitud a continuación. Cursor escribe su plan en un archivo editable.

@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.
Text

Corrija cualquier error en el plan. Luego, haz clic en Construir o regresa a Agente y envía esta solicitud.

@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.
Text

@ironword-forms aplica la regla por nombre, independientemente de si Cursor ya la ha adjuntado a través de sus globs.

¿Qué característica de Cursor encaja con cada cambio?

Tab completa una edición que ya es visible en el editor, y la edición en línea (Ctrl+K) reescribe una selección a partir de una instrucción de una sola oración. Los cambios en varios archivos, o cambios que necesitan una compilación, van a Agente. Usa el Modo Plan cuando un cambio incorrecto requiere más esfuerzo para deshacer que el que toma escribir un plan. Un Agente en la Nube se adapta al trabajo sin supervisión.

Un nuevo proveedor devuelve form-13, cuya tabla de precios fusiona una celda de ítem a través de dos categorías de precios. Resalta el bucle que itera sobre las filas de precio en FormReader, presiona Ctrl+Shift+L (Cmd+Shift+L en macOS) para agregar el código resaltado a la entrada de chat, y envía esta solicitud en Agente.

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

La verificación de longitud de fila aborda las fusiones en la otra dirección. En un archivo de prueba separado, una celda fusionada a través de columnas se devolvió como una celda, por lo que esa fila era más corta que las otras.

¿Cómo depuras valores faltantes en el texto extraído?

La pre-verificación del repositorio lee el número de registro con una expresión regular sobre el resultado 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.
Text

Las nueve fallas tienen dos causas. En cinco formularios, un párrafo de correo electrónico de contacto sigue al número, por lo que la expresión captura GB-0012345Contact y la verificación del formato lo rechaza. Los otros cuatro almacenan el número en una tabla de detalles de la empresa, donde la celda de la etiqueta dice Número de registro sin dos puntos y el valor está en la siguiente celda. Leer los párrafos individualmente y tomar el valor de la celda junto a la etiqueta resuelve ambos problemas.

¿Qué partes de un DOCX omite IronWord?

Nuestras pruebas contra IronWord 2026.10.4 identificaron contenido que la biblioteca no devuelve a un lector de formularios.

  • Encabezados: ninguna lectura devuelve texto de encabezado, y ExtractImages omite imágenes de encabezado. La configuración de la página expone la altura del encabezado pero no su contenido.
  • Controles de contenido y cuadros de texto: su texto está ausente tanto de los párrafos como del texto extraído.
  • Cambios rastreados: las lecturas omiten texto insertado mientras el rastreo estaba habilitado.
  • Archivos heredados: un archivo .doc de Word 97-2003 arroja "Archivo contiene datos corruptos" al cargarse.
  • Imágenes en línea sin atributos de espaciado: un DOCX cuyas imágenes en línea omiten distT, distB, distL y distR no se carga con una InvalidOperationException. python-docx omite estos atributos.

Las imágenes flotantes e imágenes dentro de las celdas de tabla se extraen, en orden del documento. Si los proveedores completan formularios construidos con controles de contenido, o colocan el número de registro en un encabezado, prueba esos formularios antes de depender del lector.

¿Cómo escribes pruebas de regresión para la lectura de documentos?

Las pruebas que comparan valores extraídos con una lista conocida verifican la salida del servicio de entrada, independientemente de la implementación interna del lector. Un Agente en la Nube puede escribirlas en su propia VM aislada. Primero almacena IRONWORD_LICENSE_KEY bajo secretos en el panel de Agentes en la Nube.

@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.
Text

La aserción de archivo heredado no puede referenciar el tipo de excepción de IronWord porque es interno. Se deriva de FormatException, por lo que una aserción que acepta tipos derivados, como Assert.ThrowsAny<FormatException> en xUnit, compila y aún falla cuando se lanza un error diferente.

La guía de asistentes de codificación AI incluye una tarea de IronWord ejecutada de principio a fin contra criterios de pase escritos.

¿Qué produjeron los prompts en una ejecución real?

Los siete mensajes fueron enviados a Cursor en orden en un solo chat. El repositorio de ejemplo tenía un lector OpenXML SDK, una pre-verificación de IronWord, un proyecto xUnit vacío, doce formularios con valores conocidos, y dos archivos de prueba.

  • El lector OpenXML SDK y el lector de IronWord que lo reemplazó coincidieron cada una de las 12 formas.
  • IronWord era el único paquete DOCX dejado en la aplicación y sus pruebas.
  • Con form-13 añadido, el lector coincidió 12 de 13 y dejó el nombre del artículo del segundo nivel de precios.
  • Tras el cambio de celda fusionada, el lector coincidió 13 de 13.
  • La pre-verificación señaló 9 de los 13 formularios antes de la corrección y ninguno después. Se señaló el formulario de borde sin número de registro ambas veces.
  • Todas las 21 imágenes guardadas tenían sus tamaños en píxeles listados.
  • El volcado de form-03 enumeraba 10 celdas en dos tablas y una imagen de 108 por 36 puntos y 144 por 48 píxeles.
  • Al preguntar qué dice la documentación, Cursor respondió sin cambiar ningún archivo.
  • Los 42 casos de seis métodos de prueba pasaron, con y sin una clave de licencia.
  • En copias del código final, eliminar el manejo de celda fusionada falló 2 casos. Restaurar la verificación previa falló 9 y omitir una imagen por formulario falló 13.
  • La prueba de archivo heredado aceptó cualquier excepción y pasó con el archivo eliminado. Reducido a FormatException, pasó con el archivo real y falló sin él.
  • El primer lector de IronWord de Cursor carecía del casting de fila y no pudo compilar con CS1503. Cursor añadió el casting antes de su próxima compilación.
  • Cada compilación Release tuvo 0 advertencias y 0 errores, sin ediciones manuales.
  • Algunos pasos se ejecutaron de manera diferente a lo esperado. La regla carecía del casting de fila. El mensaje de celda fusionada no solicitó una verificación de longitud de fila, y Cursor no añadió ninguna. El mensaje de prueba solo requería que se lanzara una excepción. Los mensajes, @ menciones incluidas, fueron pegados en la aplicación de escritorio como texto. El plan fue aprobado en Agente, no con el botón de construcción. El mensaje de Agente en la Nube se ejecutó localmente en modo Agente, sin una VM.

El guía de Claude Code agrega un subagente de solo lectura que verifica cada miembro de IronWord en el código generado contra IronWord.xml. El guía de ChatGPT Codex cubre el lado de la escritura y mide qué partes de un documento Word cambia un reemplazo de texto.

El registro de ejecución lista el paquete de IronWord, modelo, tiempo y máquina de prueba para estos resultados.


Solución de problemas


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

Leer más

¿Listo para empezar?

Descargas de NuGet 62,392Versión:2026.11recién lanzado