Cómo usar IronXL con Cursor

Curtis Chau
Curtis Chau
Actualizado: 15 de octubre de 2026

Un trabajo de presupuesto que edita su libro de trabajo a través de Excel Interop se ejecuta solo donde Excel está instalado. BudgetDesk, el servicio .NET 9 en esta guía, avanza el presupuesto de un centro de costos en una PC de escritorio financiero que el Programador de Tareas enciende al final del mes. Microsoft no recomienda ni admite la automatización de Office desde código no atendido, y su guía nombra un trabajo de Programador de Tareas bajo la cuenta del SISTEMA como uno de esos casos. Mover el trabajo a un agente de compilación significa reemplazar Interop. Pasar ese puerto a un agente de IA añade un riesgo más silencioso, porque Interop e IronXL no están de acuerdo en detalles que aún se compilan.

El editor de Cursor se basa en el código de VS Code, y tres de sus características mantienen un puerto como este honesto. Una regla de proyecto nombra los hábitos de Interop y EPPlus que se deben abandonar, Plan Mode establece el mapeo antes de cualquier cambio de archivo, y los enlaces de documentación en cada solicitud brindan al agente la API real de IronXL. Cada movimiento de BudgetDesk inserta una fila y una columna, edita valores y fórmulas, ordena líneas por variación, copia las líneas superiores a una segunda hoja, y agrega y elimina hojas mensuales. IronXL hace todo eso con archivos .xlsx en máquinas sin Office.

Inicio rápido
NuGetInstalar con NuGet

PM > Install-Package IronXL.Excel

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

Con BudgetDesk abierto en Cursor, pega esto en Agent. Sus dos menciones entregan la clase Interop y el libro de trabajo que esa clase edita.

@src/BudgetDesk/Workbooks/BudgetBook.cs @TestData/budget-2026.xlsx

BudgetBook drives Excel over COM. I want to see what IronXL makes of the same workbook.
Fetch https://ironsoftware.com/excel/csharp/llms.txt before you write anything.

1. Run dotnet test once and tell me what the failures have in common.
2. Add IronXL.Excel 2026.10.1 to src/BudgetDesk.
3. Add an "inspect <file>" command to Program.cs that loads the workbook with IronXL.
4. Have it print the sheet names in tab order first.
5. Then have it print every Lines cell that holds a formula, with its address, formula text and value.
6. Run inspect on TestData/budget-2026.xlsx and show me the output.

The program takes the key from IRONXL_LICENSE_KEY and assigns it to License.LicenseKey.
Don't print the key's value or list any environment variables.
Leave BudgetBook.cs as it is for now.
Text

En una máquina sin Excel, cinco de las seis pruebas se detienen en new Excel.Application() con COMException 0x80040154, clase no registrada. La sexta pasa porque la exportación de Watchlist utiliza EPPlus 4.5.3.3. En la misma máquina, el comando inspect lista 15 hojas, que son Resumen, Líneas y Plantilla seguidas por doce hojas mensuales de Oct-2025 a Sep-2026. Las fórmulas de Líneas que imprime son una Variación de E2-D2 a E9-D9 en las filas 2 a 9 más tres totales SUM en la fila 10.

Deja la clave de licencia fuera de cada solicitud. El agente de Cursor edita archivos y ejecuta comandos shell, por lo que una clave escrita en la conversación puede terminar en código o en un mensaje de confirmación. En su lugar, establece la variable de entorno IRONXL_LICENSE_KEY. IronXL no lee esa variable por sí mismo, por lo que la solicitud tiene el código para asignarla a License.LicenseKey. La guía de claves de licencia cubre la excepción que arroja una clave faltante y los archivos de configuración que IronXL lee por su cuenta.



¿Cuál modelo de Cursor debería usar para el trabajo con IronXL?

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.

Planificar un puerto significa leer cada llamada de Interop y cada prueba y decidir en qué se convierte cada uno, lo que recompensa a un modelo que razone por más tiempo. Construirlo es principalmente ediciones mecánicas y nuevas ejecuciones de pruebas, donde un modelo rápido mantiene cada ciclo corto. Cualquiera que elija, nombra los archivos, las pruebas y los números esperados en la solicitud, porque dos modelos pueden interpretar una solicitud de manera diferente.

