IronQR ve GitHub Copilot Nasıl Kullanılır

Curtis Chau
Curtis Chau
Güncellendi: 9 Ekim 2026

.NET belge hattı tarafından üretilen faturalar, hesap ekstreleri ve imzalı sözleşmeler genellikle belgelerin özgünlüğünü doğrulamaları için alıcıya QR kodu içerir. Ekipler genellikle bu hattı Visual Studio çözümü içinde, PDF oluşturma hizmetleri ile birlikte muhafaza eder ve bu çözüm içinde çalışan bir asistana ihtiyaç duyar.

GitHub Copilot, Visual Studio, VS Code, Copilot CLI olarak terminalde ve GitHub'da çalışır. IronQR, mevcut PDF sayfalarına QrCode.StampToExistingPdfPage kullanarak QR kodları ekler. Depo talimat dosyaları, her Copilot arayüzünün bu çağrıyı nasıl kullanacağını tanımlar.

PDF'ye damga kılavuzu, damgalama çağrısını ayrıntılı olarak belgelendirir.

Hızlı Başlangıç
NuGetNuGet ile Yükle

PM > Install-Package IronQR

Yukarıdaki komutu NuGet Paket Yöneticisi Konsolunda çalıştırarak veya NuGet Paket Yöneticisinde arama yaparak IronQR'u yükleyin.

Çözüm kökünde bir terminalde Copilot CLI başlatın ve istemciyi gönderin. Visual Studio sohbetinde, # ve @ yerine dosya adı ile iki dosyayı referans alın.

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

İstemci, damga boyutunu kasıtlı olarak çıkartır. Aşağıdaki yol özgü talimat dosyası bu kuralı taşır ve çalıştırmada Copilot, yöntemi yazmadan önce onu okur.

Ortam Copilot'un başladığı IRONQR_LICENSE_KEY ayarlayın ve anahtarı saklayabileceğiniz diğer yerler için lisans anahtarı kılavuzuna bakın.



Visual Studio'da zaten bir projede Copilot nerede yer alır?

İzlemek istediğiniz bir damgalama değişikliği için Visual Studio veya VS Code'da ajan modunu kullanın, çünkü çözümü derleyebilir ve damgalama işini kendisi yürütebilir. Copilot CLI bir terminalde aynı şekilde çalışır. GitHub'daki bulut ajanı, atanan bir sorunu alır ve bir çekme isteği ile geri döner.

Copilot için IronQR kurallarını nasıl belirlersiniz?

IronQR kurallarını .github/copilot-instructions.md olarak ayarlayın. GitHub'un destek tablosu, Copilot CLI, bulut ajanı, Copilot kod incelemesi ve Visual Studio, VS Code ve JetBrains IDE'lerindeki Copilot Sohbeti için dosyayı listeler, bu nedenle her arayüz aynı kurallardan başlar.

# 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

Damgalama koduna kendi kurallarını nasıl verirsiniz?

Yalnızca damgalama kodunun bulunduğu yerde önemli olan kurallar .github/instructions/stamping.instructions.md içine gider. Onun applyTo yol deseni, iş yürütücüsü veya testlerle ilgili isteklerden damga geometrisini uzak tutar ve Copilot CLI, yalnızca eşleşen bir dosyada çalışırken dosyayı dahil eder.

---
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 sayfasında bir QR kodunu nasıl yerleştirir ve boyutlandırırsınız?

PDF formatı pozisyonları sol alt köşeden saklarken, IronQR sol üst köşeden sayar. IronQR 2026.10.1 ile, x 455 ve y 30, kodu bir A4 sayfasının sağ üstüne koyar ve aynı kutu için sol alt figür olan y 702, onu alt kenarına yakın yerleştirir.

Hiçbir damga yöntemi bir boyut almaz. A4 sayfasının sağ kenarına yakın 110 puan kutusunda, QrStyleOptions olmadan kaydedilen bir kod sayfadan taşar ve oluşturulan sayfa hiçbir kod döndürmez. 10'luk varsayılan kenar boşluğu her tarafa eklenir, bu nedenle 110 boyutu olan bir kenar boşluğu 130 puanlık bir damga verir.

Bazı örnekler ilk sayfa için 0 geçirir, bu da 2026.10.1'de "Sayfa Numarası 0 mevcut değil" mesajı ile ArgumentOutOfRangeException atar. Sonun ötesinde bir sayfa aynı şekilde başarısız olur ve her durumda dosya değişmeden kalır.

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

Bir Letter sayfası 612 puan genişliğindedir ve bir A4 sayfası 595,28, bu yüzden her ikisi için bir x değeri StampToExistingPdfPages çağrısında, Letter damgasını kutusunun 17 puan solunda yerleştirir. Yanlış yerleştirilmiş damga hata vermez ve hala taranır, bu yüzden testler, nereye indirildiğini ve ne dediğini kontrol eder.

