IronQR과 GitHub Copilot 사용 방법
.NET 문서 파이프라인에서 생성된 송장, 계좌 명세서 및 서명된 계약서에는 일반적으로 문서의 진위성을 확인하기 위한 QR 코드가 포함됩니다. 팀은 일반적으로 Visual Studio 솔루션 내에서 이 파이프라인을 유지하며, PDF 생성 서비스와 함께 솔루션 내에서 동작할 수 있는 보조 도구가 필요합니다.
GitHub Copilot은 Visual Studio, VS Code, 터미널에서는 Copilot CLI로, 그리고 GitHub에서 작동합니다. IronQR은 QrCode.StampToExistingPdfPage을 사용하여 기존 PDF 페이지에 QR 코드를 추가합니다. 저장소의 지시 파일에는 각 Copilot 인터페이스가 이 호출을 처리하는 방법이 정의되어 있습니다.
PDF에 도장 가이드는 도장 호출을 자세히 문서화합니다.
빠른 시작솔루션 루트에서 터미널에서 Copilot CLI를 시작하고 프롬프트를 전송합니다. Visual Studio 채팅에서 #과 파일 이름으로 두 파일을 참조하고, 대신 @을 사용합니다.
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.
프롬프트는 고의적으로 도장 크기를 생략합니다. 아래의 경로별 지시 파일에는 이 규칙이 있으며, Copilot은 메서드 작성을 시작하기 전에 이를 읽습니다.
Copilot이 시작하는 환경에서 IRONQR_LICENSE_KEY을 설정하고, 라이선스 키 가이드에서는 키를 저장할 다른 장소를 확인합니다.
최소 워크플로우(5단계)
- NuGet에서 C# QR 코드 라이브러리를 다운로드하세요
- 도장 규칙을
.github/copilot-instructions.md와 경로별 지시 파일에 커밋합니다. QrWriter.Write로 코드를 생성하고,Save로 크기를 조절한 후StampToExistingPdfPage로 도장합니다.- 페이지를 이미지로 렌더링하고 IronQR로 디코딩하여 각 도장을 증명합니다.
- 다음 변경 사항을 위한 이슈를 클라우드 에이전트에게 제출하고 API 레퍼런스에 대해 풀 리퀘스트를 확인합니다.
Copilot이 이미 Visual Studio에 있는 프로젝트에 어떻게 맞춰질까요?
Visual Studio 또는 VS Code에서 에이전트 모드를 사용하여 감시하고자 하는 도장 변경 사항을 확인하세요. 이 모드는 솔루션을 빌드하고 도장 작업을 자체로 실행할 수 있습니다. Copilot CLI는 터미널에서 동일한 방식으로 작동합니다. GitHub의 클라우드 에이전트는 할당된 문제를 받아 풀 요청을 반환합니다.
Copilot을 위한 IronQR 규칙을 설정하는 방법
IronQR 규칙을 .github/copilot-instructions.md으로 커밋합니다. GitHub의 지원 테이블은 Copilot CLI, 클라우드 에이전트, Copilot 코드 리뷰 및 Visual Studio, VS Code, JetBrains IDE의 Copilot Chat을 위한 파일을 나열하므로 각 인터페이스는 동일한 규칙에서 시작합니다.
# 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.
도장 코드를 위한 규칙을 어떻게 설정합니까?
도장 코드에만 영향을 미치는 규칙은 .github/instructions/stamping.instructions.md에 들어갑니다. 경로 패턴 applyTo은 작업 런너나 테스트에 관한 요청에서 도장 기하를 배제하며, Copilot CLI는 일치하는 파일에서 작업할 때만 파일을 포함합니다.
---
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.
PDF 페이지에 QR 코드를 배치하고 크기를 조정하는 방법
PDF 형식은 왼쪽 하단 모서리에서 위치를 저장하는 반면, IronQR은 왼쪽 상단에서 시작합니다. IronQR 2026.10.1에서는 x 455와 y 30이 A4 페이지의 오른쪽 상단에 코드를 배치하고, 같은 박스의 경우 y 702가 하단 가장자리 근처에 배치합니다.
어떤 도장 메서드도 크기를 가져가지 않습니다. A4 페이지의 오른쪽 가장자리 근처의 110포인트 박스에서는, QrStyleOptions를 사용하지 않고 저장된 코드가 페이지를 벗어나고, 렌더링된 페이지는 어떤 코드도 반환하지 않았습니다. 기본 여백 10은 모든 측면에 추가되므로, 여백이 포함된 110의 치수는 130포인트 도장을 제공합니다.
2026.10.1에서 첫 페이지에 대해 0을 전달하면 "페이지 번호 0이 존재하지 않음"이라는 메시지와 함께 ArgumentOutOfRangeException을 발생시킵니다. 끝을 넘은 페이지는 동일한 방식으로 실패하며, 각 경우 파일은 변경되지 않습니다.
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.
Letter 페이지의 너비는 612포인트이고 A4 페이지는 595.28포인트이므로 StampToExistingPdfPages 호출에서 둘 다에 대한 x값 하나는 Letter 도장을 박스의 왼쪽으로 17포인트 옮깁니다. 잘못된 위치의 도장은 오류를 발생시키지 않으며 여전히 스캔이 가능하므로, 테스트는 위치와 그 내용 모두를 확인합니다.
암호로 보호된 PDF를 어떻게 도장합니까?
도장 메서드는 암호를 마지막 인수로 취하며, IronQR의 API 문서는 이를 "PDF 암호화 또는 관리자 암호"라고 부릅니다. PDFsharp 6.2.4로 암호화된 두 페이지 계약서를 도장하였으며, 파일을 열기 위한 사용자 암호와 변경을 위한 소유자 암호를 설정합니다. RC4 40비트, RC4 128비트 및 AES 128비트 복사는 동일한 결과를 제공했습니다.
- 소유자 암호: 도장에 성공하였으며, 저장된 파일은 암호 없이 열렸습니다.
- 사용자 암호, 잘못된 암호 또는 없음: "PDF를 열 수 없음"이라는 IronQrPdfPasswordException이 발생하였으며, 파일은 변경되지 않았습니다.
- AES 256비트 복사본: 두 암호에서 IronQrPdfPasswordException이 발생하였으며, PDFium은 사용자 암호로 동일한 파일을 열 수 있었습니다.
다른 두 결과는 오류 처리를 형성합니다. 누락된 파일과 .pdf로 이름이 변경된 텍스트 파일은 동일한 예외를 발생시켰습니다. MuPDF로 암호화된 계약 사본이 '헤더 체크섬이 불법적이다'라는 PdfSharpCore.SharpZipLib.SharpZipBaseException 예외와 함께 발생했으며, 이는 IronQR 예외만 잡는 배치를 막는 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은 다음 파이프라인 단계에 파일을 다시 암호화하거나 보류할 플래그를 제공합니다. 조용히 보호를 잃는 도장된 계약서는 도장에 실패하는 것보다 더 나쁩니다.
도장된 QR 코드가 스캔되는지를 어떻게 테스트합니까?
IronQR 기술 파일은 라이브러리에 PDF 로더가 없음을 확인합니다. PDFtoImage는 PDFium을 기반으로 하여 MIT 라이선스에 따라 빌드된 패키지로서, 선택한 DPI에서 페이지를 렌더링하고, Conversion.GetPageSizes을 통해 페이지 크기를 보고하며, 암호로 보호된 파일을 엽니다. 50, 72, 100, 150, 300 DPI로 렌더링된 QrReader을 사용해 디코딩된 110포인트 도장이므로, 이러한 테스트에서 실패한 읽기는 도장 자체에 문제가 있습니다.
Shift+Tab을 눌러 Copilot CLI가 계획 모드를 표시하도록 한 후 이 프롬프트를 전송합니다.
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.
계획 모드는 이 스위트에 적합합니다. 왜냐하면 렌더링 및 읽기 보조자가 있어야 하는 한 가지 존재해야만 모든 개별 테스트가 의미가 있기 때문입니다. 마지막 단언은 이전 섹션의 동작을 고정합니다. 나중에 IronQR 릴리스에서 암호화를 유지하면 해당 테스트가 실패하며, PasswordRemoved를 의도적으로 다시 방문해야 합니다.
클라우드 에이전트가 작동할 수 있는 문제는 무엇입니까?
문제를 할당하면 클라우드 에이전트는 제목, 설명, 기존 댓글 및 추가 지시 사항을 받습니다. GitHub는 할당 후 게시된 댓글에 반응하지 않으므로, 과제가 완료되었음을 알리는 방법을 포함하여 전체 간략한 정보를 가져야 합니다.
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.
법적 팀은 페이지의 하단에서 위치를 측정했으므로 클라우드 에이전트는 경로별 지시에 따른 규칙을 사용하여 이를 변환해야 하며, 수락 테스트는 변환 누락을 포착합니다.
왜 클라우드 에이전트의 테스트가 IronQR 프로젝트에서 실패합니까?
클라우드 에이전트는 기본적으로 Ubuntu Linux 러너에서 작동합니다. 일반 IronQR 패키지는 IronSoftware.ReaderInternals.Windows에 의존하며, NuGet 패키지 가이드는 Linux 서버, 컨테이너 및 CI를 위해 IronQR.Linux을 지정합니다. 라이선스 키가 없으면 QrWriter.Write는 도장이 그려지기 전에 LicensingException을 throw 합니다. 구성에 의해 발생된 붉은 테스트는 변경에 의해 발생된 테스트와 동일해 보이므로, diff를 수행하기 전에 첫 번째 예외를 읽으세요.
딱 한 가지 작업 copilot-setup-steps이 있는 .github/workflows/copilot-setup-steps.yml에서의 설정 워크플로우가 Copilot 시작 전에 러너를 준비하며, 파일이 기본 분기(on the default branch)에 있을 때까지 트리거되지 않습니다.
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.
클라우드 에이전트는 Actions, Dependabot 또는 Codespaces에 저장된 비밀을 읽을 수 없습니다. IRONQR_LICENSE_KEY와 DOCSTAMP_PDF_OWNER_PASSWORD을 Agents 비밀로 저장하고, 저장소의 설정에서 보안의 비밀 및 변수를 통해 Copilot은 이를 환경 변수로 받습니다.
도장되지 않는 PDF를 진단하는 방법
위의 암호 실패와 읽을 수 없는 파일은 하나의 예외를 공유하기 때문에, 추측에 남겨진 보조는 암호 처리를 계속해서 재작업하게 됩니다.
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.
PDF 표준에서 V 5와 R 6은 AES 256비트 암호화를 표시하며, V 2와 R 3은 RC4입니다. 설명 전에 이러한 읽기를 요청하면 파일과 비교할 수 있는 클레임을 얻을 수 있습니다. 이유 텍스트를 변경하지 않음으로써 두 번째 PDF 라이브러리가 프로젝트에 들어오지 않게 하며, 이는 계약을 소유한 팀의 결정입니다.
병합 전에 무엇을 확인해야 합니까?
/review을 자체 copilot -p 호출로 전송합니다. 첫 번째 실행에서 코드를 작성한 세션에 들어갔다가 이전 작업으로 돌아가 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은 x와 y를 픽셀로 설명하며, 지시 파일은 포인트로 설명합니다. 둘 다 실제로 적용됩니다. 왜냐하면 도장이 픽셀당 한 포인트로 그려지기 때문이며, 두 소스를 모두 읽었으면서 버그라고 부르지 않고 차이를 보고하는 리뷰어가 이를 검사했음을 의미합니다.
실제 실행에서 프롬프트가 무엇을 생성했습니까?
7개의 프롬프트가 키보드 없이 순서대로 Copilot CLI로 전송되었습니다. 처음 여섯 개는 동일한 세션을 공유했으며, 네 번째는 계획 모드와 자동 조종 모드였습니다. 대상은 이 가이드를 위해 만든 작은 문서 파이프라인이었으며, 콘솔 작업, 빈 xUnit 프로젝트 및 샘플 PDF가 포함되어 있으며, 그 중 하나는 암호로 보호된 계약서였습니다. 두 개의 추가 계약서는 진단 프롬프트 이전에 벤더 폴더에 도착했습니다. 아래의 모든 숫자는 세션이 종료된 후에 작업과 테스트를 다시 실행하고 각 계약의 /Encrypt 항목을 읽어 확인되었습니다. AI 코딩 도우미 가이드는 이러한 종류의 검사를 반복 가능한 테스트로 전환합니다.
- 모든 페이지에 도장을 찍으면 A4 페이지에서는 x 455에, Letter에서는 x 472에 코드를 배치하였고, 150 DPI에서 8개의 페이지 중 8개가 박스 내에서 디코딩되었습니다.
- 보호된 계약 프롬프트 후,
PasswordRemoved가 계약에 대해서만 참이었습니다. 8개의 페이지 중 8개가 여전히 디코드되었으며, 격리된 것은 없었습니다. - 계획된 스위트는 릴리스 실행에서 9개의 테스트 중 9개를 통과했습니다. 파일은 수작업으로 편집되지 않았습니다.
- 두 벤더 파일은 V 5, R 6, 길이 256으로 읽었으며, contract-7310에서는 V 2, R 3, 길이 128에 비해 벤더 값이 제공되었습니다.
- 일부 단계는 페이지와 달리 작동했습니다. 설정 워크플로우가 Actions 비밀 저장소에서 키를 매핑했습니다. 진단은 이미 기계에 설치된 pypdf로 암호를 시도했으며, 주요 에이전트는 별도의 리뷰 에이전트 없이 검토를 수행했습니다. 이슈, 클라우드 에이전트, Actions의 설정 워크플로우 및 Agents 비밀은 GitHub 저장소가 필요하므로, 아무 것도 실행되지 않았습니다.
Copilot CLI 버전, Auto가 선택한 모델, 실행 시간 및 테스트 기기는 실행 기록에 가이드당 한 번 기록됩니다.
문제 해결
StampToExistingPdfPage의 각 매개변수에 대해 PDF에 QR 코드 도장- 코드가 Copilot에서 실행되는 위치에 키를 설정하려면 IronQR에 라이선스 키 적용
- Linux 러너 또는 컨테이너에 적합한 패키지를 선택하려면 IronQR NuGet 패키지
- 파일별 예외를 기록하려면 QR 코드 오류 메시지 및 디버깅
- 머신 러닝 DLL이 출력 폴더에 도달하지 않을 경우 런타임 복사 예외
질문?
질문이 있으시면 support@ironsoftware.com으로 문의하세요.
커티스 차우는 칼턴 대학교에서 컴퓨터 과학 학사 학위를 취득했으며, Node.js, TypeScript, JavaScript, React를 전문으로 하는 프론트엔드 개발자입니다. 직관적이고 미적으로 뛰어난 사용자 인터페이스를 만드는 데 열정을 가진 그는 최신 프레임워크를 활용하고, 잘 구성되고 시각적으로 매력적인 매뉴얼을 제작하는 것을 즐깁니다.