如何在GitHub Copilot中使用IronQR

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

.NET文档流水线生成的发票、账户对账单和签署的合同通常包括二维码,供收件人验证文档的真实性。 团队通常在Visual Studio解决方案中维护此流水线,与PDF生成服务一起,并需要一个可以在该解决方案内工作的助手。

GitHub Copilot在Visual Studio、VS Code、终端作为Copilot CLI以及GitHub上运行。 IronQR使用QrCode.StampToExistingPdfPage将二维码添加到现有的PDF页面。 存储库的说明文件定义了每个Copilot界面如何处理此调用。

PDF盖章指南详细记录了盖章调用。

快速入门
NuGet使用NuGet安装

PM > Install-Package IronQR

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

在解决方案的根目录中启动终端中的Copilot CLI并发送提示。 在Visual Studio聊天中,引用两个文件,使用#和文件名代替@。

Open @src/DocStamp/Stamping/VerificationStamper.cs and add a public static
method StampFirstPage(string pdfPath, string documentId). Use IronQR, which
installs as the IronQR package and lives in the IronQr namespace, to draw a QR
code for https://verify.example.com/d/{documentId} inside the Scan to verify
box that @docs/stamp-layout.md specifies. That document measures from the
bottom-left corner, while IronQR takes x and y in points from the top-left and
numbers pages from 1, so convert before you call it. Stamp the path you are
given and leave copying to the caller. The license key comes from
IRONQR_LICENSE_KEY. Build the solution and fix anything that fails.
Text

提示故意省略了盖章尺寸。 下方的路径特定说明文件遵循此规则,并在执行Copilot时先读取它再编写方法。

在Copilot启动的环境中设置IRONQR_LICENSE_KEY,并查阅许可证密钥指南了解其他存放密钥的位置。



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

在您想要观察的盖章更改中使用Visual Studio或VS Code中的代理模式,因为它可以自行构建解决方案并运行盖章作业。 Copilot CLI以相同的方式从终端运行。 GitHub上的云代理接收分配的问题,并返回一个拉取请求。

如何为Copilot设置IronQR惯例?

将IronQR惯例提交为.github/copilot-instructions.md。 GitHub的支持表列出了文件,用于Copilot CLI、云代理、Copilot代码审查以及在Visual Studio、VS Code和JetBrains IDE中的Copilot Chat,以便每个界面从相同的规则开始。

# Copilot instructions

## Verification stamps

- QR codes come from IronQR. The NuGet package is IronQR (IronQR.Linux on
  Linux), the namespace is IronQr, and its exceptions live in
  IronQr.Exceptions. Add no QR or barcode package from another vendor.
- The IronQR version is pinned in Directory.Packages.props. Change it only
  when the task is an upgrade.
- Read the license key from the IRONQR_LICENSE_KEY environment variable. Never
  write a key or a PDF password into code, configuration, tests or output.
- A stamp encodes https://verify.example.com/d/{documentId}, where documentId
  is the PDF file name without its extension.
- IronQR cannot open a PDF for reading. Code that checks a stamp renders the
  page with PDFtoImage and decodes the image with QrReader.
- Documentation: https://ironsoftware.com/qr/csharp/llms.txt
- When you are not sure an IronQR member exists, say so and check the
  documentation before you use it.

## Tests

- Stamp copies in a temporary folder. Never stamp a file under TestData.
- Assert on the decoded value and on where the code sits on the page, never
  on the bytes of a stamped PDF.
Markdown

如何为盖章代码提供其自身的规则?

仅在盖章代码所在之处有效的规则放入.github/instructions/stamping.instructions.md。 其applyTo路径模式将盖章几何形状从关于作业运行器或测试的请求中排除,并且Copilot CLI仅在处理匹配文件时才包括该文件。

---
applyTo: "src/DocStamp/Stamping/**"
---

- StampToExistingPdfPage and StampToExistingPdfPages overwrite the file at the
  path given. The caller passes a copy.
