Usando IronOCR com Assistentes de Codificação de IA
IronOCR é uma biblioteca comercial de OCR para .NET com mais de seis milhões de downloads no NuGet. Seus tutoriais, guias práticos e notas de solução de problemas estão disponíveis publicamente há anos, então assistentes de codificação geralmente já os viram em seus dados de treinamento.
Essa familiaridade não se estende à qual versão seu projeto fixa. Um assistente que lê a documentação do IronOCR tem mais chances de escrever um código de OCR que compila e retorna texto preciso. Compartilhe a documentação antes do primeiro pedido.
Essas ferramentas se dividem em duas categorias, que diferem em quanto fazem antes de você revisar o resultado.
- Um assistente trabalha dentro de uma parte do seu fluxo de trabalho. Ele completa uma linha, explica um método, ou faz uma pequena edição, como as sugestões inline do GitHub Copilot.
- Um agente realiza uma tarefa de múltiplas etapas, edita arquivos, executa a compilação e os testes, e comete o resultado para revisão, como fazem Claude Code, ChatGPT Codex, Cursor e Google Antigravity.
A configuração é idêntica para ambos. Instale o pacote, aplique a chave de licença a partir de uma variável de ambiente, forneça a documentação legível por máquina do IronOCR e verifique cada valor extraído em uma página cujo texto você já conheça. Isso se aplica a imagens e PDFs digitalizados da mesma forma, e ao tornar uma digitalização pesquisável, ler múltiplos idiomas, extrair códigos de barras na mesma leitura, ou melhorar uma digitalização de baixa qualidade.
Como Usar IronOCR com um Assistente ou Agente de Codificação de IA
- Baixe a biblioteca OCR C# do NuGet
- Carregue a chave de licença a partir de uma variável de ambiente antes da primeira leitura
- Dê ao assistente o índice
llms.txtdo IronOCR antes que ele escreva qualquer código - Registre as regras do IronOCR onde quer que seu assistente mantenha instruções de projeto
- Inicie uma nova sessão com o prompt de configuração one-shot abaixo
- Compile e, em seguida, verifique a saída do IronOCR comparando com os valores que você espera em cada página de amostra
Meu Assistente de IA Não Consegue Lidar com OCR Sozinho?
Sem documentação, um assistente depende do que quer que ele tenha absorvido sobre OCR em seu treinamento, que frequentemente mistura configurações de wrappers Tesseract brutos ou uma versão anterior do IronOCR.
IronOCR publica documentação construída para ser lida por ferramentas, incluindo tutoriais, guias práticos e mais de cinquenta artigos de solução de problemas. Depois que o assistente carrega isso, a documentação mostra como IronTesseract, OcrInput e OcrResult se encaixam.
A seleção do motor ainda importa. Wrappers Tesseract gratuitos lidam bem com uma página limpa e reta em inglês.
- Saída legível não garante saída correta: um resultado de OCR pode ler fluentemente e ainda transformar 589,50 em 580,50.
OcrResultrelata uma pontuação de confiança para cada palavra para mostrar onde olhar. - Digitalizações requerem preparação: páginas tortas, ruidosas ou de baixa resolução são lidas mal em qualquer motor.
OcrInputpossui filtros que endireitam uma página, removem ruído, aumentam a resolução e mais. - Ajustar manualmente um motor é custoso: cada tentativa que um assistente faz em configurações brutas do Tesseract gasta tokens em um trabalho que a biblioteca já faz, e o custo se repete com cada novo tipo de documento.
- O pacote depende da plataforma:
IronOcrcobre Windows,IronOcr.MacOscobre Macs com Intel, eIronOcr.MacOs.ARMcobre Apple silicon. Um assistente também pode inventar um nome de pacote plausível, e invasores registram tais nomes com código malicioso, uma prática chamada slopsquatting. Nomeie o pacote no prompt. - Licenciamento é previsível: serviços de OCR em nuvem geralmente cobram por página ou por ligação, e um assistente não mencionará esses termos por conta própria. IronOCR é executado localmente sob uma licença comercial perpétua precificada em camadas por desenvolvedores, locais e projetos, sem medição por página.
Passo 1: Instale IronOCR
Uma vez que a referência ao pacote exista, o assistente pode ver os tipos reais de IronOCR ao gerar código.
Install the IronOcr NuGet package into this project and confirm it restores.
O guia avançado de instalação NuGet lista as outras opções de instalação.
Passo 2: Aplique sua chave de licença
IronOCR não possui um modo não licenciado com marca d'água. Construir um IronTesseract sem uma chave é bem-sucedido, mas a primeira leitura lança IronSoftware.Exceptions.LicensingException com a mensagem "Chave de Licença de Produção Necessária". Uma chave presente mas mal digitada produz "Chave de Licença Não Reconhecida" no mesmo chamado. Você pode obter uma chave de teste gratuita abaixo.
Comece a usar IronOCR em seu projeto hoje com uma avaliação gratuita.
Defina IronOcr.License.LicenseKey no início do aplicativo, antes de qualquer outra chamada ao IronOCR, e leia a partir da variável de ambiente IRONOCR_LICENSE_KEY para que nunca entre no controle de versão. A mesma classe também tem um método que testa uma string de chave sem aplicá-la.
Web.config e appsettings.json.Passo 3: Aponte seu Assistente para a Documentação LLM do IronOCR
llms.txté o índice, uma linha por página.- Resumos de 145 páginas chegam em uma única busca de
llms-full.txt. llms-full-catalog.txtadiciona o blog ao índice.- A Referência de API documenta cada tipo e membro.
- Configuração, licenciamento, receitas e correções estão em
skill.md. - O Folha de Fatos do Produto de IA resume escopo, plataformas e limites.
Quando uma tarefa depende do detalhe de um guia, peça ao assistente para abrir a página daquele guia.
Forneça uma instrução direta juntamente com o índice.
Before writing any IronOCR code, read https://ironsoftware.com/ocr/csharp/llms.txt
and use only APIs documented there. A read is assembled on an OcrInput, whose
Load overloads differ by source type, and run through IronTesseract.Read.
Confirm the overload you pick against
https://ironsoftware.com/ocr/csharp/object-reference/api/, and if you cannot find
it, say so instead of guessing.
Passo 4: Adicione o Contexto do IronOCR ao Seu Projeto
Coloque as regras do IronOCR em qualquer arquivo que sua equipe já use. Claude Code lê CLAUDE.md, GitHub Copilot lê .github/copilot-instructions.md, e ChatGPT Codex e Google Antigravity lêem AGENTS.md. Cursor lê .cursor/rules/*.mdc ou AGENTS.md, e apenas seu arquivo de regras precisa de frontmatter MDC. Use o seguinte como ponto de partida.
## OCR with IronOCR
This project uses IronOCR (NuGet package `IronOcr`, or `IronOcr.Linux` for Linux and Docker, namespace `IronOcr`) for all OCR work.
- Reference: https://ironsoftware.com/ocr/csharp/llms.txt
- Skill file: https://ironsoftware.com/ocr/csharp/skill.md
- Read with `IronTesseract` and an `OcrInput` inside a `using` block, and use the `OcrResult` it returns.
- Read the license key from the IRONOCR_LICENSE_KEY environment variable at startup. Never inline it.
- Every OCR change must be tested against sample pages whose text is known, reporting the values read and their confidence.
- Do not add another OCR engine or a cloud OCR service. If IronOCR cannot do something, say so.
O exemplo de arquivo único da skill file ainda fixa IronOcr 2026.7.2 enquanto o NuGet agora serve 2026.10.2. Ele também diz manter todos os pacotes do Iron na mesma versão, o que pacotes de idioma não podem seguir, já que IronOcr.Languages.German foi publicado pela última vez como 2020.11.2. Sua receita ConvertToSearchablePdf de uma linha lançou em PDFs digitalizados apenas com imagem em nossos testes, enquanto carregar o PDF, lê-lo e chamar SaveAsSearchablePdf no resultado funcionou.
Passo 5: Prompt de Configuração Única
Tudo dos Passos 1 a 4 pode ser enviado em uma única mensagem.
Use IronOCR for all OCR work in this project.
1. Install the IronOcr NuGet package (IronOcr.Linux when the app runs on Linux or Docker).
2. Apply the license key at application startup, before any other IronOCR call,
reading it from the IRONOCR_LICENSE_KEY environment variable. Never write
the key into source or into a committed file.
3. Read https://ironsoftware.com/ocr/csharp/llms.txt before writing OCR code
and work only from APIs documented there, checking the API reference when a
member is unfamiliar.
4. Load https://ironsoftware.com/ocr/csharp/skill.md if your tooling supports skill files.
5. Keep these instructions for future sessions in this project.
Passo 6: Padrões de Prompt que Produzem Código Funcional
Resultados fracos geralmente vêm de um prompt que deixa espaço para o assistente adivinhar.
Nomeie a entrada, os campos e o idioma.
Vago Leia as faturas com IronOCR.
Melhor Usando IronTesseract com um OcrInput que carregue cada PDF digitalizado, leia o número da fatura e a linha começando com Total due, e retorne o valor com a confiança dessa linha.
Declare a versão e a estrutura também.
Melhor Dirija-se a .NET 9 com IronOcr 2026.9.4.
Solicite o arquivo inteiro.
Melhor Entregue o Program.cs completo, diretrizes e configuração de licença incluídas, pronto para compilar sem edições.
Passo 7: Verifique o Que Você Obtém de Volta
Fique atento a esses erros comuns.
- OCR em um PDF que já tem texto: extrair uma camada de texto real é mais rápido e preciso do que executar OCR sobre as páginas. Verifique uma camada de texto primeiro e execute OCR apenas nas páginas digitalizadas.
- Todos os filtros de uma vez: empilhar uma correção após outra em uma página limpa pode diminuir a precisão e sempre adiciona tempo. Em um conjunto denso de faturas em nossos testes,
DeNoisetransformou o final 1 de um número de fatura rodado em 4, e adicionarDilatecorrigiu aquela página mas custou a outros conjuntos de uma a três linhas. Aplique apenas o filtro que corrige o defeito que você vê. O arquivo das habilidades do IronOCR oferece o mesmo conselho, e o guia de correção de qualidade da imagem descreve quando cada filtro se aplica.
Deixe o Agente Verificar Seu Próprio Trabalho
Build and run this project in Release. Confirm that every IronOCR member you used
appears in the documentation, that IronOcr.License.IsLicensed returns true, and
that every sample page reads back with the values it is known to contain.
Report the build result and a table of page, expected value, value read, confidence, and match.
Como Você Lê Idiomas Além do Inglês?
Inglês é o único idioma no pacote IronOcr. A lista de idiomas do IronOCR cobre 125. Dê esses fatos ao assistente.
- Outro idioma precisa de seu pacote, como
IronOcr.Languages.German, entãoLanguage = OcrLanguage.German. - Sem acesso ao NuGet, use o arquivo
.ocrdataeInstallation.LanguagePackDirectory. - Variantes Fast e Best como
OcrLanguage.GermanFastsão enviadas no mesmo pacote. - Para uma página em vários idiomas, chame
AddSecondaryLanguage, o mais comum primeiro. - Tabelas financeiras usam
OcrLanguage.FinancialdeIronOcr.Languages.Financial. - Um modelo treinado em outro lugar carrega através de
UseCustomTesseractLanguageFilecom um arquivo.traineddata.
Um pacote ausente gera LanguagePackException na primeira leitura. Sua mensagem nomeia o exato pacote NuGet e a alternativa .ocrdata, então peça ao assistente para instalar o que a mensagem nomeia.
O guia de configuração rápida do IronOCR reporta um ganho de 17% com EnglishFast combinado com o desligamento da leitura de códigos de barras. Em dez de nossas páginas, essa variante por si só permaneceu dentro do ruído de execução para execução do inglês, então meça as variantes em suas próprias páginas antes de optar pela velocidade em detrimento da precisão.
A publicação ClickOnce omite os arquivos .ocrdata dos idiomas secundários, conforme explicado na nota ClickOnce. No Windows, adicionar EnglishFast como um idioma secundário pode travar em grandes PDFs nas versões 2025.12.3 até 2026.7.2, conforme registrado nesta entrada de solução de problemas.
Quais Configurações do IronOCR Estão Ligadas por Padrão?
O código gerado frequentemente define valores que já são os padrões ou perde uma configuração que é desligada por padrão. Esses são os valores iniciais no IronOcr 2026.9.4, lidos de um IronTesseract novo.
| Contexto | Default | Mude isto para |
|---|---|---|
Language | Inglês | Outros idiomas |
Configuration.ReadBarCodes | desligado | Códigos de barras |
Configuration.ReadDataTables | desligado | Estrutura da tabela |
Configuration.RenderSearchablePdf | ligado | Pular saída pesquisável |
Configuration.RenderHocr | desligado | Saída hOCR |
Configuration.PageSegmentationMode | AutoOsd | Recortes de linha única ou palavra única |
Configuration.EngineMode | LstmOnly | Raramente |
Configuration.WhiteListCharacters e BlackListCharacters | vazio | Conjuntos de caracteres estreitos |
Configuration.TesseractVariables | três entradas predefinidas | Variáveis brutas do Tesseract |
MultiThreaded | ligado | Raramente |
MaxDegreeOfParallelism | Environment.ProcessorCount | Grandes lotes com pouca memória |
OcrInput.TargetDPI | 0 | Digitalizações de baixa resolução |
Além da leitura padrão, IronTesseract fornece leitores ajustados para outras entradas. ReadPhoto lida com fotografias de documentos e ReadScreenShot lida com capturas de tela. O tutorial de documentos especializados ainda lista IronOcr.Extensions.AdvancedScan para eles, mas esse pacote foi enviado pela última vez em 2025 e nenhum leitor precisou dele. O mesmo tutorial também cobre os leitores de passaportes e placas de automóveis.
Um Resultado Que Você Pode Reproduzir
O prompt
Build a .NET 9 console app that reads totals from scanned invoices. Start in an empty folder; if it already holds code or project files, stop and report. Work start to finish alone: write, build, run, and fix, making sensible assumptions where anything is unspecified. Save every deliverable under the project root, in the folders named below.
1. Install the IronOcr NuGet package pinned to version 2026.9.4.
2. Read https://ironsoftware.com/ocr/csharp/llms.txt and the pages it links to, and use only IronOCR APIs documented there for the OCR work. Any .NET imaging library may draw the test images.
3. Read the license key from the IRONOCR_LICENSE_KEY environment variable at startup and never write it into source or any output file. If IronOcr.License.IsLicensed is false, stop and report that.
4. With random seed 2026, generate testset/invoice-01.png to invoice-10.png. Each is a US Letter page of exactly 1700 x 2200 pixels, saved as PNG with 200 DPI in the file metadata, with all text in Arial inside 0.75 inch margins, headings at 14 point bold and everything else at 11 point. Each invoice has an invoice number made of INV- and six random digits, a customer name, three line items with random prices in dollars and cents, and a total equal to their sum, with no two totals alike.
5. Rotate invoice-02 and invoice-07 by 3 degrees about the page center, keeping the 1700 x 2200 canvas. Add speckle noise to invoice-04 and invoice-09: dark square specks 1 or 2 pixels wide, placed anywhere including over the text, until they have darkened 1% of the page's pixels, counting a pixel as dark below 128 of 255. Leave the other six clean. Write manifest.csv with each file, invoice number, the three prices, total, and distortion (none, rotated, or speckled).
6. Before the first OCR call, check every saved image: 1700 x 2200 pixels, 200 DPI when rounded, and, measured on each page before distortion, the smallest distance from any ink to an edge, at least 0.75 inch. On each speckled page, check that speckling raised the share of dark pixels by 0.9 to 1.1 percentage points. Also draw a capital H with the 11 point font on a 200 DPI bitmap and check that its ink is 21 to 23 pixels tall. If a check fails, fix the generator. After the first OCR call, never regenerate or change the saved image files; filters applied in memory are expected.
7. Read all 10 images in one OcrInput with one set of filters for every page. Each run of the program uses one filter set; it must not try several or choose between them, and choosing filters is your job between runs. No manifest value, file name, or expected value may steer the OCR or the parsing of its text; read the manifest only to write roundtrip.md. The reader must hold no invoice number, price, or total as a literal and must run the same code for every page. Extract each page's invoice number and total, save each page's OCR text as ocr/invoice-01.txt to invoice-10.txt, and save the result as invoices-searchable.pdf.
8. Build in Release and run.
9. Write roundtrip.md: the step 6 checks as measured numbers for every image, not pass or fail words, the filter set used, then a table of file, distortion, expected invoice number, invoice number read, expected total, total read, the Confidence (0 to 100) of the OCR line holding the total or n/a, and match, then the page count of invoices-searchable.pdf loaded back with OcrInput. A row matches only when the invoice number read is identical to the expected one and the total read equals the expected total to the cent.
10. All 10 rows must match and the PDF must have 10 pages. If not, read the saved OCR text of the failing pages, change the filter set or the reader, rebuild, and run again. If rows still fail after eight such runs, stop and report which rows failed, the filter sets tried, and why.
11. Finish with a short report: build result, match count, filters used, font sizes used, and assumptions made.
Saída
Esta é a fatura-09, uma das duas páginas salpicadas da execução, cortada para a área impressa. Uma leitura simples combinou 8 de 10 faturas e perdeu ambas as páginas salpicadas, retornando o número desta fatura como ANV-938066, e Deskew sozinho não fez melhor. Com DeNoise adicionado, IronOCR retornou INV-939066 e 1731,53, com 41,45 de confiança na linha total, a menor da execução. A outra linha total salpicada foi lida com 63,86 e as páginas limpas em cerca de 95. Claude Code escolheu esses dois filtros em seu primeiro rascunho e os manteve em todas as cinco execuções do programa.
- Uma verificação independente mediu novamente todos os requisitos, e todas as 10 faturas combinaram.
- ChatGPT Codex com GPT-6 Luna também combinou 10 de 10 no mesmo prompt.
roundtrip.mdé publicado sem edições e
em tamanho reduzido.
O que passa
- O código não precisou de edições suas.
- Abrir qualquer imagem mostra um texto pequeno sem nada cortado nas bordas, e manchas no texto assim como nas margens.
- Cada número de fatura e total em
roundtrip.mdtambém aparece no texto OCR salvo daquela página.
O registro da execução
- A máquina executa Windows 11 x64 em um Core i9-14900KF com 64 GB de memória.
- Cada projeto visa .NET 9.
- Este guia, o Copilot e o Cursor executaram
IronOcr2026.9.4, enquanto Claude Code, Codex e Antigravity executaram 2026.10.2. Copilot adicionouIronOcr.Linux2026.9.4, e Codex, Cursor e Antigravity adicionaramIronOcr.Languages.German2020.11.2. - Último teste 8 de outubro de 2026, com a execução do Cursor. Todas as outras execuções são de 6 de outubro.
| Guia | Assistente e versão | Modelo | Duração (minutos) |
|---|---|---|---|
| Este guia | Claude Code 2.1.277, prompts de permissão desativados | Claude Opus 5 | 20.8 |
| Claude Code | Claude Code 2.1.277 | Claude Sonnet 5 | 9.4 |
| ChatGPT Codex | Codex CLI 0.160.0 | GPT-6 Luna | 27.7 |
| GitHub Copilot | Modo agente do Copilot no VS Code 1.140 | GPT-6 Luna, roviado pelo Auto | 22.0 |
| Cursor | Aplicativo desktop Cursor 3.23.23 | Grok 4.7 | 83.5 |
| Google Antigravity | Antigravity CLI 1.3.0 | Gemini 3.8 Flash (Alto) | 32.7 |
Guias Específicos para Agentes
Para etapas que se adequam a uma ferramenta, abra seu guia.
- Use IronOCR com Claude Code
- Use IronOCR com ChatGPT Codex
- Use IronOCR com GitHub Copilot
- Use IronOCR com Cursor
- Use IronOCR com Google Antigravity
Solução de problemas
- Aplique uma Chave de Licença no IronOCR
- Melhore a Precisão do OCR se o texto reconhecido não corresponder à página
- Solução de Problemas Geral de OCR se erros aparecerem após a implantação
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.