Como Usar o IronPrint com o GitHub Copilot
Um depósito de frete imprime um formulário de entrega do transportador para cada reboque que sai de suas docas. O portal web do depósito salva cada formulário como um PDF preenchido com campos para o motorista, o número do selo, a contagem de paletes e mercadorias perigosas, e um serviço .NET em uma solução do Visual Studio imprime duas cópias de cada um. Um assistente que edita o serviço precisa trabalhar dentro dessa solução, no editor que a equipe já utiliza.
O GitHub Copilot oferece modo de chat e agente dentro do Visual Studio e VS Code, Copilot CLI para o terminal, e um agente na nuvem do GitHub que responde a uma issue atribuída com um pull request. O IronPrint envia PDFs e imagens para uma impressora do .NET, com tamanho de papel, cópias, resolução e achatamento de formulário configurados em um único objeto PrintSettings. Cada uma dessas superfícies do Copilot lê as regras do IronPrint de arquivos de instrução no repositório.
Os prompts abaixo pedem ao Copilot o código de impressão construído no IronPrint. Escolher hardware de impressora ou configurar um servidor de impressão é uma tarefa separada que nenhum assistente pode realizar a partir do repositório. O guia de achatamento descreve a configuração do IronPrint de que esses formulários dependem.
Início RápidoInicie copilot da pasta da solução e envie o prompt. No CLI, @ antes de um caminho anexa esse arquivo. No Visual Studio, o Chat do Copilot usa # para o mesmo 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.
O prompt não nomeia nenhuma configuração individual. O perfil de impressão em docs/print-profile.md lista cada uma, e Flatten está entre elas.
A chave de licença vai em IRONPRINT_LICENSE_KEY, configurada no ambiente em que o Copilot é executado. O próprio IronPrint não lê essa variável. Em nosso teste, License.IsLicensed permaneceu falso com a variável configurada até que o programa atribuísse seu valor a License.LicenseKey. Outros locais suportados para a chave estão listados no guia de chave de licença.
Fluxo de trabalho mínimo (5 etapas)
- Baixe a biblioteca de impressão C# do NuGet
- Escreva as regras do IronPrint em .github/copilot-instructions.md mais um arquivo de instruções específico do caminho
- Configure Flatten em cada tarefa de formulário e verifique cada nome de impressora na lista instalada
- Teste as PrintSettings que o código constrói em vez de enviar tarefas reais
- Atribua a próxima alteração ao agente na nuvem como uma issue e verifique o pull request em relação à referência de API do IronPrint
Como definir as convenções do IronPrint para o Copilot?
As regras de todo o projeto pertencem a .github/copilot-instructions.md. A matriz de suporte do GitHub mostra suporte para esse arquivo no Copilot Chat no Visual Studio, VS Code e IDEs JetBrains, e para Copilot CLI, revisão de código Copilot e o agente na nuvem. O Visual Studio adiciona o arquivo às solicitações do Chat do Copilot somente quando a caixa de seleção de instruções personalizadas está marcada, em GitHub, Copilot, Chat do Copilot nas configurações de Opções.
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.
A última regra de impressão vem da máquina de teste. Lá, o Microsoft Print to PDF solicita um nome de arquivo e o Adobe PDF abriu uma janela Criar Adobe PDF, então uma tarefa enviada para qualquer impressora espera por uma resposta de uma pessoa.
Como dar ao código de impressão suas próprias regras?
Os padrões applyTo de .github/instructions/printing.instructions.md limitam suas regras a parte da árvore, neste caso os projetos de origem e teste. A documentação do CLI do GitHub afirma que o CLI adiciona um arquivo específico do caminho ao seu contexto apenas para trabalho em um arquivo que o valor applyTo corresponda. Em nossa execução, printing.instructions.md foi o primeiro arquivo que o Copilot abriu no prompt 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 uma dessas regras foi medida com o IronPrint 2026.10.1. As seções Flatten e nome da impressora abaixo trazem as medições por trás da primeira delas.
Por que os campos do formulário imprimem vazios sem Flatten?
Essas medições usaram uma impressora simulada. No Windows, o IronPrint envia cada tarefa por meio da chamada PrintDocument do diálogo de impressão WPF. Um gancho nessa chamada salvou as páginas e o ticket de impressão de cada tarefa em um arquivo XPS, e nenhuma fila de impressão recebeu uma tarefa. Os quatro formulários de entrega passaram por ele com as configurações do exemplo combinado do guia de achatamento. Os resultados descrevem a página que o IronPrint fornece ao driver da impressora, não o papel de uma impressora física.
A comparação abaixo usa o formulário de entrega HO-1001, salvo com um valor em cada campo.
- Com
Flattendeixado em seu padrão de falso, o Motorista, Número do Selo, Contagem de Paletes e caixas de Mercadorias Perigosas estavam vazios em todos os quatro formulários. Três formulários continham fluxos de aparência para seus campos, e as caixas também estavam vazias nesses. - Com
Flatten = true, todos os valores foram impressos. O formulário salvo sem fluxos de aparência também imprimiu seus valores. - Cada página PDF tornou-se uma imagem de 2479 por 3508 pixels em uma página em retrato ISO A4, que é A4 a 300 DPI. O formulário de duas páginas produziu duas páginas.
- O ticket de impressão carregava uma contagem de cópias de 2, enquanto o documento continha uma página por página PDF.
- As margens de 10 mm do exemplo não moveram a imagem, que preencheu a página desde seu canto superior esquerdo.
Saída
O HO-1001 passou pelo gancho duas vezes, primeiro com Flatten falso e depois com Flatten verdadeiro. Cada PDF abaixo é a imagem da página de uma tarefa capturada, não modificada e em seu tamanho original.
HO-1001 com Flatten falso, como o IronPrint construiu a tarefa, capturado em um arquivo no lugar de uma impressora.
HO-1001 com Flatten verdadeiro, como o IronPrint construiu a tarefa, capturado em um arquivo no lugar de uma impressora.
O guia de achatamento atribui campos vazios a drivers de impressoras que ignoram camadas de formulários. Na captura, os valores já estavam ausentes da página antes que qualquer driver a recebesse.
Como imprimir uma pasta de formulários sem enviar uma tarefa?
A tarefa em lote precisa de uma execução a seco para que possa ser testada sem uma impressora. A execução a seco registra as configurações que cada formulário receberia, e um revisor pode comparar esse log com o perfil de impressão.
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 é uma impressora na máquina de teste. Use um nome da sua própria lista de impressoras.
O que acontece quando um nome de impressora não corresponde?
O IronPrint compara PrinterName com os nomes que o Windows relata, caractere por caractere, e não levanta erro quando a comparação falha. Tarefas capturadas foram endereçadas a "NoSuchPrinter 7", a um "adobe pdf" em minúsculas e a "Adobe PDF" seguido por um espaço. Microsoft Print to PDF, a impressora padrão do Windows, recebeu todas as três, e somente o nome exato foi para o Adobe PDF. Uma tarefa licenciada para o nome desconhecido não levantou exceção e retornou apenas após o diálogo Salvar Como do Microsoft Print to PDF ser respondido.
GetPrinterTrays não pode substituir a verificação de nome, já que retornou uma lista vazia para o nome desconhecido e também para Fax e Microsoft Print to PDF. GetPrinterNames retornou todas as quatro impressoras sem uma chave de licença, então a verificação também funciona em testes que são executados sem uma.
Como testar as configurações de impressão?
Pressione Shift+Tab no CLI do Copilot até que o modo de plano esteja ativo, depois envie o prompt abaixo.
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 o plano primeiro mostra como o conjunto obterá um nome real de impressora antes que qualquer teste dependa da lista de impressoras da máquina.
Como corrigir uma reimpressão que deixa os campos do formulário vazios?
Um caminho de reimpressão escrito separado do serviço principal pode omitir uma configuração que o serviço principal aplica. Neste cenário, o ReprintService de um colega constrói seu próprio PrintSettings sem Flatten, e os drivers recebem reimpressões com caixas vazias.
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.
O IronPrint.xml expedido conecta a configuração ao sintoma em uma frase, que descreve Flatten como útil para exibir valores de campos de formulários. Não afirma que os valores estão ausentes sem ela.
O que faz de um problema algo que o agente de nuvem pode atuar?
Copilot recebe o título do problema, descrição e comentários existentes quando o problema é atribuído, junto com qualquer texto no campo de prompt opcional. A documentação do GitHub afirma que o agente não está ciente dos comentários postados após a atribuição, então o corpo do problema deve declarar quando o trabalho está concluído.
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.
Porque o teste usa um nome que difere da impressora instalada apenas por maiúsculas, uma verificação que ignora maiúsculas e minúsculas falha.
Por que os testes do agente na nuvem falham em um projeto IronPrint?
A menos que o repositório configure outro executor, o ambiente do agente é o Ubuntu Linux. A página do produto do IronPrint nomeia Windows, macOS, iOS e Android e não nomeia Linux, e todo projeto nesta solução tem como alvo net9.0-windows. O GitHub suporta executores Windows 64-bit para o agente de nuvem. Seu firewall integrado não é compatível com Windows, então o GitHub recomenda executores auto-hospedados ou executores maiores hospedados pelo GitHub com redes privadas do Azure para esse caso.
Sem um segredo Agents, esse ambiente também não possui uma chave de licença. Na sonda, cada chamada de impressão não licenciada executou "Licença de Produção Requerida" dentro de 0,2 segundos, antes que qualquer tarefa fosse criada.
O trabalho copilot-setup-steps em .github/workflows/copilot-setup-steps.yml é executado antes do agente começar a trabalhar, e o GitHub o aciona somente após o branch padrão conter o arquivo.
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.
Use um segredo Agents para a chave: o agente de nuvem não pode ler as Actions, Codespaces ou Dependabot secrets. Adicione IRONPRINT_LICENSE_KEY na página de Agents de Segredos e Variáveis, encontrada no grupo de Segurança das Configurações do repositório. O agente então obtém a chave como uma variável de ambiente.
O que você deve verificar antes de fazer o merge?
Envie a revisão como seu próprio comando copilot -p. Sem --continue ou --resume, esse comando inicia uma nova sessão sem histórico da sessão de codificação.
/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.
O que os prompts produziram em uma execução real?
Os seis prompts foram agendados para operar um após o outro no CLI do Copilot, sem ninguém no teclado, em uma solução de depósito construída para este guia. Após cada prompt, o commit foi reconstruído e a tarefa em lote executada nele. As configurações para cada formulário então passaram pelo IronPrint com a chamada de impressão interceptada, então nenhuma tarefa chegou a uma impressora.
- Antes da execução, HandoverPrinter era uma classe estática vazia e a tarefa em lote era um stub que saia com código 1.
- O primeiro prompt modificou apenas o HandoverPrinter.cs.
- Após o primeiro prompt, BuildSettings retornou Flatten ligado, 2 cópias, A4, retrato, 300 DPI e tons de cinza.
- Bandeja e margens permaneceram não definidas, então os padrões da impressora foram aplicados.
- PrintAsync verificou o nome da impressora com uma comparação ordinal, que é sensível a maiúsculas e minúsculas.
- Cada valor de campo apareceu nas páginas capturadas de todos os quatro formulários.
- O ticket de impressão para cada formulário carregou 2 cópias, ISO A4 retrato, saída monocromática e 300 DPI.
- A tarefa capturada para o formulário de duas páginas continha duas páginas, e cada outra tarefa continha uma.
- A solução foi construída com 0 erros após cada um dos dois prompts.
- Após o segundo prompt, a execução a seco para Adobe PDF saiu com código 0 e registrou uma linha por formulário.
- Cada linha registrada correspondia ao perfil de impressão, com Flatten e Grayscale ambos Verdadeiros.
- A execução a seco para Depot Laser 2 saiu com código 2, e sua saída de console nomeou as quatro impressoras instaladas.
- Nenhuma execução a seco fez uma chamada de impressão.
- Nenhuma tarefa de impressão apareceu em qualquer fila durante a execução.
- Alguns passos foram executados de forma diferente da página. A cota mensal do Copilot esgotou-se no segundo prompt, após o Copilot construir a tarefa e antes de suas execuções a seco. Ambas as execuções a seco foram executadas fora do Copilot em vez disso. Os prompts 3 a 6 não foram executados, então o modo de plano, a correção de reimpressão, o fluxo de trabalho de configuração e a revisão não possuem resultados de execução nesta página. A issue, o agente na nuvem e o segredo de Agents exigem um repositório hospedado, então nenhum deles foi testado.
Cursor também restringe suas regras a padrões de arquivos, e Claude Code da mesma forma espera por um plano aprovado antes de qualquer alteração no código. O registro de execução compartilhado contém a versão do CLI, o modelo escolhido pelo Auto, o tempo total de execução e o hardware.
Solução de problemas
- Como Achatar PDFs Antes de Imprimir para campos de formulário que imprimem vazios
- Como Obter Nomes de Impressoras para os nomes que o Windows relata
- Como Especificar o Nome da Impressora para tarefas que chegam à impressora errada
- Método Print() Trava em WPF e WinForms para uma chamada de impressão que congela a interface
- Aplicando Chaves de Licença para cada local onde a chave pode ser configurada
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.