如何使用IronXL与GitHub Copilot

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

.NET报告解决方案可以将正确的数字写入普通工作簿中,但仍然会收到关于外观的请求。 财务部门希望它的标题颜色、千分位分隔符、突出显示的边距、可以在滚动时固定的标题行,以及可以指向其他工作表的名称。

IronXL提供了字体、填充、数字格式、条件规则、冻结窗格、列宽、表格和命名范围的样式调用。 两个提交到存储库的指令文件记录了这些调用的行为。

本指南为现有的月度销售报告样式化输出,并通过测试证明每种样式,测试将保存工作簿、再次打开并读取每个设置。 单元格格式化指南和条件格式化指南记录了这些调用本身。

快速入门
NuGet使用NuGet安装

PM > Install-Package IronXL.Excel

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

在解决方案根目录打开终端,启动copilot,并发送此提示。 Visual Studio聊天使用相同的两个文件作为#report-style.md和#ReportStyler.cs。

Read @docs/report-style.md, then fill in @src/FinanceReports/Styling/ReportStyler.cs.
Give it a public static ApplyHouseStyle(WorkBook workbook) method.
It styles the workbook that MonthlySalesReport.Build returns.
IronXL is the IronXL.Excel package.
Styling types are in IronXL.Styles and number formats in IronXL.Formatting.

Keep this first pass to the header row, the data rows and the Total row of the Sales sheet.
Set their fonts, fills, borders, alignment and number formats. The other sections come later.
Find the Total row by the word Total in column A. Don't count on a fixed row number.

1. Call ApplyHouseStyle from Program.cs just before SaveAs.
2. Run the job.
3. Load out/monthly-sales-2026-09.xlsx again.
4. Print the fill and font color of A1 and the FormatString of E2, exactly as IronXL gives them.
Text

提示没有关于IronXL在重新加载后如何报告颜色和格式的信息,因为路径特定的指令文件包含了这些规则。

在Copilot启动的环境中设置IRONXL_LICENSE_KEY,并查看许可证密钥指南以了解其他保存密钥的地方。 不要将其包含在提示和提交中。 这里的每个测试都会加载一个工作簿,因此无论在哪里运行测试,都必须存在密钥。



Copilot如何适应已经在Visual Studio中的项目中?

从终端使用Copilot CLI,或在Visual Studio或VS Code中使用代理模式进行您想要观察的样式更改,因为它可以自行构建解决方案并运行报告工作。 内联聊天足以进行单个文件的更改。 GitHub上的云代理接收分配的问题,并返回一个拉取请求。

如何为Copilot设置IronXL惯例?

将IronXL惯例提交为.github/copilot-instructions.md。 Copilot CLI、Visual Studio和VS Code中的聊天、云代理和Copilot代码审查全部读取它,因此将包、许可证规则和测试规则放在那里。

# Copilot instructions

## Workbooks

- Excel work uses IronXL from the IronXL.Excel NuGet package. Styling types
  live in IronXL.Styles, number formats in IronXL.Formatting, and comparison
  operators in IronXL.Formatting.Enums. Add no other spreadsheet package and
  no Office Interop.
- The IronXL version is pinned in Directory.Packages.props. Leave it alone
  unless the task is an upgrade.
- The license key comes from the IRONXL_LICENSE_KEY environment variable,
  and the program reads it there. Never put a key in code, settings files,
  tests or console output, and don't list environment variables.
- docs/report-style.md is the source for every color, border, format and
  name in the monthly sales workbook.
- IronXL documentation is at https://ironsoftware.com/excel/csharp/llms.txt
  and https://ironsoftware.com/excel/csharp/skill.md
- Say so whenever you depart from docs/report-style.md, and before you use
  an IronXL member you cannot find in IronXL.xml in the NuGet cache.

## Tests

- Build the workbook into a temporary folder, save it, load it again with
  WorkBook.Load and assert on what the loaded file reports.
- Never compare workbook bytes and never edit files under TestData.
Markdown

如何为样式代码设置其自己的规则?

