Comment utiliser IronQR avec GitHub Copilot

Curtis Chau
Curtis Chau
Mis à jour : 9 octobre 2026

Les factures, relevés de compte et contrats signés générés par un pipeline de documents .NET incluent souvent un code QR pour que les destinataires puissent vérifier l'authenticité du document. Les équipes maintiennent généralement ce pipeline au sein d'une solution Visual Studio, aux côtés de services de génération de PDF, et ont besoin d'un assistant qui fonctionne à l'intérieur de cette solution.

GitHub Copilot opère dans Visual Studio, VS Code, le terminal en tant que Copilot CLI, et sur GitHub. IronQR ajoute des codes QR aux pages PDF existantes en utilisant QrCode.StampToExistingPdfPage. Les fichiers d'instructions du dépôt définissent comment chaque interface Copilot doit gérer cet appel.

Le guide de tamponnage sur PDF documente l'appel de tamponnage en détail.

Démarrage rapide
NuGetInstaller avec NuGet

PM > Install-Package IronQR

Installez IronQR en exécutant la commande ci-dessus dans la console du gestionnaire de packages NuGet, ou recherchez le package dans le gestionnaire de packages NuGet.

Démarrez Copilot CLI dans un terminal à la racine de la solution et envoyez l'invite. Dans le chat Visual Studio, référencez les deux fichiers avec # et le nom de fichier au lieu de @.

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

L'invite omet délibérément la taille du tampon. Le fichier d'instructions spécifique au chemin ci-dessous contient cette règle, et lors de l'exécution, Copilot la lit avant d'écrire la méthode.

Définissez IRONQR_LICENSE_KEY dans l'environnement d'où Copilot démarre, et consultez le guide de la clé de licence pour d'autres endroits où conserver la clé.



Où Copilot s'inscrit-il dans un projet déjà en cours sous Visual Studio ?

Utilisez le mode agent dans Visual Studio ou VS Code pour une modification de tamponnage que vous souhaitez surveiller, car il peut construire la solution et exécuter le travail de tamponnage lui-même. Copilot CLI fonctionne de la même manière depuis un terminal. L'agent cloud sur GitHub prend un problème assigné et renvoie une demande de tirage.

Comment définissez-vous les conventions d'IronQR pour Copilot?

Engagez les conventions IronQR comme .github/copilot-instructions.md. Le tableau de support de GitHub liste le fichier pour Copilot CLI, l'agent cloud, la revue de code Copilot et Copilot Chat dans Visual Studio, VS Code et les IDE JetBrains, afin que chaque interface parte des mêmes règles.

# 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

Comment donnez-vous ses propres règles au code de tamponnage?

Les règles qui ne concernent que l'endroit où vit le code de tamponnage vont dans .github/instructions/stamping.instructions.md. Son motif de chemin applyTo garde la géométrie du tampon hors des requêtes concernant le gestionnaire de tâches ou les tests, et Copilot CLI inclut le fichier uniquement lorsqu'il travaille sur un fichier correspondant.

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

Comment placez-vous et dimensionnez-vous un code QR sur une page PDF?

Le format PDF stocke les positions depuis le coin inférieur gauche, tandis qu'IronQR compte depuis le coin supérieur gauche. Avec IronQR 2026.10.1, x 455 et y 30 placent le code en haut à droite d'une page A4, et y 702, la figure inférieure gauche pour la même boîte, le place près du bord inférieur.

Aucune méthode de tamponnage ne prend une taille. Dans la boîte de 110 points près du bord droit d'une page A4, un code enregistré sans QrStyleOptions est sorti de la page, et la page rendue n'a renvoyé aucun code. La marge par défaut de 10 est ajoutée de chaque côté, donc une dimension de 110 avec cette marge donne un tampon de 130 points.

Certains exemples passent 0 pour la première page, ce qui dans 2026.10.1 lance ArgumentOutOfRangeException avec le message "Page Number 0 does not exist". Une page au-delà de la fin échoue de la même façon, et dans chaque cas le fichier est resté inchangé.

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

Une page Lettre fait 612 points de large et une page A4 mesure 595,28, donc une valeur x pour les deux dans un appel StampToExistingPdfPages place le tampon Lettre à 17 points à gauche de sa boîte. Le tampon mal placé ne soulève aucune erreur et reste scannable, c'est pourquoi les tests vérifient où il est tombé ainsi que ce qu'il dit.

