如何使用IronPrint与GitHub Copilot

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

每个离开其货位的拖车,货运站都会打印一份承运商交接表。 货运站的网页门户将每个表单保存为填充的PDF,其中包含司机、封条号、托盘数量和危险品字段,并且Visual Studio解决方案中的.NET服务将每个表单打印两份。 编辑服务的助手必须在团队已经使用的编辑器中工作于该解决方案内部。

GitHub Copilot在Visual Studio和VS Code中提供聊天和代理模式,在终端中提供Copilot CLI,以及一个GitHub云代理,该代理通过拉取请求来回复指定的问题。IronPrint从.NET发送PDF和图像到打印机,纸张大小、份数、分辨率和表单扁平化设置在单个PrintSettings对象上。 这些Copilot界面都会从存储库中的指令文件读取IronPrint规则。

以下提示要求Copilot构建基于IronPrint的打印代码。 选择打印机硬件或配置打印服务器是一个单独的任务,助理无法从存储库中完成。 扁平指南描述了这些表单所依赖的IronPrint设置。

快速入门
NuGet使用NuGet安装

PM > Install-Package IronPrint

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

从解决方案文件夹启动copilot并发送提示。 在CLI中,@在路径前附加该文件。在Visual Studio中,Copilot聊天使用#出于同样的目的。

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.
Text

提示未命名任何单独的设置。 docs/print-profile.md中的打印配置文件列出了每一个,其中包含Flatten。

许可证密钥位于IRONPRINT_LICENSE_KEY,在Copilot运行的环境中设置。 IronPrint本身不读取该变量。 在我们的测试中,License.IsLicensed在变量设置后的情况下保持为假,直到程序为License.LicenseKey分配其值。 其他支持密钥的位置列在许可证密钥指南中。



如何为Copilot设置IronPrint约定?

项目范围的规则放在.github/copilot-instructions.md中。 GitHub的支持矩阵显示,在Visual Studio、VS Code和JetBrains IDEs上的Copilot Chat中,以及Copilot CLI、Copilot代码审查和云代理中支持该文件。 Visual Studio仅在选中自定义指令复选框时,将该文件添加到Copilot聊天请求中,位于选项设置下的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.
Markdown

最后的打印规则来自测试机器。那里,Microsoft Print to 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.
Markdown

这些规则中的每一个都用IronPrint 2026.10.1测量。下面的Flatten和打印机名称部分提供了它们背后第一次的测量数据。

为什么在没有Flatten的情况下打印时表单字段为空?

这些测量值使用了模拟打印机。 在Windows上,IronPrint通过WPF打印对话框的PrintDocument调用发送每个作业。 该调用上的一个挂钩将每个作业的页面和打印票据保存为XPS文件,且没有任何打印队列接收到作业。 四个交接表单通过它使用扁平指南的组合示例中的设置。 结果描述了IronPrint提供给打印机驱动程序的页面,而不是来自物理打印机的纸张。

下面的比较使用了手持表单HO-1001,保存了每个字段中的一个值。

  • Flatten保持其默认值为假时,司机、封条号、托盘数量和危险品框在所有四个表单上均为空。 三个表单携带了其字段的外观流,这些框在这些表单上也为空。
  • 使用Flatten = true时,每个值都被打印。 保存的表单在没有外观流的情况下也打印了其值。
  • 每个PDF页面在ISO A4纵向页面上变成了2479乘3508像素的图像,即300DPI的A4。 双页表单产生了两个页面。
  • 打印票据携带着2份的复印数量,而文档每页持有一页PDF页面。
  • 示例中的10毫米边距没有移动图像,图像从其左上角填充页面。

输出

HO-1001通过两次挂钩,第一次设置Flatten为假,然后设置为真。 下面的每个PDF为捕获工作之一的页面图像,未修改,保持原始大小。

IronPrint构建作业时捕获到文件中,作为打印机所用的HO-1001,未设置Flatten。

IronPrint构建作业时捕获到文件中,作为打印机所用的HO-1001,设置Flatten为真。

扁平指南将空字段归因于跳过表单图层的打印机驱动程序。 在捕获中,页面上的值在任何驱动程序接收之前就已经缺失。

如何不发送作业就打印一个表单文件夹?

批处理作业需要进行预演,以便无需打印机进行测试。 预演记录每个表单会接收到的设置,审核员可以将该日志与打印配置文件进行比较。

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.
Text

Adobe PDF是测试机器上的一台打印机。使用您自己的打印机列表中的名称。

当打印机名称不匹配时会发生什么?

IronPrint逐个字符地将PrinterName与Windows报告的名称进行比较,并且在比较失败时不会产生错误。 捕获到的作业被传送给“NoSuchPrinter 7”、小写的“adobe pdf”以及后面跟随一个空格的“Adobe PDF”。 Microsoft Print to PDF,Windows的默认打印机,接收了这三者,只有确切的名称传给了Adobe PDF。 寄给未知名称的有牌作业未引发异常,并仅在回答了Microsoft Print to PDF的另存为对话框后返回。

GetPrinterTrays无法替代名称检查,因为它对未知名称和传真以及Microsoft Print to 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.
Text

首先查看计划显示套件如何在任何测试依赖于机器的打印机列表之前获取一个真实的打印机名称。

如何修复导致表单字段为空的重印?

一个与主服务分开的重印路径可能会省去主服务应用的设置。 在此场景中,队友的ReprintService构建了自己的PrintSettings,没有Flatten,驱动程序收到带有空框的重印。

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.
Text

发送的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.
Markdown

由于测试使用的名称与安装的打印只在大小写上有所不同,因此忽略大小写的检查会失败。

为什么云代理的测试在IronPrint项目上失败?

除非存储库配置另一个运行器,代理的环境是Ubuntu Linux。 IronPrint的产品页面命名了Windows、macOS、iOS和Android并未命名Linux,且这个解决方案中的每个项目都以net9.0-windows为目标。 GitHub支持云代理的Windows 64位运行器。 其集成的防火墙与Windows不兼容,因此GitHub建议自托管运行器或更大的GitHub托管运行器与Azure私有网络用于此情况。

没有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.
Text

为密钥使用Agents秘密:云代理无法读取Actions、Codespaces或Dependabot秘密。 在存储库的设置的安全组下的Secrets和变量的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.
Text

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

六个提示被安排在没有人触键的情况下在Copilot CLI中一个接一个运行,基于本指南构建的一个仓库解决方案。在每个提示之后,提交被重建,批处理作业在其上运行。 每个表单的设置然后通过IronPrint进行,其中打印调用被拦截,因此没有作业到达打印机。

  • 运行前,HandoverPrinter是一个空的静态类,而批处理作业是一个以代码1退出的样板。
  • 第一个提示仅更改了HandoverPrinter.cs。
  • 第一个提示之后,BuildSettings返回Flatten开,2份,A4,纵向,300 DPI和灰度。
  • Tray和边距保持未设置,因此应用了打印机默认值。
  • 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选择的模型,总运行时间和硬件。


故障排除


有问题吗?

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

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

阅读更多

准备开始了吗?

NuGet 下载量 52,106版本:2026.11刚刚发布