Cómo usar IronQR con GitHub Copilot
Facturas, estados de cuenta y contratos firmados generados por un pipeline de documentos .NET a menudo incluyen un código QR para que los destinatarios verifiquen la autenticidad del documento. Los equipos suelen mantener este pipeline dentro de una solución de Visual Studio, junto con servicios que generan PDFs, y necesitan un asistente que funcione dentro de esa solución.
GitHub Copilot opera en Visual Studio, VS Code, la terminal como Copilot CLI y en GitHub. IronQR agrega códigos QR a páginas PDF existentes usando QrCode.StampToExistingPdfPage. Los archivos de instrucciones del repositorio definen cómo cada interfaz de Copilot debe manejar esta llamada.
La guía de estampado en PDF documenta la llamada de estampado en detalle.
Inicio rápidoInicie Copilot CLI en una terminal en la raíz de la solución y envíe la solicitud. En el chat de Visual Studio, haga referencia a los dos archivos con # y el nombre del archivo en lugar 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.
El aviso omite el tamaño del sello a propósito. El archivo de instrucciones específico de la ruta a continuación lleva esa regla, y en la ejecución, Copilot lo lee antes de escribir el método.
Configure IRONQR_LICENSE_KEY en el entorno desde el cual Copilot comience, y consulte la guía de clave de licencia para otros lugares donde guardar la clave.
Flujo de trabajo mínimo (5 pasos)
- Descarga la biblioteca de códigos QR C# desde NuGet
- Comprometa las reglas de estampado en
.github/copilot-instructions.mdy un archivo de instrucciones específico de la ruta. - Cree el código con
QrWriter.Write, tamaño conAhorra, y estampe conStampToExistingPdfPage - Demuestre cada sello renderizando la página a una imagen y decodificándola con IronQR
- Dé al agente de la nube un problema para el próximo cambio y revise su solicitud de extracción frente a la referencia API
¿Dónde encaja Copilot en un proyecto ya en Visual Studio?
Use el modo agente en Visual Studio o VS Code para un cambio de estampado que quiera observar, ya que puede construir la solución y ejecutar el trabajo de estampado por sí mismo. Copilot CLI funciona de la misma manera desde una terminal. El agente de la nube en GitHub toma un problema asignado y devuelve una solicitud de extracción.
¿Cómo se configuran las convenciones de IronQR para Copilot?
Comprometa las convenciones de IronQR como .github/copilot-instructions.md. La tabla de soporte de GitHub enumera el archivo para Copilot CLI, el agente de la nube, la revisión de código de Copilot y el Chat de Copilot en Visual Studio, VS Code e IDEs de JetBrains, para que cada interfaz comience desde las mismas reglas.
# 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.
¿Cómo le das al código de estampado sus propias reglas?
Las reglas que solo importan donde vive el código de estampado van en .github/instructions/stamping.instructions.md. Su patrón de ruta applyTo mantiene la geometría del sello fuera de las solicitudes sobre el ejecutor de trabajos o las pruebas, y Copilot CLI incluye el archivo solo cuando trabaja en un archivo coincidente.
---
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.
¿Cómo se coloca y dimensiona un código QR en una página PDF?
El formato PDF almacena posiciones desde la esquina inferior izquierda, mientras que IronQR cuenta desde la esquina superior izquierda. Con IronQR 2026.10.1, x 455 e y 30 colocan el código en la esquina superior derecha de una página A4, e y 702, la cifra inferior izquierda para el mismo cuadro, lo colocan cerca del borde inferior.
Ningún método de estampado toma un tamaño. En el cuadro de 110 puntos cerca del borde derecho de una página A4, un código guardado sin QrStyleOptions se salió de la página, y la página renderizada no devolvió ningún código en absoluto. El margen predeterminado de 10 se agrega en cada lado, por lo que una dimensión de 110 con ese margen da un sello de 130 puntos.
Algunas muestras pasan 0 para la primera página, que en 2026.10.1 lanza ArgumentOutOfRangeException con el mensaje "Page Number 0 does not exist". Una página más allá del final falla de la misma manera, y en cada caso el archivo quedó sin cambios.
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.
Una página Carta tiene 612 puntos de ancho y una página A4 tiene 595.28, por lo que un valor x para ambos en una llamada StampToExistingPdfPages coloca el sello Carta 17 puntos a la izquierda de su cuadro. El sello mal colocado no genera un error y aún se escanea, por lo que las pruebas verifican dónde aterrizó además de lo que dice.
¿Cómo se estampa un PDF protegido con contraseña?
Los métodos de estampado toman la contraseña como su último argumento, y la documentación de la API de IronQR lo llama "la contraseña de encriptación del PDF o del administrador". Estampamos un contrato de dos páginas encriptado con PDFsharp 6.2.4, que establece una contraseña de usuario para abrir el archivo y una contraseña de propietario para cambiarlo. Copias RC4 de 40-bit, RC4 de 128-bit y AES de 128-bit dieron los mismos resultados.
- Contraseña de propietario: el sello tuvo éxito, y el archivo guardado se abrió sin contraseña.
- Contraseña de usuario, contraseña incorrecta o ninguna: IronQrPdfPasswordException con "PDF could not be opened", y el archivo quedó sin cambios.
- Copia AES de 256-bit: IronQrPdfPasswordException con ambas contraseñas, mientras que PDFium abrió el mismo archivo con la contraseña de usuario.
Otros dos resultados moldean el manejo de errores. Un archivo faltante y un archivo de texto renombrado a .pdf generaron la misma excepción. Copias del contrato cifrado por MuPDF lanzaron PdfSharpCore.SharpZipLib.SharpZipBaseException con "Header checksum illegal", una excepción fuera de IronQr.Exceptions que detiene cualquier lote cuyo catch solo nombre excepciones 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.
PasswordRemoved da al siguiente paso del pipeline una bandera para actuar, ya sea que ese paso re-encripte el archivo o lo retenga. Un contrato estampado que pierde silenciosamente su protección es peor que uno que no logra estamparse.
¿Cómo pruebas que un código QR estampado se escanea?
El archivo de habilidades de IronQR confirma que la biblioteca no tiene un cargador de PDFs. PDFtoImage es un paquete con licencia MIT basado en PDFium que renderiza una página en un DPI escogido, reporta tamaños de página a través de Conversion.GetPageSizes y abre archivos protegidos con una contraseña. Un sello de 110 puntos decodificado con QrReader de renderizaciones a 50, 72, 100, 150 y 300 DPI, por lo que una lectura fallida en estas pruebas apunta al propio sello.
Presione Shift+Tab hasta que Copilot CLI muestre el modo de plan, luego envíe esta solicitud.
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.
El modo de plan se adapta a esta suite porque el ayudante de renderización y lectura debe existir antes de que cualquier prueba individual tenga sentido. La última aseveración fija el comportamiento de la sección anterior. Si una versión posterior de IronQR conserva la encriptación, esa prueba falla, y alguien revisita PasswordRemoved a propósito.
¿Qué hace que un problema sea en el que el agente de la nube pueda actuar?
Cuando asigna un problema, el agente de la nube recibe su título, descripción, comentarios existentes y cualquier instrucción extra que agregue. GitHub declara que no reacciona a comentarios posteados después de la asignación, por lo que el problema debe contener toda la información, incluyendo cómo saber que el trabajo está hecho.
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.
El equipo legal midió la posición desde la parte inferior de la página, por lo que el agente de la nube debe convertirlo con la regla en las instrucciones específicas de la ruta, y la prueba de aceptación detecta una conversión perdida.
¿Por qué fallan las pruebas del agente de la nube en un proyecto de IronQR?
El agente de la nube funciona en un ejecutor de Ubuntu Linux por defecto. El paquete IronQR depende de IronSoftware.ReaderInternals.Windows, y la guía de paquetes NuGet nombra IronQR.Linux para servidores Linux, contenedores y CI. Sin una clave de licencia, QrWriter.Write lanza LicensingException antes de que se dibuje cualquier sello. Una prueba roja causada por una configuración se ve igual que una causada por el cambio, así que lea la primera excepción antes de la diferencia.
Un flujo de configuración en .github/workflows/copilot-setup-steps.yml, con su único trabajo llamado copilot-setup-steps, prepara el ejecutor antes de que comience Copilot, y no se activa hasta que el archivo está en la rama por defecto.
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.
El agente de la nube no puede leer secretos almacenados para Actions, Dependabot o Codespaces. Almacene IRONQR_LICENSE_KEY y DOCSTAMP_PDF_OWNER_PASSWORD como secretos de Agents, bajo Secretos y variables en la parte de Seguridad de los Ajustes del repositorio, y Copilot recibe ambos como variables de entorno.
¿Cómo diagnosticar un PDF que no se estampa?
Debido a que las fallas de contraseña y los archivos ilegibles de arriba comparten una excepción, un asistente dejado a adivinar sigue rehaciendo el manejo de contraseñas.
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.
En el estándar PDF, V 5 con R 6 marca encriptación AES de 256-bits, y V 2 con R 3 es RC4. Pedir esas lecturas antes de la explicación le da una afirmación que puede verificar contra los archivos. Mantener el cambio en el texto de razón mantiene una segunda biblioteca PDF fuera del proyecto, una decisión que pertenece al equipo que posee los contratos.
¿Qué debes verificar antes de fusionar?
Envíe /review como su propia llamada copilot -p. En una primera ejecución, fue a la sesión que escribió el código, luego volvió a la tarea anterior y editó 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.
El XML enviado en el paquete describe x e y como píxeles, mientras que el archivo de instrucciones dice puntos. Ambos se sostienen en la práctica, porque el sello se dibuja un punto por píxel, y un revisor que reporta la diferencia de redacción sin llamar a ninguno de ellos un error ha leído ambas fuentes.
¿Qué produjeron los prompts en una ejecución real?
Las siete solicitudes fueron a Copilot CLI en orden sin nadie en el teclado. Las primeras seis compartieron una sesión, con la cuarta en modo de planificación y piloto automático. El objetivo era un pequeño pipeline de documentos hecho para esta guía, con un trabajo de consola, un proyecto xUnit vacío y PDFs de muestra, uno de ellos un contrato protegido con contraseña. Dos contratos más llegaron a una carpeta de proveedor antes de la solicitud de diagnóstico. Cada figura a continuación fue verificada después de que la sesión terminó, ejecutando nuevamente el trabajo y las pruebas y leyendo las entradas de /Encrypt de cada contrato. La guía de asistentes de codificación AI convierte este tipo de verificación en una prueba repetible.
- Estampar cada página puso el código en x 455 en páginas A4 y x 472 en Carta, y 8 de 8 páginas se decodificaron dentro del cuadro a 150 DPI.
- Después de la solicitud de contrato protegido,
PasswordRemovedfue verdadero solo para el contrato. 8 de 8 páginas aún se decodificaron, y ninguna fue puesta en cuarentena. - La suite planificada pasó 9 de 9 pruebas en una ejecución de Release. Ningún archivo fue editado a mano.
- Ambos archivos de proveedor leyeron V 5, R 6, Longitud 256, contra V 2, R 3, Longitud 128 en el contrato-7310, y ambos archivos de razón dan los valores del proveedor.
- Algunos pasos se ejecutaron de manera diferente a lo esperado. El flujo de configuración mapeó la clave del almacén de secretos de Actions. El diagnóstico intentó las contraseñas con pypdf, que ya estaba en la máquina, y el agente principal hizo la revisión sin un agente revisor separado. El problema, el agente de la nube, el flujo de configuración en Actions y los secretos de Agents necesitan un repositorio de GitHub, por lo que ninguno de ellos se ejecutó.
La versión de Copilot CLI, el modelo Auto elegido, el tiempo de ejecución y la máquina de prueba se registran una vez para cada guía en el registro de ejecución.
Solución de problemas
- Estampar Código QR en PDF para cada parámetro de
StampToExistingPdfPage - Aplicar una clave de licencia en IronQR para establecer la clave donde Copilot ejecuta el código
- Paquetes NuGet de IronQR para elegir el paquete para un ejecutor de Linux o un contenedor
- Mensajes de error de Código QR y depuración para registrar las excepciones por archivo en un lote
- Excepción de Copia de Runtimes si las DLLs de aprendizaje automático nunca llegan a la carpeta de salida
¿Preguntas?
Si tienes alguna pregunta, contacta a support@ironsoftware.com
Curtis Chau tiene una licenciatura en Ciencias de la Computación (Carleton University) y se especializa en el desarrollo front-end con experiencia en Node.js, TypeScript, JavaScript y React. Apasionado por crear interfaces de usuario intuitivas y estéticamente agradables, disfruta trabajando con frameworks modernos y creando manuales bien estructurados y visualmente atractivos.