如何使用IronXL与Cursor

Curtis Chau
Curtis Chau
更新: 2026年10月15日

通过Excel Interop编辑其工作簿的预算任务仅在安装了Excel的地方运行。 .NET 9服务BudgetDesk在本指南中,一台由任务计划程序在月末唤醒的财务桌面PC上推进成本中心预算。 微软不推荐或支持通过无人值守代码自动化Office,并且其指导将SYSTEM帐户下的任务计划程序任务命名为此类情况之一。 将任务移至构建代理意味着替换Interop。将该端口交给AI代理增加了一种较安静的风险,因为Interop和IronXL在仍然编译的细节上存在分歧。

Cursor的编辑器基于VS Code代码库,其三个功能保证此类端口的准确性。项目规则命名了需要放弃的Interop和EPPlus习惯,计划模式在文件更改之前确定映射,每个提示中的文档链接为代理提供IronXL的真实API。 每个BudgetDesk滚动插入一行和一列,编辑值和公式,按差异排序行,将顶行复制到第二张表,并添加和删除月度表。 IronXL对没有Office的机器上的.xlsx文件执行以上所有操作。

快速入门
NuGet使用NuGet安装

PM > Install-Package IronXL.Excel

通过在 NuGet 包管理器控制台中运行上述命令安装 IronXL,或在 NuGet 包管理器中搜索该包。

在Cursor中打开BudgetDesk,将此粘贴到Agent中。 它的两个提及交给了Interop类和该类编辑的工作簿。

@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

在没有Excel的机器上,六个测试中的五个在new Excel.Application()停止,出现COMException 0x80040154,类未注册。 第六个通过了,因为Watchlist导出使用了EPPlus 4.5.3.3。在同一机器上,inspect命令列出了15个工作表,分别是Summary、Lines和Template,以及从Oct-2025到Sep-2026的12个月工作表。它打印的Lines公式是从E2-D2到E9-D9的差异,在第2到9行加上第10行的三个SUM总计。

在每个提示中省略许可证密钥。 Cursor的代理编辑文件并运行shell命令,因此输入对话中的键可能会最终出现在代码或提交消息中。 请改为设置IRONXL_LICENSE_KEY环境变量。 IronXL本身不会读取该变量,因此提示中有代码将其分配给License.LicenseKey。 许可证密钥指南介绍了缺少密钥时抛出的异常和IronXL自己读取的配置文件。



您应该使用哪个Cursor模型来处理IronXL工作?

Composer是Cursor自己的代理模型。 模型选择器还提供Cursor共同开发的SpaceXAI的Grok模型,以及来自OpenAI,Anthropic,Google和其他实验室的模型。 下面的测试运行使用了Grok 4.7。

计划端口意味着要阅读每个Interop调用和每个测试,并决定每个调用将变成什么,这奖励了一个推理时间更长的模型。 构建它主要是机械编辑和测试重跑,快速模型保持每个循环简短。 无论您选择哪个,在提示中命名文件、测试和预期数字,因为两个模型可能会对一个请求进行不同的解读。

您如何将IronXL文档提供给Cursor?

将IronXL的文档链接放入请求中,或将其保存在提交的规则中,以便无需粘贴。 llms.txt 索引链接指南和示例。 截至2026年10月,Cursor的@菜单附加文件、文件夹、终端、聊天、Git差异和浏览器,因此IronXL的文档通过链接到达代理。

端口围绕两个问题展开。 哪些IronXL参数从零开始计数,以及Interop在未被要求时提供的行为已变成什么?

@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

IronXL的页面直接回答了索引问题。 行和列指南将InsertRow参数描述为以零为基的索引,工作表指南称它提到的每个位置都是以零为基的。 排序指南和SortByColumn的API参考都没有提到标题行。

提示: 将没有页面支持的答案视为未经验证,直到您在API参考中找到该成员。
请注意: IronXL还发布了一个技能文件,其前言将其命名为ironxl。 保存为.cursor/skills/ironxl/SKILL.md,在Cursor启动时被发现,在Agent中输入/ironxl可以将其附加到一条消息。

如何编写项目规则以编码您的IronXL约定?

项目规则是.mdc文件,位于.cursor/rules中。 它们与代码一起提交,因此每个克隆都具有相同的规则。 该文件夹中的纯.md文件被忽略,因为它没有前言说明何时适用。 description、globs和alwaysApply字段决定何时规则加入请求。

该规则设置globs并关闭alwaysApply,因此它在服务或其测试处于上下文中时附加,并保留在从未接触工作簿的请求之外。 @ironxl-port按名称附加它。 几个模式放一行,用逗号分隔。 将其保存为.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

索引标记存在是因为偏差一行将在Total行下写入新行。

规则适用于Agent请求。 根据Cursor的文档,它们不会影响Tab,并且用户规则不适用于内联编辑。 自行检查那些功能的建议与规则。