仅影响设置或检查样式的代码的规则进入.github/instructions/workbook-styling.instructions.md。 其applyTo值命名两个文件夹,用逗号分隔,使规则能够到达样式器及其测试,并排除涉及CSV导入的请求。 GitHub的文档表明,只有当Copilot在文件模式匹配的文件上工作时,CLI才会包含文件。 在我们的运行中,Copilot CLI在每个会话中列出了文件的模式和路径,并告诉代理在更改代码前读取它。 代理在每次更改代码的提示中首次编辑前打开它,第二次则依赖于会话中已有的副本。

---
applyTo: "src/FinanceReports/Styling/**,tests/FinanceReports.Tests/**"
---

- IronXL returns colors as lowercase hex. A fill set with "#1F4E78" reads
  back as "#1f4e78", so compare colors ignoring case.
- A cell with no fill still reports BackgroundColor "#ffffff". Use
  FillPattern (NoFill or SolidForeground) to tell the two apart.
- FormatString only changes how numbers and dates display. A number written
  as a string keeps its raw text, its DecimalValue is 0, and SUM skips it.
- Font.Height is the size in points, the number Excel shows.
- Call AutoSizeColumn last. It measures the formatted text in the cell's
  font, and on a machine without that font it measures in Arial.
- AddNamedTable and AddNamedRange throw ArgumentException when the name
  already exists, and AddConditionalFormatting adds another copy of a rule
  on every call. Guard each one so restyling a styled workbook changes nothing.
- IronXL has no getter for freeze panes. Check one by reading the pane
  element in the sheet XML.
Markdown

在CLI会话中运行/instructions以确认在长提示之前两个文件中哪个文件处于激活状态。

IronXL如何在重新加载后回读单元格样式?

某些IronXL在WorkBook.Load后返还的值与代码传递的值不同。 使用IronXL 2026.10.1,使用"#FFFFFF"设置的字体回读为#ffffff,使用"#BFBFBF"设置的边框回读为#bfbfbf。 Assert.Equal("#1F4E78", cell.Style.BackgroundColor)在我们的参考工作簿上失败,而忽略大小写的对比测试通过。 报告写入日期值,IronXL为这些单元格设置的格式为m/d/yy h:mm,直到样式器设置yyyy-mm-dd。 使用#,##0.00,FormattedCellValue返回176,366.84,而Text仍然返回176366.84157142858,底层的数字。 写为字符串"-0.075"的边距在0.00%下保留了该文本,而IsText为真。 作为文本写入的收入数据保持格式字符串#,##0.00,因此仅检查FormatString的测试在该损坏的单元格上通过。 随软件包一起提供的XML文档以像素描述了Font.Height,但高度为12时被保存为大小12。

如何添加条件格式、冻结窗格和列宽?

边距规则来自CreateConditionalFormattingRule,它采用ComparisonOperator和一个公式,而AddConditionalFormatting将规则附加到范围上。 冻结标题是一个调用,CreateFreezePane(0, 1),第一个参数计算冻结的列,第二个计算冻结的行,因此CreateFreezePane(1, 4)冻结了A列和1到4行。列宽来自AutoSizeColumn。

Add three more parts of @docs/report-style.md to ApplyHouseStyle.
It lives in @src/FinanceReports/Styling/ReportStyler.cs.

- The margin highlighting. Both rules go on the data rows of column F and stay off the Total row.
- The frozen header row.
- The column widths. Size them as the very last step, after every font, fill and number format.

Run the job and reload the output. Then print:

- the range, operator and formula of each rule, as IronXL reads them
- the pane element in the Sales sheet's XML
- the width of columns A to F
Text

我们的参考样式器将列最后调整大小,并得到了A到F列的2,790、6,988、3,660、1,740、3,430和1,792的宽度,单位为GetColumn(i).Width运行中得到的1/256个字符的单位。 在格式之前先调整大小为单位得到1,587,收入为3,123,一旦千分位出现后过于狭窄,并且日期列为3,635,是根据更长的默认日期时间格式测量的。

字体也会改变数字。 在我们的Windows机器上,未安装的四种字体产生了与Arial完全相同的宽度,而Arial比Calibri宽6%到9%。 因此,任何缺少报告所需字体的运行器都会导致测试固定的精确宽度失败。

冻结窗格在工作表XML中写为<pane ySplit="1" topLeftCell="A2" activePane="bottomLeft" state="frozen"/>,经过IronXL加载和保存后仍然存在。