¿Cómo le das a Cursor la documentación de IronXL?

Ponga el enlace de documentación de IronXL en la solicitud, o manténgalo en una regla comprometida para que nadie tenga que pegarlo. El índice llms.txt enlaza las guías y ejemplos. A partir de octubre de 2026, el menú @ de Cursor adjunta archivos, carpetas, terminales, chats, diffs de Git y el navegador, por lo que la documentación de IronXL llega al agente como un enlace.

Un puerto gira en torno a dos preguntas. ¿Cuáles argumentos de IronXL cuentan desde cero, y qué ha pasado con el comportamiento que Interop proporcionaba sin que se le pidiera?

@src/BudgetDesk/Workbooks/BudgetBook.cs

These are questions, so don't change any files.
Answer from https://ironsoftware.com/excel/csharp/llms.txt and the how-to pages it links.
Cite the page URL for every answer.

1. List each Interop call in BudgetBook in one column and the IronXL member that replaces it in a second.
2. Mark every IronXL argument that counts rows, columns or sheets from 0.
3. Which IronXL method replaces Sort with Header set to xlYes?
4. Does any page describe a header option for that method?
Text

Las páginas de IronXL responden directamente la pregunta del índice. La guía de filas y columnas describe el argumento InsertRow como un índice basado en cero, y la guía de hojas de trabajo dice que cada posición que menciona es basada en cero. Ni la guía de ordenación ni la referencia de la API para SortByColumn mencionan una fila de encabezado.

Consejos: Trate una respuesta sin una página detrás como no verificada hasta que encuentre el miembro en la referencia de la API.
Por favor, tenga en cuenta: IronXL también publica un archivo de habilidades cuyo encabezado lo nombra ironxl. Guardado como .cursor/skills/ironxl/SKILL.md, se descubre cuando Cursor se inicia, y al escribir /ironxl en Agente se adjunta a un mensaje.

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

Las reglas de proyecto son archivos .mdc en .cursor/rules. Son comprometidas con el código, por lo que cada clon recibe las mismas reglas. Un archivo .md simple en esa carpeta es ignorado, porque no tiene frontmatter para decir cuándo se aplica. Los campos description, globs, y alwaysApply deciden cuándo la regla se une a una solicitud.

Esta regla establece globs y deja alwaysApply fuera, por lo que se adjunta siempre que el servicio o sus pruebas estén en contexto y se mantiene fuera de las solicitudes que nunca tocan un libro de trabajo. @ironxl-port lo adjunta por nombre. Varios patrones van en una línea, separados por comas. Guárdelo como .cursor/rules/ironxl-port.mdc.

---
description: Port Excel Interop and EPPlus workbook code in BudgetDesk to IronXL
globs: src/BudgetDesk/**/*.cs, tests/BudgetDesk.Tests/**/*.cs
alwaysApply: false
---

# BudgetDesk edits workbooks with IronXL

- Use IronXL only. The NuGet package is IronXL.Excel and the namespace is IronXL.
  Remove Microsoft.Office.Interop.Excel and EPPlus.
  Don't add ClosedXML, NPOI or another spreadsheet package.
- Documentation: https://ironsoftware.com/excel/csharp/llms.txt
- Delete the COM cleanup along with the Interop calls.
  IronXL code has no Marshal.ReleaseComObject, Application.Quit, GC.Collect or DisplayAlerts.
- Set License.LicenseKey from the IRONXL_LICENSE_KEY environment variable.
  Never write a key into code, tests or logs.
- A1 addresses such as "D10" mean the same in both libraries.
  IronXL index arguments start at 0, where Interop and EPPlus Cells[row, col] start at 1.
  Zero-based: InsertRow, InsertColumn, GetRow, GetColumn, GetCellAt, SetActiveTab, RemoveWorkSheet.
