如何在 GitHub Copilot 中使用 IronXL
.NET 報告解決方案已經能夠將正確的數字寫入簡單的工作簿並且仍然接收到有關外觀的要求。 財務部想要其標題顏色、千位分隔符號、突出的邊界、在滾動時始終位於固定位置的標題行,以及可以被其他表指向的名稱。
IronXL 提供字體、填充、數字格式、條件規則、凍結窗格、列寬、表和命名範圍的樣式調用。 提交到存儲庫的兩個指令文件記錄這些調用的行為。
本指南對現有月度銷售報告的輸出進行樣式設定,並通過檢測來驗證每種樣式,這些檢測分別保存工作簿、重新打開並讀取每個設置。 儲存格格式指南和條件格式指南記錄了調用本身。
快速開始在方案根目錄中打開終端機,啟動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.
提示中未提到 IronXL 在重新加載後如何報告顏色和格式,因為路徑特定的指令文件包含這些規則。
在Copilot啟動的環境中設置IRONXL_LICENSE_KEY,並查看授權金鑰指南以了解保留金鑰的其他位置。 避免在提示和提交中包含密鑰。 此處的每個檢測都會加載一個工作簿,因此無論檢測在哪裡運行,密鑰都必須存在。
最小工作流程(5 個步驟)
- 從NuGet下載C# Excel程式庫
- 記錄 IronXL 在 中的報告樣式以及路徑特定的 文件。
- 樣式設定後,數據和總計行,然後添加條件規則、凍結頭和名稱,最後調整列大小。
- 在檢測中重新加載每個保存的工作簿並檢查每種樣式,從 sheet XML 中讀取凍結窗格。
- 將XLS後續工作指派給雲代理作為問題,並根據API參考檢查其拉取請求。
Copilot 如何融入已在 Visual Studio 的項目中?
從終端使用 Copilot CLI,或者在 Visual Studio 或 VS Code 中使用代理模式進行希望查看的樣式更改,因為它可以自行構建解決方案並運行報告工作。 內聯聊天適用於單文件修改。 GitHub 上的雲代理會接受指定的議題並返回一個 pull request。
您如何為 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.
您如何為樣式代碼賦予其自身的規則?
僅對設置或檢查樣式的代碼重要的規則放入.github/instructions/workbook-styling.instructions.md。 其applyTo值名稱由逗號分隔的兩個文件夾,從而使規則影響樣式調整程序及其測試,並避免涉及CSV導入的請求。 GitHub 的文檔介紹了只有當 Copilot 操作與 glob 匹配的文件時,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.
在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
我們的參考樣式調整程序最後調整了列的大小,自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 寬度,比 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.
在添加新規則之前使用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.
為什麼格式化單元格價值依賴文化?
IronXL使用當前.NET文化格式化FormattedCellValue。 工作簿在任何情況下都是相同的文件,我們嘗試的每一種文化中格式字符串讀取為#,##0.00。
- en-CA:一個收入單元格顯示 176,366.84。
- de-DE:同一單元格顯示 176.366,84。
- fr-FR:同一單元格顯示 176 366,84,其中空隙是一個窄的不換行空格(U+202F)。
格式化為0.00%的-0.075邊距在de-DE和fr-FR中回來的結果均為-7,50%。 Text也會變化,而DecimalValue則不會。
從/plan提示中寫出的套件Copilot直接比較這些字符串,例如第一次收入單元格上的Assert.Equal("47,999.33", ...)。 我們在 de-DE 和 fr-FR 下再次運行它。 內部風格測試兩次都失敗,實際值分別為 47.999,33 和 47 999,33,其他三個測試通過。
在測試的頂部將CultureInfo.CurrentCulture設置為en-US,使其再次對de-DE和fr-FR通過。 在轉換到 en-US 後讀取一個使用 de-DE 加載的工作簿也生成了 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.
問題中的 XLS 規則來自測量結果。
- 命名表格:
AddNamedTable和SaveAsNamedTable在XLS工作簿上拋出NotSupportedException,消息為"僅XLSX支持命名表格。" - 帶有.xls路徑的SaveAs: 對格式化的XLSX工作簿,
SaveAs拋出FormulaParseException,消息指出命名範圍TotalRevenue在當前工作簿中不存在。 - 填充順序:XLS 在共享調色板中儲存顏色,在一次檢測中,設置為白色的邊界字體來自三次填充中的第二個,回傳為 #ddebf7,而首先設置填充將其保持為 #ffffff。
- 規則填充:從重新加載的 XLS 文件中讀取邊界規則的填充拋出 NullReferenceException,因此接受行要求每個規則的運算符和公式,而不是其顏色。
為什麼雲代理的測試在 IronXL 項目上失敗?
默認情況下代理的環境運行於 Ubuntu Linux。 當所有樣式測試在代理推送的一個分支上一起失敗時,請先閱讀異動之前的第一個異常。 LicensingException 指向許可鑰匙。
雲代理不能讀取 Actions、Codespaces 或 Dependabot 秘密,所以需要一個 Agents 秘密來存儲密鑰。 在"設定"下添加IRONXL_LICENSE_KEY,然後依次是Secrets和變數,然後是代理,代理將其接收為環境變數。 代理的 pull requests 進入實際的存庫,因此保持分支保護和人工批准開啟。
為什麼來自其他程式庫的工作簿上的樣式失敗?
一個來自 EMEA 辦事處,使用 Python 作業在 openpyxl 上寫入並與報告佈局相同的工作簿拋出 InvalidOperationException,信息顯示“可空對象必須有一個值”,無論是否設置粗體文本或數字格式。 ApplyHouseStyle在我們自己任務寫入的每個工作簿上均有效,這使得當原因在文件中時,看上去是樣式調整程序中的一個錯誤。
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.
合作夥伴文件的第一種填充是<patternFill />,沒有patternType屬性,這是openpyxl 3.1.5為其默認填充寫入的。 我們工作的文件在相同的地方有<patternFill patternType="none"/>。 IronXL 加載了合作夥伴文件並無錯誤地讀取了它的值。 加載它,通過 IronXL 保存並再次加載仍然保留原有元素,並仍然引發異常。 在內存中向該元素添加遺漏的屬性並加載補丁包,通過我們探測中的WorkBook.Load(Stream)或從臨時副本中,可以應用完整的樣式,而磁碟上的文件則保持如合作夥伴所傳送的模樣。
在加載步驟保持修復阻止助手在樣式師內捕獲異常,這會掩蓋問題並使合作夥伴工作簿未樣式化。
合併之前應檢查什麼?
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.
提示命名了兩個指令文件,以使樣式規則適用於整個審查,而不僅僅限於 glob 匹配的文件。 GitHub 上的 Copilot 程序碼評審也支持路徑特定文件。
異動仍需要人工讀來發現評審和測試可能會錯過的唯一一件事,那就是值是否改變。 樣式設定必須保留每一個數字和日期,正如報告所寫的那樣,並且每一個公式除外——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 秘密和 pull request 審查需要託管的存庫,因此沒有一個運行。
每個指南在運行記錄中記錄Copilot CLI版本、自動駕駛儀選擇的模型、運行時間和測試機器。
疑難排解
- 當測試在設置任何樣式之前拋出LicensingException時,在IronXL中應用授權金鑰
- C# Excel條件格式以添加、讀取並移除邊距規則
- C# Excel儲存格格式化用於
FormatString值和內建格式 - 自動調整Excel列和行的大小用於自動調整大小調用和Excel測量寬度的單位
- 在Excel中添加命名表格用於表格樣式和篩選按鈕
問題?
如果您有任何疑問,請聯繫support@ironsoftware.com
Curtis Chau 擁有卡爾頓大學計算機科學學士學位,專注於前端開發,擅長於 Node.js、TypeScript、JavaScript 和 React。Curtis 熱衷於創建直觀且美觀的用戶界面,喜歡使用現代框架並打造結構良好、視覺吸引人的手冊。