IronXL将每个规则填充保存为xl/styles.xml中的自定义索引调色板中的一个条目,我们的文件保留了正确的颜色,FFC7CE和C6EFCE。 通过PatternFormatting.BackgroundColor回读,两个规则都报告了#ffc7ce。 每个规则的范围、运算符、公式和字体颜色回读正确。 只有填充需要文件,但从中读取两种颜色让一个测试助手覆盖它们。

如何添加命名表格和命名范围?

样式文档中的名称来自两个调用。 AddNamedTable("SalesData", range, true, TableStyle.TableStyleLight9, true)将标题和数据行转换为带有过滤按钮的表。 AddNamedRange("TotalRevenue", range, true)为总计行的收入单元格提供一个工作簿范围的名称,汇总公式可以将其用作=TotalRevenue。 在EvaluateAll后,该公式返回的总计与它命名的单元格相同。 FindNamedRange("TotalRevenue")将引用作为文本'Sales'!$E$38:$E$38返回,而不是Range。 SaveAsNamedTable和SaveAsNamedRange在Range上执行相同的工作。

四个调用没有检查现有名称。 在已经样式化的工作簿上再次运行样式器,AddNamedTable抛出ArgumentException,消息为"工作簿已经包含名称为: SalesData的表"。 AddNamedRange对TotalRevenue也如此,两个SaveAs调用抛出相同的两个异常。 AddConditionalFormatting没有抛出,在我们的测试中第二次运行将工作表从两个边距规则变为四个。 IronXL还拒绝了表格名称Sales Table,抛出ArgumentException,称名称不能包含空格。

Finish @src/FinanceReports/Styling/ReportStyler.cs with what's left in @docs/report-style.md.
That's the SalesData table, the TotalRevenue name and the Summary sheet rules.
Column sizing stays the final step.

Finance fixes figures directly in a saved workbook and sends it back for the house style.
So add a restyle <path> command to Program.cs.
It loads the file, calls ApplyHouseStyle and saves the file over itself.
Restyling a file twice has to leave exactly one table, one TotalRevenue name and two margin rules.

Show me that it holds:

1. Run the job once.
2. Make a copy of the output in out/ and restyle that copy twice.
3. After each pass, print the table names, named ranges, rule count and the value of Summary!B2.
Text

在添加新规则之前使用RemoveConditionalFormatting删除旧的边距规则,或跳过工作表已经持有的规则,将规则计数保持在两个,并在每次添加前检查GetNamedTableNames和GetNamedRanges阻止第二次传递抛出。

如何在重新加载后测试Excel样式?

在任何单个测试有用之前,套件需要一些助手,分别用于读取工作表XML和解析规则颜色,因此这个提示从/plan开始。 在计划模式下,Copilot CLI在您批准计划之前会阻止对项目文件的编辑。

/plan an xUnit suite in tests/FinanceReports.Tests that checks the house style after a reload.

Build the September report into a temp folder, save it and open it again with WorkBook.Load.
Then check each rule in docs/report-style.md against what the reopened file holds.

- Check FillPattern beside every fill color.
- Read the frozen pane from the Sales sheet XML with ZipArchive.
- For the margin rules, read each rule's range, operator and formula through IronXL.
- Resolve each rule's fill and font color from its dxf entry in xl/styles.xml.
- An indexed color there points into the indexedColors list, so follow it.
- Check FormattedCellValue for a sample of cells in every numeric column.
- Add a test that restyles a saved copy twice.
- For the widths, autosize a reloaded copy again and confirm no column moves.
- Never assert an exact column width.

Implement the plan, then run dotnet test.
Text

为什么格式化的单元格值取决于文化?

IronXL使用当前.NET文化格式化FormattedCellValue。 无论如何,工作簿是相同的文件,我们尝试的每种文化中格式字符串都读为#,##0.00。

  • en-CA: 收入单元格显示为176,366.84。
  • de-DE: 相同单元格显示为176.366,84。
  • fr-FR: 相同单元格显示为176 366,84,其中间隙是窄不间断空格(U+202F)。

-0.075的边距格式化为0.00%在de-DE和fr-FR中返回为-7,50%。 Text也发生变化,而DecimalValue则没有。

