Cómo usar IronPrint con GitHub Copilot
Un depósito de carga imprime un formulario de entrega para cada tráiler que sale de sus bahías. El portal web del depósito guarda cada formulario como un PDF completado con campos para el conductor, el número de sello, el conteo de paletas y mercancías peligrosas, y un servicio .NET en una solución de Visual Studio imprime dos copias de cada uno. Un asistente que edita el servicio tiene que trabajar dentro de esa solución, en el editor que el equipo ya usa.
GitHub Copilot ofrece chat y modo agente dentro de Visual Studio y VS Code, Copilot CLI para el terminal, y un agente en la nube de GitHub que responde a un problema asignado con una solicitud de pull. IronPrint envía PDFs e imágenes a una impresora desde .NET, con tamaño de papel, copias, resolución y aplanamiento de formulario establecidos en un único objeto PrintSettings. Cada una de esas superficies de Copilot lee las reglas de IronPrint de los archivos de instrucciones en el repositorio.
Las instrucciones a continuación le piden a Copilot código de impresión construido sobre IronPrint. Elegir hardware de impresora o configurar un servidor de impresión es una tarea separada que ningún asistente puede realizar desde el repositorio. La guía de aplanamiento describe la configuración de IronPrint de la que dependen estos formularios.
Inicio rápidoLanza copilot desde la carpeta de la solución y envía la instrucción. En el CLI, @ antes de un path adjunta ese archivo. En Visual Studio, Copilot Chat utiliza # para el mismo propósito.
Fill in @src/Depot.Printing/HandoverPrinter.cs so the depot can print its handover forms.
Use IronPrint 2026.10.1, the version Directory.Packages.props already pins.
Give the class three public static members:
- InstalledPrinters() returns the names from Printer.GetPrinterNames.
- BuildSettings(string printerName) returns the PrintSettings that @docs/print-profile.md describes.
- PrintAsync(string pdfPath, string printerName) checks the name first, then sends the job.
An unknown name throws an ArgumentException whose message lists the installed printers.
Build the solution and fix every error.
Then list the files you changed.
La instrucción no nombra ninguna configuración individual. El perfil de impresión en docs/print-profile.md lista cada una, y Aplanar está entre ellas.
La clave de licencia va en IRONPRINT_LICENSE_KEY, configurada en el entorno en el que Copilot se ejecuta. IronPrint en sí no lee esa variable. En nuestra prueba, License.IsLicensed permaneció falso con la variable configurada hasta que el programa asignó su valor a License.LicenseKey. Otros lugares admitidos para la clave se enumeran en la guía de clave de licencia.
Flujo de trabajo mínimo (5 pasos)
- Descargue la biblioteca de impresión C# desde NuGet
- Escribe las reglas de IronPrint en .github/copilot-instructions.md más un archivo de instrucciones específico de path
- Configura Aplanar en cada trabajo de formulario y verifica cada nombre de impresora contra la lista instalada
- Prueba los PrintSettings que el código construye en lugar de enviar trabajos reales
- Asignar el próximo cambio al agente en la nube como un problema y verifica la solicitud de pull contra la referencia de API de IronPrint
¿Cómo configuras las convenciones de IronPrint para Copilot?
Las reglas a nivel de proyecto pertenecen a .github/copilot-instructions.md. La matriz de soporte de GitHub muestra soporte para ese archivo en Copilot Chat en Visual Studio, VS Code e IDEs JetBrains, y para Copilot CLI, revisión de código Copilot y el agente en la nube. Visual Studio añade el archivo a las solicitudes de Copilot Chat solo cuando su casilla de instrucciones personalizadas está seleccionada, debajo de GitHub, Copilot, Copilot Chat en la configuración de Opciones.
These rules apply to printing code in this repository:
- Handover forms print through IronPrint. The NuGet package and the namespace are both IronPrint.
- Add no other printing library and no System.Drawing.Printing code.
- Keep the IronPrint version that Directory.Packages.props sets. Only an upgrade task changes it.
- IRONPRINT_LICENSE_KEY holds the license key.
- IronPrint does not read that variable, so Program.cs copies its value into License.LicenseKey.
- Never print the value, and don't dump environment variables either.
- docs/print-profile.md is the print contract. Leave it as it is and suggest changes in your reply.
- https://ironsoftware.com/print/csharp/llms.txt indexes IronPrint's docs for agents.
- No printer on this machine finishes a job without someone answering a dialog.
- Don't send a print job from a session, a test or a dry run.
Printing tests follow these rules:
- Test the PrintSettings the code builds.
- A test never calls Printer.Print or Printer.PrintAsync with a printer name that exists.
La última regla de impresión proviene de la máquina de prueba. Allí, Microsoft Print to PDF solicita un nombre de archivo y Adobe PDF abrió una ventana Crear Adobe PDF, por lo que un trabajo enviado a cualquiera de las impresoras espera a que una persona responda.
¿Cómo le das al código de impresión sus propias reglas?
Los patrones applyTo de .github/instructions/printing.instructions.md limitan sus reglas a parte del árbol, en este caso los proyectos de origen y prueba. La documentación del CLI de GitHub indica que el CLI añade un archivo específico de path a su contexto solo para trabajar en un archivo que el valor de applyTo coincida. En nuestra ejecución, printing.instructions.md fue el primer archivo que Copilot abrió en la instrucción 1.
---
applyTo: "src/**,tests/**"
---
Source and test code here follow these IronPrint rules:
- Set Flatten = true for every handover form.
- With Flatten false, IronPrint sends the page with four empty boxes.
- Those boxes are Driver, SealNumber, PalletCount and Hazmat.
- Check a printer name against Printer.GetPrinterNames before a job.
- IronPrint throws nothing for a name it cannot match, even by case or a trailing space.
- It prints on the Windows default printer instead.
- GetPrinterTrays returns an empty list for an unknown name, as it does for some real printers.
- So an empty tray list cannot prove that a printer exists.
- NumberOfCopies reaches the driver as a copy count.
- The job itself holds one page per PDF page.
- With no key, Printer.Print throws an AggregateException that wraps a LicensingException.
- PrintAsync throws the LicensingException itself.
- Margins takes millimeters, in the order left, top, right, bottom.
Cada una de esas reglas fue medida con IronPrint 2026.10.1. Las secciones de Aplanar y nombre de la impresora a continuación dan las mediciones detrás de la primera de ellas.
¿Por qué los campos del formulario se imprimen vacíos sin Aplanar?
Estas mediciones utilizaron una impresora simulada. En Windows, IronPrint envía cada trabajo a través de la llamada PrintDocument del diálogo de impresión WPF. Un gancho en esa llamada guardó las páginas y el ticket de impresión de cada trabajo en un archivo XPS, y ninguna cola de impresión recibió un trabajo. Los cuatro formularios de entrega pasaron por ello con la configuración del ejemplo combinado de la guía de aplanamiento. Los resultados describen la página que IronPrint le da al controlador de la impresora, no el papel de una impresora física.
La comparación a continuación utiliza el formulario de entrega HO-1001, guardado con un valor en cada campo.
- Con
Flattendejado en su valor predeterminado de falso, el Conductor, número de Sello, conteo de Paletas y las casillas de Material Peligroso estaban vacías en los cuatro formularios. Tres formularios llevaban flujos de apariencia para sus campos, y las casillas también estaban vacías en ellos. - Con
Flatten = true, cada valor fue impreso. El formulario guardado sin flujos de apariencia imprimió sus valores también. - Cada página PDF se convirtió en una imagen de 2479 por 3508 píxeles en una página en retrato ISO A4, que es A4 a 300 DPI. El formulario de dos páginas produjo dos páginas.
- El ticket de impresión llevaba una cuenta de copias de 2, mientras que el documento contenía una página por página PDF.
- Los márgenes de 10 mm del ejemplo no movieron la imagen, que llenó la página desde su esquina superior izquierda.
Resultado
HO-1001 pasó por el gancho dos veces, primero con Aplanar en falso y luego con Aplanar en verdadero. Cada PDF a continuación es la imagen de página de un trabajo capturado, sin modificar y en su tamaño original.
HO-1001 con Aplanar en falso, como IronPrint construyó el trabajo, capturado en un archivo en lugar de una impresora.
HO-1001 con Aplanar en verdadero, como IronPrint construyó el trabajo, capturado en un archivo en lugar de una impresora.
La guía de aplanamiento atribuye campos vacíos a controladores de impresoras que saltan capas de formulario. En la captura, los valores ya faltaban en la página antes de que cualquier controlador la recibiera.
¿Cómo imprimes una carpeta de formularios sin enviar un trabajo?
El trabajo por lotes necesita un simulacro para que pueda ser probado sin una impresora. El simulacro registra la configuración que cada formulario recibiría, y un revisor puede comparar ese registro con el perfil de impresión.
Turn @src/Depot.PrintJob/Program.cs into the batch job that prints forms/inbox.
It accepts two options:
- --printer <name> picks the printer for every form.
- --dry-run writes the log and sends nothing.
The job runs in this order:
1. Exit with code 2 when the printer isn't installed, and list the installed ones on the console.
2. Read every PDF in forms/inbox in file name order.
3. Get each form's settings from HandoverPrinter.BuildSettings.
4. Append a line per form to out/print-log.csv, then print the form unless it's a dry run.
Paths are relative to the solution root.
The log is semicolon-delimited, with this header line:
Form;Printer;Flatten;Copies;PaperSize;Orientation;Dpi;Grayscale
Run the job twice with --dry-run.
Use --printer "Adobe PDF" the first time and --printer "Depot Laser 2" the second.
Show me both exit codes and the log.
Adobe PDF es una impresora en la máquina de prueba. Usa un nombre de tu propia lista de impresoras.
¿Qué pasa cuando un nombre de impresora no coincide?
IronPrint compara PrinterName con los nombres que Windows informa, carácter por carácter, y no genera un error cuando la comparación falla. Los trabajos capturados se dirigieron a "NoSuchPrinter 7", a una "adobe pdf" en minúsculas y a "Adobe PDF" seguido de un espacio. Microsoft Print to PDF, la impresora predeterminada de Windows, recibió todos los tres, y solo el nombre exacto fue a Adobe PDF. Un trabajo licenciado al nombre desconocido no generó excepción y solo regresó después de que se respondió el diálogo Guardar Como de Microsoft Print to PDF.
GetPrinterTrays no puede reemplazar la verificación de nombre, ya que devolvió una lista vacía para el nombre desconocido y también para Fax y Microsoft Print to PDF. GetPrinterNames devolvió las cuatro impresoras sin una clave de licencia, por lo que la verificación también funciona en pruebas que se ejecutan sin una.
¿Cómo pruebas la configuración de impresión?
Presiona Shift+Tab en Copilot CLI hasta que el modo plan esté activo, luego envía la instrucción a continuación.
Plan an xUnit project in tests/Depot.Printing.Tests and add it to the solution.
Hold off on code until I approve the plan.
Its tests cover these cases:
- Every setting BuildSettings fills in matches @docs/print-profile.md.
- PaperMargins and Tray stay null, so the printer's own defaults apply.
- PrintAsync refuses a name with the wrong case or a trailing space.
- That refusal names every printer InstalledPrinters() returns.
Once the plan is approved, add the tests and run dotnet test.
Then give me the pass and fail counts.
Revisar el plan primero muestra cómo la suite obtendrá un nombre de impresora real antes de que cualquier prueba dependa de la lista de impresoras de la máquina.
¿Cómo solucionas una reimpresión que deja los campos del formulario vacíos?
Una ruta de reimpresión escrita aparte del servicio principal puede omitir una configuración que el servicio principal aplica. En este escenario, el ReprintService de un compañero de equipo construye su propio PrintSettings sin Flatten, y los controladores reciben reimpresiones con casillas vacías.
Drivers say reprinted handover forms have empty Driver, Seal number and Pallet count boxes.
First prints look right. The reprint code is @src/Depot.Printing/ReprintService.cs.
Work out the cause before you edit anything:
1. Compare ReprintService.BuildSettings with HandoverPrinter.BuildSettings.
2. Open IronPrint.xml inside the IronPrint package in the NuGet cache.
3. Quote its summary for the setting that explains the empty boxes.
Then fix ReprintService.cs, and keep a reprint at one copy.
Leave the other source files alone.
Add a test for the reprint settings and run dotnet test.
Tell me the cause you found and the test result.
El archivo IronPrint.xml enviado conecta la configuración al síntoma en una oración, que describe Flatten como útil para mostrar los valores de los campos del formulario. No afirma que los valores faltan sin él.
¿Qué hace que un problema sea en el que el agente de la nube pueda actuar?
Copilot recibe el título del problema, descripción y comentarios existentes cuando el problema está asignado, junto con cualquier texto en el campo de instrucción opcional. La documentación de GitHub establece que el agente no está al tanto de los comentarios publicados después de la asignación, por lo que el cuerpo del problema debe indicar cuándo el trabajo está completo.
Title: Log the printer each reprint was sent to
The work involves these files and settings:
- Files: src/Depot.Printing/ReprintService.cs, tests/Depot.Printing.Tests
- IronPrint version: unchanged from Directory.Packages.props
- Framework: net9.0-windows
After the change, reprints behave like this:
- Every reprint appends a line to out/reprint-log.csv.
- The line holds the form, the printer name, the time and the copy count.
- A printer name that Windows does not report stops the reprint before anything is sent.
Today, reprints leave no record, and ReprintAsync sends a job to any name it receives.
Keep to these limits:
- Keep the ReprintAsync signature.
- Follow .github/instructions/printing.instructions.md.
- Add no packages.
Acceptance means these checks pass:
- Every existing test passes.
- A new test passes "adobe pdf" in lower case and expects an ArgumentException before any job.
Debido a que la prueba usa un nombre que difiere de la impresora instalada solo por el caso, una verificación que ignora el caso la falla.
¿Por qué fallan las pruebas del agente en la nube en un proyecto de IronPrint?
A menos que el repositorio configure otro ejecutor, el entorno del agente es Ubuntu Linux. La página de producto de IronPrint nombra Windows, macOS, iOS y Android y no nombra Linux, y cada proyecto en esta solución tiene como objetivo net9.0-windows. GitHub admite ejecutores de Windows 64 bits para el agente en la nube. Su firewall integrado no es compatible con Windows, por lo que GitHub recomienda ejecutores auto-alojados o ejecutores de GitHub más grandes con redes privadas de Azure para ese caso.
Sin un secreto de Agentes, ese entorno tampoco tiene clave de licencia. En la sonda, cada llamada de impresión sin licencia lanzó "Licencia de Producción Requerida" dentro de 0,2 segundos, antes de que se creara cualquier trabajo.
El trabajo copilot-setup-steps en .github/workflows/copilot-setup-steps.yml se ejecuta antes de que el agente comience el trabajo, y GitHub lo activa solo después de que la rama predeterminada contenga el archivo.
The cloud agent has to build this solution, so add a setup workflow for it.
Its path is .github/workflows/copilot-setup-steps.yml.
Copilot looks for one job, and it has to be named copilot-setup-steps.
The job works like this:
- Run it on windows-latest, because every project targets net9.0-windows.
- Its only permission is contents: read.
- Start it from workflow_dispatch and from pull requests that edit this workflow file.
- Its steps are a checkout, a .NET 9 SDK install, a restore and a Release build.
Printing calls need IRONPRINT_LICENSE_KEY, which is stored as an Agents secret.
The job sees that secret as an environment variable.
Add a step that tests whether the key is set:
- For pull_request and workflow_dispatch events, a missing key is a warning and the step passes.
- For every other event, a missing key fails the step with a message that names the secret.
That step goes last, since Copilot skips every setup step after one that fails.
Create the file and show me the YAML.
Usa un secreto de Agentes para la clave: el agente en la nube no puede leer secretos de Actions, Codespaces o Dependabot. Añade IRONPRINT_LICENSE_KEY en la página de Agentes de Secretos y Variables, que se encuentra en el grupo Seguridad de la configuración del repositorio. El agente luego obtiene la clave como una variable de entorno.
¿Qué debes verificar antes de fusionar?
Envía la revisión como su propio comando copilot -p. Sin --continue ni --resume, ese comando inicia una nueva sesión sin historial de la sesión de codificación.
/review the changes made since this branch's first commit.
Compare each IronPrint call with .github/instructions/printing.instructions.md.
Then compare it with the IronPrint.xml that ships in the IronPrint NuGet package.
Name every place where the code and those two sources disagree.
Flag any of these as well:
- a PrintSettings for a handover form that leaves Flatten unset or false
- a print call whose printer name was never checked against Printer.GetPrinterNames
- a test that sends a real print job
- a catch block that would miss the LicensingException a print call throws
- any line that writes IRONPRINT_LICENSE_KEY to the console or a log
Report what you find and leave every file unchanged.
¿Qué produjeron los prompts en una ejecución real?
Las seis instrucciones se programaron para ejecutarse una tras otra en Copilot CLI, sin una persona en el teclado, en una solución de depósito construida para esta guía. Después de cada instrucción, el commit se reconstruyó y se ejecutó el trabajo por lotes en él. Las configuraciones para cada formulario luego pasaron por IronPrint con la llamada de impresión interceptada, por lo que ningún trabajo llegó a una impresora.
- Antes de la ejecución, HandoverPrinter era una clase estática vacía y el trabajo por lotes era una plantilla que salía con código 1.
- La primera instrucción cambió solo HandoverPrinter.cs.
- Después de la primera instrucción, BuildSettings devolvió Aplanar activado, 2 copias, A4, retrato, 300 DPI y escala de grises.
- Bandeja y márgenes no se establecieron, por lo que se aplicaron los valores predeterminados de la impresora.
- PrintAsync verificó el nombre de la impresora con una comparación ordinal, que distingue entre mayúsculas y minúsculas.
- Cada valor de campo apareció en las páginas capturadas de los cuatro formularios.
- El ticket de impresión para cada formulario llevó 2 copias, ISO A4 en retrato, salida monocromática y 300 DPI.
- El trabajo capturado para el formulario de dos páginas contenía dos páginas, y cada otro trabajo contenía una.
- La solución se construyó con 0 errores después de cada una de las dos instrucciones.
- Después de la segunda instrucción, el simulacro para Adobe PDF salió con código 0 y registró una línea por formulario.
- Cada línea registrada coincidía con el perfil de impresión, con Aplanar y Escala de Grises ambos Verdaderos.
- El simulacro para Depot Laser 2 salió con código 2, y su salida de consola nombró las cuatro impresoras instaladas.
- Ningún simulacro hizo una llamada de impresión.
- Ningún trabajo de impresión apareció en ninguna cola durante la ejecución.
- Algunos pasos se ejecutaron de manera diferente a lo esperado. La cuota mensual de Copilot se agotó en la segunda instrucción, después de que Copilot construyó el trabajo y antes de sus simulacros. Ambos simulacros se ejecutaron fuera de Copilot en su lugar. Las instrucciones 3 a 6 no se ejecutaron, por lo que el modo plan, la solución de reimpresión, el flujo de trabajo de configuración y la revisión no tienen resultados de ejecución en esta página. El problema, el agente en la nube y el secreto de Agentes requieren un repositorio alojado, por lo que ninguno de ellos fue probado.
Cursor también limita sus reglas a patrones de archivo, y Claude Code igualmente espera un plan aprobado antes de cualquier cambio de código. El registro compartido de ejecución guarda la versión del CLI, el modelo elegido por Auto, el tiempo total de ejecución y el hardware.
Solución de problemas
- Cómo Aplanar PDFs Antes de Imprimir para campos de formulario que se imprimen vacíos
- Cómo Obtener Nombres de Impresoras para los nombres que Windows informa
- Cómo Especificar el Nombre de la Impresora para trabajos que llegan a la impresora incorrecta
- El Método Print() Se Congela en WPF y WinForms para una llamada de impresión que congela la interfaz
- Aplicando Claves de Licencia para cada lugar donde se puede establecer la clave
¿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.