So verwenden Sie IronQR mit GitHub Copilot

Curtis Chau
Curtis Chau
Aktualisiert: 9. Oktober 2026

Rechnungen, Kontoauszüge und unterschriebene Verträge, die von einer .NET-Dokumentenpipeline erstellt werden, enthalten oft einen QR-Code, damit die Empfänger die Echtheit des Dokuments überprüfen können. Teams pflegen diese Pipeline üblicherweise innerhalb einer Visual Studio-Lösung, neben PDF-erzeugenden Diensten, und benötigen einen Assistenten, der innerhalb dieser Lösung funktioniert.

GitHub Copilot arbeitet in Visual Studio, VS Code, dem Terminal als Copilot CLI und auf GitHub. IronQR fügt mit QrCode.StampToExistingPdfPage QR-Codes zu bestehenden PDF-Seiten hinzu. Die Anleitungsdateien des Repositories definieren, wie jede Copilot-Schnittstelle diesen Aufruf behandeln soll.

Der Stempel-zu-PDF-Leitfaden dokumentiert den Stempelaufruf im Detail.

Schnellstart
NuGetMit NuGet installieren

PM > Install-Package IronQR

Installieren Sie IronQR, indem Sie den obigen Befehl in der NuGet Packet Manager-Konsole ausführen, oder suchen Sie das Paket im NuGet Paket Manager.

Starten Sie Copilot CLI in einem Terminal im Lösungsstammverzeichnis und senden Sie den Prompt. Beziehen Sie sich im Visual Studio-Chat auf die beiden Dateien mit # und dem Dateinamen anstelle von @.

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

Der Prompt lässt die Stempelgröße absichtlich aus. Die pfadspezifische Anleitungsdatei unten enthält diese Regel, und bei der Ausführung liest Copilot sie, bevor die Methode geschrieben wird.

Setzen Sie IRONQR_LICENSE_KEY in der Umgebung, von der Copilot gestartet wird, und schauen Sie im Lizenzschlüssel-Leitfaden nach weiteren Orten, um den Schlüssel aufzubewahren.



Wo passt Copilot in ein bereits in Visual Studio vorhandenes Projekt?

Verwenden Sie den Agent-Modus in Visual Studio oder VS Code für eine Stempeländerung, die Sie beobachten möchten, da er die Lösung selbst erstellen und den Stempelauftrag ausführen kann. Copilot CLI arbeitet auf die gleiche Weise von einem Terminal aus. Der Cloud-Agent auf GitHub nimmt ein zugewiesenes Problem und gibt eine Pull-Anfrage zurück.

Wie setzen Sie IronQR-Konventionen für Copilot?

Übertragen Sie die IronQR-Konventionen als .github/copilot-instructions.md. Die Support-Tabelle von GitHub listet die Datei für Copilot CLI, den Cloud-Agenten, Copilot Code Review und Copilot Chat in Visual Studio, VS Code und JetBrains IDEs auf, damit jede Schnittstelle mit denselben Regeln beginnt.

# 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

Wie geben Sie dem Stempelcode eigene Regeln?

Regeln, die nur an dem Ort wichtig sind, an dem der Stempelcode lebt, gehen in .github/instructions/stamping.instructions.md. Sein applyTo Pfadmuster hält die Stempelgeometrie aus Anfragen über den Job-Runner oder die Tests heraus, und Copilot CLI schließt die Datei nur ein, wenn es an einer passenden Datei arbeitet.

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

Wie platzieren und dimensionieren Sie einen QR-Code auf einer PDF-Seite?

Das PDF-Format speichert Positionen von der unteren linken Ecke aus, während IronQR von der oberen linken zählt. Mit IronQR 2026.10.1 positionieren x 455 und y 30 den Code in der oberen rechten Ecke einer A4-Seite, und y 702, die untere linke Zahl für dasselbe Feld, positioniert ihn in der Nähe des unteren Randes.

Keine Stempelmethode nimmt eine Größe entgegen. Im 110-Punkt-Feld nahe dem rechten Rand einer A4-Seite lief ein Code, der ohne QrStyleOptions gespeichert wurde, von der Seite ab, und die gerenderte Seite gab überhaupt keinen Code zurück. Die Standardmarge von 10 wird auf jede Seite addiert, sodass eine Dimension von 110 mit dieser Marge einen 130-Punkt-Stempel ergibt.

Einige Beispiele übergeben 0 für die erste Seite, was in 2026.10.1 ArgumentOutOfRangeException mit der Nachricht "Page Number 0 does not exist" wirft. Eine Seite über das Ende hinaus schlägt auf dieselbe Weise fehl, und in jedem Fall blieb die Datei unverändert.

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

Eine Letter-Seite ist 612 Punkte breit und eine A4-Seite 595.28, sodass ein x-Wert für beide in einem StampToExistingPdfPages Aufruf den Letter-Stempel 17 Punkte links von seinem Feld platziert. Der falsch platzierte Stempel löst keinen Fehler aus und kann dennoch gescannt werden, weshalb die Tests überprüfen, wo er gelandet ist und was er aussagt.