Copilot从/plan提示写的套件直接比较这些字符串,例如Assert.Equal("47,999.33", ...)在第一个收入单元格上。 我们在de-DE下再次运行它,然后在fr-FR下运行。 房屋样式测试在两次都失败,实际值为47.999,33和47 999,33,另外三个测试通过。

在测试顶部将CultureInfo.CurrentCulture设置为en-US使其在de-DE和fr-FR下再次通过。 一个加载了de-DE的工作簿并在切换到en-US后读取时也给出了176,366.84,因此测试读取单元格时生效的是当前的设置。 在任何比较显示字符串的测试中都钉住文化,或者比较DecimalValue和FormatString。 同事的笔记本电脑或云代理的环境可以与产生预期字符串的机器的文化不同。

是什么让云代理能够处理一个问题?

云代理收到问题标题、描述、问题上已有的评论以及分配中添加的任何说明。 GitHub表示它看不到之后发布的评论,因此每个要求和关闭任务的测试都属于问题主体。

Title: Add an XLS copy of the monthly sales workbook for the ERP import

**Files:** src/FinanceReports/Program.cs, src/FinanceReports/Styling/ReportStyler.cs
**IronXL version:** as pinned in Directory.Packages.props
**Framework:** .NET 9

**Expected:** Each run writes out/monthly-sales-2026-09.xls next to the XLSX,
with the same values and the house style in docs/report-style.md, except the
SalesData table. The TotalRevenue name and Summary!B2 stay.

**Actual:** The ERP import accepts only .xls, and finance converts the file by
hand every month.

**Constraints:** Leave the XLSX output unchanged. Build the XLS workbook with
WorkBook.Create(ExcelFileFormat.XLS) rather than saving the XLSX under a new
extension. In XLS, set every fill before any font color. No new packages.

**Acceptance:** dotnet test passes, plus tests that reopen the .xls and check
the header fill and white header text, the four number formats, the
TotalRevenue name and the operator and formula of both margin rules.
Markdown

问题中的XLS规则来自测量。

  • 命名表格: 在XLS工作簿上的AddNamedTable和SaveAsNamedTable抛出NotSupportedException,消息为"仅支持XLSX中的命名表格。"
  • 带.xls路径的SaveAs: 在已样式化的XLSX工作簿上SaveAs抛出FormulaParseException,消息称当前工作簿中不存在命名范围TotalRevenue。
  • 填充顺序: XLS将颜色存储在共享调色板中,在一次探测中,将标题字体设置为白色后添加的三个填充返回为#ddebf7,即这三填中的第二个,而先设置填充则保持为#ffffff。
  • 规则填充: 从重新加载的XLS文件中读取边距规则的填充抛出NullReferenceException,因此接受行要求每个规则的运算符和公式而不是它的颜色。

为什么云代理的测试在IronXL项目中失败?

默认情况下,代理的环境运行Ubuntu Linux。 当所有样式测试在代理推送的分支上同时失败时,在diff之前读取第一个异常。 LicensingException指向许可证密钥。

云代理无法读取Actions、Codespaces或Dependabot秘密,因此需要Agents秘密密钥。 在设置、秘密和变量、代理下添加IRONXL_LICENSE_KEY,代理将其接收为环境变量。 代理的拉取请求进入实际的存储库,因此保持分支保护和人的批准开启。

为什么来自其他库的工作簿样式化失败?

来自EMEA办公室,由openpyxl上的Python作业撰写的工作簿与报告布局相同,从第一个被调用的样式设置器开始抛出InvalidOperationException,消息为"Nullable对象必须有一个值",无论是设置粗体文本或数字格式。 所有我们自己作业编写的工作簿都可以使用ApplyHouseStyle,这使得样式器中的bug看起来像是文件中的问题所致。

A colleague added tests/FinanceReports.Tests/PartnerWorkbookTests.cs and it fails.
It covers the workbooks the EMEA office sends, which a Python job writes with openpyxl.
It throws InvalidOperationException "Nullable object must have a value".
The exception comes from deep inside the first style setter.
ApplyHouseStyle still passes on our own output.

Before you edit anything, find out what causes it and tell me:

