Como usar IronQR com o GitHub Copilot

Curtis Chau
Curtis Chau
Atualizado: 9 de outubro de 2026

Faturas, extratos de conta e contratos assinados gerados por um pipeline de documentos .NET frequentemente incluem um código QR para que os destinatários verifiquem a autenticidade do documento. As equipes geralmente mantêm esse pipeline dentro de uma solução do Visual Studio, junto com serviços geradores de PDF, e precisam de um assistente que funcione dentro dessa solução.

O GitHub Copilot opera no Visual Studio, VS Code, no terminal como Copilot CLI, e no GitHub. IronQR adiciona códigos QR a páginas PDF existentes usando QrCode.StampToExistingPdfPage. Os arquivos de instruções do repositório definem como cada interface do Copilot deve lidar com essa chamada.

O guia de carimbo para PDF documenta a chamada de carimbo em detalhes.

Início Rápido
NuGetInstalar com NuGet

PM > Install-Package IronQR

Instale o IronQR executando o comando acima no Console do Gerenciador de Pacotes NuGet, ou procure pelo pacote no Gerenciador de Pacotes NuGet.

Inicie o Copilot CLI em um terminal na raiz da solução e envie o prompt. No chat do Visual Studio, faça referência aos dois arquivos com # e o nome do arquivo em vez 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.
Text

O prompt omite propositalmente o tamanho do carimbo. O arquivo de instruções específico do caminho abaixo carrega essa regra, e no run o Copilot o lê antes de escrever o método.

Defina IRONQR_LICENSE_KEY no ambiente de onde o Copilot começa, e veja o guia de chave de licença para outros locais para guardar a chave.



Onde o Copilot se encaixa em um projeto já no Visual Studio?

Use o modo agente no Visual Studio ou VS Code para uma alteração de carimbo que você deseja assistir, já que pode construir a solução e executar a tarefa de carimbo. O Copilot CLI funciona da mesma forma a partir de um terminal. O agente de nuvem no GitHub aceita um problema atribuído e retorna um pull request.

Como definir convenções do IronQR para o Copilot?

Comprometa as convenções do IronQR como .github/copilot-instructions.md. A tabela de suporte do GitHub lista o arquivo para Copilot CLI, o agente em nuvem, revisão de código Copilot e Copilot Chat no Visual Studio, VS Code e IDEs JetBrains, para que cada interface inicie a partir das mesmas regras.

# 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

Como dar ao código de carimbo suas próprias regras?

Regras que importam apenas onde o código de carimbo vive vão em .github/instructions/stamping.instructions.md. Seu padrão de caminho applyTo mantêm a geometria do carimbo fora de pedidos sobre o executor de tarefas ou os testes, e o Copilot CLI inclui o arquivo apenas quando trabalha em um arquivo correspondente.

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

Como posicionar e dimensionar um código QR em uma página PDF?

O formato PDF armazena posições a partir do canto inferior esquerdo, enquanto IronQR conta a partir do superior esquerdo. Com IronQR 2026.10.1, x 455 e y 30 posicionam o código no canto superior direito de uma página A4, e y 702, a figura inferior esquerda para a mesma caixa, coloca-o próximo à borda inferior.

Nenhum método de carimbo aceita um tamanho. Na caixa de 110 pontos próxima à borda direita de uma página A4, um código salvo sem QrStyleOptions saiu da página, e a página renderizada não retornou nenhum código. A margem padrão de 10 é adicionada em todos os lados, então uma dimensão de 110 com essa margem dá um carimbo de 130 pontos.

Alguns exemplos passam 0 para a primeira página, que em 2026.10.1 lança ArgumentOutOfRangeException com a mensagem 'Page Number 0 does not exist'. Uma página após o fim falha da mesma forma, e em cada caso o arquivo foi deixado inalterado.

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

Uma página Letter tem 612 pontos de largura e uma página A4 tem 595.28, então um valor x para ambos em uma chamada StampToExistingPdfPages coloca o carimbo Letter 17 pontos à esquerda de sua caixa. O carimbo deslocado não gera erro e ainda é legível, por isso os testes verificam onde ele pousou, bem como o que diz.

