GitHub Copilot での IronQR の使用方法

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

.NET ドキュメントパイプラインによって生成される請求書、口座明細書、および署名済み契約書には、受取人が文書の信頼性を確認するためのQRコードが含まれていることがよくあります。 チームは通常、このパイプラインをPDF生成サービスと共に Visual Studio ソリューション内で維持しており、そのソリューション内で動作するアシスタントが必要です。

GitHub Copilot は Visual Studio、VS Code、ターミナルの Copilot CLI、GitHub 上で動作します。 IronQR は QrCode.StampToExistingPdfPage を使用して既存のPDFページにQRコードを追加します。 リポジトリの指示ファイルには、各Copilotインターフェイスがこの呼び出しをどのように処理すべきかが定義されています。

PDFへのスタンプガイド には、スタンプ呼び出しの詳細が記載されています。

クイックスタート
NuGetNuGet でインストール

PM > Install-Package IronQR

NuGetパッケージマネージャーコンソールで上記のコマンドを実行するか、NuGetパッケージマネージャーでパッケージを検索して、IronQRをインストールします。

ソリューションのルートでターミナルに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 を設定し、他のキー保存場所については ライセンスキーガイド を参照してください。



Visual Studioですでに進行中のプロジェクトにCopilotをどのように組み込むのですか?

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ページにQRコードをどのように配置しサイズを調整しますか?

PDF形式は左下から位置を保存しますが、IronQR は左上から数えます。 IronQR 2026.10.1 では、x 455 と y 30 が A4 ページの右上にコードを配置し、y 702 が同じボックスの左下の数値として下部近くに配置します。

スタンプメソッドはサイズを受け取りません。A4 ページの右端近くの110ポイントボックス内で、QrStyleOptions なしで保存されたコードはページ外に流出し、レンダリングされたページは全くコードを返しませんでした。 デフォルトの余白10がすべての側に追加されるため、その余白を含んだ110の寸法が130ポイントのスタンプを与えます。

いくつかのサンプルは最初のページに0を渡しますが、これは2026.10.1では「Page Number 0 does not exist」というメッセージと共に ArgumentOutOfRangeException をスローします。 終了後のページも同様に失敗し、それぞれの場合、ファイルは変更されませんでした。

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

レターページは612ポイント幅でA4ページは595.28ポイントであるため、StampToExistingPdfPages呼び出しで同じ数値を使用すると、レターのスタンプはそのボックスの左に17ポイント移動します。 誤った位置のスタンプはエラーを発生させずにスキャンできるため、テストはそれがどこに着地したかを確認し、それが何と言っているかも確認します。

パスワードで保護されたPDFにどのようにスタンプを押しますか?

スタンプメソッドは最後の引数としてパスワードを受け取り、IronQRのAPIドキュメントはそれを「PDFの暗号化または管理者パスワード」と呼んでいます。 PDFsharp 6.2.4で暗号化された2ページの契約書にスタンプを押しました。それはファイルを開くためのユーザーパスワードと変更のためのオーナーパスワードを設定します。 RC4 40ビット、RC4 128ビット、AES 128ビットのコピーは同じ結果を示しました。

  • オーナーパスワード: スタンプは成功し、保存されたファイルはパスワードなしで開けました。
  • ユーザーパスワード、間違ったパスワード、またはなし: IronQrPdfPasswordException が「PDFを開けませんでした」というメッセージと共に表示され、ファイルは変更されませんでした。
  • AES 256ビットコピー: IronQrPdfPasswordException が両方のパスワードで発生し、一方でPDFiumはユーザーパスワードで同じファイルを開けました。

他の2つの結果がエラーハンドリングを形作っています。 欠落ファイルとテキストファイルを.pdfに改名したファイルは同じ例外を引き起こしました。 MuPDFで暗号化された契約のコピーが「ヘッダーのチェックサムが不正です」というPdfSharpCore.SharpZipLib.SharpZipBaseExceptionを投げました。これはIronQRの例外のみをキャッチするバッチを停止する、IronQr.Exceptions の外側からの例外です。

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 は適切に処理するためのフラグを提供し、そのステップがファイルを再暗号化するか保持するかを判断します。 静かに保護を失うスタンプ済み契約書は、スタンプが失敗するよりも悪いです。