1. Open TestData/partner/emea-2026-09.xlsx and one workbook our job writes with ZipArchive.
2. Compare the fill entries in xl/styles.xml.
3. Try a single style setter on each workbook.

Then fix it at the point where the restyle command and this test load a workbook.
Leave the partner file untouched on disk and add no package.
Run dotnet test when you're done.
Text

合作伙伴文件的第一个填充是<patternFill />,没有patternType属性,这是openpyxl 3.1.5为其默认填充编写的。 我们的作业文件在相同位置有<patternFill patternType="none"/>。 IronXL加载了合作伙伴文件并读取其值而未发生错误。 加载它并通过IronXL保存后再重新加载保持了裸元素并仍然抛出异常。 将缺失的属性添加到内存中的该元素,并通过WorkBook.Load(Stream)或者tmp的副本加载修补过的包,使得完整的家庭风格得以应用,并且在磁盘上的文件保持合作伙伴发送的状态。

在加载步骤保持修复可以阻止助手在样式器内部捕获异常,这会掩盖问题并使合作伙伴工作簿没有样式。

合并前应检查什么?

GitHub的文档显示/review作为copilot -p提示发送,因此此审查可以在合并前运行一个脚本。

/review the commits on this branch after the first one.
Check them against docs/report-style.md and both instruction files under .github.

Flag any of these:

- a color compared with case-sensitive equality
- an AutoSizeColumn call that runs before a later format or font change
- an AddNamedTable, AddNamedRange or AddConditionalFormatting call with no guard for a second run
- a test that pins an exact column width or compares workbook bytes
- an IronXL member that isn't in IronXL.xml in the NuGet cache

Give each finding its file and line. Don't edit anything.
Text

提示命名了两个指令文件,因此样式规则适用于整个审查,而不仅限于与模式匹配的文件。 GitHub上的Copilot代码审查还支持路径特定的文件。

diff仍然需要人为检查,这是审查和测试可能遗漏的唯一事情,即值是否发生变化。 样式化必须将每个数字和日期保留为报告撰写时的样子,除Summary!B2外每个公式不变,样式文档将其移到TotalRevenue名称上。 总计应与CSV提要匹配。

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

Copilot CLI按顺序接收六个提示,键盘上无人。 前五个共享一个会话,/plan提示在计划模式和自动驾驶运行,/review作为其自身的copilot -p调用运行。 目标是一个为本指南在.NET 9上构建的报告解决方案,其中一个控制台作业从CSV提要编写未经样式化的九月工作簿,一个尚无测试的xUnit项目和样式文档。 合作伙伴提示之前的提交添加了EMEA工作簿和同事失败的测试。以下每个图来自重建解决方案、重新运行作业并在Copilot完成后运行测试。 AI编码助手指南将此类型的检查变成可重复的测试。

  • 我们的样式检查在第一个提示后通过了30个检查中的23个,其中包括每个标题、数据和总计检查。 在规则、窗格和宽度之后通过了30个中的25个,而在名字和重新样式命令后31个中通过了31个,并且每个值仍然与CSV提要匹配。
  • 在第二个提示之后,列宽与我们的参考样式器完全匹配,并且两个边距规则位于F2:F37上。
  • 重新样式化两次的副本留下了一个表格,一个TotalRevenue名称和两个边距规则,Summary!B2仍然返回10,977,073.68。
  • 计划套件通过了3个测试中的3个。 在最终代码的副本中将列大小调整移动到格式之前使其宽度测试失败。
  • 在合作伙伴提示之后,4个测试中4个通过,EMEA工作簿的重新样式化副本通过所有32个检查。
  • /review调用没有发现列出的五个问题中的任何一个。
  • 有些步骤与页面中的运行不一样。 第一个提示还添加了两个边距规则,页面将其留给第二个。 在较早的运行中,宽度测试仅检查宽度是否存在并在先调整列大小时通过,因此/plan提示现在要求进行第二次自动调整大小。 问题、云代理、Agents秘密和拉取请求审查需要托管的存储库,因此都没有运行。

Copilot CLI版本、Auto选择的模型、运行时间和测试机器为每个指南在运行记录中记录一次。


故障排除


有问题吗?

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

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

阅读更多

准备开始了吗?

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