如何使用 IronPrint 結合 GitHub Copilot
一個貨運倉庫為每個離開其裝卸台的拖車列印運輸交接單。 該倉庫的網路入口網站將每個表單儲存為填寫的 PDF,其中包含駕駛、封條號碼、托盤數量和危險品等欄位,並且在 Visual Studio 解決方案中的 .NET 服務會印出每個 PDF 的兩份副本。 一位助理編輯該服務,必須在團隊已經使用的編輯器中操作該解決方案。
GitHub Copilot 在 Visual Studio 和 VS Code 中提供聊天和代理模式、終端機 Copilot CLI,以及可以透過拉請求回應指派問題的 GitHub 雲端代理。IronPrint 將 PDF 和圖片從 .NET 發送到印表機,紙張大小、份數、解析度及表單扁平設置一次設在單一的 PrintSettings 物件上。 這些 Copilot 表面都從儲存庫中的指令文件中讀取 IronPrint 規則。
以下的提示向 Copilot 索取基於 IronPrint 的列印代碼。 選擇印表機硬體或配置列印伺服器是無法從儲存庫執行的獨立任務。 扁平化指南描述了這些表格所依的 IronPrint 設定。
快速開始從解決方案資料夾中啟動 copilot 並發送提示。 在 CLI 中,@ 在路徑之前附加該檔案。在 Visual Studio 中,Copilot Chat 使用 # 來達到相同目的。
Fill in @src/Depot.Printing/HandoverPrinter.cs so the depot can print its handover forms.
Use IronPrint 2026.10.1, the version Directory.Packages.props already pins.
Give the class three public static members:
- InstalledPrinters() returns the names from Printer.GetPrinterNames.
- BuildSettings(string printerName) returns the PrintSettings that @docs/print-profile.md describes.
- PrintAsync(string pdfPath, string printerName) checks the name first, then sends the job.
An unknown name throws an ArgumentException whose message lists the installed printers.
Build the solution and fix every error.
Then list the files you changed.
提示不涉及任何個別設定。 docs/print-profile.md 中的列印配置列舉了每一個,其中包含 Flatten。
授權金鑰放入 IRONPRINT_LICENSE_KEY,設定在 Copilot 執行的環境中。 IronPrint 本身並不讀取該變數。 在我們的測試中,設置該變數時 License.IsLicensed 始終為 false,直到程式將其值指定給 License.LicenseKey。 其他支援金鑰的地方在 授權金鑰指南 中列出。
最小工作流程(5 個步驟)
- 從NuGet下載C#打印庫
- 將 IronPrint 規則寫入 .github/copilot-instructions.md 以及一個特定路徑的指令檔案
- 在每個表單工作上設置 Flatten,並檢查每個印表機名稱是否匹配已安裝列表
- 測試代碼建構的 PrintSettings 而不是發送實際工作
- 將下一個變更指派給雲端代理作為問題,並根據 IronPrint API 參考 驗證拉請求
如何為 Copilot 設定 IronPrint 慣例?
專案範圍的規則屬於 .github/copilot-instructions.md。 GitHub 的支援矩陣顯示該文件在 Visual Studio、VS Code 和 JetBrains IDEs 的 Copilot Chat 中受支援,以及 Copilot CLI、Copilot 代碼檢視和雲端代理。 Visual Studio 僅當自訂指導核取方塊被選中時,才將該文件加入到 Copilot Chat 請求中,位於選項設定的 GitHub、Copilot、Copilot Chat 下。
These rules apply to printing code in this repository:
- Handover forms print through IronPrint. The NuGet package and the namespace are both IronPrint.
- Add no other printing library and no System.Drawing.Printing code.
- Keep the IronPrint version that Directory.Packages.props sets. Only an upgrade task changes it.
- IRONPRINT_LICENSE_KEY holds the license key.
- IronPrint does not read that variable, so Program.cs copies its value into License.LicenseKey.
- Never print the value, and don't dump environment variables either.
- docs/print-profile.md is the print contract. Leave it as it is and suggest changes in your reply.
- https://ironsoftware.com/print/csharp/llms.txt indexes IronPrint's docs for agents.
- No printer on this machine finishes a job without someone answering a dialog.
- Don't send a print job from a session, a test or a dry run.
Printing tests follow these rules:
- Test the PrintSettings the code builds.
- A test never calls Printer.Print or Printer.PrintAsync with a printer name that exists.
最後的列印規則來自測試機。在那裡,Microsoft 列印到 PDF 會要求檔案名稱,Adobe PDF 則會開啟創建 Adobe PDF 視窗,因此,發送到任一印表機的工作會等待人員回覆。
如何給列印代碼其自身的規則?
.github/instructions/printing.instructions.md 的 applyTo 模式將其規則限制在樹的某一部分,這次是源代碼和測試專案。 GitHub 的 CLI 文件聲明,CLI 只有在進行 applyTo 值匹配的文件工作時,才會將路徑特定文件加入其上下文。 在我們的運行中,printing.instructions.md 是 Copilot 在提示 1 中打開的第一個文件。
---
applyTo: "src/**,tests/**"
---
Source and test code here follow these IronPrint rules:
- Set Flatten = true for every handover form.
- With Flatten false, IronPrint sends the page with four empty boxes.
- Those boxes are Driver, SealNumber, PalletCount and Hazmat.
- Check a printer name against Printer.GetPrinterNames before a job.
- IronPrint throws nothing for a name it cannot match, even by case or a trailing space.
- It prints on the Windows default printer instead.
- GetPrinterTrays returns an empty list for an unknown name, as it does for some real printers.
- So an empty tray list cannot prove that a printer exists.
- NumberOfCopies reaches the driver as a copy count.
- The job itself holds one page per PDF page.
- With no key, Printer.Print throws an AggregateException that wraps a LicensingException.
- PrintAsync throws the LicensingException itself.
- Margins takes millimeters, in the order left, top, right, bottom.
這些規則都是用 IronPrint 2026.10.1 測量的。下面的 Flatten 和印表機名稱部分給出了其首個測量背後的數據。
為什麼表單欄位在沒有 Flatten 時列印空白?
這些測量使用模擬印表機完成。 在 Windows 中,IronPrint 將每個工作通過 WPF 列印對話框的 PrintDocument 調用發送。 該調用上的掛鉤將每個工作的頁面和列印票保存到一個 XPS 文件中,未有任何列印佇列收到工作。 四個交接表遵循扁平化指南的合併示例設置進行。 結果描述了 IronPrint 給印表機驅動之頁面,而非實體印表機之紙張。
下方比較使用 HO-1001 交接表,保存著每個欄位值。
- 當
Flatten維持預設 false 時,駕駛員、封條號碼、托盤數和危險品箱在四個表格中為空。 三個表單帶有欄位的外觀流,而那些內容也為空。 - 使用
Flatten = true,每個值皆列印出來。 保存無外觀流的表單也列印出其值。 - 每個 PDF 頁面成為 ISO A4 縱向頁面上的 2479 x 3508 像素圖像,即 300 DPI 的 A4。 兩頁表單產生兩頁。
- 列印票攜帶兩份副本,而文件則每個 PDF 頁面持有一頁。
- 從示例中的 10 mm 頁邊距未移動圖像,填滿從頁面左上角開始的頁面。
輸出
HO-1001 經過掛鉤兩次,先是 Flatten 調為 false,然後為 true。 每個以下的 PDF 是一個捕獲工作的頁面圖像,未經修改,且維持原始大小。
HO-1001 在 Flatten 為 false 時,IronPrint 設置的任務,被捕捉到一個檔案,而非印表機。
HO-1001 在 Flatten 為 true 時,IronPrint 設置的任務,被捕捉到一個檔案,而非印表機。
扁平化指南將空欄歸因於跳過表層的印表機驅動。 在捕捉過程中,值在任何驅動接收到之前即已從頁面消失。
如何在無需發送任務下列印一資料夾的表格?
批量作業需要一次“演練”,以便在無需印表機的情況下測試。 演練記錄了每個表格將接收的設置,且審核者可以將該日誌與列印配置比對。
Turn @src/Depot.PrintJob/Program.cs into the batch job that prints forms/inbox.
It accepts two options:
- --printer <name> picks the printer for every form.
- --dry-run writes the log and sends nothing.
The job runs in this order:
1. Exit with code 2 when the printer isn't installed, and list the installed ones on the console.
2. Read every PDF in forms/inbox in file name order.
3. Get each form's settings from HandoverPrinter.BuildSettings.
4. Append a line per form to out/print-log.csv, then print the form unless it's a dry run.
Paths are relative to the solution root.
The log is semicolon-delimited, with this header line:
Form;Printer;Flatten;Copies;PaperSize;Orientation;Dpi;Grayscale
Run the job twice with --dry-run.
Use --printer "Adobe PDF" the first time and --printer "Depot Laser 2" the second.
Show me both exit codes and the log.
Adobe PDF 是測試機上的一臺印表機。使用您自己的印表機列表中的名稱。
當印表機名稱不匹配時會怎麼樣?
IronPrint 逐字比較 PrinterName 與 Windows 報告的名稱,當比較失敗時不會引發任何錯誤。 捕捉的工作被寄給“ NoSuchPrinter 7”、小寫“ adobe pdf”及後接空格的“ Adobe PDF”。 Microsoft 列印到 PDF,是 Windows 的預設印表機,接收了全部三者,而只有精確名稱傳至 Adobe PDF。 向未知名稱發送的授權工作未引發例外狀況,僅在回應 Microsoft 打印到 PDF 的“另存為”對話框後返回。
GetPrinterTrays 不能替代名稱檢查,因為它對未知名稱及傳真和 Microsoft 列印到 PDF 返回空列表。 GetPrinterNames 在無授權金鑰時返回了全部四台印表機,所以該檢查也適用於無須金鑰運行之測試。
如何測試列印設置?
在 Copilot CLI 中按 Shift+Tab 直到計畫模式啟動,然後發送下方的提示。
Plan an xUnit project in tests/Depot.Printing.Tests and add it to the solution.
Hold off on code until I approve the plan.
Its tests cover these cases:
- Every setting BuildSettings fills in matches @docs/print-profile.md.
- PaperMargins and Tray stay null, so the printer's own defaults apply.
- PrintAsync refuses a name with the wrong case or a trailing space.
- That refusal names every printer InstalledPrinters() returns.
Once the plan is approved, add the tests and run dotnet test.
Then give me the pass and fail counts.
先查閱計畫顯示套件將如何在任何測試依賴於機器的印表機列表之前獲取真實的印表機名稱。
如何修復使表單欄位留空的重新列印?
由主要服務分開編寫的重新列印路徑可能會省略主要服務所應用的設置。 在此場景中,隊友的 ReprintService 在無 Flatten 的情況下構建其自身的 PrintSettings,且驅動收到留空盒之重新列印。
Drivers say reprinted handover forms have empty Driver, Seal number and Pallet count boxes.
First prints look right. The reprint code is @src/Depot.Printing/ReprintService.cs.
Work out the cause before you edit anything:
1. Compare ReprintService.BuildSettings with HandoverPrinter.BuildSettings.
2. Open IronPrint.xml inside the IronPrint package in the NuGet cache.
3. Quote its summary for the setting that explains the empty boxes.
Then fix ReprintService.cs, and keep a reprint at one copy.
Leave the other source files alone.
Add a test for the reprint settings and run dotnet test.
Tell me the cause you found and the test result.
發運的 IronPrint.xml 連接設置與症狀在一句話中,描述 Flatten 可用於顯示表單欄位值。 它並未說明缺少它就會導致值缺失。
使雲代理可以操作的問題具備什麼條件?
Copilot 在問題被指派時收到問題標題、描述及現有評論,以及選填提示字段中的任何文本。 GitHub 的文件說明代理並不知道指派後發表的評論,因此問題正文必須指出工作完成的時間。
Title: Log the printer each reprint was sent to
The work involves these files and settings:
- Files: src/Depot.Printing/ReprintService.cs, tests/Depot.Printing.Tests
- IronPrint version: unchanged from Directory.Packages.props
- Framework: net9.0-windows
After the change, reprints behave like this:
- Every reprint appends a line to out/reprint-log.csv.
- The line holds the form, the printer name, the time and the copy count.
- A printer name that Windows does not report stops the reprint before anything is sent.
Today, reprints leave no record, and ReprintAsync sends a job to any name it receives.
Keep to these limits:
- Keep the ReprintAsync signature.
- Follow .github/instructions/printing.instructions.md.
- Add no packages.
Acceptance means these checks pass:
- Every existing test passes.
- A new test passes "adobe pdf" in lower case and expects an ArgumentException before any job.
因為測試使用的名稱與僅不同大小寫的安裝印表機不同,忽略大小寫的檢查會使其失效。
為何雲端代理的測試在 IronPrint 項目上失敗?
除非儲存庫配置了其他運行者,否則代理的環境是 Ubuntu Linux。 IronPrint 的產品頁面列出 Windows、macOS、iOS 和 Android,未列 Linux,且此解決方案中的每個項目均針對 net9.0-windows。 GitHub 支援 Windows 64 位運行者,用於雲端代理。 其整合式防火牆不相容於 Windows,因此 GitHub 建議在此情況下使用自託管運行者或具有 Azure 私有網路的大型 GitHub 託管運行者。
若無 Agents 機密,該環境中也不持有任何授權金鑰。 在探測中特提中,於 0.2 秒內每次非授權打印呼叫均拋出“生產授權所需”,在任何工作創建之前。
.github/workflows/copilot-setup-steps.yml 中的 copilot-setup-steps 工作在代理開始工作之前執行,GitHub 僅在預設分支包含文件後觸發它。
The cloud agent has to build this solution, so add a setup workflow for it.
Its path is .github/workflows/copilot-setup-steps.yml.
Copilot looks for one job, and it has to be named copilot-setup-steps.
The job works like this:
- Run it on windows-latest, because every project targets net9.0-windows.
- Its only permission is contents: read.
- Start it from workflow_dispatch and from pull requests that edit this workflow file.
- Its steps are a checkout, a .NET 9 SDK install, a restore and a Release build.
Printing calls need IRONPRINT_LICENSE_KEY, which is stored as an Agents secret.
The job sees that secret as an environment variable.
Add a step that tests whether the key is set:
- For pull_request and workflow_dispatch events, a missing key is a warning and the step passes.
- For every other event, a missing key fails the step with a message that names the secret.
That step goes last, since Copilot skips every setup step after one that fails.
Create the file and show me the YAML.
使用 Agents 機密來獲取金鑰:雲端代理無法讀取 Actions、Codespaces 或 Dependabot 機密。 在 Secret 和變量的 Agents 頁中加入 IRONPRINT_LICENSE_KEY,位於儲存庫設置的安全群組中。 然後代理將金鑰作為環境變數獲得。
合併之前應檢查什麼?
將評論作為自身的 copilot -p 命令發送。 若無 --continue 或 --resume ,那條命令將啟動完全無歷史的全新會話。
/review the changes made since this branch's first commit.
Compare each IronPrint call with .github/instructions/printing.instructions.md.
Then compare it with the IronPrint.xml that ships in the IronPrint NuGet package.
Name every place where the code and those two sources disagree.
Flag any of these as well:
- a PrintSettings for a handover form that leaves Flatten unset or false
- a print call whose printer name was never checked against Printer.GetPrinterNames
- a test that sends a real print job
- a catch block that would miss the LicensingException a print call throws
- any line that writes IRONPRINT_LICENSE_KEY to the console or a log
Report what you find and leave every file unchanged.
在實際運行中,這些提示產生了什麼結果?
六條提示被安排在 Copilot CLI 中依次運行,無須有人在鍵盤上,依據此指南建立的儲存方案。於每次提示結束時,提交被重建,且批量作業運行於其上。 隨後每個表格的設置經 IronPrint 進行處理,且在攔截列印呼叫時,未有工作送達印表機。
- 假運行之前,HandoverPrinter 是一個空的靜態課及批量作業是一個以代碼 1 退出的存根。
- 第一個提示僅改變 HandoverPrinter.cs。
- 在第一個提示後,BuildSettings 返回 Flatten 開啟,2 份副本,A4,縱向,300 DPI 及灰階。
- 托盤和邊距保持未設置,因此印表機默認適用。
- PrintAsync 使用序數比較檢查印表機名稱,這是大小寫敏感的。
- 每個欄位值皆出現在所有四份表單所捕捉的頁面上。
- 每個表格的列印票攜帶著 2 份副本,ISO A4 豎版,單色輸出及 300 DPI。
- 兩頁表格的捕捉工作持有兩頁,每個其他的工作持有一頁。
- 每兩個提示後的解決方案構建發生 0 錯誤。
- 第二個提示來之後,Adobe PDF 之乾跑以代碼 0 退出,且為每個表格記錄一行。
- 每個記錄的行均匹配列印配檔,其中 Flatten 及 Grayscale 均為 True。
- Depot Laser 2 的乾朗以代碼 2 退出,且其控制台輸出為四台安裝的印表機命名。
- 任何乾跑都沒有進行列印呼叫。
- 運行中未有列印工作出現於任何佇列中。
- 一些步驟與頁面上運行的不同。 Copilot 的月度配額於第二個提示中用盡,在 Copilot 構建任務後及其乾朗之前。 因此,兩次乾朗被運行於 Copilot 之外。 提示 3 至 6 未運行,因此計畫模式、重新列印修復、安裝工作流及評論頁面無運行結果。 問題、雲端代理及 Agents 機密需要託管的儲存庫,因此未有任何進行測試。
Cursor 亦將其規則範圍限定至文件類型,且 Claude Code 同樣等待核准之計劃,然後再進行任何代碼變更。 共享運行記錄 包含 CLI 版本,Auto 選擇的模型、總運行時間和硬體。
疑難排解
- 列印前如何扁平 PDF 用於印刷空白的表單欄位
- 如何獲取印表機名稱 用於 Windows 的名稱報告
- 如何指定印表機名稱 用於發送至錯誤印表機的工作
- Print() 方法在 WPF 和 WinForms 中卡住 用於導致界面停頓的打印請求
- 應用授權金鑰 在每個可設置該金鑰的地點
問題?
如果您有任何疑問,請聯繫support@ironsoftware.com
Curtis Chau 擁有卡爾頓大學計算機科學學士學位,專注於前端開發,擅長於 Node.js、TypeScript、JavaScript 和 React。Curtis 熱衷於創建直觀且美觀的用戶界面,喜歡使用現代框架並打造結構良好、視覺吸引人的手冊。