如何使用IronQR與GitHub Copilot結合
由.NET 文件管道生成的發票、帳戶對帳單和已簽署的合約通常包含QR碼,以供收件人驗證文件真實性。 團隊通常在Visual Studio解決方案中維護此管道,與PDF生成服務一起運作,因此需要一個在該解決方案內工作的助手。
GitHub Copilot在Visual Studio、VS Code、終端中作為Copilot CLI運行,也可在GitHub上運行。 IronQR使用QrCode.StampToExistingPdfPage將QR碼添加到現有的PDF頁面上。 倉庫的說明文件定義了每個Copilot介面應如何處理這個呼叫。
PDF蓋章指南中詳細記錄了蓋章呼叫。
快速開始在解決方案根目錄的終端中啟動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.
提示故意省略了蓋章大小。 下面路徑專用的說明文件包含了該規則,並在運行Copilot時在編寫方法前閱讀它。
在Copilot開始的環境中設置IRONQR_LICENSE_KEY,並查看授權金鑰指南以了解其他保存金鑰的位置。
最小工作流程(5 個步驟)
- 從NuGet下載C# QR Code程式庫
- 將蓋章規則提交到
.github/copilot-instructions.md及路徑專用的說明文件中 - 使用
QrWriter.Write創建代碼,用Save設置大小,並用StampToExistingPdfPage蓋章 - 通過將頁面渲染為圖像並使用IronQR解碼來驗證每個蓋章
- 給雲代理一個待解決的問題,並根據API參照檢查拉取請求
Copilot 如何融入已在 Visual Studio 的項目中?
在Visual Studio或VS Code中使用代理模式進行您想要觀看的蓋章更改,因為它可以建立解決方案並自行運行蓋章作業。 Copilot CLI在終端中以相同方式工作。 GitHub 上的雲代理會接受指定的議題並返回一個 pull request。
如何為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.
如何為蓋章代碼設置自己的規則?
只能在蓋章代碼所在位置生效的規則放在.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.
如何在PDF頁面上放置和設置QR碼的大小?
PDF格式從左下角開始存儲位置,而IronQR從左上角開始計算。 使用IronQR 2026.10.1,x 455 和 y 30將代碼放在A4頁面的右上角,而y 702,即相同框的左下角數值,將其放在靠近底邊的位置。
沒有蓋章方法可以接受大小。在A4頁面右側邊緣110點的框中,以不含QrStyleOptions儲存的代碼在頁面上跑出,而渲染的頁面完全沒有任何代碼。 默認邊距為10,這將添加到每一側,因此此邊距的110維度將提供130點的蓋章。
某些範例傳0作為第一頁,這在2026.10.1中拋出ArgumentOutOfRangeException,信息為"頁碼0不存在"。 超出末尾的頁面以相同方式失敗,在每種情況下文件都保持不變。
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.
Letter頁面寬612點,A4頁面寬595.28,因此在StampToExistingPdfPages呼叫中相同的x值將Letter蓋章放在其框的左邊17點處。 錯誤的蓋章不會引發錯誤並仍可掃描,這就是為何測試需要檢查其降落位置與其所述的原因。
如何蓋章受密碼保護的PDF?
蓋章方法將密碼作為其最後一個參數,IronQR的API文檔稱其為"PDF加密或管理員密碼"。 我們蓋章了一個使用PDFsharp 6.2.4加密的兩頁合約,該加密為打開文件設置了用戶密碼,為更改文件設置了擁有者密碼。 RC4 40-bit、RC4 128-bit和AES 128-bit的副本給出了相同的結果。
- 擁有者密碼:蓋章成功,保存的文件無需密碼即可打開。
- 用戶密碼、錯誤密碼或沒有:IronQrPdfPasswordException,信息為"無法打開PDF",文件維持不變。
- AES 256-bit副本:使用兩個密碼會引發IronQrPdfPasswordException,然而PDFium可以使用用戶密碼打開相同的文件。
另外兩種結果影響錯誤處理。 丟失的文件和重命名為.pdf的文本文件引發了相同的例外。 由MuPDF加密的合約副本引發PdfSharpCore.SharpZipLib.SharpZipBaseException,信息為"標頭校驗和非法",這是來自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.
PasswordRemoved為下一管道步驟提供一個用以行動的標記,無論那步驟是重新加密文件還是保留文件。 一份靜默丟失保護的蓋章合約比一個未能成功蓋章的合約更糟糕。
如何測試蓋章的QR碼能否掃描?
IronQR技術文件確認庫沒有PDF加載器。 PDFtoImage是基於PDFium構建的MIT授權包,可在選定DPI下渲染頁面,通過Conversion.GetPageSizes報告頁面尺寸,並可使用密碼打開受保護的文件。 一個110點的印記使用QrReader從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.
計劃模式適合此套件,因為渲染和讀取助手必須在任何單一測試之前存在。 最後的斷言釘住了上一節的行為。 如果後續的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.
法律團隊從頁面底部測量位置,因此雲代碼代理必須根據路徑專用的說明中的規則將其轉換,驗收測試會捕捉掉未轉換的。
為何雲代碼代理的測試在IronQR專案上失敗?
雲代碼代理預設在Ubuntu Linux運行器上工作。 純IronQR包依賴於IronSoftware.ReaderInternals.Windows,NuGet包指南中為Linux伺服器、容器和CI列出了IronQR.Linux。 沒有授權金鑰,QrWriter.Write在繪製任何蓋章之前就拋出LicensingException。 配置造成的紅測試看起來與變更造成的一樣,因此在差異之前閱讀第一個異常。
一個命名為copilot-setup-steps的唯一作業設置工作流在.github/workflows/copilot-setup-steps.yml,準備運行器後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.
雲代碼代理無法讀取為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.
在PDF標準中,V 5配R 6標示AES 256-bit加密,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.
包中附帶的XML將x和y描述為像素,而說明文件指示為點。 兩者在實踐中都成立,因為蓋章被繪製為每像素一點,而報告字詞差異而不將其視為bug的審核者已閱讀了兩個來源。
在實際運行中,這些提示產生了什麼結果?
七個提示按順序發送給Copilot CLI而鍵盤沒有人操作。 前六個共享一個會話,第四個在計劃模式和自動駕駛中。 目標是本指南製作的小型文檔管道,帶有控制台任務、一個空的xUnit專案和範例PDF,其中一個是受密碼保護的合約。 在診斷提示之前,兩份合約在供應商資料夾中到達。 下面的每個數據都在會話結束後檢查過,通過再次運行工作和測試並閱讀每個合約的/Encrypt條目。 AI編碼助手指南將此類檢查轉換為可重複測試。
- 對每頁蓋章,將代碼放置在A4頁面的x 455和Letter的x 472,共8頁在150 DPI的框內解碼。
- 受保護合約提示後,
PasswordRemoved對合約有效。 8頁中的8頁仍然被解碼,且無頁面被隔離。 - 計劃套件在發布運行中通過9個中的9個測試。 沒有文件由手動編輯。
- 兩個供應商文件讀取V 5、R 6、長度256,比對合約-7310的V 2、R 3、長度128,兩個理由文件提供供應商值。
- 一些步驟與頁面上運行的不同。 設置工作流映射了來自Actions秘密存儲的金鑰。 診斷嘗試使用pypdf測試密碼,該方法已在機器上,並且主要代理在沒有單獨審查代理的情況下進行了審查。 問題、雲代碼代理、Actions上的設置工作流和代理秘密需要GitHub存儲庫,因此沒有執行。
每個指南在運行記錄中記錄Copilot CLI版本、自動駕駛儀選擇的模型、運行時間和測試機器。
疑難排解
- QR碼蓋章到PDF用於
StampToExistingPdfPage的每個參數 - 在IronQR中申請授權金鑰以設置Copilot運行代碼的金鑰
- IronQR NuGet套件以選擇Linux執行器或容器的包
- QR碼錯誤信息與調試以記錄批次中的每個文件例外
- 運行時間複製例外如果機器學習DLL從未到達輸出文件夾
問題?
如果您有任何疑問,請聯繫support@ironsoftware.com
Curtis Chau 擁有卡爾頓大學計算機科學學士學位,專注於前端開發,擅長於 Node.js、TypeScript、JavaScript 和 React。Curtis 熱衷於創建直觀且美觀的用戶界面,喜歡使用現代框架並打造結構良好、視覺吸引人的手冊。