- x and y are PDF points measured from the top-left corner of the page.
  Page numbers start at 1. Page 0 throws ArgumentOutOfRangeException.
- The stamp is drawn one point per pixel of the QR image. Call
  qr.Save(new QrStyleOptions(110, 0)) before stamping, or the code comes out
  250 points square.
- Protected PDFs open only with the owner password, read from
  DOCSTAMP_PDF_OWNER_PASSWORD. The stamped file is saved without encryption.
Markdown

如何在PDF页面上放置和调整二维码的大小?

PDF格式从左下角存储位置,而IronQR从左上角开始。 在IronQR 2026.10.1中,x 455和y 30将代码放在A4页面的右上角,而y 702是同一框的左下角数值,将其放在靠近底部边缘。

没有盖章方法采用尺寸。在靠近A4页面右边缘的110点框中,若没有QrStyleOptions保存的代码超出页面渲染结果没有任何代码。 默认边距为10,因此使用该边距的尺寸为110时提供了130点的章。

一些示例传递0给第一页,这在2026.10.1中会抛出ArgumentOutOfRangeException并附带消息“Page Number 0 does not exist”。 跨过结尾的页面以相同方式失败,并且在每种情况下文件都保持不变。

Statements run to three pages, and TestData/inbound/bundle-5120.pdf puts a
Letter page behind an A4 page. Add StampEveryPage(string pdfPath, string
documentId) to @src/DocStamp/Stamping/VerificationStamper.cs so every page gets
its code in its own box. StampToExistingPdfPages applies a single x and y to
each page it receives, so read the page sizes with PDFtoImage's
Conversion.GetPageSizes, group pages that share a size, and stamp once per
group. Then rework @src/DocStamp/Pipeline/StampJob.cs to copy each inbound PDF
to the outbound folder and stamp the copy. Run the job against TestData/inbound
and print the coordinates used for each page.
Text

Letter页面的宽度为612点,而A4页面为595.28,因此在StampToExistingPdfPages调用中将两者的x值放置在一起会使Letter章比其框左偏17点。 错位的章不会引发错误,仍然可以扫描,这就是为什么在测试中检查其落地位置及内容的原因。

如何在密码保护的PDF上盖章?

盖章方法将密码作为其最后一个参数,并且IronQR的API文档将其称为“PDF加密或管理员密码”。 我们在用PDFsharp 6.2.4加密的两页合同上盖章,该软件为打开文件设置用户密码并为修改文件设置所有者密码。 RC4 40位,RC4 128位和AES 128位的副本都给出了相同的结果。

  • 所有者密码:盖章成功,保存的文件无需密码即可打开。
  • 用户密码、错误密码或无密码:IronQrPdfPasswordException并显示“PDF无法打开”,文件未更改。
  • AES 256位副本:与两个密码一起的IronQrPdfPasswordException,而PDFium使用用户密码打开了相同文件。

另外两个结果塑造了错误处理。 缺失文件和重命名为.pdf的文本文件引发了相同的异常。 由MuPDF加密的合同副本抛出PdfSharpCore.SharpZipLib.SharpZipBaseException显示“Header checksum illegal”,这是IronQr.Exceptions外部的一个异常中止任何仅命名IronQR异常的批次。

Make the owner password an explicit input for contract-7310-protected.pdf. Give
@src/DocStamp/Stamping/VerificationStamper.cs an optional password parameter in
place of any environment lookup inside it, and have StampJob pass
DOCSTAMP_PDF_OWNER_PASSWORD from the environment. IronQR opens a protected file
only with its owner password and saves the stamped copy without encryption, so
add PasswordRemoved to the job's per-file summary. A document that throws
IronQrPdfPasswordException, or any other exception, moves to a quarantine folder
beside outbound with a .reason.txt naming the exception type and message, and
the batch carries on. Never print the password. Run the job and list outbound
and quarantine.
Text

PasswordRemoved给管道的下一步提供了一个可操作的标志,无论该步骤是否重新加密文件或将其保留。 静静失去保护的已盖章合同比盖章失败的合同更糟。