Şifre korumalı bir PDF'yi nasıl damgalarsınız?

Damga yöntemleri şifreyi son argüman olarak alır ve IronQR'nin API belgeleri onu "PDF şifresi veya yönetici şifresi" olarak adlandırır. PDFsharp 6.2.4 ile şifrelenmiş iki sayfalı bir sözleşmeye damgaladık, bu da dosyayı açmak için bir kullanıcı şifresi ve değiştirmek için bir sahip şifresi ayarlar. RC4 40-bit, RC4 128-bit ve AES 128-bit kopyaları aynı sonuçları verdi.

  • Sahip şifresi: damga başarılı oldu ve kaydedilen dosya şifresiz açıldı.
  • Kullanıcı şifresi, yanlış şifre veya yok: IronQrPdfPasswordException ile "PDF açılamadı" ve dosya değişmedi.
  • AES 256-bit kopya: her iki şifre ile IronQrPdfPasswordException, aynı dosyayı kullanıcı şifresi ile açarken PDFium ile.

İki diğer sonuç hata işleme şekillendirir. Eksik bir dosya ve .pdf olarak yeniden adlandırılmış bir metin dosyası aynı istisnayla karşılaştı. MuPDF tarafından şifrelenmiş sözleşme kopyaları, "Başlık kontrol toplamı yasa dışı" ile PdfSharpCore.SharpZipLib.SharpZipBaseException fırlattı, ki bu, yalnızca IronQR istisnalarını adlandıran bir batch'i durduran IronQr.Exceptions dışından bir istisnadır.

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 bir sonraki hat adımına hareket edecek bir bayrak verir, o adım dosyayı yeniden şifreler veya geri tutar. Sessizce korumasını kaybeden bir damgalanmış sözleşme, damgalanamayan birinden daha kötüdür.

Damgalanmış bir QR kodunun tarandığını nasıl test edersiniz?

IronQR beceri dosyası kütüphane için bir PDF yükleyici olmadığını doğrular. PDFtoImage, PDFium üzerinde inşa edilmiş, bir sayfayı seçilen bir DPI'da oluşturan, Conversion.GetPageSizes aracılığıyla sayfa boyutlarını raporlayan ve bir şifre ile korunan dosyaları açan bir MIT lisanslı pakettir. 50, 72, 100, 150 ve 300 DPI'da QrReader ile kodu çözülen bir 110 puan damga, bu testlerde başarısız bir okumanın doğrudan damgayı işaret ettiğini gösterir.

Plan modunu gösterene kadar Copilot CLI'da Shift+Tab tuşlarına basın, ardından bu istemciyi gönderin.

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

Plan modu, tek bir test mantıklı gelmeden önce var olması gereken render-and-read yardımcı programı olduğundan dolayı bu suite için uygundur. Son çıkarım, önceki bölümdeki davranış şekillendirir. Eğer daha sonraları bir IronQR sürümü şifrelemeyi korursa, bu test başarısız olur ve PasswordRemoved bilinçli olarak yeniden ziyaret edilir.

Bulut ajanının etkili olduğu bir sorun ne yapar?

Bir sorunu atadığınızda, bulut ajanı başlığı, açıklaması, mevcut yorumları ve eklediğiniz diğer talimatları alır. GitHub, atanma sonrasında yapılan yorumlara tepki vermediğini bildirir, bu yüzden mesele tüm açıklamayı taşımalıdır ve işin bittiğini anlatmanın yolu dahil olmalıdır.

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

Hukuk ekibi pozisyonu sayfanın altından ölçtü, bu yüzden bulut ajanı yol özgü talimatlardaki kuralla bunu dönüştürmeli ve kabul testi kaçırılan bir dönüştürmeyi yakalar.

Bulut ajanının testleri neden bir IronQR projesinde başarısız oluyor?

Bulut ajanı varsayılan olarak Ubuntu Linux yürütücüde çalışır. Düz IronQR paketi IronSoftware.ReaderInternals.Windows bağımlıdır ve NuGet paketleri kılavuzu Linux sunucuları, kaplar ve CI için IronQR.Linux adını verir. Bir lisans anahtarı olmadan, QrWriter.Write herhangi bir damga çizilmeden önce LicensingException atar. Yapılandırmadan kaynaklanan bir kırmızı test, değişiklikten kaynaklananla aynı görünür, bu yüzden diff öncesi ilk istisnayı okuyun.

Bir iş copilot-setup-steps olarak adlandırılmış .github/workflows/copilot-setup-steps.yml'de kurulum iş akışı, Copilot başlamadan önce yürütücüyü hazırlar ve dosya varsayılan dallına getirilene kadar tetiklenmez.

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