QRコードがスキャンされるかどのようにテストしますか?

IronQR スキルファイルは、そのライブラリにはPDFローダーがないことを確認します。 PDFtoImageは、PDFium上に構築され、選んだDPIでページをレンダリングし、Conversion.GetPageSizesを通じてページサイズを報告し、パスワード付きで保護されたファイルを開くMITライセンスのパッケージです。 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 は割当後に投稿されたコメントに反応しないと述べているため、Issue はジョブが完了したことを伝える方法を含む全体的なブリーフを担わなければなりません。

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 に依存しており、Linux サーバー、コンテナ、CIとしては NuGet パッケージガイド にIronQR.Linux として名前が挙げられています。 ライセンスキーがないと、QrWriter.Write はスタンプが描画される前に LicensingException をスローします。 設定による赤いテストは、変更によるものと同一に見えるため、差異の前に最初の例外を読みます。

セットアップワークフローが.github/workflows/copilot-setup-steps.ymlで、その1つのジョブが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です。それらのリーディングを説明前に尋ねると、ファイルと照合できる主張を得ることができます。 変更を理由テキストに保持することでプロジェクトから2番目の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 をピクセルとして説明し、指示ファイルはポイントとしています。 どちらも実際には保持されているため、スタンプはピクセルごとに1ポイントで描画され、ワード数の違いを報告してもバグとして認識しないレビューアーは両方のソースを読んでいます。

プロンプトが実運用で生成したものは何ですか?

7つのプロンプトは順番に Copilot CLI に送られ、だれもキーボードにいませんでした。 最初の6つは1つのセッションを共有し、4番目はプランモードとオートパイロットでした。 対象はこのガイドのために作成された小さなドキュメントパイプラインで、コンソールジョブ、空のxUnitプロジェクト、およびサンプルPDFが含まれ、そのうちの一つはパスワードで保護された契約書です。 診断プロンプトの前に、供給者フォルダに2つの契約書が届きました。 以下のすべての数値がセッション終了後に確認され、ジョブとテストを再実行し、各契約書の /Encrypt 条項を読みました。 AIコーディングアシスタントガイドは、この種のチェックを繰り返し可能なテストに変えます。

  • すべてのページにスタンプが押された場合、コードはA4ページでx 455、レターでx 472に配置され、8つのページのうち8ページが150 DPIでボックス内でデコードされました。
  • 保護された契約書のプロンプトの後、PasswordRemoved が契約書に対してのみ真でした。 8つのページのうち8ページはデコードされ、隔離されませんでした。
  • 計画されたスイートは、リリース実行で9つのテストのうち9つが合格しました。 手作業で編集されたファイルはありませんでした。
  • どちらの供給者ファイルも契約-7310と異なり、長さ256のV 5、R 6、長さ128のV 2、R 3を読みました。どちらの理由ファイルも供給者の値を示しています。
  • 一部のステップはページと異なる方法で実行されました。 セットアップワークフローはアクションシークレットストアからキーをマッピングしました。 診断はpypdfでパスワードを試し、それは既にマシンにあり、メインエージェントは個別のレビューエージェントなしでレビューを行いました。 問題、クラウドエージェント、Actions 上のセットアップワークフロー、およびエージェントのシークレットには GitHub リポジトリが必要であるため、いずれも実行されませんでした。

Copilot CLIのバージョン、モデルAutoが選択されたもの、ランタイム、テストマシンは、ランレコードの中で各ガイドに対して1回記録されます。


トラブルシューティング


質問ありますか?

質問がある場合は、support@ironsoftware.com にお問い合わせください。

Curtis Chauは、カールトン大学でコンピュータサイエンスの学士号を取得し、Node.js、TypeScript、JavaScript、およびReactに精通したフロントエンド開発を専門としています。直感的で美しいユーザーインターフェースを作成することに情熱を持ち、Curtisは現代のフレームワークを用いた開発や、構造の良い視覚的に魅力的なマニュアルの作成を楽しんでいます。

もっと読む

準備はできましたか?

NuGetダウンロード数 82,442バージョン:2026.11ちょうどリリースされました