如何确保已盖章的二维码扫描?

IronQR技能文件确认库没有PDF加载器。 PDFtoImage是一个基于PDFium构建的MIT许可包,可以选择DPI渲染页面,通过Conversion.GetPageSizes报告页面尺寸并使用密码打开受保护文件。 使用QrReader解码的110点盖章从50、72、100、150和300 DPI的渲染中,所以这些测试中的阅读失败指向盖章本身。

按Shift+Tab,直到Copilot CLI显示计划模式,然后发送此提示。

Before writing anything, plan an xUnit suite for tests/DocStamp.Tests and wait
for my approval. IronQR reads images, not PDFs, so each check stamps a temp
copy, renders the page with PDFtoImage at 150 DPI, decodes the PNG with
QrReader, and scales the corner points by 72/150 to get PDF points. The suite
should prove that every page of every file in TestData/inbound decodes to its
own verification URL, that the corners sit inside the box in
docs/stamp-layout.md, that page 0 and a page past the end throw
ArgumentOutOfRangeException without touching the file, that the user password
and a wrong one both raise IronQrPdfPasswordException, and that the stamped
contract opens with no password. The owner password for the sample is in
TestData/README.md. After approval, write it and run dotnet test.
Text

计划模式适合此套件,因为渲染和读取助手必须在任何单个测试具有意义之前存在。 最后的断言确认了上一节的行为。 如果稍后的IronQR版本保留了加密,则测试失败,并且有人故意重新访PasswordRemoved。

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

当您分配一个议题时,云代理会收到其标题、描述、现有评论和您添加的任何额外说明。 GitHub声明它不会对分配后发布的评论作出反应,因此议题必须包含整个简报,包括如何判断任务完成。

Title: Contracts need the verification stamp beside the signature block on the last page

**Files:** src/DocStamp/Stamping/VerificationStamper.cs, src/DocStamp/Pipeline/StampJob.cs
**IronQR version:** as pinned in Directory.Packages.props
**Framework:** .NET 9

**Expected:** Files whose names start with contract- get one stamp, on the last
page only, 110 points square, 60 points in from the left edge, with its bottom
edge 150 points above the bottom of the page. Other documents keep a stamp in
the Scan to verify box on every page.

**Actual:** Contracts are stamped on every page in the top-right box, where the
signing service prints its own seal.

**Constraints:** Keep the signature of StampEveryPage. Keep passing the owner
password from DOCSTAMP_PDF_OWNER_PASSWORD. No new packages.

**Acceptance:** dotnet test passes, plus a new test that stamps a copy of
contract-7310-protected.pdf, renders its last page, and finds exactly one code,
inside the new rectangle, that decodes to the contract's URL.
Markdown

法律团队从页面底部测量位置,因此云代理必须使用路径特定说明中的规则进行转换,而验收测试则捕捉到漏掉的转换。

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

云代理默认在Ubuntu Linux运行器上工作。 简单IronQR包依赖于IronSoftware.ReaderInternals.Windows,而NuGet包指南为Linux服务器、容器和CI指定了IronQR.Linux。 没有许可证密钥,QrWriter.Write会在任何盖章开始前抛出LicensingException。 由于配置原因引发的红色测试看起来与由更改引发的测试相同,因此请在查看差异之前阅读第一个异常。

在.github/workflows/copilot-setup-steps.yml中设置工作流,其一个名为copilot-setup-steps的作业在Copilot启动前准备运行器,直到文件在默认分支上才会触发。

Create .github/workflows/copilot-setup-steps.yml so the cloud agent can build
and test this solution on its Ubuntu runner. GitHub ignores the file unless its
one job is named copilot-setup-steps. Trigger it from workflow_dispatch and from
pushes and pull requests that touch the file. Check out the code, install the
.NET SDK version the projects target, restore, and build. The IronQR package
brings the Windows reader, so make the projects reference IronQR.Linux in place
of IronQR when they build on Linux. Make the last step fail with a readable
message when IRONQR_LICENSE_KEY is empty, because a failed step makes Copilot
skip the steps after it. Then show the YAML and every project file change.
Text

