如何在Claude Code中使用IronXL

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

一个包含100万条日记账行的总帐导出在Excel中打开时没有报错,但在需要读取它的导入作业中出现停止。 在我们的测试机上,WorkBook.Load需要大约26秒和3GB内存来读取一个60 MB大小的工作簿,而在我们的测试场景中,容器限制了.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,因此将该值转换为小数会抛出InvalidCastException,使用不变文化的Convert.ToDecimal是修复方法。 我们每次运行都从开始使用Convert。



Claude Code在.NET Excel项目中做什么?

在Excel项目中,Claude Code编写了分类帐读取器,并将每个读取器作为独立进程启动。 您描述工作簿并审核返回的数字。

如何设置Claude Code?

使用Anthropic的快速入门安装Claude Code并登录。 当它启动并回复后,环境已准备就绪。

如何设置一个Claude Code可以工作的项目吗?

经过测试的存储库是一个.NET 9控制台应用程序,具有两个输入:分类帐工作簿和描述其列并记录生产容器512 MB堆限制的Markdown文件。

每个会话打开时,Claude Code会读取CLAUDE.md。 规则通过URL命名流指南。 IronXL的llms.txt索引列出了指南,但其skill.md固定在IronXL 2026.8.1版上,即StreamRows于2026.9.2发布之前的版本。该文件或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堆限制
用文件路径流行行10.6秒1.0秒178 MB在178 MB处完成
用流流行行10.6秒1.6秒641 MB在1.5秒处内存不足
用字节数组流行行10.4秒1.5秒628 MB在1.6秒处内存不足
用文件路径加载工作簿26.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设置垃圾回收器可能提交的最大内存,以十六进制字节计数,所以0x20000000是512 MB。 超出它的读取器在自己的进程中失败,基准记录退出代码而不会崩溃。
  3. 总和必须一致:快速且错误的读取器会使命令失败。
  4. 子代理关闭回合:@agent-stream-auditor直接命名项目子代理,因此Claude Code将审查委托给该子代理。
提示: 当计划显示子进程从何处获取环境以及总数何时进行比较时,接受该计划。 一个在父进程上设置堆上限的计划会限制所有读取器,包括基准本身。

提示说明了加载读取器如何遍历工作表,因为完全加载的基准线本身就有一个陷阱。 WorkSheet.RowCount在每次读取时都要耗时,在加载的百万行工作表上一通话就耗时33.5毫秒。 在每次传递中读取RowCount的循环需要每次支付此费用,这对于此工作表需要大约九小时。 在循环之前读取计数一次,将整个加载的单元格遍历降低到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限制的容器相匹配。 在该限制下,流和字节数组读取器在所有三次校准重复中都停止于"内存不足"。 完全加载两次失败,具有相同的消息,且有一次带有FileLoadException和"无法从给定流加载Excel"。 流在解析过程中变得不可读,这可能表示文件大小不足的内存。

StreamRows的限制是什么?

StreamRows按顺序从XLSX工作表中读取值,且不做其他事情。 流指南列出界限,下表记录了我们探测中IronXL 2026.10.1对每一个的处理。

输入StreamRowsWorkBook.Load
.xls文件OLE2NotOfficeXmlFileException加载
带密码的.xlsx文件OLE2NotOfficeXmlFileException使用Workbook.Load和密码加载,否则ArgumentNullException
CSV文件ZipException"无法找到中心目录"加载
具有缓存结果的公式缓存结果,IsFormula为真公式和值
保存无结果的公式类型为空,值为空,IsFormula为真计算值
缺少路径第一行上的ZipException"EOF在标头中"FileNotFoundException
缺少工作表名称第一行上的ArgumentException"未找到工作表'Ledger'"。不适用

前面三行中的异常来自IronXL中嵌入的库,这些库包含一个生成的标识符的命名空间名,因此没有catch子句可以命名它们。 在第一次枚举周围捕获Exception,或在流传输之前检查文件。 .xls文件和加密的.xlsx文件都以OLE2签名开头,即字节D0 CF 11 E0。也在第一次调用之前检查File.Exists。 在我们的探测中,流传输一个不存在的路径在那里创建了一个零字节文件,而随后WorkBook.Load该路径返回一个具有一个空白工作表的工作簿而不是错误。