- Write dates as a DateTime plus a FormatString.
  IronXL stores a string that reads as a date, such as Oct-2026, as a date.
- Call EvaluateAll before SaveAs.
- Don't invent IronXL members. When unsure, say so and cite the page.
Markdown

La viñeta del índice está ahí porque una fila desfasada por uno escribe la nueva línea abajo de la fila Total.

Las reglas se aplican a las solicitudes de Agent. Según la documentación de Cursor, no afectan a Tab, y las reglas de usuario no se aplican a las ediciones en línea. Verifique usted mismo las sugerencias de esas características contra la regla.

¿Cómo mapeas las llamadas de Excel Interop y EPPlus a IronXL?

Una regla que solo dice "usa IronXL" hace que el modelo resuelva en qué se convierte cada llamada. Cada resultado de IronXL se midió con IronXL 2026.10.1 en el libro de trabajo BudgetDesk, cuya hoja de Líneas contiene ocho centros de costos en las filas 2 a 9 sobre una fila Total en la fila 10.

Llamada de Interop o EPPlusEsperadoIronXL
Rows[10].Insert(), Cells[row, col]Contando desde 1InsertRow(9) se inserta sobre la fila 10, GetCellAt(0, 0) es A1. Total movido a la fila 11, SUM(D2:D9) sin cambios, Summary!B2 se convirtió en Lines!D11
Range.Copy de la línea de arribaLa fórmula sigue la nueva filaF10 mantuvo E9-D9
EPPlus Copy de A1:F4 a Watchlist A3Fórmulas siguen las filas de WatchlistWatchlist F4 obtuvo E2-D2 y leyó 0
Range["F2:F9"].Formula = "=E2/Summary!$B$5*12"Una fórmula por filaTodas las ocho celdas obtuvieron la fórmula F2 y leyeron 128,666.67
Sort con Header configurado en xlYes sobre A1:F9El encabezado se mantiene, las filas se ordenan por VariaciónSin opción de encabezado. Números ordenados como texto y 11,200 quedaron en cuarto lugar.
El mismo orden sobre A2:F9Las fórmulas se mueven con sus filas.Orden correcto, las fórmulas se convirtieron en números. E2 configurado en 0 dejó F2 en 11,200
Bucle FindSheet sobre WorksheetsUn mes faltante se omiteGetWorkSheet devuelve nulo, RemoveWorkSheet arrojó ArgumentException "El índice -1 está fuera de rango"
Template.Copy(After: lastSheet)La nueva hoja llega últimaCopySheet la colocó en el puesto 16 de 16, un nombre duplicado arrojó ArgumentException

La inserción en sí se mantuvo. InsertColumn(5) movió Variance a la columna G, reescribió su total como SUM(G2:G9) y movió Summary!B4 a Lines!G10. Dos filas de la tabla causan más daño que el resto, porque cambian lo que significa una celda. Una fórmula copiada con sus referencias antiguas informa los números de otro centro de costos. Un ordenamiento que convierte fórmulas en números deja una columna de Variance que deja de seguir Actual, por lo que los datos reales del mes siguiente nunca la alcanzan. Ambos sobreviven a una ojeada a los totales. SortAscending tampoco es un atajo, ya que en un bloque de columnas ordena cada columna por su cuenta, y en nuestra prueba la fila 2 regresó como CC-110 en Instalaciones, propiedad de Berg.

Agregue las traducciones a la regla como tres viñetas más.

- Range.Copy keeps formula references unchanged.
  After copying cells that hold formulas, write each formula again for the row it landed on.
- Setting Formula on a multi-cell Range puts the same text in every cell.
  Write per-row formulas in a loop.
- SortByColumn has no header option and leaves values where the sorted formulas were.
  Sort from row 2 down, then write each row's formulas again.
Markdown

¿Por qué GetCellAt devuelve nulo en IronXL?