Comment tamponnez-vous un PDF protégé par mot de passe?

Les méthodes de tamponnage prennent le mot de passe en dernier argument, et la documentation API d'IronQR l'appelle "le mot de passe de chiffrement PDF ou d'administrateur". Nous avons tamponné un contrat de deux pages crypté avec PDFsharp 6.2.4, qui définit un mot de passe utilisateur pour ouvrir le fichier et un mot de passe propriétaire pour le modifier. Les copies RC4 40-bit, RC4 128-bit et AES 128-bit ont donné les mêmes résultats.

  • Mot de passe propriétaire : le tampon a réussi, et le fichier enregistré s'est ouvert sans mot de passe.
  • Mot de passe utilisateur, mot de passe incorrect ou aucun : IronQrPdfPasswordException avec "PDF could not be opened", et le fichier est resté inchangé.
  • Copie AES 256-bit : IronQrPdfPasswordException avec les deux mots de passe, tandis que PDFium ouvrait le même fichier avec le mot de passe utilisateur.

Deux autres résultats modèlent la gestion des erreurs. Un fichier manquant et un fichier texte renommé en .pdf ont soulevé la même exception. Les copies du contrat crypté par MuPDF ont lancé PdfSharpCore.SharpZipLib.SharpZipBaseException avec "Header checksum illegal", une exception venant de l'extérieur IronQr.Exceptions qui arrête tout lot dont le nom de capture est uniquement 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 donne à l'étape suivante du pipeline un drapeau pour agir, que cette étape re-cryptage le fichier ou le retienne. Un contrat tamponné qui perd silencieusement sa protection est pire qu'un qui échoue à être tamponné.

Comment testez-vous qu'un code QR tamponné est scanné?

Le fichier de compétence IronQR confirme que la bibliothèque n'a pas de chargeur PDF. PDFtoImage est un package sous licence MIT construit sur PDFium qui rend une page à un DPI choisi, rapporte les tailles de page via Conversion.GetPageSizes et ouvre les fichiers protégés avec un mot de passe. Un tampon de 110 points décodé avec QrReader des rendus à 50, 72, 100, 150 et 300 DPI, donc une lecture échouée dans ces tests pointe sur le tampon lui-même.

Appuyez sur Shift+ Tab jusqu'à ce que Copilot CLI montre le mode plan, puis envoyez cette invite.

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

Le mode plan convient à cette suite parce que le helper de rendu-et-lecture doit exister avant que tout test individuel ait du sens. La dernière assertion précise le comportement de la section précédente. Si une version ultérieure d'IronQR conserve le cryptage, ce test échoue, et quelqu'un revisite PasswordRemoved exprès.

Qu'est-ce qui rend un problème sur lequel l'agent cloud peut agir ?

Quand vous assignez un problème, l'agent cloud reçoit son titre, sa description, les commentaires existants et toutes les instructions supplémentaires que vous ajoutez. GitHub déclare qu'il ne réagit pas aux commentaires postés après l'assignation, donc le problème doit porter tout le brief, y compris comment savoir que le travail est terminé.

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

L'équipe juridique a mesuré la position depuis le bas de la page, donc l'agent cloud doit la convertir avec la règle dans les instructions spécifiques au chemin, et le test d'acceptation attrape une conversion manquée.

Pourquoi les tests de l'agent cloud échouent-ils sur un projet IronQR?

L'agent cloud fonctionne par défaut sur un runner Ubuntu Linux. Le package brut IronQR dépend de IronSoftware.ReaderInternals.Windows, et le guide des packages NuGet nomme IronQR.Linux pour les serveurs Linux, les conteneurs et CI. Sans clé de licence, QrWriter.Write lance LicensingException avant qu'aucun tampon ne soit dessiné. Un test rouge causé par la configuration ressemble au même qu'un causé par le changement, donc lisez la première exception avant le diff.

Un flux de travail de configuration à .github/workflows/copilot-setup-steps.yml, avec son seul job nommé copilot-setup-steps, prépare le runner avant que Copilot ne commence, et il ne se déclenche pas tant que le fichier n'est pas sur la branche par défaut.

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

