Cómo utilizar IronOCR con GitHub Copilot

Curtis Chau
Curtis Chau
Actualizado: 9 de octubre de 2026

Los equipos .NET con soluciones de Visual Studio establecidas para captura de documentos, cuentas por pagar, procesamiento de reclamaciones o gestión de registros no necesitan cambiar de editores para evaluar GitHub Copilot, ya que es compatible con sus flujos de trabajo existentes.

Copilot se ejecuta en Visual Studio, VS Code, IDEs de JetBrains y en GitHub.com. IronOCR realiza el reconocimiento localmente en .NET.

Para más detalles sobre los modelos de IronOCR para fotografías y escritura a mano, consulte la guía de lectura de fotos y la guía de escritura a mano.

Inicio rápido
NuGetInstalar con NuGet

PM > Install-Package IronOcr

Instale IronOCR ejecutando el comando arriba en la Consola del Administrador de Paquetes NuGet, o busque el paquete en el Administrador de Paquetes NuGet.

En su IDE actual, indique qué debe devolver el método y cualquier valor predeterminado que el modelo de otro modo necesitaría recordar.

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

Configure IRONOCR_LICENSE_KEY en el entorno desde el que el editor comienza, y consulte la guía de la clave de licencia para otros lugares donde mantener la clave. Sin ella, la primera lectura se detiene en la verificación de la licencia y Copilot no puede ejecutar el código OCR que escribe.



¿Dónde encaja Copilot en un proyecto ya en Visual Studio?

Utilice el chat en línea para un cambio de IronOCR de un archivo. Cambie al modo de agente cuando el cambio abarque varios archivos, ya que puede compilar el proyecto y ejecutar el código OCR por sí mismo. El agente de la nube en GitHub toma un problema asignado y devuelve una solicitud de extracción.

¿Cómo se establecen las convenciones de IronOCR para Copilot?

Comprometa las convenciones de IronOCR como .github/copilot-instructions.md, que Copilot Chat, el modo de agente y el agente en la nube leen. Las completaciones en línea lo ignoran.

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

¿Cómo se le da a una carpeta sus propias reglas de idioma de OCR?

Las configuraciones de IronOCR a menudo varían según la fuente, como las facturas de proveedores alemanes y los escaneos de almacén en inglés. Coloque las reglas alemanas en .github/instructions/ocr-german.instructions.md. Copilot aplica ese archivo junto con el de todo el repositorio siempre que el archivo en el que está trabajando coincida con el patrón de ruta en la parte superior del archivo alemán.

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

Una lectura de muestra alemana con el paquete alemán más reciente, 2020.11.2, y el inglés como idioma secundario devolvió "Gesamtbetrag: 3.271,07 EUR" con una confianza de 96.6 en esa línea.

¿Qué hace que un problema sea en el que el agente de la nube pueda actuar?

Un problema que solo informa totales de factura incorrectos deja al agente en la nube encontrar el archivo culpable, los escaneos afectados y los totales correctos.

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

La nota de que las facturas enviadas por correo se leen correctamente dirige la investigación hacia la calidad del escaneo más que al análisis.

¿Por qué fallan las pruebas del agente en la nube en un proyecto de IronOCR?

Por defecto, el agente en la nube compila y prueba en un corredor efímero de Ubuntu Linux. El paquete IronOcr solo incluye tiempos de ejecución nativos de Windows, por lo que el corredor necesita IronOcr.Linux. Un flujo de trabajo de configuración en .github/workflows/copilot-setup-steps.yml, con su único trabajo llamado copilot-setup-steps, cierra esa brecha una vez que se fusiona en la rama predeterminada.

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.
Text
  • La clave de licencia: El agente en la nube no puede leer secretos de Actions, Codespaces o Dependabot, por lo que la clave necesita un secreto de Agentes. Agregue la clave en Configuración, luego Secretos y variables, luego Agentes, con el mismo nombre que lee el editor, y el agente la recibe como una variable de entorno.
  • Un paso de configuración fallido: No detiene al agente en la nube. El agente se salta los pasos restantes y comienza a trabajar de todos modos, así que ejecute el flujo de trabajo una vez desde la pestaña de Actions y confirme que pasa.

¿Qué debes verificar antes de fusionar?

Revise una solicitud de extracción de Copilot como lo haría con la de un 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.
Text

Un nuevo lanzamiento de IronOCR puede cambiar el espaciado y los saltos de línea sin cambiar los valores. La guía de asistentes de codificación AI convierte esta revisión en una prueba repetible.

¿Cómo se diagnostica un resultado incorrecto de OCR?

Un resultado incorrecto generalmente tiene una de tres causas. La página necesita un filtro de imagen o un DPI más alto, el paquete de idiomas del documento nunca fue agregado, o la lectura está dirigida a la región incorrecta. Una colección de códigos de barra vacía también puede significar que Configuration.ReadBarCodes nunca fue 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.
Text

En una ejecución sin la instrucción de medir primero, Copilot inicialmente culpó a la resolución, luego rastreó los códigos de barras faltantes a códigos QR impresos en gris desvanecido y los recuperó recortando una región fija y seleccionando un solo tono de gris. En un segundo conjunto con códigos desvanecidos impresos más abajo en la página, esa solución no leyó ninguno. Con la instrucción, Copilot midió primero, descartó el contraste, binarización, ampliación y recorte, y agregó una segunda lectura después de aplicar un filtro de enfoque. Siempre pruebe las soluciones en páginas que Copilot no haya visto previamente.

Si el reconocimiento funciona localmente pero falla en un corredor o en un contenedor, proporcione a Copilot el mensaje completo de excepción en lugar de un resumen.

¿Qué produjeron los prompts en una ejecución real?

Cada solicitud en esta guía que se ejecuta en el editor fue enviada en secuencia, en dos chats, contra una aplicación de recepción de muestra, un proyecto de consola .NET 9 con gestión central de paquetes, un lector de facturas y escaneos con valores conocidos. Cada resultado a continuación fue medido nuevamente fuera del chat.

  • Las notas de entrega con un código de barras pasaron de 6 de 9 antes de la solución a 9 de 9 después de ella, y la misma solución leyó 8 de 12 códigos desvanecidos en el segundo conjunto.
  • La suite /tests pasó 14 de 14. También cambió la salida de consola de ImportJob sin preguntar, y probó el umbral de confianza en registros construidos, no escaneos.
  • Después de las cuatro solicitudes, la compilación Release quedó limpia, sin ediciones manuales.
  • Dos partes se ejecutaron de manera diferente a la página. La persona pegó la clave de licencia en la solicitud de pruebas, y Copilot la mantuvo fuera de cada archivo. El flujo de trabajo de configuración, el agente en la nube, su problema y el secreto de Agentes necesitan Acciones de GitHub o un repositorio de GitHub, por lo que ninguno de ellos se ejecutó.

La versión del asistente, el modelo, los tiempos y la máquina de prueba detrás de estos números se enumeran con todas las demás guías en el registro de ejecución.


Solución de problemas


¿Preguntas?

Si tienes alguna pregunta, contacta a support@ironsoftware.com

Curtis Chau tiene una licenciatura en Ciencias de la Computación (Carleton University) y se especializa en el desarrollo front-end con experiencia en Node.js, TypeScript, JavaScript y React. Apasionado por crear interfaces de usuario intuitivas y estéticamente agradables, disfruta trabajando con frameworks modernos y creando manuales bien estructurados y visualmente atractivos.

Leer más

¿Listo para empezar?

Descargas de NuGet 6,394,824Versión:2026.11recién lanzado