Wie Sie IronOCR mit GitHub Copilot verwenden

Curtis Chau
Curtis Chau
Aktualisiert: 9. Oktober 2026

.NET-Teams mit etablierten Visual Studio-Lösungen für Dokumentenerfassung, Kreditorenbuchhaltung, Schadenbearbeitung oder Dokumentenverwaltung müssen die Editoren nicht wechseln, um GitHub Copilot zu evaluieren, da es ihre bestehenden Workflows unterstützt.

Copilot läuft in Visual Studio, VS Code, JetBrains IDEs und auf GitHub.com. IronOCR verarbeitet die Erkennung lokal in .NET.

Für Details zu IronOCRs Modellen für Fotografien und Handschriften siehe den Fotolesen-Leitfaden und den Handschrift-Leitfaden.

Schnellstart
NuGetMit NuGet installieren

PM > Install-Package IronOcr

Installieren Sie IronOCR, indem Sie den obigen Befehl in der NuGet Packet Manager-Konsole ausführen, oder suchen Sie das Paket im NuGet Paket Manager.

Geben Sie in Ihrer aktuellen IDE an, was die Methode zurückgeben muss, und welche Standardeinstellung das Modell sonst zurückrufen müsste.

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

Setzen Sie IRONOCR_LICENSE_KEY in der Umgebung, von der der Editor startet, und sehen Sie im Lizenzschlüssel-Leitfaden nach weiteren Orten, um den Schlüssel zu speichern. Ohne ihn hält der erste Lesevorgang bei der Lizenzprüfung an, und Copilot kann nicht den OCR-Code ausführen, den es schreibt.



Wo passt Copilot in ein bereits in Visual Studio vorhandenes Projekt?

Verwenden Sie den Inline-Chat für eine Änderung an einer Einzeldatei von IronOCR. Wechseln Sie in den Agentenmodus, wenn die Änderung mehrere Dateien umfasst, da es das Projekt selbst bauen und den OCR-Code ausführen kann. Der Cloud-Agent auf GitHub nimmt ein zugewiesenes Problem und gibt eine Pull-Anfrage zurück.

Wie setzen Sie IronOCR-Konventionen für Copilot?

Bestätigen Sie die IronOCR-Konventionen als .github/copilot-instructions.md, die Copilot-Chat, der Agentenmodus und der Cloud-Agent lesen. Inline-Vervollständigungen ignorieren dies.

# 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

Wie geben Sie einem Ordner seine eigenen OCR-Sprachregeln?

IronOCR-Einstellungen variieren oft nach Quelle, z. B. deutsche Lieferantenrechnungen und englische Lagerscans. Legen Sie die deutschen Regeln in .github/instructions/ocr-german.instructions.md ab. Copilot wendet diese Datei zusammen mit der repository-weit geltenden an, wann immer die Datei, an der gearbeitet wird, dem Pfadmuster ganz oben in der deutschen Datei entspricht.

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

Ein deutscher Beispiel-Scan mit dem neuesten deutschen Pack, 2020.11.2, und Englisch als Sekundärsprache ergab "Gesamtbetrag: 3.271,07 EUR" mit 96,6 % Sicherheit auf dieser Zeile.

Was macht ein Problem aus, auf das der Cloud-Agent reagieren kann?

Ein Issue, das nur falsche Rechnungsbeträge meldet, überlässt es dem Cloud-Agenten, die schuldige Datei, die betroffenen Scans und die korrekten Beträge zu finden.

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

Die Notiz, dass per E-Mail verschickte Rechnungen korrekt gelesen werden, lenkt die Untersuchung eher auf die Scanqualität als auf das Parsing.

Warum schlagen die Tests des Cloud-Agenten bei einem IronOCR-Projekt fehl?

Standardmäßig baut und testet der Cloud-Agent auf einem flüchtigen Ubuntu-Linux-Runner. Das IronOcr-Paket enthält nur Windows-native Laufzeiten, daher benötigt der Runner IronOcr.Linux. Ein Setup-Workflow bei .github/workflows/copilot-setup-steps.yml, mit einem einzigen Job namens copilot-setup-steps, schließt diese Lücke, sobald er in den Standardzweig integriert ist.

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
  • Der Lizenzschlüssel: Der Cloud-Agent kann keine Secrets von Actions, Codespaces oder Dependabot lesen, daher benötigt der Schlüssel ein Agents-Secret. Fügen Sie den Schlüssel unter Einstellungen, dann Secrets und Variablen, dann Agents hinzu, mit demselben Namen, den der Editor liest, und der Agent erhält ihn als Umgebungsvariable.
  • Ein gescheiterter Einrichtungsschritt: Er stoppt den Cloud-Agenten nicht. Der Agent überspringt die verbleibenden Schritte und beginnt trotzdem mit der Arbeit, also führen Sie den Workflow einmal aus dem Aktionen-Tab aus und bestätigen Sie, dass er bestanden wird.