Como carimbar um PDF protegido por senha?

Os métodos de carimbo aceitam a senha como seu último argumento, e a documentação da API do IronQR a chama de 'senha de criptografia ou senha de administrador do PDF'. Carimbamos um contrato de duas páginas criptografado com PDFsharp 6.2.4, que define uma senha de usuário para abrir o arquivo e uma senha de proprietário para alterá-lo. Cópias RC4 40-bit, RC4 128-bit e AES 128-bit deram os mesmos resultados.

  • Senha do proprietário: o carimbo teve sucesso, e o arquivo salvo abriu sem senha.
  • Senha do usuário, senha errada ou nenhuma: IronQrPdfPasswordException com 'PDF could not be opened', e o arquivo ficou inalterado.
  • Cópia AES de 256 bits: IronQrPdfPasswordException com ambas as senhas, enquanto PDFium abriu o mesmo arquivo com a senha do usuário.

Outros dois resultados moldam o tratamento de erros. Um arquivo ausente e um arquivo de texto renomeado para .pdf geraram a mesma exceção. Cópias do contrato criptografadas por MuPDF lançaram PdfSharpCore.SharpZipLib.SharpZipBaseException com 'Header checksum illegal', uma exceção de fora IronQr.Exceptions que interrompe qualquer lote cujo catch nomeia apenas exceções de 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.
Text

PasswordRemoved dá ao próximo passo do pipeline um sinal para agir, se esse passo irá recriptografar o arquivo ou segurá-lo. Um contrato carimbado que perde silenciosamente sua proteção é pior do que um que falha ao carimbar.

Como testar se um código QR carimbado é lido?

O arquivo de habilidade IronQR confirma que a biblioteca não tem carregador de PDF. PDFtoImage é um pacote licenciado pelo MIT construído sobre PDFium que renderiza uma página em um DPI escolhido, relata tamanhos de página através de Conversion.GetPageSizes e abre arquivos protegidos com uma senha. Um carimbo de 110 pontos decodificado com QrReader de renderizações em 50, 72, 100, 150 e 300 DPI, então uma leitura falha nesses testes aponta para o próprio carimbo.

Pressione Shift+Tab até que o Copilot CLI mostre o modo plano, então envie este 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

O modo plano é adequado para este conjunto porque o auxiliar de renderizar e ler tem que existir antes que qualquer teste individual faça sentido. A última asserção fixa o comportamento do parágrafo anterior. Se uma versão futura do IronQR manter a criptografia, esse teste falhará, e alguém revisita PasswordRemoved de propósito.

O que faz de um problema algo que o agente de nuvem pode atuar?

Quando você atribui uma issue, o agente em nuvem recebe seu título, descrição, comentários existentes e quaisquer instruções adicionais que você adicionar. O GitHub afirma que não reage a comentários postados após a atribuição, então a issue tem que carregar o briefing completo, incluindo como saber que a tarefa está concluída.

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

A equipe legal mediu a posição a partir da parte inferior da página, então o agente em nuvem precisa convertê-la com a regra nas instruções específicas do caminho, e o teste de aceitação detecta uma conversão perdida.

Por que os testes do agente em nuvem falham em um projeto IronQR?

O agente em nuvem funciona em um executor Ubuntu Linux por padrão. O pacote simples IronQR depende de IronSoftware.ReaderInternals.Windows, e o guia de pacotes NuGet nomeia IronQR.Linux para servidores Linux, containers e CI. Sem uma chave de licença, QrWriter.Write lança LicensingException antes que qualquer carimbo seja desenhado. Um teste vermelho causado por configuração parece o mesmo que um causado pela mudança, então leia a primeira exceção antes do diff.

Um fluxo de configuração em .github/workflows/copilot-setup-steps.yml, com seu único trabalho chamado copilot-setup-steps, prepara o executor antes que o Copilot comece, e ele não desencadeia até que o arquivo esteja no branch padrão.

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