Bulut ajanı, Actions, Dependabot veya Codespaces için saklanan sırları okuyamaz. IRONQR_LICENSE_KEY ve DOCSTAMP_PDF_OWNER_PASSWORD'yi, Depo Ayarları'nın Güvenlik bölümündeki Secrets ve değişkenler altında Ajan Sırları olarak depolayın ve Copilot her iki sır da ortam değişkenleri olarak alır.

Damgalamayacak bir PDF'yi nasıl teşhis edersiniz?

Yukarıdaki parola hataları ve okunamayan dosyalar tek bir istisnayı paylaştığı için, bir asistana bırakılan bu tahmin, parola işlemi üzerinde çalışmaya devam eder.

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 standardında, V 5 ile R 6 AES 256-bit şifrelemeyi işaret eder ve V 2 ile R 3 RC4'dur. İstekte bulunarak bu okumaları dosyalara karşı kontrol edebileceğiniz bir iddia elde edebilirsiniz. Sebep metnini değişikliğini korumak, projede ikinci bir PDF kütüphanesini dışarıda tutar, bu da kontratlara sahip olan ekibe ait bir karardır.

Birleştirmeden önce neyi kontrol etmelisiniz?

/review'yı kendi copilot -p çağrısı olarak gönderin. İlk çalıştırmada, oturum kodunu yazdığında alaç bir sonraki göreve geri gitti ve StampJob.cs düzenledi.

/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

Paket içinde gönderilen XML, x ve y'yi piksel olarak tanımlar, talimat dosyası ise puanlar olarak belirtir. Her ikisi pratikte geçerlidir, çünkü damga bir puan başına bir piksel çizilir ve hiçbirini hata olarak savunmayan bir gözden geçiren, her iki kaynağı da okuyarak sorunu bildirmiştir.

Gerçek bir çalıştırmada istemler ne üretti?

Yedi istem, klavyede kimse olmadan sırayla Copilot CLI'ye gitti. İlk altı biri oturumu paylaştı, dördüncü plan modunda ve autopilot. Hedef, bu kılavuz için yapılmış, bir konsol işi, boş bir xUnit projesi ve örnek PDF'ler, bunlardan biri şifre korumalı bir sözleşme içeren küçük bir belge hattıydı. Teşhis isteminden önce bir satıcı klasörüne iki sözleşme daha geldi. Aşağıdaki her rakam, oturum bittikten sonra, işleri ve testleri yeniden çalıştırarak ve her sözleşmenin /Encrypt girişlerini okuyarak kontrol edildi. AI kodlama asistanları kılavuzu, bu tür bir kontrolü tekrarlanabilir bir teste dönüştürür.

  • Her sayfayı damgalamak, A4 sayfalarında x 455 ve Letter'da x 472'de kodu koydu ve 8'den 8 sayfa, kutunun içinde 150 DPI'da çözüldü.
  • Korunan sözleşme isteminin ardından, PasswordRemoved yalnızca sözleşme için doğruydu. 8'den 8 sayfa hala çözüldü ve hiçbiri karantinaya alınmadı.
  • Planlanan suite, bir Sürüm çalışmasında 9'dan 9 testi geçti. Hiçbir dosya elle düzenlenmedi.
  • Her iki satıcı dosyası, contract-7310'da V 2, R 3, Uzunluk 128'e karşı V 5, R 6, Uzunluk 256 okudu ve her iki sebep dosyası da satıcı değerlerini verdi.
  • Bazı adımlar sayfadan farklı çalıştı. Kurulum iş akışı, anahtarı Actions gizli mağazasından eşledi. Teşhis, zaten makinede bulunan pypdf ile şifreleri denedi ve ana ajan ayrı bir gözden geçirme ajanı olmadan incelemeyi yaptı. Sorun, bulut ajanı, Actions üzerinde kurulum iş akışı ve Ajan Sırları bir GitHub deposuna ihtiyaç duyar, bu yüzden hiçbiri çalışmadı.

Copilot CLI sürümü, seçilen Otomatik model, çalışma süresi ve test makinesi, çalıştırma kaydında her kılavuz için bir kez kaydedilir.


Hata Ayıklama


Sorular?

Herhangi bir sorunuz varsa, support@ironsoftware.com adresinden bize ulaşın

Curtis Chau, Bilgisayar Bilimleri alanında Lisans Derecesine (Carleton Üniversitesi) sahip ve Node.js, TypeScript, JavaScript ve React konularında uzmanlaşmış ön uç geliştirmeyle ilgileniyor. Sezgisel ve estetik açıdan hoş kullanıcı arayüzleri oluşturma tutkunu, Curtis modern çerçevelerle çalışmayı ve iyi yapılandırılmış, görsel olarak çekici kılavuzlar oluşturmayı seviyor.

Daha Fazla Oku

Başlamaya Hazır mısınız?

NuGet İndirmeleri 82,442Sürüm:2026.11yeni çıktı