Comment utiliser IronQR avec GitHub Copilot
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 rapideDé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.
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é.
Flux de travail minimal (5 étapes)
- Télécharger la bibliothèque de code QR C# depuis NuGet
- Commit les règles de tamponnage dans
.github/copilot-instructions.mdet un fichier d'instructions spécifique au chemin - Créez le code avec
QrWriter.Write, dimensionnez-le avecSave, et tamponnez-le avecStampToExistingPdfPage - Prouvez chaque tampon en rendant la page sur une image et en la décodant avec IronQR
- Donnez au cloud agent une issue pour la prochaine modification et vérifiez sa pull request par rapport à la référence API
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.
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.
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.
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.
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.
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.
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.
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.
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.
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
- Tamponner un Code QR sur PDF pour chaque paramètre de
StampToExistingPdfPage - Appliquer une clé de licence dans IronQR pour définir la clé où Copilot exécute le code
- Packages NuGet IronQR pour choisir le package pour un runner Linux ou un conteneur
- Messages d'erreur et débogage des codes QR pour enregistrer les exceptions par fichier dans un lot
- Exception de copie des runtimes si les DLL d'apprentissage automatique n'atteignent jamais le dossier de sortie
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.