怎么将Excel Interop和EPPlus调用映射到IronXL?

仅说明“使用IronXL”的规则使模型推断每个调用成为什么。 每个IronXL结果使用IronXL 2026.10.1在BudgetDesk工作簿上进行了测量,其Lines表在第2到9行上方保存八个成本中心,总计行在第10行。

Interop或EPPlus调用预期IronXL
Rows[10].Insert(), Cells[row, col]从1开始计数InsertRow(9)插入在第10行上方,GetCellAt(0, 0)是A1。Total移到第11行,SUM(D2:D9)未更改,Summary!B2变为Lines!D11
Range.Copy的上一行公式跟随新行F10保留E9-D9
EPPlus Copy从A1:F4到Watchlist A3公式跟随Watchlist行Watchlist F4获得E2-D2并读取0
Range["F2:F9"].Formula = "=E2/Summary!$B$5*12"每行一个公式所有八个单元格获得F2公式并读取128,666.67
Sort与Header设置为xlYes超过A1:F9保留标题行,按差异排序没有标题选项。 数字按文本排序,11,200排第四
在A2:F9上的相同排序公式随着其行移动正确顺序,公式变为数字。 E2设置为0,F2保持在11,200
FindSheet循环遍历Worksheets缺失月份被跳过GetWorkSheet返回null,RemoveWorkSheet抛出ArgumentException"Index -1超出范围"
Template.Copy(After: lastSheet)新工作表最后落地CopySheet将其放在第16个,共16个,重复名称抛出ArgumentException

插入本身支持住。InsertColumn(5)将差异移动到列G,重写其总计为SUM(G2:G9),并将Summary!B4移到Lines!G10。 表中的两行比其余的损害更严重,因为它们改变了一个单元格的含义。 一个带有旧引用的公式复制会报告另一个成本中心的数字。 一个将公式变成数字的排序留下一个不再跟随实际的差异列,所以下个月的实际永远无法到达它。 两者都能在总数一瞥中幸存。 SortAscending也不是捷径,因为在一个列块上它会单独对每一列进行排序,并且在我们的测试中,第2行回来了,成为设施中的CC-110,由Berg拥有。

将翻译添加到规则中,作为另外三个项目符号。

- 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

为什么GetCellAt在IronXL中返回null?

该规则将GetCellAt列为以零为基的成员之一,这吸引了Cells[row, col]的逐行端口。 Interop为任何地址返回一个Range,无论是否已填充,因此AddLine将新成本中心写入它插入的行中。 IronXL的GetCellAt返回null“如果单元格未填充”,正如其API参考所述。 在InsertRow(9)之后,新第10行中的所有六个位置返回null,并且GetCellAt(9, 0).Value = "CC-190"抛出NullReferenceException。

这里未填充意味着在工作簿XML中不存在。 在发货的工作簿中,B10和C10没有值但在总计行中带有样式,并且GetCellAt将它们作为空单元返回。 G2,超过差异的一列和A11,总计以下一行,为null。

按地址索引总是返回一个单元格。 ws["A10"]接受新行中的CC-190,并且GetCellAt(9, 0)随后找到了它。 保持数字索引的端口可以在GetCellAt找不到时退回至地址。

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

如何计划并运行IronXL的迁移?

端口触及每个方法,撤消一个错误的代价超过编写它所花费的成本。 在发送下一个提示之前使用Shift+Tab将聊天切换到计划模式。 在计划模式下,Agent读取代码,可能会提出澄清问题,并用计划代替编辑。

@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

计划是您可以编辑的Markdown文件,因此计划本身即可修正错误映射。 当计划读取正确时,点击构建,或切换回Agent并发送下一个提示。

@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

在我们的校准中,一个直接翻译替换每次调用为其最近的IronXL成员编译并清通过了六个测试中的两个。 四个失败是预测公式、排序、Watchlist复制和新行的差异,如上表所示。 遵循规则的端口通过了所有六个。

Cursor功能适合哪个变化?

根据变化的范围选择一个。 Tab处理可预测的下一次编辑,内联编辑处理一项选择,这一项由一句话描述。 Agent承担需要多个文件或构建循环的更改。

财政开始关闭成本中心,因此BudgetBook需要一种删除一行的方法。突出显示AddLine方法的整个组件,在BudgetBook.cs中按下Ctrl+Shift+L以将其添加到打开的聊天中,然后在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

IronXL在删除一行后如何更新总计?

RemoveLine作为GetRow(index).RemoveRow()周围的几行出现,而在工作表中间的一行,IronXL保持总计正确。 从第4行删除CC-130将其下方的行上移一行,将Total的SUM(D2:D9)缩小至SUM(D2:D8),并将Summary!B2移到Lines!D9。

