如何在.NET Excel專案中使用IronXL和Claude Code

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

具有百萬筆日記帳行數的一般總帳匯出在Excel中開啟未報錯,然而匯入任務在必須讀取它時卡住。 在我們的測試機上,WorkBook.Load讀取大小為60 MB的工作簿時需要大約26秒和3 GB記憶體,而我們的測試場景中的容器將.NET堆設限於512 MB。 Anthropic提供適用於終端機、VS Code和JetBrains IDEs、桌面和網頁的Claude Code。 在這些地方,代理人可以讀取儲存庫,更改文件並執行命令。

IronXL有第二種進入XLSX文件的方式。該讀取器無法處理來自未計算公式到.xls文件的多個輸入,某個未被告知它們的代理人可以回退到WorkBook.Load或者安靜地緩衝整個文件的重載。該指南為Claude Code提供了四個經測試的提示。Sonnet處理短任務,Opus在計畫模式下設計基準,並且只讀專案子代理審核結果。

四個提示中的三個以/model行開始,並且它選擇的模型保持活躍狀態,直到您選擇另一個。 Anthropic的模型配置頁面將sonnet別名作為日常編碼任務的選擇,並將opus作為複雜推理的選擇。

快速開始
NuGet使用NuGet安裝

PM > Install-Package IronXL.Excel

在 NuGet 包管理器控制台中運行上述命令安裝 IronXL,或在 NuGet 包管理器中搜索該包。

在儲存庫中打開終端並啟動claude。 將/model行送出作為獨立訊息,然後將其區塊其餘部分作為請求發送。輸入@在路徑前會附上該檔案,因此在寫入代碼前,列註釋會先到達代理。 提到註釋而不是工作簿,因為60 MB的壓縮XML供代碼閱讀。

/model sonnet

Add the IronXL.Excel NuGet package to LedgerScan.
Then read data/gl-2025.xlsx with it, without building a WorkBook.
The column notes are in @docs/ledger-export.md.
The license key is in the IRONXL_LICENSE_KEY environment variable. Don't print it.

Print every worksheet name first.
After that, make one forward-only pass over the Ledger sheet and print four figures:

- how many data rows the sheet holds
- the Amount total of the Posted rows
- how many seconds the pass took
- the peak working set of this process in megabytes
Text

在我們的運行中,Claude Code還傳遞標記第一行為標題的選項,因此每個單元格可以按列名讀取。 千兆比特的高峰表明代碼加載了工作簿,而超過600 MB的高峰意味著它將流或位元組數組交給IronXL。

StreamCell.Value持有每個數字作為裝箱的Double,所以將該值轉換為decimal會拋出InvalidCastException,而Convert.ToDecimal與不變文化是修復。 我們的每次運行從頭開始都使用Convert。



Claude Code在.NET Excel專案中做什麼?

在Excel專案中,Claude Code編寫總帳讀取器並將每個作為單獨的進程啟動。 您描述工作簿並複查返回的數據。

您如何設置Claude Code?

用Anthropic的快速啟用指南安裝Claude Code並登入。 當它開始並回复時,環境已就緒。

如何設立一個Claude Code可以工作的項目?

經過測試的儲存庫是一個.NET 9控制台應用,具有兩個輸入:總帳工作簿和描述其列的Markdown文件,以及記錄生產容器的512 MB堆設限。

每次會話打開時,Claude Code會讀取CLAUDE.md。 規則按URL命名流指導。 IronXL的llms.txt索引列出該指南,但其skill.md固定到IronXL 2026.8.1,一個在2026.9.2中發行StreamRows之前的版本。無論是該文件還是llms-full.txt都不提及StreamRows,因此只讀這些文件的代理只學習WorkBook.Load。 專案子代理是.claude/agents/下的一個Markdown文件,其首部信息命名它,說明何時使用它,列出它可能調用的工具,並選擇其模型。 IronXL已通過快速啟動被引用,現在一個提示寫了這兩個文件。

This repo needs a CLAUDE.md at its root, with a section named Large workbooks.
Write it so every later session starts from these rules:

- IronXL.Excel stays on the version LedgerScan.csproj references now.
- Read workbooks under data/ with WorkBook.StreamRows and a file path, never a Stream or byte[].
- Use WorkBook.Load in a test or benchmark that compares it with StreamRows.
- Outside those, use WorkBook.Load only when the file is .xls, has a password or must be edited.
- Any StreamCell can be null on a sparse row.
- Convert StreamCell.Value with Convert. Don't cast it.
- Memory and time figures come from a separate child process, one per reader.
- A long command runs in the foreground until it exits, never as a background task.
- The license key comes from IRONXL_LICENSE_KEY and nowhere else. Don't print it.
- The reference is https://ironsoftware.com/excel/csharp/how-to/stream-large-excel-files/.