Wie stempeln Sie ein passwortgeschütztes PDF?

Die Stempelmethoden nehmen das Passwort als ihr letztes Argument, und die API-Dokumentation von IronQR nennt es "das PDF-Verschlüsselungs- oder Administratorpasswort". Wir stempelten einen zweiseitigen Vertrag, der mit PDFsharp 6.2.4 verschlüsselt war, welches ein Benutzerpasswort zum Öffnen der Datei und ein Eigentümerpasswort zum Ändern setzt. RC4 40-Bit, RC4 128-Bit und AES 128-Bit Kopien ergaben dieselben Ergebnisse.

  • Besitzerpasswort: der Stempel war erfolgreich, und die gespeicherte Datei öffnete sich ohne Passwort.
  • Benutzerpasswort, falsches Passwort oder keines: IronQrPdfPasswordException mit "PDF could not be opened", und die Datei blieb unverändert.
  • AES 256-Bit Kopie: IronQrPdfPasswordException mit beiden Passwörtern, während PDFium dieselbe Datei mit dem Benutzerpasswort öffnete.

Zwei andere Ergebnisse gestalten die Fehlerbehandlung. Eine fehlende Datei und eine in .pdf umbenannte Textdatei warfen dieselbe Ausnahme. Kopien des Vertrags, die mit MuPDF verschlüsselt wurden, warfen PdfSharpCore.SharpZipLib.SharpZipBaseException mit "Header checksum illegal", eine Ausnahme von außerhalb IronQr.Exceptions, die jeden Batch stoppt, dessen Catch nur IronQR-Ausnahmen nennt.

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 gibt dem nächsten Pipeline-Schritt eine Flagge, auf der er handeln kann, ob dieser Schritt die Datei erneut verschlüsselt oder sie zurückhält. Ein gestempelter Vertrag, der stumm seinen Schutz verliert, ist schlimmer als einer, der es nicht schafft zu stempeln.

Wie prüfen Sie, dass ein gestempelter QR-Code gelesen werden kann?

Die IronQR Skill-Datei bestätigt, dass die Bibliothek keinen PDF-Loader hat. PDFtoImage ist ein MIT-lizenziertes Paket, das auf PDFium basiert und eine Seite mit einer gewählten DPI rendert, Seitengrößen durch Conversion.GetPageSizes meldet und geschützte Dateien mit einem Passwort öffnet. Ein 110-Punkt-Stempel wurde mit QrReader von Renderings bei 50, 72, 100, 150 und 300 DPI dekodiert, sodass ein Fehllesung in diesen Tests auf den Stempel selbst hinweist.

Drücken Sie Shift+Tab, bis Copilot CLI den Planmodus anzeigt, und senden Sie dann diesen Prompt.

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

Der Planmodus passt zu dieser Suite, da der Render- und Lesehelfer existieren muss, bevor ein einzelner Test sinnvoll ist. Die letzte Behauptung legt das Verhalten aus dem vorherigen Abschnitt fest. Wenn eine spätere IronQR-Version die Verschlüsselung beibehält, schlägt dieser Test fehl, und jemand besucht PasswordRemoved absichtlich erneut.

Was macht ein Problem aus, auf das der Cloud-Agent reagieren kann?

Wenn Sie ein Problem zuweisen, erhält der Cloud-Agent dessen Titel, Beschreibung, bestehende Kommentare und alle zusätzlichen Anweisungen, die Sie hinzufügen. GitHub gibt an, dass es nicht auf Kommentare reagiert, die nach der Zuweisung gepostet werden, sodass das Problem das gesamte Briefing tragen muss, einschließlich der Anleitung, wie man erkennt, dass der Job erledigt ist.

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

Das rechtliche Team maß die Position von unten auf der Seite, daher muss der Cloud-Agent diese mit der Regel in den pfadspezifischen Anweisungen umwandeln, und der Abnahmetest erkennt eine verpasste Umwandlung.

Warum schlagen die Tests des Cloud-Agenten in einem IronQR-Projekt fehl?

Der Cloud-Agent arbeitet standardmäßig auf einem Ubuntu Linux-Runner. Das einfache IronQR Paket hängt von IronSoftware.ReaderInternals.Windows ab, und der NuGet-Pakete-Leitfaden nennt IronQR.Linux für Linux-Server, Container und CI. Ohne einen Lizenzschlüssel wirft QrWriter.Write LicensingException, bevor ein Stempel gezogen wird. Ein durch Konfiguration verursachter roter Test sieht genauso aus wie ein durch die Änderung verursachter, also lesen Sie die erste Ausnahme vor dem Unterschied.

Ein Setup-Workflow bei .github/workflows/copilot-setup-steps.yml, mit seinem einzigen Job copilot-setup-steps genannt, bereitet den Runner vor, bevor Copilot startet, und er wird nicht ausgelöst, bis die Datei im Standardzweig ist.

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

