Usando IronOCR com Assistentes de Codificação de IA

Curtis Chau
Curtis Chau
Atualizado: 9 de outubro de 2026

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.

Logotipo do agente de codificação de IA Claude CodeLogotipo do agente de codificação de IA ChatGPT CodexLogotipo do assistente de codificação de IA GitHub CopilotLogotipo do editor de código da IA CursorLogotipo do agente de codificação de IA Google Antigravity

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. OcrResult relata 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. OcrInput possui 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: IronOcr cobre Windows, IronOcr.MacOs cobre Macs com Intel, e IronOcr.MacOs.ARM cobre 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.
Text

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.

Primeiro Passo:
arrow pointer

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.

Por favor, note: Chaves de Licença IronOCR cobre outros lugares para armazenar uma chave, incluindo Web.config e appsettings.json.

Passo 3: Aponte seu Assistente para a Documentação LLM do IronOCR

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.
Text

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.
Markdown

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.
Text

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, DeNoise transformou o final 1 de um número de fatura rodado em 4, e adicionar Dilate corrigiu 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.
Text

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ão Language = OcrLanguage.German.
  • Sem acesso ao NuGet, use o arquivo .ocrdata e Installation.LanguagePackDirectory.
  • Variantes Fast e Best como OcrLanguage.GermanFast são enviadas no mesmo pacote.
  • Para uma página em vários idiomas, chame AddSecondaryLanguage, o mais comum primeiro.
  • Tabelas financeiras usam OcrLanguage.Financial de IronOcr.Languages.Financial.
  • Um modelo treinado em outro lugar carrega através de UseCustomTesseractLanguageFile com 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.

ContextoDefaultMude isto para
LanguageInglêsOutros idiomas
Configuration.ReadBarCodesdesligadoCódigos de barras
Configuration.ReadDataTablesdesligadoEstrutura da tabela
Configuration.RenderSearchablePdfligadoPular saída pesquisável
Configuration.RenderHocrdesligadoSaída hOCR
Configuration.PageSegmentationModeAutoOsdRecortes de linha única ou palavra única
Configuration.EngineModeLstmOnlyRaramente
Configuration.WhiteListCharacters e BlackListCharactersvazioConjuntos de caracteres estreitos
Configuration.TesseractVariablestrês entradas predefinidasVariáveis brutas do Tesseract
MultiThreadedligadoRaramente
MaxDegreeOfParallelismEnvironment.ProcessorCountGrandes lotes com pouca memória
OcrInput.TargetDPI0Digitalizaçõ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

Por favor, note: Executar o prompt requer uma nova sessão, o SDK .NET, uma conexão de rede, um assistente com acesso ao terminal e uma chave de teste ou de produção do IronOCR.

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.
Text

Saída

Speckled test invoice that IronOCR read correctly in the acceptance test run

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 invoice.png 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.md também aparece no texto OCR salvo daquela página.
Por favor, note: O registro de alterações do IronOCR lista o que cada versão alterou.

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 IronOcr 2026.9.4, enquanto Claude Code, Codex e Antigravity executaram 2026.10.2. Copilot adicionou IronOcr.Linux 2026.9.4, e Codex, Cursor e Antigravity adicionaram IronOcr.Languages.German 2020.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.
GuiaAssistente e versãoModeloDuração (minutos)
Este guiaClaude Code 2.1.277, prompts de permissão desativadosClaude Opus 520.8
Claude CodeClaude Code 2.1.277Claude Sonnet 59.4
ChatGPT CodexCodex CLI 0.160.0GPT-6 Luna27.7
GitHub CopilotModo agente do Copilot no VS Code 1.140GPT-6 Luna, roviado pelo Auto22.0
CursorAplicativo desktop Cursor 3.23.23Grok 4.783.5
Google AntigravityAntigravity CLI 1.3.0Gemini 3.8 Flash (Alto)32.7

Guias Específicos para Agentes

Para etapas que se adequam a uma ferramenta, abra seu guia.


Solução de problemas


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.

Leia Mais

Pronto para começar?

Downloads no NuGet 6,394,824Versão:2026.11recém-lançado