La regla enumera GetCellAt entre los miembros basados en cero, lo que invita a un puerto línea por línea de Cells[row, col]. Interop devuelve un Rango para cualquier dirección, lleno o no, por lo que AddLine escribe el nuevo centro de costos en la fila que insertó. El GetCellAt de IronXL devuelve nulo "si la celda no está llena", como lo dice su referencia de API. Después de InsertRow(9), todas las seis posiciones en la nueva fila 10 regresaron nulas, y GetCellAt(9, 0).Value = "CC-190" arrojó NullReferenceException.

No lleno aquí significa ausente del XML de la hoja. En el libro de trabajo enviado, B10 y C10 no tienen valor pero llevan un estilo en la fila Total, y GetCellAt las devolvió como celdas vacías. G2, una columna después de Variance, y A11, una fila debajo de Total, estaban nulas.

Indexar por dirección siempre devuelve una celda. ws["A10"] tomó CC-190 en la nueva fila, y GetCellAt(9, 0) la encontró después. Un puerto que mantiene índices numéricos puede recurrir a la dirección cuando GetCellAt no encuentra nada.

static Cell At(WorkSheet sheet, int row, int column) =>
    sheet.GetCellAt(row, column) ?? sheet[$"{(char)('A' + column)}{row + 1}"].First();
C#

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

Un puerto toca cada método, y deshacer uno incorrecto cuesta más que escribirlo. Cambie el chat a Plan Mode con Shift+Tab antes de enviar la próxima solicitud. En Plan Mode Agente lee el código, puede hacer preguntas aclaratorias y escribe un plan en lugar de ediciones.

@src/BudgetDesk/ @tests/BudgetDesk.Tests/ @ironxl-port

Plan the move to IronXL. Don't write code yet.

Here's the scope:
- BudgetBook moves off Excel Interop.
- WatchlistExport moves off EPPlus.
- The tests stop reading workbooks with EPPlus.
- BudgetBook keeps its public methods, and the six tests keep their names.

Put this in the plan:
1. List each Interop or EPPlus call with its IronXL replacement and the file it's in.
2. Flag every place where a row, column or sheet number changes base.
3. Explain how copied cells, the Forecast column and the sort keep each formula pointing at its own row.
Text

El plan es un archivo Markdown que puedes editar, por lo que un mapeo incorrecto se puede corregir en el plan mismo. Cuando el plan se lee correctamente, haz clic en Compilar, o vuelve a Agent y envía la próxima solicitud.

@ironxl-port

Build the approved plan.

- Remove the Interop and EPPlus package references and the EmbedExcelInteropTypes target.
- In the tests, change only how workbooks are opened and read.
- Leave every assertion in BudgetBookTests as it is.
- If IronXL can't read what an assertion checks, read the saved file's XML and keep the assertion.

When the port is done:
1. Build the solution and run the tests.
2. Run "dotnet run --project src/BudgetDesk -- roll Oct-2026".
3. Print each Lines row of out/budget-Oct-2026.xlsx with its formulas.
4. Tell me how many tests passed before the port and how many pass now.
Text

En nuestra calibración, una traducción directa que intercambiaba cada llamada por su miembro de IronXL más cercano se compiló limpiamente y pasó dos de las seis pruebas. Las cuatro fallas fueron las fórmulas de Forecast, el ordenamiento, la copia de Watchlist, y la Variance de la nueva línea, las mismas filas que la tabla anterior. El puerto que siguió la regla pasó las seis.

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

Elija una según qué tan lejos llegue el cambio. Tab maneja una edición siguiente predecible, y la edición en línea maneja una selección que una frase cubre. Agent toma un cambio que necesita varios archivos o un bucle de compilación.

Finanzas ha comenzado a cerrar centros de costos, por lo que BudgetBook necesita una forma de eliminar una línea. Resalte todo el método AddLine en BudgetBook.cs, presione Ctrl+Shift+L para agregarlo al chat abierto, y envíe la solicitud en modo Agent.

Add RemoveLine(string code) directly below the AddLine method I highlighted.
It finds a line by its code and deletes that row from Lines.
If the code isn't there, throw KeyNotFoundException, the same way SetActual does.
Text

¿Cómo actualiza IronXL los totales cuando se elimina una fila?