Then create .claude/agents/stream-auditor.md, a project subagent that runs on sonnet.
Give it Read, Grep and Glob and no other tools, and a description that says when to use it.
It checks C# changes against that section and against IronXL.xml in the local NuGet cache.
It replies with the file, the line and the rule broken, and it edits nothing.
Text

Claude Code監視.claude/agents/中新文件,但僅在該資料夾在會話開始時存在時才監視。 在創建資料夾的此提示的儲存庫中,在下一個提示之前用claude --continue重啟以便子代理可用。

在首次讀取前解決授權。 沒有金鑰,流和表名調用在被調用的那一刻就會拋出LicensingException,在文件打開之前。 啟動時檢查License.IsLicensed。IronXL授權金鑰頁面涵蓋了獲取和存儲金鑰的過程。

哪些IronXL設定應該寫入CLAUDE.md?

對於手動書寫的CLAUDE.md,下面的區塊包含相同的部分。

## Large workbooks

- Keep IronXL.Excel on the version LedgerScan.csproj references now.
- Read workbooks under data/ with WorkBook.StreamRows and a file path, never a Stream or byte[].
- WorkBook.Load is fine in a test or benchmark that compares it with StreamRows.
- Anywhere else, use WorkBook.Load only when the file is .xls, has a password or must be edited.
- Any StreamCell can be null on a sparse row.
- Convert StreamCell.Value with Convert. Don't cast it.
- Take memory and time figures from a separate child process, one per reader.
- Run a long command in the foreground until it exits, never as a background task.
- Read the license key from IRONXL_LICENSE_KEY and nowhere else, and never print it.
- The reference is https://ironsoftware.com/excel/csharp/how-to/stream-large-excel-files/
Markdown

為什麼大型Excel文件在C#中需要流處理?

WorkBook.Load將完整的工作簿構建在內存中,所有單元格、樣式和公式可供隨機訪問和編輯。 該模型的成本遠高於文件。WorkBook.StreamRows按順序讀取工作表XML,每次保留一行,這就足夠進行匯入、總計和驗證。 下面的數據來自我們對60 MB XLSX文件(含有1,000,000行、十列和每行不同說明)的調校。 每個讀取器在自己的進程中運行三次,表格顯示中位數。

讀取器時間首行最高工作集512 MB堆設限
使用文件路徑的StreamRows10.6秒1.0秒178 MB在178 MB完成
使用流的StreamRows10.6秒1.6秒641 MB在1.5秒時內存不足
使用位元組數組的StreamRows10.4秒1.5秒628 MB在1.6秒時內存不足
使用文件路徑的WorkBook.Load26.4秒23.7秒3,072 MB在1.2秒內失敗

所有四個讀取器生成了相同的60個按地區和月份發佈的總計。

路徑讀取器的數據取決於文件中的文字。XLSX文件將每個不同的字符串保存一次,在共享字符串表中,包含很多條目的表使流更重且啟動更慢。 在500,000行時,一個重複258個字符串的工作簿以81 MB的峰值流出,首行用時0.22秒,而其描述均不同的工作簿需要130 MB和0.58秒。 百萬行固定設備攜帶超百萬個不同的字符串。

您應該使用哪種StreamRows重載?

只有採用文件路徑的重載。 StreamRows有九種重載,分別對應路徑、流或位元組數組輸入與工作表索引、工作表名稱或StreamReadOptions的配對。 路徑重載自磁盤逐部分讀取包。與流運輸一起傳遞的文件說明它們在解析之前將流複製到私人緩衝區中,因此IronXL不會關閉呼叫者擁有的流,並將該副本稱為"非低內存路徑"。 流指南在其重載表中劃定相同的界線。

對位元組數組重載的XML文檔仍將它們描述為"低內存讀取",但對於60 MB的設備,流和位元組數組重載都超過了文件磁盤大小的十倍以上。 接收文件作為流的上傳處理程序應將其保存到臨時文件並流路徑。

如何提示進行流基準測試?

