如何使用 IronXL 與 Cursor
透過 Excel Interop 編輯其工作簿的預算工作僅在安裝 Excel 的地方運行。 在本指南中的 .NET 9 服務 BudgetDesk 會將成本中心預算向前推進至一台財務桌 PC 上,該 PC 會在月底由任務排程程式喚醒。 Microsoft 不建議或支援從無人值守的程式碼自動化 Office,並指出這類案例中的一個是系統賬號下的任務排程程式任務。 將工作轉移到構建代理意味著替換 Interop。而將該端口交給 AI 代理則增加了安靜的風險,因為 Interop 和 IronXL 在仍可編譯的細節上有分歧。
Cursor 的編輯器基於 VS Code 程式碼庫構建,其三個功能保持像這樣的端口誠實。一個專案規則指出要放棄的 Interop 和 EPPlus 習慣,計劃模式在文件更改前確定映射,每個提示中鏈接的文檔為代理提供 IronXL 的真實 API。 每次 BudgetDesk 捲軸插入一行和一列、編輯值和公式、按差異排序行、將頂部行複製到第二張工作表,以及增加和刪除月份表。 IronXL 可以在沒有 Office 的計算機上對 .xlsx 文件執行所有這些操作。
快速開始在 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.
在沒有 Excel 的機器上,六個測試中的五個在 new Excel.Application() 停止,顯示為 COMException 0x80040154,類未註冊。 第六個通過是因為 Watchlist 匯出使用了 EPPlus 4.5.3.3。在同一台機器上,inspect 命令列出了 15 張工作表,包括總結、行和模板,然後從 2025 年 10 月到 2026 年 9 月的十二個月工作表。它列印的行公式是行 2 到 9 的 E2-D2 到 E9-D9 的差異加上第 10 行的三個 SUM 總計。
在每個提示中都不包含授權密鑰。 因為 Cursor 的代理會編輯文件和執行 shell 命令,所以在對話中鍵入的密鑰可能會以某種方式進入程式碼或提交消息。 而是將 IRONXL_LICENSE_KEY 設為環境變量。 IronXL 不會自行讀取該變量,這就是為什麼提示中有程式碼將其指派給 License.LicenseKey。 授權密鑰指南涵蓋了缺失密鑰引發的異常以及 IronXL 自行讀取的配置文件。
最小工作流程(5 個步驟)
- 從NuGet下載C# Excel程式庫
- 在
.cursor/rules下提交一個禁止 Interop 和 EPPlus 並鏈接 IronXL 文檔的規則 - 將測量的複製、公式和排序翻譯添加到規則中
- 在計劃模式中同意該端口,然後根據現有測試構建它
- 用第二個讀者重新打開每個保存的工作簿,並在 API 參考中檢查成員名稱
應該使用哪一個 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 參數從 0 開始,而 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?
IronXL 的頁面直接回答了索引問題。 行和列指南將 InsertRow 參數描述為從 0 開始的索引,並且工作表指南表示其提及的每個位置都以 0 為基礎。 既沒有排序指南也沒有 SortByColumn 的 API 參考提及標頭行。
ironxl。 保存為 .cursor/skills/ironxl/SKILL.md,在 Cursor 啟動時發現,並在代理中輸入 /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.
索引符號存在是因為一個行數錯位寫入了總計行之下的新行。
規則適用於 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。總位於第 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 返回空值,RemoveWorkSheet 拋出 ArgumentException "Index -1 超出範圍" |
Template.Copy(After: lastSheet) | 新工作表放在最後 | CopySheet 把它放在第 16 位,重複的名字拋出了 ArgumentException |
插入本身持住了。InsertColumn(5) 將 Variance 移動到了 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.
為什麼 GetCellAt 在 IronXL 中返回空值?
該規則在零基成員中列出 GetCellAt,這邀請了Cells[row, col] 的逐行港口。 Interop 對任何地址返回一個範圍,無論是否填充,因此AddLine將新的支出中心寫入它插入的行中。 IronXL 的 GetCellAt 根據其 API 參考,“若儲存格未填充”則返回空值。 在InsertRow(9)之后,新行第 10 行的六個位置全都返回空值,GetCellAt(9, 0).Value = "CC-190" 拋出了 NullReferenceException。
未填充此處意味著在工作表 XML 中缺失。 在發送的工作簿中,B10 和 C10 在總計行中不持有任何值但附帶風格,而且 GetCellAt 返回它們為空儲存格。 G2,直接過了 Variance 的一列,和比總計多一行的 A11 是空值。
按地址編列總是返回一個儲存格。 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();
您如何計劃和運行到 IronXL 的遷移?
一個港口觸及每個方法,撤銷錯誤的操作成本比編寫它還要高。 在發送下一個提示前用 Shift+Tab 將對話切換到計劃模式。 在計劃模式中,代理會讀取代碼,可能會問澄清性問題,並書寫一個規劃替代編輯。
@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.
該計劃是一個 Markdown 文件,您可以編輯以修正錯誤的映射。 當計劃顯示正確時,點擊構建,或切換回代理並發送下一個提示。
@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.
在我們的校準中,將每次呼叫替換為其最接近的 IronXL 成員的直接翻譯清晰編譯並通過了六個測試中的兩個。 四次失敗是預測公式、排序、Watchlist 複製和新行的偏差,表格以上同一行。 遵循規則的端口通過了所有六個。
哪個 Cursor 功能適合每個變更?
按變更到達的距離選擇一個。 Tab 處理一個可預測的下一個編輯,內嵌編輯處理一句話覆蓋的一個選擇。 代理處理需要多個文件或構建循環的變更。
財務已開始關閉費用中心,因此 BudgetBook 需要一種刪除行的方法。突出顯示AddLine 方法的整個 BudgetBook.cs,按 Ctrl+Shift+L 將其添加到打開的對話並在代理模式中發送請求。
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.
IronXL 如何在刪除行時更新總計?
RemoveLine 作為 GetRow(index).RemoveRow() 周圍的幾行出現,並且對於工作表中間的行 IronXL 保持總計正確。 從第 4 行刪除 CC-130 移動了其下的行向上移了一行,縮小了總計的 SUM(D2:D9) 至 SUM(D2:D8),並將 Summary!B2 移到了 Lines!D9。
最後一行是例外。 刪除第 9 行,即與總計直接相鄰的行,將總計向上移進了第 9 行,而其公式保持 SUM(D2:D9),現在包含了總計儲存格本身的範圍。 IronXL 將其評估為 CIRCULARREF~。
本指南中的十一月關閉了 CC-140,即十月排序直接放在總計之上。
@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.
單獨使用 RemoveRow,我們的校準中的十一月輸出保持了=SUM(D2:D10)於第 10 行,三個摘要儲存格讀取 CIRCULARREF~,和報告預算為 0 的捲軸。在移除後再次寫入四個總計公式產生的預算為 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.
如何測試已遷移的 IronXL 程式碼?
雲代理可以在無人值守情況下編寫回歸套件。 在開始一個之前,將IRONXL_LICENSE_KEY添加為雲代理儀表板中的秘密。
@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.
解壓縮文件的指令依循 IronXL 的保存方式。 SaveAs 寫入該公式最後計算的結果。 在我們的測量中,將 CC-110 的實際值提高到 104,900 並在沒有 EvaluateAll 的情況下保存留下 527,300 作為存儲在文件中的行實際總計和摘要,而儲存格加總到 535,700。將該文件用 IronXL 加載回來報告了 535,700,因為 IronXL 在讀取它們時計算公式。 因此,通過 IronXL 進行讀取的測試會通過其存儲數字已過時的文件,而 openpyxl 會讀取存儲的結果,顯示 527,300。在保存前讀取一次總計僅刷新那個儲存格,而保存前呼叫 EvaluateAll 則刷新了每一個,這就是為什麼規則要求這樣做。
IronXL 也無法告訴套件哪個工作表是活動的,因為 SetActiveTab 寫入值,沒有屬性讀回。 在 SetActiveTab(14)、保存和重新加載後,DefaultWorkSheet 仍返回摘要,因此十月測試從工作簿 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 匯出、EdgePlus 讀取結果的六個 xUnit 測試以及包含十月實際值和一個新行的預算工作簿。在使用前的提示中添加了規則文件和十一月封閉文件,授權密鑰僅設置為環境變量。
- 該套件在端口前的 6 個測試中通過 1 個,端口後的 6 個則全部通過,原來的 31 行斷言行每一行都在同一位置。
- 端口後,Release 構建沒有警告,
IronXL.Excel2026.10.1 是應用及其測試中唯一保留的電子表格包。 - 在十一月修復之前,捲軸在從摘要預算儲存格中讀取
CIRCULARREF~ 時停止,顯示為 FormatException。 當重新寫入總計公式後,存儲的十一月總計等於校正後的校驗號,文件中不再存在循環引用。 - 十月的捲軸保存了一個 511,500 的預算,590,950 的實際支出和 79,450 的偏差。我們的工作簿檢查全部 19 項通過。 它們涵蓋了第 1 行的標題,按差異排序的九個行,預測和差異中每行一個公式,Oct-2026 作為活動工作表,以及使用自身行為公式的 CC-120、CC-130 和 CC-110 Watchlist。
- 獲批准的計劃將活動工作表映射到
DefaultWorkSheet。 端口後的首次測試運行抓住了這一點,而 Cursor 則讓測試從已保存的工作簿 XML 中讀取活動標籤。 - 五個新測試將套件帶到了 11 個中的 11 個。我們的變異運行從最終代碼的副本中一次省略了一種行為。 這五個是總計重寫、排序後和新行中的公式重寫、保存前的評估及活動標籤呼叫。 每個副本都未能通過為其編寫的測試。
- 每個 Release 構建中有 0 個錯誤,不需人工編輯。
- 一些步驟與頁面上運行的不同。 提示通過桌面應用手動發送,
@的提及被作為文本粘貼。 通過發送下一個提示批准計劃,而未點擊構建,且雲代理提示在本地以代理模式運行,因此未設置儀表板密碼。 這是第二次嘗試,因為十一月封閉提示在第一次未到對話中。
有關這些數字背後的 IronXL 包、Cursor 版本、定時和測試機器,請參閱運行記錄。
疑難排解
- 當端口代碼觸發 LicensingException 時,在 IronXL 中應用授權密鑰
- 當保存的文件仍顯示上個月的總計時,編輯 Excel 公式
- 當排序移動標頭或分割記錄時,在 Excel 中排序儲存格
- 當總計停止涵蓋其行時,插入新行和列
- 當一個月的工作表在錯誤位置著陸時,管理工作表
問題?
如果您有任何疑問,請聯繫support@ironsoftware.com
Curtis Chau 擁有卡爾頓大學計算機科學學士學位,專注於前端開發,擅長於 Node.js、TypeScript、JavaScript 和 React。Curtis 熱衷於創建直觀且美觀的用戶界面,喜歡使用現代框架並打造結構良好、視覺吸引人的手冊。