RemoveLine sale como unas pocas líneas alrededor de GetRow(index).RemoveRow(), y para una línea en el medio de la hoja IronXL mantiene los totales correctos. Eliminar CC-130 de la fila 4 desplazó las líneas debajo hacia arriba una fila, redujo SUM(D2:D9) del Total a SUM(D2:D8), y movió Summary!B2 a Lines!D9.

La última línea es la excepción. Eliminar la fila 9, la línea directamente arriba de Total, movió Total hacia arriba en la fila 9 mientras su fórmula se mantuvo en SUM(D2:D9), un rango que ahora incluye la celda Total en sí misma. IronXL lo evaluó como CIRCULARREF~.

El cierre de noviembre en esta guía cierra CC-140, la línea que el ordenamiento de octubre puso directamente arriba de Total.

@TestData/closures/Nov-2026.csv @TestData/actuals/Nov-2026.csv @src/BudgetDesk/Program.cs

Finance closed CC-140 at the end of November.

Change roll so it calls RemoveLine for each code in TestData/closures/<month>.csv.
Have roll do that before it applies new lines and actuals.
A month with no closures file closes nothing.

Then check the numbers:
1. Run roll Oct-2026.
2. Run roll Nov-2026 with out/budget-Oct-2026.xlsx as its input.
3. Add up Budget, Actual and Variance from the remaining line cells yourself.
4. Compare your sums with the Lines Total row and Summary B2:B4.
5. If they disagree, find the cause in BudgetBook, fix it and roll November again.

Show me the Total row formulas either way.
Text

Con RemoveRow solo, la salida de noviembre en nuestra calibración contenía =SUM(D2:D10) en la fila 10, tres celdas de Resumen leyendo CIRCULARREF~, y un avance que reportaba un presupuesto de 0. Escribir las cuatro fórmulas de Total nuevamente después de la eliminación produjo un presupuesto de 477,750, un gasto real de 606,600, y una variación de 128,850, que coinciden con las sumas de las ocho líneas restantes. Dale a la regla su próxima viñeta.

- After RemoveRow, write the Total row's SUM formulas again.
  Removing the line directly above Total leaves a range that includes the Total cell itself.
Markdown

¿Cómo pruebas el código de IronXL migrado?

Un Cloud Agent puede escribir la suite de regresión sin que nadie lo supervise. Agregue IRONXL_LICENSE_KEY como un secreto en el panel de Cloud Agents antes de comenzar uno.

@tests/BudgetDesk.Tests/ @TestData/

Add five xUnit tests to BudgetDesk.Tests that pin down the port.
Write each one as a new test, even where an existing test already covers part of it.

1. Sorting keeps the header in row 1 and a formula in every Variance cell.
2. A line added above Total gets formulas that use its own row.
3. Removing the line just above Total leaves SUM formulas that end one row higher.
4. After the October roll, Oct-2026 is the active sheet.
5. The totals stored in the saved file equal the recalculated ones.

IronXL recalculates on load and has no getter for the active tab.
Read the stored totals and the active tab by unzipping the xlsx and parsing its XML.

Run dotnet test when they're written and tell me how many pass.
Text

La instrucción para descomprimir el archivo sigue de cómo IronXL guarda. SaveAs escribe el resultado que cada fórmula calculó por última vez. En nuestra medición, elevar lo real de CC-110 a 104,900 y guardar sin EvaluateAll dejó 527,300 en el archivo como el total real de Líneas guardado y en Resumen, mientras que las celdas sumaban 535,700. Cargar ese archivo nuevamente con IronXL reportó 535,700, porque IronXL calcula fórmulas mientras las lee. Por lo tanto, una prueba que lee a través de IronXL pasa en un archivo cuyos números almacenados están desactualizados, mientras que openpyxl, que lee los resultados almacenados, mostró 527,300. Leer un total antes de guardar actualizó solo esa celda, y llamar a EvaluateAll antes de guardar actualizó todas, por lo cual la regla lo solicita.