云代理无法读取为Actions、Dependabot或Codespaces存储的秘密。 将IRONQR_LICENSE_KEY和DOCSTAMP_PDF_OWNER_PASSWORD存储为代理秘密,存放在存储库的设置中安全部分的秘密和变量下,Copilot将两个作为环境变量接收。

如何诊断无法盖章的PDF?

由于上述密码失败和无法读取的文件共享同一异常,独自猜测的助手不断重新处理密码处理。

A new e-signature vendor sent contract-7311.pdf and contract-7312.pdf, now in
TestData/vendor-batch. When StampJob runs on that folder, both end up in
quarantine with IronQrPdfPasswordException. The vendor confirms
DOCSTAMP_PDF_OWNER_PASSWORD, and contract-7310-protected.pdf still stamps with
it. Explain the cause before you change any code. First measure, reading the V,
R and Length entries of each file's /Encrypt dictionary, trying the owner and
user passwords against each, and comparing with contract-7310. Base the
explanation on those results. Then change only how StampJob words the reason
text, so an operator can see the real cause. It may read the same /Encrypt
entries, which need no password. Add no package and do not decrypt anything.
Text

在PDF标准中,V 5与R 6标记AES 256位加密,而V 2与R 3为RC4。在解释之前要求这些读取给您一个可以与文件相比的信息。 将变更保持为原因文本使另一个PDF库不进入项目,这是属于拥有合同的团队的决策。

合并前应检查什么?

将/review作为其自己的copilot -p调用发送。 在首次运行中,它进入了编写代码的会话,然后返回到先前任务并编辑StampJob.cs。

/review the changes on this branch since its first commit. Check each IronQR
call against .github/instructions/stamping.instructions.md and against the
IronQr.xml that the IronQR.Slim package puts in the NuGet cache, and note any
place the two disagree. Confirm that pages are numbered from 1, that each code
is sized with Save(QrStyleOptions) before it is stamped, and that protected
files receive the owner password. Flag any test that stamps a file under
TestData, compares the bytes of a stamped PDF, or could write a license key or
password to output. Report the findings and change no files.
Text

包中附带的XML将x和y描述为像素,而说明文件中称为点。 在实践中两者都适用,因为盖章是每像素一点绘制的,并且那名没有将其视为错误而仅报告措辞差异的审阅者已阅读了两个来源。

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

七个提示按顺序发送到Copilot CLI,没有人使用键盘。 前六个共享一个会话,第四个处于计划模式和自动驾驶状态。 目标是为本指南制作的小文档管道,内含一个控制台作业、一个空的xUnit项目和示例PDF,其中一个是受密码保护的合同。 在诊断提示之前还有两个合同到达供应商文件夹。 逐一在会话结束后通过重新运行作业和测试和阅读每个合同的/Encrypt条目来检查下面的每个数字。 AI编码助手指南将此类型的检查变成可重复的测试。

  • 在每页盖章将代码在A4页面的x 455和在Letter页面的x 472上放置,8页中的8页在150 DPI时在框内解码。
  • 在受保护合同提示之后,仅该合同的PasswordRemoved为真。 8页中的8页仍已解码,没有应隔离的。
  • 在Release运行中,已规划套件通过了9个中的9个测试。 没有文件是手动编辑的。
  • 两个供应商文件读取V 5,R 6,长度256,而在contract-7310上为V 2,R 3,长度128,并且两个原因文件给出了供应商值。
  • 有些步骤与页面中的运行不一样。 设置工作流将密钥从操作秘密存储映射出来。 诊断尝试了机器上已经存在的pypdf密码,并且没有一个单独的审核代理,主代理进行了审核。 议题、云代理、Actions上的设置工作流和代理秘密需要一个GitHub存储库,因此没有一个运行。

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


故障排除


有问题吗?

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

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

阅读更多

准备开始了吗?

NuGet 下载量 82,442版本:2026.11刚刚发布