O agente em nuvem não pode ler segredos armazenados para Ações, Dependabot ou Codespaces. Armazene IRONQR_LICENSE_KEY e DOCSTAMP_PDF_OWNER_PASSWORD como segredos de Agentes, sob Segredos e variáveis na parte de Segurança das Configurações do repositório, e o Copilot recebe ambos como variáveis de ambiente.

Como diagnosticar um PDF que não carimbará?

Como as falhas de senha e os arquivos ilegíveis acima compartilham uma exceção, um assistente deixado para adivinhar continua retrabalhando o tratamento de senhas.

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

No padrão PDF, V 5 com R 6 marca criptografia AES de 256 bits, e V 2 com R 3 é RC4. Pedir por essas leituras antes da explicação fornece uma alegação que você pode verificar contra os arquivos. Manter a mudança no texto da razão mantém uma segunda biblioteca de PDF fora do projeto, uma decisão que pertence à equipe que possui os contratos.

O que você deve verificar antes de fazer o merge?

Envie /review como sua própria chamada copilot -p. Na primeira execução ele entrou na sessão que escreveu o código, depois voltou para a tarefa anterior e editou 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

O XML enviado no pacote descreve x e y como pixels, enquanto o arquivo de instruções diz pontos. Ambos se mantêm na prática, porque o carimbo é desenhado um ponto por pixel, e um revisor que relata a diferença de vocabulário sem chamar nenhum deles de bug leu ambas as fontes.

O que os prompts produziram em uma execução real?

Os sete prompts foram para o Copilot CLI em ordem sem ninguém no teclado. Os primeiros seis compartilharam uma sessão, com o quarto em modo plano e piloto automático. O alvo era um pequeno pipeline de documentos feito para este guia, com um trabalho de console, um projeto xUnit vazio e PDFs de amostra, um deles um contrato protegido por senha. Mais dois contratos chegaram em uma pasta de fornecedor antes do prompt de diagnóstico. Cada figura abaixo foi verificada após o término da sessão, reexecutando o trabalho e os testes e lendo as entradas /Encrypt de cada contrato. O guia de assistentes de codificação de IA transforma este tipo de verificação em um teste repetível.

  • Carimbando cada página colocou o código em x 455 nas páginas A4 e x 472 em Letter, e 8 de 8 páginas decodificaram dentro da caixa em 150 DPI.
  • Após o prompt de contrato protegido, PasswordRemoved era verdadeiro apenas para o contrato. 8 de 8 páginas ainda decodificaram, e nenhuma foi colocada em quarentena.
  • O conjunto planejado passou 9 de 9 testes em uma execução de Release. Nenhum arquivo foi editado manualmente.
  • Ambos os arquivos do fornecedor leram V 5, R 6, Comprimento 256, contra V 2, R 3, Comprimento 128 no contract-7310, e ambos os arquivos de razão fornecem os valores do fornecedor.
  • Alguns passos foram executados de forma diferente da página. O fluxo de configuração mapeou a chave do armazenamento de segredos das Ações. O diagnóstico tentou as senhas com pypdf, que já estava na máquina, e o agente principal fez a revisão sem um agente de revisão separado. A issue, o agente em nuvem, o fluxo de configuração nas Ações e os segredos dos Agentes precisam de um repositório GitHub, portanto, nenhum deles foi executado.

A versão do Copilot CLI, o modelo automático escolhido, o tempo de execução e a máquina de teste são registrados uma vez para cada guia no registro de execução.


Solução de problemas


Questões?

Se você tiver dúvidas, entre em contato com support@ironsoftware.com

Curtis Chau é bacharel em Ciência da Computação (Universidade Carleton) e se especializa em desenvolvimento front-end, com experiência em Node.js, TypeScript, JavaScript e React. Apaixonado por criar interfaces de usuário intuitivas e esteticamente agradáveis, Curtis gosta de trabalhar com frameworks modernos e criar manuais bem estruturados e visualmente atraentes.

Leia Mais

Pronto para começar?

Downloads no NuGet 82,442Versão:2026.11recém-lançado