Der Cloud-Agent kann keine für Actions, Dependabot oder Codespaces gespeicherten Geheimnisse einsehen. Speichern Sie IRONQR_LICENSE_KEY und DOCSTAMP_PDF_OWNER_PASSWORD als Agents-Geheimnisse, unter Geheimnisse und Variablen im Sicherheitsteil der Repository-Einstellungen, und Copilot erhält beide als Umgebungsvariablen.

Wie diagnosizieren Sie ein PDF, das nicht gestempelt werden kann?

Da die oben genannten Passwortfehler und die nicht lesbaren Dateien eine Ausnahme teilen, ein Assistent, der zum Raten gelassen wird, bearbeitet weiterhin die Passwortbehandlung.

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

Im PDF-Standard kennzeichnet V 5 mit R 6 AES 256-Bit-Verschlüsselung, und V 2 mit R 3 ist RC4. Das Abfragen dieser Lesungen vor der Erklärung gibt Ihnen einen Anspruch, den Sie anhand der Dateien überprüfen können. Das Beibehalten der Änderung des Grundtextes hält eine zweite PDF-Bibliothek aus dem Projekt, eine Entscheidung, die dem Team gehört, das die Verträge besitzt.

Was sollten Sie prüfen, bevor Sie zusammenführen?

Senden Sie /review als eigenen copilot -p Aufruf. In einem ersten Lauf ging es in die Sitzung, die den Code schrieb, dann ging es zurück zur vorherigen Aufgabe und bearbeitete 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

Das im Paket enthaltene XML beschreibt x und y als Pixel, während die Anleitungsdatei Punkte sagt. Beide gelten in der Praxis, da der Stempel mit einem Punkt pro Pixel gezeichnet wird, und ein Prüfer, der den Wortlautunterschied berichtet, ohne einen als Fehler zu bezeichnen, hat beide Quellen gelesen.

Was haben die Aufforderungen in einem realen Lauf erzeugt?

Die sieben Prompts gingen in der richtigen Reihenfolge an Copilot CLI, ohne dass jemand an der Tastatur saß. Die ersten sechs teilten sich eine Sitzung, wobei die vierte im Planmodus und auf Autopilot war. Das Ziel war eine kleine Dokumentenpipeline, die für diesen Leitfaden erstellt wurde, mit einem Konsolenauftrag, einem leeren xUnit-Projekt und Beispiel-PDFs, darunter ein passwortgeschützter Vertrag. Zwei weitere Verträge kamen in einem Anbieterverzeichnis an, bevor der Diagnose-Prompt erfolgte. Jede unten stehende Zahl wurde überprüft, nachdem die Sitzung beendet war, indem der Job und die Tests erneut ausgeführt und die /Encrypt Einträge jedes Vertrags gelesen wurden. Der AI Coding Assistants Guide verwandelt diese Art von Überprüfung in einen wiederholbaren Test.

  • Das Stempeln jeder Seite platzierte den Code bei x 455 auf A4-Seiten und x 472 auf Letter, und 8 von 8 Seiten dekodierten innerhalb des Feldes bei 150 DPI.
  • Nach dem geschützten Vertrags-Prompt war PasswordRemoved nur für den Vertrag wahr. 8 von 8 Seiten wurden immer noch dekodiert, und keine wurden unter Quarantäne gestellt.
  • Die geplante Suite bestand 9 von 9 Tests in einem Release-Lauf. Kein Datei wurde von Hand bearbeitet.
  • Beide Anbieterdateien lasen V 5, R 6, Länge 256, im Vergleich zu V 2, R 3, Länge 128 auf Vertrag-7310, und beide Begründungsdateien geben die Anbieterswerte.
  • Einige Schritte liefen anders als die Seite. Der Setup-Workflow hat den Schlüssel aus dem Actions-Geheimnisspeicher abgebildet. Die Diagnose versuchte die Passwörter mit pypdf, das bereits auf der Maschine war, und der Hauptagent führte die Rezension ohne einen separaten Revisionsagenten durch. Das Problem, der Cloud-Agent, der Setup-Workflow auf Actions und die Agents-Geheimnisse benötigen ein GitHub-Repository, daher wurde keiner von ihnen ausgeführt.

Die Copilot CLI-Version, das Auto ausgewählte Modell, die Laufzeit und der Testrechner werden einmal für jede Anleitung im Laufprotokoll aufgezeichnet.


Fehlerbehebung


Fragen?

Wenn Sie Fragen haben, wenden Sie sich an support@ironsoftware.com.

Curtis Chau hat einen Bachelor-Abschluss in Informatik von der Carleton University und ist spezialisiert auf Frontend-Entwicklung mit Expertise in Node.js, TypeScript, JavaScript und React. Leidenschaftlich widmet er sich der Erstellung intuitiver und ästhetisch ansprechender Benutzerschnittstellen und arbeitet gerne mit modernen Frameworks sowie der Erstellung gut strukturierter, optisch ansprechender Handbücher.

Mehr lesen

Bereit loszulegen?

NuGet-Downloads 82,442Version:2026.11gerade veröffentlicht