Como usar IronOCR com o GitHub Copilot
.NET teams com soluções Visual Studio estabelecidas para captura de documentos, contas a pagar, processamento de reclamações ou gerenciamento de registros não precisam mudar de editor para avaliar o GitHub Copilot, pois ele suporta seus fluxos de trabalho existentes.
Copilot é executado no Visual Studio, VS Code, IDEs JetBrains e no GitHub.com. IronOCR processa o reconhecimento localmente em .NET.
Para detalhes sobre os modelos do IronOCR para fotografias e escrita à mão, consulte o guia de leitura de fotos e o guia de escrita à mão.
Início RápidoNo seu IDE atual, declare o que o método deve retornar e qualquer padrão que o modelo teria que lembrar.
Add a ReadDeliveryNote method to Imports/DeliveryNotes.cs that uses IronOCR (the
IronOcr NuGet package, namespace IronOcr) to read a scanned delivery note and
return both its text and the barcode values found in the same pass. Barcode
reading is off by default, so switch it on before the read. Take the license key
from the IRONOCR_LICENSE_KEY environment variable, never inline. Then build and
fix any errors.
Defina IRONOCR_LICENSE_KEY no ambiente de onde o editor começa, e veja o guia de chave de licença para outros locais para guardar a chave. Sem ele, a primeira leitura para na verificação de licença, e o Copilot não pode executar o código OCR que ele escreve.
Fluxo de trabalho mínimo (5 etapas)
- Baixe a biblioteca OCR C# do NuGet
- Verifique suas convenções IronOCR em
.github/copilot-instructions.md - Use o chat inline para um único arquivo e o modo agente quando vários arquivos estão envolvidos
- Escreva um problema detalhado quando o agente em nuvem trabalhar sozinho
- Confirme cada membro do IronOCR no pull request usando a referência de API
Onde o Copilot se encaixa em um projeto já no Visual Studio?
Use o chat inline para uma alteração do IronOCR em um único arquivo. Mude para o modo agente quando a alteração abranger vários arquivos, já que ele pode compilar o projeto e executar o código OCR por conta própria. O agente de nuvem no GitHub aceita um problema atribuído e retorna um pull request.
Como você define as convenções do IronOCR para o Copilot?
Commit as convenções do IronOCR como .github/copilot-instructions.md, que o Copilot Chat, modo agente e o agente em nuvem lêem. Os completions inline ignoram-no.
# Copilot instructions
## OCR
- Use IronOCR for all OCR work. The NuGet package is IronOcr on Windows and
IronOcr.Linux on Linux and Docker. The namespace is IronOcr. Do not add
another OCR engine or a cloud OCR service.
- Documentation: https://ironsoftware.com/ocr/csharp/llms.txt
Skill file: https://ironsoftware.com/ocr/csharp/skill.md
- Target the IronOcr version pinned in Directory.Packages.props. Do not upgrade
it as part of an unrelated change.
- Never inline a license key. Read it from configuration or the
IRONOCR_LICENSE_KEY environment variable.
- Always dispose OcrInput with a using block.
- Barcode reading is off by default. Set Configuration.ReadBarCodes only where needed.
- Apply only the image filters that fix a visible defect.
- Do not invent IronOCR API names. If a member is uncertain, say so and cite
the documentation rather than guessing.
## Testing
- Every OCR change must be run against pages with known values.
- Assert on extracted fields. Never assert on the full text of a page.
## Pull requests
- Say which IronOCR APIs the change introduces, and link the page for each.
- If the OCR tests fail, check the runner environment before changing code
that the issue did not ask you to touch.
Como você dá a uma pasta suas próprias regras de linguagem OCR?
As configurações do IronOCR geralmente variam de acordo com a fonte, como faturas de fornecedores alemães e digitalizações de armazéns em inglês. Coloque as regras alemãs em .github/instructions/ocr-german.instructions.md. O Copilot aplica esse arquivo junto com o da base do repositório sempre que o arquivo em que está trabalhando corresponde ao padrão de caminho no topo do arquivo alemão.
---
applyTo: "Imports/De/**"
---
- Invoices in this folder are German. Set Language = OcrLanguage.German and add
English with AddSecondaryLanguage(OcrLanguage.English) for supplier names.
- German comes from the IronOcr.Languages.German NuGet package. Language packs
keep their own version numbers, so never align this one with IronOcr.
- Amounts use German formatting, such as 1.234,56. Parse them with the de-DE culture.
Uma leitura de amostra em alemão com o pack alemão mais recente, 2020.11.2, e inglês como idioma secundário retornou "Gesamtbetrag: 3.271,07 EUR" com 96,6 de confiança nessa linha.
O que faz de um problema algo que o agente de nuvem pode atuar?
Um problema que apenas reporta totais de fatura incorretos deixa o agente em nuvem para encontrar o arquivo culpado, as digitalizações afetadas e os totais corretos.
Title: Totals misread on rotated scans from the warehouse scanner
**Files:** Imports/InvoiceReader.cs, Imports/ImportJob.cs
**IronOcr version:** as pinned in Directory.Packages.props
**Framework:** .NET 8
**Expected:** Every invoice in TestData/warehouse/ returns the total recorded in
TestData/warehouse/expected.csv, with line confidence of at least 80.
**Actual:** About a third of warehouse scans return totals with one wrong digit.
The pages are rotated a few degrees and have speckle. Invoices from the email
inbox read correctly. No exception is thrown.
**Constraints:** Keep the Total due parsing as it is. Do not change the public
signature of InvoiceReader.ReadTotal. No new packages.
**Acceptance:** Existing tests pass, plus a new test that reads every scan in
TestData/warehouse/ and matches expected.csv.
A nota de que as faturas enviadas por e-mail lidas corretamente direciona a investigação para a qualidade da digitalização em vez de interpretação.
Por que os testes do agente em nuvem falham em um projeto IronOCR?
Por padrão, o agente em nuvem compila e testa em um runner Ubuntu Linux efêmero. O pacote IronOcr embarca apenas runtimes nativos para Windows, então o runner precisa de IronOcr.Linux. Um fluxo de configuração em .github/workflows/copilot-setup-steps.yml, com seu único trabalho nomeado copilot-setup-steps, fecha essa lacuna quando é mesclado no branch padrão.
Write .github/workflows/copilot-setup-steps.yml for this repository.
The job must be named copilot-setup-steps exactly, or it is ignored. Trigger it
manually, and on push and pull request limited to that one file path.
Run it on ubuntu-latest with read access to repository contents. Check out the
repository, set up the .NET SDK for the version this project targets, install
the native dependencies IronOCR needs on Ubuntu, then restore packages.
For those dependencies read
https://ironsoftware.com/ocr/csharp/get-started/linux/ and use what it lists for
Ubuntu rather than a list from memory. Note in a comment that the list can
change between releases.
The runner is Linux, so OCR there needs the IronOcr.Linux package this
repository's instructions name. Show me the finished YAML, then any project
change the runner still needs to restore IronOcr.Linux.
- A chave de licença: O agente em nuvem não pode ler segredos do Actions, Codespaces ou Dependabot, então a chave precisa de um segredo de Agentes. Adicione a chave em Configurações, então Segredos e variáveis, então Agentes, com o mesmo nome que o editor lê, e o agente a recebe como uma variável de ambiente.
- Um passo de configuração falhado: Isso não para o agente em nuvem. O agente pula os passos restantes e começa a trabalhar de qualquer forma, então execute o fluxo uma vez na aba Ações e confirme que passa.
O que você deve verificar antes de fazer o merge?
Revise um pull request do Copilot como faria com o de um colega.
/tests Add xUnit tests for this change: every scan in TestData/warehouse/ returns
the invoice number and total in its expected.csv, a page without a total returns
null rather than a guess, and reads below 80 confidence are flagged. Assert on
extracted fields, not on the full page text.
Um novo lançamento do IronOCR pode mudar espaçamentos e quebras de linha sem mudar os valores. O guia de assistentes de codificação de IA transforma esta revisão em um teste repetível.
Como você diagnostica um resultado OCR incorreto?
Um resultado incorreto geralmente tem uma das três causas. A página precisa de um filtro de imagem ou uma DPI mais alta, o pack de linguagem do documento nunca foi adicionado, ou a leitura direciona para a região errada. Uma coleção de códigos de barras vazia também pode significar que Configuration.ReadBarCodes nunca foi configurado.
Delivery notes in TestData/notes/ return their text, but about a third
come back with an empty barcode collection, while the same notes decode fine on
the handheld scanner.
Explain the cause before changing anything, then fix it in ReadDeliveryNote only.
Do not change the text extraction. Report how many notes return a barcode before
and after. Measure the current count first and base the explanation on what you
measured, not on a guess.
Em uma execução sem a instrução de medição-primeiro, o Copilot inicialmente culpou a resolução, então rastreou os códigos de barras ausentes até códigos QR impressos em cinza desbotado e os recuperou cortando uma região fixa e selecionando um tom de cinza. Em um segundo conjunto com códigos desbotados impressos mais abaixo na página, essa correção não leu nenhum deles. Com a instrução, o Copilot mediu primeiro, excluiu contraste, binarização, upscaling e corte, e adicionou uma segunda leitura após aplicar um filtro de nitidez. Sempre teste correções em páginas que o Copilot não viu anteriormente.
Se o reconhecimento funciona localmente, mas falha em um runner ou em um contêiner, dê ao Copilot a mensagem completa da exceção em vez de um resumo.
O que os prompts produziram em uma execução real?
Cada prompt neste guia que é executado no editor foi enviado em sequência, ao longo de dois chats, contra um aplicativo receptor de amostra, um projeto console .NET 9 com gerenciamento central de pacotes, um leitor de faturas e digitalizações com valores conhecidos. Cada resultado abaixo foi medido novamente fora do chat.
- Notas de entrega com um código de barras passaram de 6 de 9 antes da correção para 9 de 9 depois dela, e a mesma correção leu 8 de 12 códigos desbotados no segundo conjunto.
- A suíte
/testspassou 14 de 14. Ela também mudou a saída do console do ImportJob sem solicitação, e testou o limiar de confiança em registros construídos, não digitalizações. - Após os quatro prompts, a compilação Release estava limpa, sem edições manuais.
- Duas partes rodaram de forma diferente da página. A pessoa colou a chave de licença no prompt dos testes, e o Copilot a manteve fora de cada arquivo. O fluxo de configuração, o agente em nuvem, seu problema e o segredo Agentes precisam de GitHub Actions ou um repositório GitHub, então nenhum deles foi executado.
A versão do assistente, modelo, tempos e máquina de teste por trás desses números são listados com cada outro guia no registro de execução.
Solução de problemas
- Aplique uma chave de licença no IronOCR se um pull request compilar, mas a primeira leitura lançar uma exceção de licença
- IronOCR no Linux se um runner Linux estiver faltando dependências nativas
- Melhorar a precisão do OCR se os valores extraídos diferirem da digitalização
- Pasta de Runtimes do IronOCR se arquivos nativos estiverem ausentes da saída da compilaçã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.