Jak korzystać z IronQR z GitHub Copilot
Faktury, zestawienia kont i podpisane umowy generowane przez pipeline dokumentów .NET często zawierają kod QR, aby odbiorcy mogli zweryfikować autentyczność dokumentu. Zespoły zazwyczaj utrzymują ten pipeline w rozwiązaniu Visual Studio, obok usług generowania PDF-ów, i potrzebują asystenta, który działa wewnątrz tego rozwiązania.
GitHub Copilot działa w Visual Studio, VS Code, terminalu jako Copilot CLI i na GitHubie. IronQR dodaje kody QR do istniejących stron PDF, używając QrCode.StampToExistingPdfPage. Pliki z instrukcjami repozytorium definiują, jak każda interfejs Copilot powinna obsługiwać to wywołanie.
Przewodnik stemplowania do PDF dokumentuje szczegółowo wywołanie stemplowania.
Szybki startUruchomić Copilot CLI w terminalu w katalogu głównym rozwiązania i przesłać prompt. W rozmowie w Visual Studio odnieść się do dwóch plików za pomocą # oraz nazwy pliku zamiast @.
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.
Prompt celowo pomija rozmiar stempla. Plik instrukcji specyficzny dla ścieżki poniżej zawiera tę regułę, a w biegu Copilot odczytuje go, zanim zacznie pisać metodę.
Ustawić IRONQR_LICENSE_KEY w środowisku, z którego Copilot się uruchamia, i zobaczyć przewodnik po kluczu licencyjnym dla innych miejsc, gdzie trzymać klucz.
Minimalny proces (5 kroków)
- Pobierz bibliotekę kodów QR C# z NuGet
- Zatwierdź zasady stemplowania do
.github/copilot-instructions.mdi pliku z instrukcjami specyficznymi dla ścieżki. - Utworzyć kod za pomocą
QrWriter.Write, zmienić jego rozmiar za pomocąSave, i ostemplować go za pomocąStampToExistingPdfPage - Udowodnić każdy stempel, renderując stronę do obrazu i dekodując go z IronQR
- Dać agentowi chmurowemu zadanie dokonywania kolejnej zmiany i sprawdzić jego pull request w porównaniu z dokumentacją API
Gdzie Copilot pasuje do projektu już istniejącego w Visual Studio?
Użyć trybu agenta w Visual Studio lub VS Code dla zmiany stemplowania, którą chce się obserwować, ponieważ może on zbudować rozwiązanie i uruchomić zadanie stemplowania samodzielnie. Copilot CLI działa w ten sam sposób z terminalu. Agent chmurowy na GitHub przejmuje przypisany temat i zwraca pull request.
Jak ustawić konwencje IronQR dla Copilot?
Zatwierdź konwencje IronQR jako .github/copilot-instructions.md. Tabela wsparcia GitHub wymienia plik dla Copilot CLI, agenta chmurowego, przeglądu kodu Copilot i Copilot Chat w Visual Studio, VS Code i IDE JetBrains, aby każda interfejs zaczynała od tych samych reguł.
# 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.
Jak nadać kodowi stemplowania jego własne reguły?
Reguły, które mają znaczenie tylko tam, gdzie kod stemplowania żyje, trafiają do .github/instructions/stamping.instructions.md. Jego wzór ścieżki applyTo trzyma geometrię stempla z dala od zapytań o uruchamianie jobów lub testy, a Copilot CLI uwzględnia plik tylko wtedy, gdy pracuje nad pasującym plikiem.
---
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.
Jak umieścić i dopasować kod QR na stronie PDF?
Format PDF przechowuje pozycje od lewego dolnego rogu, podczas gdy IronQR liczy od lewego górnego. W wersji IronQR 2026.10.1, x 455 i y 30 umieszczają kod w prawym górnym rogu strony A4, a y 702, dolna lewa figura dla tego samego pola, umieszcza go blisko dolnej krawędzi.
Żadna metoda stemplowania nie przyjmuje rozmiaru. W skrzynce o 110 punktach w pobliżu prawej krawędzi strony A4, kod zapisany bez QrStyleOptions wybiegał poza stronę, a renderowana strona nie zwracała żadnego kodu. Domyślny margines 10 jest dodawany po każdej stronie, więc rozmiar 110 z tym marginesem daje stempel o wielkości 130 punktów.
Niektóre próbki przekazują 0 dla pierwszej strony, co w wersji 2026.10.1 rzuca ArgumentOutOfRangeException z wiadomością "Numer strony 0 nie istnieje". Strona poza końcem kończy się w ten sam sposób, a w każdym przypadku plik pozostał niezmieniony.
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.
Strona Letter ma szerokość 612 punktów, a strona A4 - 595,28, więc jedna wartość x dla obu w wywołaniu StampToExistingPdfPages umieszcza stempel Letter 17 punktów od lewej strony pola. Błędnie umieszczony stempel nie wywołuje błędu i nadal się skanuje, dlatego testy sprawdzają, gdzie wylądował oraz co mówi.
Jak ostemplować plik PDF chroniony hasłem?
Metody stemplowania przyjmują hasło jako ostatni argument, a dokumentacja API IronQR nazywa je "hasłem do szyfrowania PDF lub hasłem administratora". Stemplowano dwu-stronicowy kontrakt zaszyfrowany przy użyciu PDFsharp 6.2.4, który ustawia hasło użytkownika do otwarcia pliku i hasło właściciela do jego zmiany. Kopie RC4 40-bitowe, RC4 128-bitowe i AES 128-bitowe dały te same wyniki.
- Hasło właściciela: stemplowanie powiodło się, a zapisany plik otworzył się bez hasła.
- Hasło użytkownika, błędne hasło lub brak hasła: IronQrPdfPasswordException z "Nie można otworzyć PDF", a plik pozostał niezmieniony.
- Kopia AES 256-bitowa: IronQrPdfPasswordException z obydwoma hasłami, podczas gdy PDFium otworzyło ten sam plik z hasłem użytkownika.
Dwa inne wyniki kształtują obsługę błędów. Brakujący plik i plik tekstowy przemianowany na .pdf wywoływały tę samą wyjątek. Kopie umowy zaszyfrowane przez MuPDF rzucały PdfSharpCore.SharpZipLib.SharpZipBaseException z "Nielegalnym sumą kontrolną nagłówka", wyjątek spoza IronQr.Exceptions, który zatrzymuje każdą serię, której "catch" nazywa tylko wyjątki 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 daje następnemu krokowi pipeline flagę do działania, niezależnie od tego, czy ten krok ponownie szyfruje plik, czy go zatrzymuje. Ostemplowany kontrakt, który cicho traci swoją ochronę, jest gorszy niż ten, który nie udaje się ostemplować.
Jak przetestować, czy ostemplowany kod QR skanuje się?
Plik umiejętności IronQR potwierdza, że biblioteka nie ma ładowarki PDF. PDFtoImage to pakiet licencjonowany na MIT, zbudowany na PDFium, który renderuje stronę przy wybranym DPI, podaje rozmiary stron za pomocą Conversion.GetPageSizes i otwiera chronione pliki hasłem. 110-punktowy stempel zdekodowany za pomocą QrReader z renderowanych obrazów przy 50, 72, 100, 150 i 300 DPI, więc nieudane odczyty w tych testach wskazują na sam stempel.
Nacisnąć Shift+Tab, aż Copilot CLI pokaże tryb planu, a następnie wysłać ten 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.
Tryb planu pasuje do tego zestawu, ponieważ pomocnik do renderowania i odczytu musi istnieć, zanim jakikolwiek pojedynczy test ma sens. Ostatnie twierdzenie przypina zachowanie z poprzedniej sekcji. Jeśli późniejsze wydanie IronQR utrzyma szyfrowanie, ten test nie przejdzie, a ktoś celowo wróci do PasswordRemoved.
Co sprawia, że temat jest działaniem, które agent chmurowy może realizować?
Kiedy przypisuje się problem, agent chmurowy otrzymuje jego tytuł, opis, istniejące komentarze i wszelkie dodatkowe instrukcje, które są dodawane. GitHub stwierdza, że nie reaguje na komentarze opublikowane po przypisaniu, więc sprawa musi zawierać całą brief, w tym, jak stwierdzić, że zadanie jest wykonane.
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.
Zespół prawny zmierzył pozycję od dołu strony, więc agent chmurowy musi ją przeliczyć zgodnie z regułą w specjalnych instrukcjach dla ścieżki, a test akceptacyjny wychwytuje pominiętą konwersję.
Dlaczego testy agenta chmurowego nie udają się na projekcie IronQR?
Agent chmurowy działa domyślnie na biegaczu Ubuntu Linux. Zwykły pakiet IronQR zależy od IronSoftware.ReaderInternals.Windows, a przewodnik po pakietach NuGet wymienia IronQR.Linux dla serwerów Linux, kontenerów i CI. Bez klucza licencyjnego, QrWriter.Write rzuca LicensingException zanim jakikolwiek stempel zostanie narysowany. Test na czerwono spowodowany konfiguracją wygląda tak samo jak ten spowodowany zmianą, więc przeczytaj pierwszy wyjątek przed porównaniem różnic.
Workflow konfiguracji w .github/workflows/copilot-setup-steps.yml, z jednym zadaniem o nazwie copilot-setup-steps, przygotowuje biegacza zanim Copilot się uruchomi, i nie uruchamia się, dopóki plik nie znajdzie się na domyślnej gałęzi.
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.
Agent chmurowy nie może odczytać tajemnic przechowywanych dla Akcji, Dependabot lub Codespaces. Przechowuj IRONQR_LICENSE_KEY i DOCSTAMP_PDF_OWNER_PASSWORD jako tajemnice Agentów, w sekcji Tajemnice i zmienne w części Bezpieczeństwo ustawień repozytorium, a Copilot otrzymuje oba jako zmienne środowiskowe.
Jak zdiagnozować PDF, który nie podlega stemplowaniu?
Ponieważ awarie haseł i nieczytelne pliki powyżej dzielą jeden wyjątek, asystent zostawiony do zgadywania stale przepracowuje obsługę haseł.
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.
W standardzie PDF, V 5 z R 6 oznacza szyfrowanie AES 256-bit, a V 2 z R 3 to RC4. Pytanie o te odczyty przed wyjaśnieniem daje roszczenie, które można sprawdzić względem plików. Utrzymanie zmiany w tekście przyczyny trzyma drugą bibliotekę PDF poza projektem, decyzję, która należy do zespołu, który posiada umowy.
Co należy sprawdzić przed scaleniem?
Przesłać /review jako własne wywołanie copilot -p. W pierwszym przebiegu wszedł do sesji, która napisała kod, a potem wrócił do poprzedniego zadania i edytował 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 wysyłany w pakiecie opisuje x i y jako piksele, podczas gdy plik instrukcji mówi punkty. Oba trzymają się w praktyce, ponieważ stempel jest rysowany jeden punkt na piksel, a recenzent, który zgłasza różnicę sformułowania bez nazywania żadnej z nich błędem, przeczytał oba źródła.
Co wyprodukowały zapytania w rzeczywistym uruchomieniu?
Siedem promptów trafiło do Copilot CLI w porządku z nikim przy klawiaturze. Pierwsze sześć dzieliło jedną sesję, z czwartą w trybie planowania i autopilocie. Celem był mały pipeline dokumentów stworzony dla tego przewodnika, z zadaniem w konsoli, pustym projektem xUnit i przykładami PDF, jednym z nich była umowa chroniona hasłem. Dwa kolejne kontrakty przybyły do folderu dostawcy przed promptem diagnostycznym. Każda liczba poniżej została sprawdzona po zakończeniu sesji, przez ponowne uruchomienie zadania i testów oraz przez odczytanie wpisów /Encrypt każdego kontraktu. Przewodnik AI coding assistants guide zamienia ten rodzaj kontroli na test powtarzalny.
- Stemplowanie każdej strony umieściło kod na x 455 na stronach A4 i x 472 na listach, a 8 z 8 stron zostało zdekodowanych wewnątrz pola przy 150 DPI.
- Po komunikacie o ochronie kontraktu,
PasswordRemovedbył prawdziwy tylko dla kontraktu. 8 z 8 stron nadal zostało zdekodowanych, a żadna nie była poddana kwarantannie. - Zaplanowany zestaw zdał 9 z 9 testów w wersji Release. Żaden plik nie został edytowany ręcznie.
- Oba pliki dostawców odczytały V 5, R 6, Długość 256, w porównaniu do V 2, R 3, Długość 128 na kontrakcie-7310, a oba pliki z przyczynami podają wartości dostawców.
- Niektóre kroki uruchomiono inaczej niż na stronie. Workflow konfiguracji zmapował klucz z magazynu tajemnic Akcji. Diagnoza próbowała haseł z pypdf, które już były na maszynie, a główny agent dokonał przeglądu bez oddzielnego agenta przeglądowego. Problem, agent chmurowy, konfiguracja workflow na Akcji i tajemnice Agentów potrzebują repozytorium GitHub, więc żaden z nich nie działa.
Wersja Copilot CLI, model Auto wybrany, czas dzialania i maszyna testowa sa zapisywane raz dla kazdego przewodnika w run record.
Rozwiązywanie problemów
- Ostempluj kod QR do PDF dla każdego parametru
StampToExistingPdfPage - Zastosuj klucz licencyjny w IronQR do ustawienia klucza, gdzie Copilot uruchamia kod
- IronQR NuGet Packages do wyboru pakietu dla biegacza Linux lub kontenera
- Komunikaty o błędach kodu QR i debugowanie do logowania wyjątków na plik w partii
- Runtimes Copy Exception jeśli biblioteki DLL do uczenia maszynowego nigdy nie dotrą do folderu wyjściowego
Pytania?
Jeśli są jakiekolwiek pytania, należy skontaktować się z support@ironsoftware.com
Curtis Chau posiada tytuł licencjata z informatyki (Uniwersytet Carleton) i specjalizuje się w front-endowym rozwoju, z ekspertką w Node.js, TypeScript, JavaScript i React. Pasjonuje się tworzeniem intuicyjnych i estetycznie przyjemnych interfejsów użytkownika, Curtis cieszy się pracą z nowoczesnymi frameworkami i tworzeniem dobrze zorganizowanych, atrakcyjnych wizualnie podręczników.