IronXL tampoco puede decirle a la suite qué hoja está activa, ya que SetActiveTab escribe el valor y ninguna propiedad lo vuelve a leer. Después de SetActiveTab(14), un guardado, y una recarga, DefaultWorkSheet aún devolvió Resumen, por lo que la prueba de octubre toma el atributo activeTab del XML del libro de trabajo.

¿Necesita IronXL Windows después de una migración de Interop?

No una vez que el puerto esté completo. La compilación Interop de BudgetDesk generó tres advertencias CA1416, una por cada llamada Marshal.ReleaseComObject, cada una diciendo que la llamada solo es compatible en Windows. La guía de Linux de IronXL dice que no se requieren cambios de código para ejecutar IronXL en Linux, y la guía de Docker cubre los contenedores. La calibración para esta guía se ejecutó en Windows, por lo que ejecute las pruebas una vez en la imagen de Linux a la que despliega antes de retirar la PC de escritorio.

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

Las siete solicitudes se enviaron a Cursor en orden, en un chat, contra una copia del repositorio de BudgetDesk hecha para esta guía. La copia contiene el BudgetBook de Interop, la exportación de Watchlist de EPPlus, seis pruebas xUnit que leen resultados con EPPlus, y el libro de trabajo del presupuesto con los reales de octubre y una nueva línea. El archivo de reglas y los archivos de cierre de noviembre se agregaron justo antes de las solicitudes que los utilizan, y la clave de licencia se configuró solo como una variable de entorno.

  • La suite pasó 1 de las 6 pruebas antes del puerto y todas las 6 después de él, con cada una de las 31 líneas de aserción originales aún en su lugar.
  • Después del puerto, la compilación Release no tuvo advertencias, y IronXL.Excel 2026.10.1 fue el único paquete de hoja de cálculo que quedó en la aplicación y sus pruebas.
  • Antes de la corrección de noviembre, el roll se detuvo con una FormatException mientras leía CIRCULARREF~ de la celda de presupuesto de Resumen. Una vez que las fórmulas de Total se escribieron nuevamente, los totales de noviembre almacenados igualaron las cifras de calibración corregidas, y no quedó ninguna referencia circular en el archivo.
  • El roll de octubre guardó un presupuesto de 511,500, un gasto real de 590,950 y una variación de 79,450. Todas las 19 de nuestras verificaciones del libro de trabajo pasaron. Cubrieron el encabezado en la fila 1, nueve líneas ordenadas por variación, una fórmula por fila en Forecast y Variance, Oct-2026 como la hoja activa, y una lista de vigilancia de CC-120, CC-130 y CC-110 cuyas fórmulas utilizan sus propias filas.
  • El plan aprobado mapeó la hoja activa a DefaultWorkSheet. La primera ejecución de prueba después del puerto detectó eso, y Cursor hizo que las pruebas leyeran la pestaña activa del XML del libro de trabajo guardado en su lugar.
  • Cinco nuevas pruebas llevaron la suite a 11 de 11. Nuestra ejecución de mutación eliminó un comportamiento a la vez de las copias del código final. Las cinco fueron la reescritura de Total, las reescrituras de fórmulas después del ordenamiento y en la nueva línea, la evaluación antes de guardar y la llamada a la pestaña activa. Cada copia falló en la prueba escrita para ella.
  • Cada compilación de Release tuvo 0 errores y no necesitó ediciones a mano.
  • Algunos pasos se ejecutaron de manera diferente a lo esperado. Las solicitudes se enviaron a mano en la aplicación de escritorio, y las menciones @ se pegaron como texto. El plan fue aprobado al enviar la próxima solicitud, sin hacer clic en Compilar, y la solicitud de Agente de Nube se ejecutó localmente en modo Agent, por lo que no se configuró ningún secreto en el panel. Este fue el segundo intento, porque la solicitud de cierre de noviembre nunca llegó al chat en el primero.

Para el paquete IronXL, la versión de Cursor, el tiempo y la máquina de prueba detrás de estos números, consulte el registro de ejecución.


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 2,393,101Versión:2026.11recién lanzado