生成文件的公式行最为重要。 Excel将最后计算的结果保存在每个公式旁边,流返回该结果。 由脚本编写的工作簿或没有调用EvaluateAll保存的IronXL本身仅存储公式,流然后视为空单元格。 WorkBook.Load在读取单元格时计算这些公式,因此在加载的工作簿中匹配并从流返回为零的总和指向这种情况。 公式指南涵盖EvaluateAll。

三个小细节影响流传输值。

  • 行是稀疏的:空白单元格在行的单元格中不存在,索引返回null。 TryGetCell即使单元格本身为空,已知列的返回值仍为真。
  • 行号保持在其工作表位置:RowNumber是从零开始的,因此工作表行2作为1到达,空白工作表行被跳过,不会重新编号它后的行。
  • 日期类型输入:日期单元格报告日期类型,其值为DateTime,而其文本保留格式化字符串,夹具的日期格式为4-27-25。

对于足够小以装载的工作薄,读取XLSX文件和选择范围涵盖单元至单元访问。

在流传输时如何处理Excel错误值?

从Excel保存的分类账可以携带错误值,例如失败查找留下的#N/A。 流将报告此类单元格,带有错误类型和错误文本"#N/A"或"#DIV/0!",作为其值中的字符串,并且当错误是公式的缓存结果时,其公式标志为真。 Convert.ToDecimal不能解析该字符串并抛出FormatException。 在我们的探测中,分类账的副本在其最后一行的金额单元格中具有#N/A,在第1,000,001行的表格行中,在读取后17.3秒抛出,并且没有打印总数。

WorkBook.Load读取错误单元格,不会抛出异常。 存储的错误以字节值42表示#N/A,以7表示#DIV/0!,单元格文本显示相同的数字。 DecimalValue为每个错误单元格返回0,并且IsError为真。 在具有三个错误金额的2,000行分类账中,加载读取器累计DecimalValue出来26,556.59,且没有警告。 将原始值转换回来的一个计为两个存储的错误,分别为42和7,然后在公式错误上抛出FormatException。

在转换之前测试类型。 仅当金额的类型是StreamCellType.Number时才转换,并用其行记录任何其他单元格,正如流指南中的示例在其StreamCellType.Error案例中所做的那样。 检查该检查时,百万行传递在17.6秒内完成,并标记了一个单元格,即I1000001。其发布总额为8,304,532,586.40,比干净文件低5,081.52,即该行在错误进入之前持有的金额。 加载读取器首先测试IsError。在总和旁边打印标记的单元格,以便可以追溯到其行的短总和。

如何回退到WorkBook.Load?

将第二个文件交给Claude Code并让其在其上比较两个读取器。 在最后一个提示之前,我们的测试运行添加了一个由脚本生成的40,000行工作簿。 其唯一的工作表命名为Adjustments,上方的标题和空行坐在标题上方,每个金额单元格持有没有存储结果的公式。

/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'"。当标题索引设置为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个发布行,带有不可用的金额单元格。 每个工作簿的回退到完全加载产生了15个总和,累加为330,856,030.50,峰值为284.3 MB,并且还在512 MB限制下完成。
  • 在限制下,只有路径读取器在253.1 MB处完成了分类账。 FileStream读取器在556.1 MB处内存不足,加载读取器在531.0 MB处失败。
  • 没有限制,最后的测试在FileStream读取器上达到了689.1 MB的峰值,在加载读取器上达到了3,071.3 MB的峰值,后者在43.24秒后返回其第一行,而路径读取器在1.35秒内返回。 所有60个总和一致。
  • 快速入门计数在19.32秒内记录了1,000,000行,其发布总额为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在工作表下的文档记录了它们。 在该运行中的自动模式还拒绝了提示04中的子代理文件编辑,认为是自我修改,因此计划自行批准此类编辑。 在此之前,Claude Code两次作为后台任务开始了基准测试,当孩子们仍在运行时结束了其回合。 在这些运行的第二次,测试PhysicalColumnCount的标题循环在每一次传递中都忙于加载的孩子,并且超过了其五分钟超时。

《运行记录》列出了该指南及套件中其他指南所基于的版本、模型、时间和测试机器。


故障排除


有问题吗?

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

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

阅读更多

准备开始了吗?

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