L'agent cloud ne peut pas lire les secrets stockés pour Actions, Dependabot ou Codespaces. Stockez IRONQR_LICENSE_KEY et DOCSTAMP_PDF_OWNER_PASSWORD comme secrets d'Agents, sous Secrets et variables dans la partie Sécurité des Paramètres du référentiel, et Copilot reçoit les deux comme variables d'environnement.

Comment diagnostiquez-vous un PDF qui ne se tamponne pas ?

Parce que les échecs de mot de passe et les fichiers illisibles ci-dessus partagent une exception, un assistant laissé à deviner continue de retravailler la gestion des mots de passe.

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

Dans la norme PDF, V 5 avec R 6 marque le chiffrement AES 256 bits, et V 2 avec R 3 est RC4. Demander ces lectures avant l'explication vous donne une affirmation que vous pouvez vérifier par rapport aux fichiers. Conserver le changement au texte de raison garde une deuxième bibliothèque PDF hors du projet, une décision qui appartient à l'équipe qui possède les contrats.

Que faut-il vérifier avant de fusionner ?

Envoyez /review comme son propre appel copilot -p. Lors d'une première exécution, il est allé dans la session qui a écrit le code, puis est revenu à la tâche précédente et a édité 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

Le XML livré dans le package décrit x et y comme des pixels, tandis que le fichier d'instructions indique des points. Les deux se tiennent en pratique, car le tampon est dessiné un point par pixel, et un réviseur qui rapporte la différence de formulation sans appeler l'un ou l'autre un bug a lu les deux sources.

Qu'est-ce que les messages ont produit lors d'une réelle exécution ?

Les sept invites ont été envoyées à Copilot CLI dans l'ordre sans personne au clavier. Les six premiers ont partagé une session, avec le quatrième en mode plan et autopilote. La cible était un petit pipeline de documents fait pour ce guide, avec un job console, un projet xUnit vide et des PDF d'exemples, dont un contrat protégé par mot de passe. Deux autres contrats sont arrivés dans un dossier vendeur avant l'invite de diagnostic. Chaque chiffre ci-dessous a été vérifié après la fin de la session, en relançant le job et les tests et en lisant les entrées /Encrypt de chaque contrat. Le guide des assistants de codage AI transforme ce type de vérification en un test reproductible.

  • Tamponner chaque page a mis le code à x 455 sur les pages A4 et x 472 sur Lettre, et 8 de 8 pages ont été décodées à l'intérieur de la boîte à 150 DPI.
  • Après l'invite pour le contrat protégé, PasswordRemoved ​​était vrai pour le contrat uniquement. 8 de 8 pages ont encore été décodées, et aucune n'a été mise en quarantaine.
  • La suite prévue a réussi 9 de 9 tests dans une exécution Release. Aucun fichier n'a été édité à la main.
  • Les deux fichiers vendeurs ont lu V 5, R 6, Longueur 256, contre V 2, R 3, Longueur 128 sur contrat-7310, et les deux fichiers de raison donnent les valeurs du vendeur.
  • Certaines étapes ont été exécutées différemment de la page. Le flux de travail de configuration a mappé la clé depuis le store de secrets Actions. Le diagnostic a essayé les mots de passe avec pypdf, qui était déjà sur la machine, et l'agent principal a fait l'examen sans un agent d'examen séparé. L'issue, l'agent cloud, le flux de configuration sur Actions et les secrets d'Agents ont besoin d'un référentiel GitHub, donc aucun d'eux n'a tourné.

La version de Copilot CLI, le modèle Auto choisi, le temps d'exécution et la machine de test sont enregistrés une fois pour chaque guide dans le journal d'exécution.


Dépannage


Des questions ?

Si vous avez des questions, contactez support@ironsoftware.com

Curtis Chau détient un baccalauréat en informatique (Université de Carleton) et se spécialise dans le développement front-end avec expertise en Node.js, TypeScript, JavaScript et React. Passionné par la création d'interfaces utilisateur intuitives et esthétiquement plaisantes, Curtis aime travailler avec des frameworks modernes et créer des manuels bien structurés et visuellement attrayants.

Lire la suite

Prêt à commencer ?

Téléchargements NuGet 82,442Version :2026.11tout juste publié