要求整體比較在一個提示中進行,並讓Opus計劃它。 在/model opus行之後,按Shift+Tab循環權限模式,直到狀態欄顯示計畫模式打開,然後發送請求。計畫模式允許Claude Code讀取文件並運行shell命令,在您批准計畫之前不會編輯任何源文件。

/model opus

Plan a reader benchmark for data/gl-2025.xlsx under Ledger/, then build it.

I want three readers behind one interface.
Each one returns Posted Amount totals keyed by Region and the calendar month of PostedOn.

- PathStreamReader passes the file path to WorkBook.StreamRows.
- UploadStreamReader opens a FileStream and passes that stream, as an upload handler would.
- FullLoadReader calls WorkBook.Load and indexes cells with GetCellAt.

FullLoadReader reads WorkSheet.RowCount and ColumnCount once each, before its loops.
It never touches PhysicalColumnCount.

Add a bench command to Program.cs that does this:

1. Start this program again as a child process for each reader, with no memory limit.
2. Do the same with DOTNET_GCHeapHardLimit=0x20000000 in the child's environment.
3. Record exit code, wall-clock seconds, seconds until the first data row, and peak working set.
4. Write out/bench.csv with one line per reader and limit.
5. Write out/totals.csv from the path reader.
6. Fail the command if a reader that exited cleanly differs from the path reader on any total.

Run the bench, then ask @agent-stream-auditor to review Ledger/ and Program.cs.
Show me out/bench.csv and what the auditor found.
Text

提示的每部分都彌補了可能使數據看上去比實際表現更好的間隙。

  1. 一個文件的三個讀取器: 含有上傳風格的FileStream讀取器的集合,測試重載選擇,以及在流處理和載入間進行對照。
  2. 子環境的堆設限: DOTNET_GCHeapHardLimit設置垃圾收集器可能承諾的最大內存,為16進位數字節因此 0x20000000為512 MB。 超過的讀取器會在自身進程中失敗,基準會記錄退出代碼而不是崩潰。
  3. 總計必須一致:快速但不正確的讀取器使命令失敗。
  4. 子代理關閉轉向: @agent-stream-auditor直接命名專案子代理,因此Claude Code將審核委派給該子代理。
提示: 接受計劃,當它顯示子程序獲取其環境的位置以及總數被比較的位置時。 設置父過程的堆設限的計畫將限制每個讀取器,甚至包含基準。

提示清楚寫出讀取器如何遍歷工作表,因為完整載入的基準有自己的陷阱。 WorkSheet.RowCount每次讀取都需要時間,對於載入的百萬行表,一次呼叫需時33.5毫秒。 對每輪都讀取RowCount的循環每次都要付出這個代價,對於這張表來說大約多達9小時。 在循環前一次讀取計數將整個遍歷載入的單元格降至1.8秒。 WorkSheet.PhysicalColumnCount花費大得多。 在載入的總帳本上,一次呼叫需時45到50秒,將進程抬升到從3 GB到6.7 GB,而ColumnCount約一秒的十分之一返回相同的10列。 列舉WorkSheet.Rows不能避免該成本。對50,000行耗時8秒,對100,000行耗時61秒,而對百萬行表在15分鐘後都沒到達行100,000。

如何測量每個讀取器的內存使用?

在自己的進程中運行每個讀取器,因為工作集峰值是整個進程的高水位標記且從不下降。 在一次探測中,一個過程加載了工作簿,然後運行路徑讀取器,Process.PeakWorkingSet64報告流為3,047 MB,該數據為加載的結果。 獨立的進程保持了這兩個數據的分離。

Microsoft的垃圾收集器設置頁面指出.NET默認採用容器內存限制的75%,因此512 MB上限與容器限制約683 MB匹配。 在該上限下,流和位元組數組讀取器在全部三次校準重複中停止並顯示"內存不足。"。 全面加載兩次以相同的信息失敗一次,並曾以"無法從給定的流加載Excel。"的FileLoadException失敗一次。 流在解析過程中變得不可讀,表示可能內存不足以處理文件大小。"

StreamRows的限制是什麼?

StreamRows按照順序從XLSX工作表中讀取值,並且不做其他事情。 流指南列出了界限,下面的表格記錄了IronXL 2026.10.1在我們探測中對每一個的操作。