最后一行是例外。 删除第9行,总计正上方的行,将Total上移到第9行,而其公式保持SUM(D2:D9),现在包括Total单元格本身。 IronXL将其评估为CIRCULARREF~。

本指南中的11月关闭CC-140,10月排序将其放在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

仅使用RemoveRow,在我们的校准中,11月输出在第10行保存=SUM(D2:D10),三个Summary单元格读取CIRCULARREF~,并且报告预算为0的滚动。移除后再次编写这四个Total公式产生了477,750的预算,606,600的实际支出和128,850的差异,与剩余八行之和相符。 给规则添加下一个项目符号。

- 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

如何测试迁移的IronXL代码?

Cloud Agent可以在无人察看的情况下编写回归套件。 在启动之前,将IRONXL_LICENSE_KEY添加为Cloud Agents仪表板中的一个机密。

@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

解压文件的指令遵循IronXL保存的方式。 SaveAs写入每个公式最后计算的结果。 在我们的测量中,将CC-110的实际提高到104,900并在没有EvaluateAll的情况下保存时,文件中留下了527,300作为存储的Lines实际总计和Summary,而单元格的和为535,700。将该文件用IronXL重新加载报告为535,700,因为IronXL在读取公式时计算它们。 因此,读取IronXL的测试在存储的数字过时的文件上通过了,而读取存储结果的openpyxl显示为527,300。在保存之前读取一个总计仅刷新该单元格,而在保存之前调用EvaluateAll刷新每一个,因此规则要求它。

IronXL也无法告诉套件哪个工作表是活动的,因为SetActiveTab写入值,并没有任何属性读取它。 在SetActiveTab(14)、保存和重新加载之后,DefaultWorkSheet仍然返回Summary,因此十月测试从工作簿XML获取activeTab属性。

在Interop迁移后IronXL是否需要Windows?

一旦端口完成,不需要。 BudgetDesk的Interop构建引发了三个CA1416警告,每个Marshal.ReleaseComObject调用一个,每个都说该调用仅在Windows上受支持。 IronXL的Linux指南说无需代码更改即可在Linux上运行IronXL,并且Docker指南覆盖了容器。 本指南的校准在Windows上运行,因此在桌面PC退役之前在您要部署的Linux镜像上运行一次测试。

在实际运行中这些提示生成了什么?

七个提示按顺序发送到Cursor,在一次聊天中,针对为本指南制作的BudgetDesk存储库副本。副本包含Interop BudgetBook、EPPlus Watchlist导出、六个读取结果为EPPlus的xUnit测试,以及具有10月实际和一个新行的预算工作簿。规则文件和11月关闭文件在使用它们的提示之前添加,许可证密钥则仅设置为环境变量。

  • 端口先前的1/6测试通过,端口后的6/6全部通过,所有31条原始断言行仍在原位。
  • 端口后Release构建没有警告,IronXL.Excel 2026.10.1是应用程序及其测试中唯一剩下的电子表格包。
  • 在11月修复之前,读取CIRCULARREF~时,滚动以FormatException停止。 一旦Total公式再次书写,存储的11月总计等于已纠正的校准数据,文件中没有留下循环引用。
  • 10月的滚动保存了511,500的预算,590,950的实际支出和79,450的差异。我们的工作簿检查的19项全部通过。 它们覆盖了第1行的标题,按差异排序的九行,Forecast和Variance中每行一个公式,Oct-2026作为活动工作表,以及其公式使用自己行的CC-120、CC-130和CC-110 Watchlist。
  • 批准的计划将活动工作表映射为DefaultWorkSheet。 端口后的第一次测试运行捕获了这一点,并且Cursor让测试从保存的工作簿XML读取活动选项卡。
  • 五个新测试将套件带到了11个中的11个。我们的突变运行从最终代码的副本中逐步去掉一个行为。 这五个是Total重写,排序后和新行中的公式重写,保存前评估和活动选项卡调用。 每个副本未通过为其编写的测试。
  • 每个Release构建有0错误且无需手动编辑。
  • 有些步骤与页面中的运行不一样。 提示在桌面应用中手动发送,@提及以文本形式粘贴。 通过发送下一个提示批准计划,从未点击构建,Cloud Agent提示在本地以Agent模式运行,因此未设置仪表板机密。 这是第二次尝试,因为11月关闭提示在第一次未到达聊天。

有关这些数字背后的IronXL包、Cursor版本、时间和测试机器的信息,请参见运行记录。


故障排除


有问题吗?

如果您有任何问题,请联系support@ironsoftware.com

Curtis Chau 拥有卡尔顿大学的计算机科学学士学位,专注于前端开发,精通 Node.js、TypeScript、JavaScript 和 React。他热衷于打造直观且美观的用户界面,喜欢使用现代框架并创建结构良好、视觉吸引力强的手册。

阅读更多

准备开始了吗?

NuGet 下载量 2,393,101版本:2026.11刚刚发布