Was sollten Sie prüfen, bevor Sie zusammenführen?

Überprüfen Sie einen Copilot-Pull-Request wie den eines Kollegen.

/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

Ein neues IronOCR-Release kann Abstände und Zeilenumbrüche ändern, ohne die Werte zu ändern. Der Leitfaden für KI-Coding-Assistenten macht diese Überprüfung zu einem wiederholbaren Test.

Wie diagnostizieren Sie ein falsches OCR-Ergebnis?

Ein falsches Ergebnis hat normalerweise eine von drei Ursachen. Die Seite benötigt einen Bildfilter oder eine höhere DPI, das Sprachpaket des Dokuments wurde nie hinzugefügt, oder das Leseziel ist die falsche Region. Eine leere Barcode-Sammlung kann auch bedeuten, dass Configuration.ReadBarCodes nie gesetzt wurde.

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

In einem Lauf ohne die Maß-voran-Instruktion, beschuldigte Copilot zunächst die Auflösung, dann verfolgte es die fehlenden Barcodes zu QR-Codes, die in verblasstem Grau gedruckt waren, und erholte sie, indem eine feste Region zugeschnitten und ein Grauton ausgewählt wurde. In einem zweiten Satz mit verblassten Codes, die weiter unten auf der Seite gedruckt waren, las diese Korrektur keinen von ihnen. Mit der Anweisung maß Copilot zuerst, schloss Kontrast, Binärisierung, Hochskalierung und Zuschneiden aus und fügte einen zweiten Lesevorgang hinzu, nachdem ein Schärfungsfilter angewendet wurde. Testen Sie Korrekturen immer auf Seiten, die Copilot zuvor nicht gesehen hat.

Wenn die Erkennung lokal funktioniert, aber auf einem Runner oder in einem Container fehlschlägt, geben Sie Copilot die vollständige Ausnahme-Nachricht statt einer Zusammenfassung.

Was haben die Aufforderungen in einem realen Lauf erzeugt?

Jede Eingabeaufforderung in diesem Leitfaden, die im Editor ausgeführt wurde, wurde in Sequenz, über zwei Chats, gegen eine Beispiel-Empfangs-App, ein .NET 9-Konsolenprojekt mit zentralem Paketmanagement, einen Rechnungsleser und Scans mit bekannten Werten gesendet. Jedes Ergebnis unten wurde erneut außerhalb des Chats gemessen.

  • Lieferhinweise mit einem Barcode gingen von 6 von 9 vor der Korrektur zu 9 von 9 nach der Korrektur, und die gleiche Korrektur las 8 von 12 verblassten Codes im zweiten Satz.
  • Die /tests-Suite bestand 14 von 14. Sie änderte auch ungefragt die Konsolenausgabe von ImportJob und testete die Sicherheitsschwelle auf konstruierten Datensätzen und nicht auf Scans.
  • Nach allen vier Eingabeaufforderungen war der Release-Build sauber, ohne manuelle Bearbeitung.
  • Zwei Teile liefen anders als die Seite. Die Person fügte den Lizenzschlüssel in die Tests-Eingabeaufforderung ein, und Copilot hielt ihn aus jeder Datei heraus. Der Setup-Workflow, der Cloud-Agent, sein Issue und das Agents-Secret benötigen GitHub-Actions oder ein GitHub-Repository, sodass keiner von ihnen lief.

Die Assistenzversion, das Modell, die Zeiten und die Testmaschine hinter diesen Zahlen sind zusammen mit jedem anderen Leitfaden im Ablaufprotokoll aufgelistet.


Fehlerbehebung


Fragen?

Wenn Sie Fragen haben, wenden Sie sich an support@ironsoftware.com.

Curtis Chau hat einen Bachelor-Abschluss in Informatik von der Carleton University und ist spezialisiert auf Frontend-Entwicklung mit Expertise in Node.js, TypeScript, JavaScript und React. Leidenschaftlich widmet er sich der Erstellung intuitiver und ästhetisch ansprechender Benutzerschnittstellen und arbeitet gerne mit modernen Frameworks sowie der Erstellung gut strukturierter, optisch ansprechender Handbücher.

Mehr lesen

Bereit loszulegen?

NuGet-Downloads 6,394,824Version:2026.11gerade veröffentlicht