輸入StreamRowsWorkBook.Load
.xls文件OLE2NotOfficeXmlFileException加載
帶密碼的.xlsxOLE2NotOfficeXmlFileException用WorkBook.Load和密碼加載,否則ArgumentNullException
CSV文件ZipException "無法找到中央目錄"加載
帶有快取結果的公式快取結果,IsFormula為true公式和值
保存無結果的公式類型空白,值為null,IsFormula為true計算值
缺少路徑第一行上的ZipException "標頭中遇到EOF"FileNotFoundException
缺少工作表名稱第一行上的ArgumentException "未找到工作表'Ledger'。"不適用

前三行的例外來自IronXL內嵌名稱空間名中包含生成識別符的庫,因此無捕獲條款可以命名它們。 在第一遍枚舉周圍捕獲Exception,或者在流它之前檢查文件。 .xls文件和加密的.xlsx文件均以OLE2簽名開頭,即位元組D0 CF 11 E0。在第一次調用之前也檢查File.Exists。 在我們的探測中,流一個不存在的路徑在那裡創建了一個零字節文件,而後對該路徑的WorkBook.Load返回了一個具有空白表而不是錯誤的工作簿。

公式行對生成文件最為重要。 Excel將最後計算結果存儲於每個公式附近,流返回該結果。 由腳本或不使用EvaluateAll調用的IronXL本身寫入的工作簿僅保存公式,流然後看到一個空白單元格。 WorkBook.Load在讀取單元格的時候計算這些公式,所以匹配載入工作簿的總計並以流回覆時為零指向這種情況。 公式指南涵蓋了EvaluateAll。

三個較小的細節影響已流的值。

  • 行是稀疏的: 空白單元格在行的單元格中不存在,而索引器對它返回null。 TryGetCell對一個已知的列即使單元格本身為null也返回true。
  • 行號保持在其工作表位置: RowNumber是基於零的,因此工作表行2作為1到達,而空白工作表行被跳過而不對其后的行重新編號。
  • 日期是類型化的: 日期單元格報告日期類型,其值為DateTime,而其文本持有格式化字符串,在測試裝置的日期格式下為4-27-25。

對於足夠小可載入的工作簿,閱讀XLSX文件和選擇範圍涵蓋單元格逐步訪問。

如何在流式傳輸中處理Excel錯誤值?

從Excel保存的總帳可以包含錯誤值,例如無法查找留下的#N/A。 流以錯誤類型和錯誤文本(如"#N/A"或"#DIV/0!")作為字符串在其值中報告這樣的單元格,若錯誤是公式的快取結果,其公式標誌為真。 Convert.ToDecimal無法解析該字符串並拋出FormatException。 在我們的探測中,擁有其最後一行"#N/A"數量單元格的總帳副本在17.3秒讀取後拋出並無打印總計。

WorkBook.Load讀取錯誤單元格無拋出。 存儲的錯誤以字節值返回其錯誤代碼,#N/A為42,#DIV/0!為7,單元格文本顯示同一數字。 DecimalValue對每個錯誤單元格返回0,IsError為true。 在擁有2,000行和三個錯誤金額的總帳上,累計DecimalValue的載入讀取器而無警告計算出26,556.59的缺口。 一個將原始值轉換的計算器將兩個存儲的錯誤計算為42和7,然後在公式錯誤上拋出FormatException。

在轉換之前測試類型。 僅在其類型為StreamCellType.Number時轉換Amount,並按流指南的範例在其StreamCellType.Error情況下記錄任何其他單元格及其行。 使用該檢查,百萬行通行在17.6秒內完成,並標記了一個單元格,I1000001。其發佈總額為8,304,532,586.40,較乾淨文件少5,081.52,這是該行在放入錯誤之前持有的金額。 一個載入讀取器首先測試IsError。將標記的單元格打印到總計旁,以便可追溯短總計至其行。

如何退回到WorkBook.Load?

將第二份文件交給Claude Code並讓它比較兩個讀取器。 在最後的提示之前,我們的測試運行添加了一個40,000行、由腳本生成的工作簿。 其唯一的工作表命名為Adjustments,標題和空行位於標頭之上,並且每個Amount單元格都持有無存儲結果的公式。

/model sonnet

Finance added data/gl-2025-q4-adjustments.xlsx.
A Python script of theirs writes it instead of Excel.
It has one sheet, with a title block above the header row.

