Como Utilizar IronPrint com Cursor
Quando um agente de IA porta um serviço de impressão C# de System.Drawing.Printing para IronPrint, uma configuração copiada sem alteração ainda compila e muda seu significado. Uma margem de 50 no código antigo significa meia polegada, enquanto os mesmos 50 no IronPrint significam 50 milímetros. Os nomes das impressoras também são transferidos inalterados. Em nossos testes, o IronPrint enviou um trabalho para um nome de impressora que não estava instalado para a impressora padrão sem gerar um erro.
Cursor, que é baseado no código do VS Code, adiciona um agente ao editor. Se uma migração mantém esses detalhes depende de duas funcionalidades do Cursor, os links de documentação dados ao agente e as regras de projeto comprometidas em .cursor/rules. Os exemplos se aplicam tanto a um serviço de escritório de expedição que imprime etiquetas de embalagem, etiquetas de prateleira e notas de devolução. O serviço constrói cada trabalho a partir de um arquivo de configuração em centésimos de polegada, e os prompts movem isso para o IronPrint.
Para obter detalhes sobre as configurações envolvidas, veja o guia de margens de papel e o guia de nomes de impressoras.
Início RápidoAbra o repositório de expedição, inicie um novo chat de Agente e envie este prompt.
@src/DespatchDesk/ @config/despatch.json
Start by fetching https://ironsoftware.com/print/csharp/llms.txt.
Also read the pages it links on printer names and print settings.
Then add a printers command to Program.cs:
`dotnet run --project src/DespatchDesk -- printers`
Have it show what IronPrint reports on this machine:
- Every name from Printer.GetPrinterNames, in square brackets so spaces show.
- The trays GetPrinterTrays returns for each printer, or "none".
- Whether each printer named in config/despatch.json is in that list.
Have the program read IRONPRINT_LICENSE_KEY from the environment.
Set License.LicenseKey from it before anything else runs.
Don't echo the key or dump the environment.
IronPrint stays on version 2026.10.1.
Send no print jobs, and leave DespatchJobs.cs on System.Drawing.Printing for now.
Run the printers command and show me what it prints.
Nunca cole a chave de licença no chat. O agente do Cursor pode editar arquivos e executar comandos de shell, então ele pode copiar uma chave colada em uma mensagem de commit, um arquivo fonte ou um log de construção. O prompt faz o programa atribuir IRONPRINT_LICENSE_KEY a License.LicenseKey, porque definir apenas a variável deixou IronPrint 2026.10.1 sem licença nos testes. Em uma sondagem sem chave, IronPrint listou impressoras e bandejas, e Printer.Print lançou uma AggregateException em torno de uma LicensingException antes de qualquer trabalho ser enviado. O guia de chaves de licença nomeia os lugares de onde o IronPrint lê uma chave, como appsettings.json.
Fluxo de trabalho mínimo (5 etapas)
- Baixe a biblioteca de impressão C# do NuGet
- Adicione uma regra de projeto em .cursor/rules que contenha o link de documentação do IronPrint
- Registre na regra que margens estão em milímetros e os nomes das impressoras devem corresponder exatamente
- Referencie o código de impressão e o relatório de configurações assinado em cada solicitação
- Compare as configurações de cada trabalho com esse relatório, depois confirme cada nome de membro na referência de API
Qual modelo do Cursor você deve usar para trabalhar com IronPrint?
Composer é o modelo agêntico próprio do Cursor. O seletor de modelos também oferece os modelos Grok da SpaceXAI, que o Cursor co-desenvolveu, e modelos da OpenAI, Anthropic, Google e outros laboratórios. O teste executado abaixo usou o Grok 4.7.
Como você fornece a documentação do IronPrint para Cursor?
Coloque o link de documentação do IronPrint em cada solicitação, ou uma vez numa regra de projeto para toda a equipe. O llms.txt do IronPrint lista cada guia, exemplo e página de solução com um resumo, e o llms-full.txt contém resumos de 33 páginas de documentação. Em outubro de 2026, o Cursor lista pastas, arquivos, chats passados, o navegador, terminais e diferenças Git no seu menu @, então o agente obtém a documentação do IronPrint como um link.
A documentação afirma que um nome de impressora nulo seleciona a impressora padrão, e o guia do IronPrint sobre especificar um nome de impressora diz que um nome incompatível falha silenciosamente ou lança um erro. Nenhum dos resultados ocorreu nos testes, então a regra do projeto registra o comportamento medido em vez disso.
@src/DespatchDesk/Printing/ReprintService.cs
Answer five questions about IronPrint without editing any files:
1. What unit does the Margins class use?
2. Which sides does each value of new Margins(10, 20) set?
3. What does Printer.Print do when PrintSettings.PrinterName is null?
4. What do the docs say about a name GetPrinterNames doesn't return, and does the rule agree?
5. Does NumberOfCopies always produce that many copies?
Base each answer on https://ironsoftware.com/print/csharp/llms.txt or a page linked from it.
Check them against the printers output from the last turn where that helps.
Cite the page behind each answer.
If no page covers a question, say so plainly rather than guess.
Como você escreve regras de projeto que codificam suas convenções do IronPrint?
Regras de projeto são arquivos .mdc mantidos em .cursor/rules e comprometidos com o repositório, para que cada clone carregue as mesmas regras. O sistema de regras do Cursor ignora um arquivo .md simples lá, já que ele não possui cabeçalho.
Salve a regra abaixo como .cursor/rules/ironprint-despatch.mdc. Com globs definido e alwaysApply falso, o Cursor anexa quando um arquivo C# em src/DespatchDesk ou testes está no contexto da solicitação, e o deixa de fora de outras solicitações.
---
description: IronPrint conventions for the despatch printing code
globs: src/DespatchDesk/**/*.cs, tests/**/*.cs
alwaysApply: false
---
Despatch printing code uses IronPrint and follows these rules:
- Print with IronPrint only.
- Reference IronPrint 2026.10.1 from NuGet and use its IronPrint namespace.
- Do not add another printing package.
- Move existing code to IronPrint only when a request asks for it.
- The IronPrint docs index is https://ironsoftware.com/print/csharp/llms.txt.
- Read the license key from the IRONPRINT_LICENSE_KEY variable.
- Keep the license key out of output and files.
- IronPrint Margins uses whole millimeters, as left, top, right, bottom.
- System.Drawing.Printing.Margins uses hundredths of an inch, as left, right, top, bottom.
- new Margins(a, b) sets left and right to a, and top and bottom to b.
- Printer.Print sends the job to the default printer if PrinterName is not an exact installed name.
- Check the name against Printer.GetPrinterNames before every job.
- Run the print and reprint commands only when I ask for them.
- Check settings with the jobs and reprint-jobs reports instead.
- If an IronPrint member is not in the docs, say that and cite the page you searched.
- Never make up an IronPrint member.
De acordo com a página de regras do Cursor, o Agente usa regras, mas a Aba não, e as regras do usuário são deixadas de fora da edição inline. Verifique sugestões da Aba e edição inline contra a regra manualmente.
Como você mapeia configurações System.Drawing.Printing para IronPrint?
Uma solicitação para usar IronPrint não diz qual configuração do IronPrint substitui cada configuração PrintDocument. A tabela abaixo fornece esse mapeamento.
| System.Drawing.Printing | IronPrint |
|---|---|
PrinterSettings.PrinterName | PrintSettings.PrinterName |
PageSettings.PaperSize, dimensionado em centésimos de polegada | O enum PaperSize, como PaperSize.A4 |
PageSettings.Landscape | PaperOrientation.Landscape ou PaperOrientation.Portrait |
PageSettings.Margins, centésimos de polegada, esquerda, direita, superior, inferior | PaperMargins com um valor Margins, milímetros inteiros, esquerda, superior, direita, inferior |
PrinterSettings.Copies | NumberOfCopies |
PageSettings.Color definido como falso | Grayscale definido como verdadeiro |
PrintDocument.Print com um manipulador PrintPage | Printer.Print com um caminho de arquivo e as configurações |
Uma margem configurada de 50 é 12,7 milímetros, o que arredonda para 13 porque o construtor aceita números inteiros. O guia de tamanhos de papel do IronPrint lista a ordem de quatro valores como superior, direita, inferior, esquerda, enquanto a documentação XML fornecida e uma sondagem da biblioteca ambos fornecem esquerda, superior, direita, inferior.
Como você planeja e executa uma migração para IronPrint?
Shift+Tab percorre os modos do chat. Pare no Modo Plano e envie a solicitação abaixo. Cursor salva o plano em um arquivo markdown, que pode ser editado antes da aprovação.
@src/DespatchDesk/Printing/ @TestData/expected-jobs.tsv
Plan the move of DespatchJobs from System.Drawing.Printing to IronPrint.
Write no code until I approve.
ReprintService already uses IronPrint, so keep it out of this plan.
The plan needs to cover these points:
- Each PrintDocument setting DespatchJobs uses, with its PrintSettings replacement or none.
- How margins in hundredths of an inch become IronPrint margins, including the order of the sides.
- How the jobs command keeps its columns and its values.
Keep config/despatch.json, JobSummary and the public Describe and Print signatures unchanged.
Where something is unclear, write down the assumption you made.
Edite o plano onde ele estiver errado. Para aprová-lo, clique em Build, ou volte para o modo Agente e envie esta solicitação.
@ironprint-despatch
Go ahead with the approved plan.
TestData/expected-jobs.tsv holds the jobs report the despatch office signed off.
A row matches when all eight columns agree with it.
Then follow these four steps:
1. Run `dotnet run --project src/DespatchDesk -- jobs` and count the matching rows.
2. Move DespatchJobs to IronPrint.
3. Remove System.Drawing.Common from the project file.
4. Build the solution and run the jobs command a second time.
Tell me the match count before and after the move, then show me the diff.
A menção @ironprint-despatch adiciona a regra à solicitação por nome. O relatório de trabalhos imprime as configurações de cada documento sem enviar um trabalho, então a comparação funciona em uma máquina sem impressora.
Qual recurso do Cursor se adapta a cada mudança?
Escolha o recurso pelo tamanho da mudança. A Aba oferece o restante de uma edição já em andamento. A edição inline (Ctrl+K) altera o código selecionado a partir de uma instrução de uma frase. O Agente é adequado para uma mudança que abrange vários arquivos ou precisa de uma construção. O Modo Plano vale a etapa extra quando desfazer uma mudança errada leva mais tempo do que escrever um plano, e um Agente na Nuvem lida com trabalho não atendido.
Selecione o método Print de DespatchJobs e adicione-o ao chat como contexto com Ctrl+Shift+L, ou Cmd+Shift+L no macOS. Então envie esta solicitação do modo Agente.
Make DespatchJobs.Print refuse a printer that isn't installed:
- Check the name against Printer.GetPrinterNames before anything is sent.
- Use an ordinal, case-sensitive comparison so spaces and case must match too.
- If it's missing, throw an error whose message includes every installed printer name.
- Have the print command show that message and exit with code 2.
Then run these two commands and show me what each one prints:
`dotnet run --project src/DespatchDesk -- print packing-slip`
`dotnet run --project src/DespatchDesk -- print packing-slip --printer "adobe pdf"`
O segundo comando difere do nome de uma impressora instalada apenas no caso.
O que acontece quando IronPrint não consegue encontrar o nome da impressora?
O serviço antigo parava com um erro. System.Drawing.Printing lançava um InvalidPrinterException com a mensagem "Configurações para acessar a impressora 'Despatch-A4-01' não são válidas." IronPrint 2026.10.1 endereçava o trabalho capturado para esse nome, e para outros três nomes, à impressora padrão. Estes eram o nome de impressora de amostra do guia de margens do IronPrint, uma impressora instalada digitada em minúsculas, e a mesma impressora com um espaço à direita.
Microsoft Print to PDF, que era a impressora padrão da máquina de teste, solicita um nome de arquivo, então um serviço não atendido teria parado em um diálogo Salvar Como. O guia de nomes de impressoras afirma que cada nome retornado corresponde exatamente ao nome nas configurações de impressoras do Windows, o que faz uma comparação ordinal com Printer.GetPrinterNames o cheque a ser executado antes de cada trabalho.
Como você depura dois caminhos de impressão que discordam?
O código do quiosque de reimpressão já usava IronPrint, e seu relatório de configurações discordava do relatório assinado em cada linha.
@src/DespatchDesk/Printing/ReprintService.cs @TestData/expected-jobs.tsv
Find out why the reprint report disagrees with expected-jobs.tsv on every row.
The jobs report matches it, and both read config/despatch.json.
Work through these steps before changing any code:
1. Run the reprint-jobs command and the jobs command, and compare them.
2. List each column where reprint-jobs differs, per document type.
3. Explain what ReprintService does to cause each difference.
Then fix ReprintService and keep it on IronPrint.
Give its Print method the same printer check.
Keep the check out of BuildSettings and Describe, since reprint-jobs reads those.
Run reprint-jobs again and tell me how many rows match, before and after the fix.
A discordância tem duas causas. O código do quiosque passa os centésimos diretamente para o construtor de dois valores, então uma nota de embalagem relata margens de 50 milímetros, e a nota de devolução repete seu valor superior no inferior, onde a configuração define 80 centésimos. Ele também define orientação paisagem para cada documento porque foi escrito para etiquetas de prateleira.
Saída
Em uma captura do run antes da correção, a nota de embalagem retrato enviada com orientação paisagem foi disposta em uma folha de 297 por 210 milímetros. Sua página foi escalada para 148,4 por 209,9 milímetros, e os outros 148,5 milímetros da folha ficaram em branco.
Nota de embalagem com as configurações do ReprintService não corrigido, como IronPrint construiu o trabalho, capturado em um arquivo em vez de uma impressora.
O que IronPrint envia para a impressora?
Nenhuma das quatro impressoras na máquina de teste completa um trabalho não assistido, então nada foi impresso em papel. Para estas medições, as amostras do guia de margens e o serviço migrado foram executados inalterados, e apenas a chamada final na impressão do Windows foi substituída. Naquela chamada, um patch salvou as páginas de cada trabalho e o ticket de impressão como um arquivo XPS, e a fila de impressão não recebeu nada. As medições abaixo vêm desses arquivos e descrevem o que uma impressora receberia.
- Margens: margens de 0, 10, 15, 20, 30 e 50 milímetros produziram páginas idênticas, com a imagem da página preenchendo a folha. A versão System.Drawing.Printing da nota de embalagem desenhou sua imagem dentro de margens de 12,7 milímetros.
- Escala de cinza: para uma página PNG, a configuração mudou apenas o ticket de impressão e a imagem permaneceu em cores. Para uma página PDF, a imagem em si era cinza.
- Resolução: um PDF foi renderizado na configuração
Dpi, 2479 por 3508 pixels para A4 a 300. Um PNG foi enviado em seu próprio tamanho de pixels.
Até que o IronPrint aplique PaperMargins à página no Windows, um layout que precisa de espaço em branco nas bordas deve carregá-lo no próprio documento.
Entrada
O serviço imprime três arquivos PNG de TestData/jobs, slip-1001.png, labels-aisle-07.png e return-2207.png. Cada um é uma imagem de 150 DPI com uma borda vermelha nas suas extremidades.
Saída
Os PDFs abaixo mostram um trabalho cada do código que Cursor escreveu. Cada imagem de página está inalterada e mantém o tamanho da página capturada.
Nota de embalagem como IronPrint construiu o trabalho, capturado em um arquivo em vez de uma impressora. O trabalho contém uma página A4 retrato, e seu ticket de impressão solicita duas cópias em monocromático.
Etiquetas de prateleira como IronPrint construiu o trabalho, capturado em um arquivo em vez de uma impressora. Esta página A4 paisagem mede 297 por 210 milímetros, e o ticket de impressão especifica saída colorida.
Nota de devolução como IronPrint construiu o trabalho, capturado em um arquivo em vez de uma impressora. Sua única página A5 retrato mede 148 por 210 milímetros, e a saída monocromática está definida no ticket de impressão.
Como você escreve testes de regressão para código de impressão?
Os Agentes na Nuvem do Cursor rodam em máquinas Ubuntu, e o alvo de amostra é net9.0-windows, então envie esta solicitação em um chat de Agente local.
@tests/DespatchDesk.Tests/ @TestData/
Write xUnit tests for DespatchJobs and ReprintService. None of them may send a print job.
Cover these cases with tests:
- Describe returns every row of TestData/expected-jobs.tsv, for both classes.
- The returns note reports a 20 mm bottom margin.
- Print throws when the printer is missing from GetPrinterNames.
- That error message names each printer GetPrinterNames returns when the test runs.
- An installed printer name with its case changed is refused as well.
- Hundredths of an inch convert to the millimeters in expected-jobs.tsv.
Link config and TestData from the repo root into the test output, keeping their relative paths.
Leave expected-jobs.tsv as it is, then run dotnet test.
Tell me how many tests passed and how many failed.
Os testes de recusa usam nomes de impressoras que não estão instalados, então param na verificação da impressora antes de Printer.Print ser chamado.
O guia de assistentes de codificação de IA leva uma tarefa do IronPrint de uma pasta vazia para um resultado verificado contra critérios de aprovação escritos.
O que os prompts produziram em uma execução real?
Cursor recebeu os sete prompts em ordem contra o repositório de amostras de expedição. Após a execução, novas compilações Release de cada commit que alterou o código repetiram cada relatório e comando abaixo.
- Antes da mudança para IronPrint e depois dela, o relatório de trabalhos correspondeu a todas as 3 linhas do relatório assinado.
- O relatório de reimpressão correspondeu a 0 de 3 linhas antes da correção e 3 de 3 depois dela.
- O comando de impressoras listou as quatro impressoras instaladas com suas bandejas e marcou ambas as impressoras configuradas como não instaladas.
- Cada uma das cinco respostas de documentação do Cursor citou uma página, e nenhum arquivo mudou.
- Para um nome que GetPrinterNames não retorna, o Cursor repetiu a declaração do guia e notou que a regra do projeto descreve um resultado diferente.
- O plano não encontrou substituição de PrintSettings para o nome do documento e registrou isso como uma suposição.
- Após a mudança, o aplicativo referenciou apenas o pacote IronPrint, e nenhum código System.Drawing.Printing permaneceu.
- DespatchJobs manteve suas assinaturas públicas Describe e Print.
- O comando de impressão recusou a impressora configurada para os três tipos de documento com código de saída 2 e uma lista das quatro impressoras instaladas.
- A verificação da impressora também recusou a impressora Adobe PDF instalada digitada em minúsculas ou com um espaço à direita.
- Antes da correção, o comando de reimpressão enviou trabalhos para uma impressora configurada ausente e para "adobe pdf" para a impressora padrão.
- Após a correção, o comando de reimpressão recusou ambos os nomes. Parou com uma exceção não tratada, pois o prompt 06 pediu nenhum código de saída.
- Todos os 9 testes xUnit passaram. Eles vieram de cinco métodos de teste, e nenhum enviou um trabalho.
- A execução deixou a configuração, os dados de teste e a regra do projeto inalterados.
- Cada compilação Release terminou com 0 avisos e 0 erros, e nenhum arquivo foi editado manualmente.
- Alguns passos foram executados de forma diferente da página. Cada prompt foi enviado manualmente em um chat de desktop local. O prompt 04 foi primeiro colado sem ser enviado, e foi enviado após o script de registro da execução relatá-lo ausente do chat. O plano foi aprovado enviando o prompt 04 no Agente, e o Build nunca foi clicado. A migração do Cursor já verificou o nome da impressora, conforme seu plano propôs, então o prompt 05 alterou uma verificação existente.
O guia GitHub Copilot também mantém arquivos de instrução específicos de caminho no repositório, e o guia Google Antigravity testa a página de impressão em um navegador real. O registro de execução lista a versão da ferramenta, modelo, duração e máquina de teste para cada guia.
Solução de problemas
- Como Obter Nomes de Impressora para um trabalho que vai para a impressora padrão em vez da nomeada
- Como Definir Margens de Papel ao converter margens de centésimos de polegada
- Configurações de Impressão C# para o valor padrão de cada configuração
- Usando Chaves de Licença quando o código de impressão gerado falha com uma exceção de licenciamento
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.