1. Run PathStreamReader over it and compare its Posted totals with FullLoadReader's.
2. Where they disagree, count the stream's Amount cells per Type, IsFormula and Value combination.
3. If some cells give the stream no figure, fall back to WorkBook.Load for that workbook alone.
4. Print which reader produced each total. data/gl-2025.xlsx keeps streaming.
5. Add the adjustments file to the bench as a second workbook.
6. For that workbook, compare every reader with the fallback totals.
7. Don't fail the bench when a stream reader's totals differ there.
8. Run the bench again, wait for it to exit, then read out/bench.csv.
9. Ask the stream-auditor subagent to review the files this turn changed and nothing else.

Tell me the adjustments total and which reader it came from.
Text

在我們的調校中,該文件以三種方式破壞了一個為總帳本撰寫的讀取程序。 要求Ledger工作表拋出ArgumentException。 有默認HeaderRowIndex 0時,標題名稱成為唯一標題名稱,而Amount索引器拋出"未知標頭列:'Amount'。" 設置標頭索引為2時,所有40,000個Amount單元格均作為空白公式返回,且已流發佈總計為0。

在信任生成的IronXL代碼之前應該驗證什麼?

每次更改後按順序完成這兩個檢查。

  • 構建成功: 在API參考中查找每個成員並從新的Release構建重新運行。
  • 最高峰值是路徑讀取器的: 在快速啟動提示下讀取每個峰值相對於閾值。

在實際運行中,這些提示產生了什麼結果?

本指南中的四個提示按順序發送給Claude Code,一個會話中,針對上面描述的儲存庫。 類型回复批准提示03的計畫。快速啟動提示未指定版本,因此運行安裝IronXL.Excel 2026.10.5。校準表使用2026.10.1,並且運行時間較長。

  • 在提示03之後,路徑讀取器在總帳本上達到177.3 MB的峰值,並在提示04之後達到253.4 MB。第四提示的代碼在讀取之前通過自己的StreamRows傳遞中找到標題行。
  • 在調整工作簿上,流式傳輸標記了36,045發佈行,因Amount單元格不可用。 按工作簿的退回全讀產生了15個總計,達到330,856,030.50,共284.3 MB的峰值,並且也在512 MB限制下完成。
  • 在限制下,只有路徑讀取器完成了總帳本,為253.1 MB。 FileStream讀取器在556.1 MB時內存不足,載入讀取器在531.0 MB失敗。
  • 無限制時,最終基準對FileStream讀取器達到669.1 MB的峰值,對載入讀取器為3,071.3 MB,首行返回用時43.24秒,而路徑讀取器為1.35秒。 所有60個總計都一致。
  • 快速啟動通行計數了1,000,000行,以19.32秒的8,304,537,667.92發佈總計,在180.96 MB的峰值。
  • 最後基準運行了12個子進程,對兩個工作簿各三個讀取器,不論有限制與否,並以代碼0退出。提交代碼的新Release構建重新運行它,其60個總帳本和15個調整總計與工作簿生成器記錄的值匹配。
  • 一些步驟與頁面上運行的不同。 提示03計畫以兩個問題結束,在批准後Claude Code按照其自己的建議,對每個子進程設置300秒的超時並不修改CLAUDE.md。 然後子代理報告提示03中的UploadStreamReader和提示04中的WorkBook.Load與打CLAUDE.md規則相抵觸,儘管提示要求兩者。 Claude Code將每個發現轉交且保持規則不變,因此若需返回乾淨的審閱應為每個添加豁免。 每個基準都在前台運行,且兩次審核都返回。
  • 早些時的一次運行使用了相同提示的更長措辭。其間子代理報告WorkSheet.RowCount和ColumnCount缺少,但IronXL.xml記錄了Range下的類WorkSheet繼承它們。 當運行中的自動模式也拒絕對提示04的子代理文件進行編輯作為自我修改,因此計畫自行批准該等編輯。 在此之前Claude Code兩次將基準作為背景任務啟動,並在兒童仍在運行時結束。 在這些運行中的第二個中,測試每次傳遞PhysicalColumnCount的一個標題循環也使載入子越過其五分鐘的超時。

運行記錄列出本指南和設置中的其他指南後面的版本、模型、計時和測試機。


疑難排解


問題?

如果您有任何疑問,請聯繫support@ironsoftware.com

Curtis Chau 擁有卡爾頓大學計算機科學學士學位,專注於前端開發,擅長於 Node.js、TypeScript、JavaScript 和 React。Curtis 熱衷於創建直觀且美觀的用戶界面,喜歡使用現代框架並打造結構良好、視覺吸引人的手冊。

閱讀更多

準備好開始了嗎?

NuGet 下載次數 2,393,101版本:2026.11剛剛發布