Wie man OCR in C# debuggt

This article was translated from English: Does it need improvement?
Translated
View the article in English

IronOCR ermöglicht die Erkennung von OCR-Fehlern direkt an der Quelle, die Bewertung der Erkennungsqualität auf Wort- und Zeichenebene sowie die Echtzeitüberwachung von Langzeitaufträgen. Integrierte Funktionen wie die Protokollierung von Diagnosedateien, eine hierarchisch strukturierte Ausnahmebehandlung, die Bewertung der Konfidenz pro Ergebnis und das Ereignis OcrProgress unterstützen diese Arbeitsabläufe in Produktionspipelines.

Dieser Leitfaden führt Sie durch praktische Beispiele für jeden einzelnen Punkt: Aktivieren der Diagnoseprotokollierung, Behandeln von typisierten Ausnahmen, Validieren der Ausgabe mit Konfidenzwerten, Überwachen des Jobfortschritts in Echtzeit und Isolieren von Fehlern in Batch-Pipelines.

Schnellstart: Vollständige OCR-Diagnoseprotokollierung aktivieren

Setzen Sie LogFilePath und LoggingModus in der Klasse Installation vor dem ersten Aufruf von Read. Es genügen zwei Eigenschaften, um die Initialisierung von Tesseract, das Laden von Sprachpaketen und Verarbeitungsdetails in einer Protokolldatei zu erfassen.

  1. Installieren Sie IronOCR mit NuGet Package Manager

    PM > Install-Package IronOcr
  2. Kopieren Sie diesen Codeausschnitt und führen Sie ihn aus.

    IronOcr.Installation.LogFilePath = "ocr.log"; IronOcr.Installation.LoggingModus = IronOcr.Installation.LoggingModuss.All;
  3. Bereitstellen zum Testen in Ihrer Live-Umgebung

    Beginnen Sie noch heute, IronOCR in Ihrem Projekt zu verwenden, mit einer kostenlosen Testversion

    arrow pointer


Wie aktiviere ich die Diagnoseprotokollierung?

Die Klasse Installation stellt drei Protokollierungssteuerungen bereit. Diese Einstellungen müssen vor dem Aufruf einer beliebigen Read Methode vorgenommen werden.

:path=/static-assets/ocr/content-code-examples/how-to/debugging-enable-logging.cs
using IronOcr;

// Write logs to a specific file
Installation.LogFilePath = "logs/ocr_diagnostics.log";

// Enable all logging channels: file + debug output
Installation.LoggingMode = Installation.LoggingModes.All;

// Or pipe logs into your existing ILogger pipeline
Installation.CustomLogger = myLoggerInstance;
$vbLabelText   $csharpLabel

LoggingModus akzeptiert Flag-Werte aus dem Enum LoggingModuss :

Tabelle 1: Optionen für die Protokollierungsmodi
ModusAusgabezielAnwendungsfall
NoneDeaktiviertProduktion mit externer Überwachung
DebugIDE-Debug-AusgabefensterLokale Entwicklung
FileLogFilePathserverseitige Protokollerfassung
AllDebug + DateiVollständige Diagnoseerfassung

Die Eigenschaft CustomLogger unterstützt jede Microsoft.Extensions.Logging.ILogger-Implementierung und ermöglicht es Ihnen, OCR-Diagnosedaten an Serilog, NLog oder andere strukturierte Protokollierungsziele in Ihrer Pipeline weiterzuleiten. Verwenden Sie ClearLogFiles, um zwischen den Ausführungen angesammelte Protokolldaten zu entfernen.

Nachdem die Protokollierung eingerichtet ist, besteht der nächste Schritt darin, zu verstehen, welche Ausnahmen IronOCR auslösen kann und wie man jede einzelne behandelt.

Welche Ausnahmen wirft IronOCR ?

IronOCR definiert typisierte Ausnahmen unter dem Namespace IronOcr.Ausnahmes . Indem man diese Fehler gezielt abfängt, anstatt einen allgemeinen Fehlerblock zu verwenden, kann man jeden Fehlertyp dem richtigen Abhilfepfad zuweisen.

Tabelle 2: IronOCR -Ausnahmereferenz
AusnahmeGemeinsame UrsacheFix
IronOcrInputAusnahmeBeschädigtes oder nicht unterstütztes Bild/PDFDatei vor dem Laden in OcrInput validieren.
IronOcrProductAusnahmeInterner Engine-Fehler während der OCR-AusführungProtokollierung aktivieren, Protokollausgabe prüfen, auf die neueste NuGet Version aktualisieren
IronOcrDictionaryAusnahmeFehlende oder beschädigte .traineddata -SprachdateiInstallieren Sie das Sprachpaket NuGet oder legen Sie LanguagePackDirectory fest.
IronOcrNativeAusnahmeInteroperabilitätsfehler in nativem C++Installieren Sie die Visual C++ Redistributable ; überprüfen Sie die AVX-Unterstützung.
IronOcrLicensingAusnahmeFehlender oder abgelaufener LizenzschlüsselSetzen Sie LicenseKey vor dem Aufruf Read
LanguagePackAusnahmeSprachpaket nicht im erwarteten Pfad gefundenÜberprüfen Sie LanguagePackDirectory oder installieren Sie das NuGet Sprachpaket neu.
IronOcrAssemblyVersionMismatchAusnahmeNach einer Teilaktualisierung traten Versionskonflikte in der Assembly auf.Leeren Sie den NuGet Cache, stellen Sie die Pakete wieder her und stellen Sie sicher, dass alle IronOCR Pakete übereinstimmen.

Verwenden Sie den folgenden try-catch-Block, um jeden Ausnahmetyp separat zu behandeln und Ausnahmefilter für die bedingte Protokollierung anzuwenden.

Eingabe

Eine einseitige Lieferantenrechnung von IronOCR Solutions an Acme Corporation, geladen über LoadPdf in OcrInput. Es umfasst vier Einzelposten, die Steuer und eine Gesamtsumme – genug Textvielfalt, um jedem Ausnahmebehandler eine realistische Übung zu bieten.

invoice_scan.pdf: Lieferantenrechnung (Nr. INV-2024-7829), die verwendet wird, um die einzelnen typisierten Ausnahmebehandlungsroutinen nacheinander zu demonstrieren.

:path=/static-assets/ocr/content-code-examples/how-to/debugging-exception-handling.cs
using IronOcr;
using IronOcr.Exceptions;

var ocr = new IronTesseract();

try
{
    using var input = new OcrInput();
    input.LoadPdf("invoice_scan.pdf");

    OcrResult result = ocr.Read(input);
    Console.WriteLine($"Text: {result.Text}");
    Console.WriteLine($"Confidence: {result.Confidence:P1}");
}
catch (IronOcrInputException ex)
{
    // File could not be loaded — corrupt, locked, or unsupported format
    Console.Error.WriteLine($"Input error: {ex.Message}");
}
catch (IronOcrDictionaryException ex)
{
    // Language pack missing — common in containerized deployments
    Console.Error.WriteLine($"Language pack error: {ex.Message}");
}
catch (IronOcrNativeException ex) when (ex.Message.Contains("AVX"))
{
    // CPU does not support AVX instructions
    Console.Error.WriteLine($"Hardware incompatibility: {ex.Message}");
}
catch (IronOcrLicensingException)
{
    Console.Error.WriteLine("License key is missing or invalid.");
}
catch (IronOcrProductException ex)
{
    // Catch-all for other IronOCR engine errors
    Console.Error.WriteLine($"OCR engine error: {ex.Message}");
    Console.Error.WriteLine($"Stack trace: {ex.StackTrace}");
}
$vbLabelText   $csharpLabel

Ausgabe

Erfolgsergebnis

Die Rechnung wird fehlerfrei geladen und die Engine gibt die Zeichenanzahl sowie einen Konfidenzwert zurück.

Terminalausgabe zeigt erfolgreiches OCR-Lesen von invoice_scan.pdf mit Zeichenanzahl und Konfidenzwert an.

Fehlgeschlagene Ausgabe

Terminalausgabe mit der Meldung, dass beim Laden einer fehlenden PDF-Datei eine Ausnahme ausgelöst wurde.

Ordnen Sie die Fangblöcke von den spezifischsten zu den allgemeinsten. Die when-Klausel in IronOcrNativeAusnahme filtert nach AVX-bezogenen Fehlern, ohne dabei nicht damit zusammenhängende native Fehler abzufangen. Jeder Handler protokolliert die Ausnahmemeldung; Der Catch-All-Block erfasst auch den Stack-Trace für die anschließende Analyse.

Das Abfangen der richtigen Ausnahme signalisiert, dass etwas schiefgelaufen ist, aber nicht, wie gut der Motor funktioniert hat, als er erfolgreich war. Verwenden Sie dazu Konfidenzwerte.

Wie validiere ich OCR-Ausgaben mit Konfidenzwerten?

Jeder OcrResult stellt eine Confidence-Eigenschaft bereit, einen Wert zwischen 0 und 1, der die statistische Sicherheit der Engine, gemittelt über alle erkannten Zeichen, darstellt. Sie können darauf auf jeder Ebene der Ergebnishierarchie zugreifen: Dokument , Seite ,Absatz , Wort undZeichen .

Verwenden Sie ein schwellenwertbasiertes Muster, um zu verhindern, dass minderwertige Ergebnisse nachgelagert weitergegeben werden.

Eingabe

Ein Thermobon mit detaillierten Positionen, Rabatten, Summen und einem Barcode, geladen über LoadImage. Durch seine geringe Breite, die nichtproportionale Schriftart und die schwache Schrift eignet es sich hervorragend als Stresstest für Konfidenzschwellenwerte pro Wort.

Beispiel eines Thermobons von FoodMart mit Einzelaufstellung der Einkäufe, Gesamtsumme und als OCR-Eingabe verwendeten Bonuspunkten

receipt.png: Thermodruck-Kassenbon-Scan zur Veranschaulichung der schwellenwertbasierten Konfidenzvalidierung und der detaillierten Genauigkeitsanalyse pro Wort.

:path=/static-assets/ocr/content-code-examples/how-to/debugging-confidence-scoring.cs
using IronOcr;

var ocr = new IronTesseract();
using var input = new OcrInput();
input.LoadImage("receipt.png");

OcrResult result = ocr.Read(input);
double confidence = result.Confidence;

Console.WriteLine($"Overall confidence: {confidence:P1}");

// Threshold-gated decision
if (confidence >= 0.90)
{
    Console.WriteLine("ACCEPT — high confidence, processing result.");
    ProcessResult(result.Text);
}
else if (confidence >= 0.70)
{
    Console.WriteLine("FLAG — moderate confidence, queuing for review.");
    QueueForReview(result.Text, confidence);
}
else
{
    Console.WriteLine("REJECT — low confidence, logging for investigation.");
    LogRejection("receipt.png", confidence);
}

// Drill into per-page and per-word confidence for diagnostics
foreach (var page in result.Pages)
{
    Console.WriteLine($"  Page {page.PageNumber}: {page.Confidence:P1}");

    var lowConfidenceWords = page.Words
        .Where(w => w.Confidence < 0.70)
        .ToList();

    foreach (var word in lowConfidenceWords)
    {
        Console.WriteLine($"    Low-confidence word: \"{word.Text}\" ({word.Confidence:P1})");
    }
}
$vbLabelText   $csharpLabel

Ausgabe

Terminalausgabe mit Konfidenzbewertung, Entscheidung (Annehmen/Markieren/Ablehnen) und detaillierter Aufschlüsselung der einzelnen Wörter mit geringer Konfidenz für das Belegbild

Dieses Muster ist unerlässlich in Prozessabläufen, in denen OCR in die Dateneingabe, die Rechnungsverarbeitung oder Compliance-Workflows einfließt. Die detaillierte Analyse jedes einzelnen Wortes identifiziert genau die Bereiche des Quellbildes, die zu Bildfehlern geführt haben; Anschließend können Sie Bildqualitätsfilter oder Ausrichtungskorrekturen anwenden und das Bild erneut verarbeiten. Für einen detaillierteren Einblick in die Konfidenzbewertung siehe die Anleitung zu den Konfidenzstufen .

Bei langjährigen Jobs reicht Selbstvertrauen allein nicht aus. Sie müssen außerdem wissen, ob der Motor noch Fortschritte macht, und genau hier kommt das Ereignis OcrProgress ins Spiel.

Wie kann ich den OCR-Fortschritt in Echtzeit überwachen?

Bei mehrseitigen Dokumenten wird das Ereignis OcrProgress auf IronTesseract nach Abschluss jeder Seite ausgelöst. Das Objekt OcrProgressEventArgs zeigt den Fortschritt in Prozent, die verstrichene Dauer, die Gesamtzahl der Seiten und die Anzahl der abgeschlossenen Seiten an. Das Beispiel verwendet diesen dreiseitigen Quartalsbericht als Grundlage: ein strukturiertes Geschäftsdokument, das eine Managementzusammenfassung, eine Umsatzaufschlüsselung und operative Kennzahlen umfasst.

Eingabe

Ein dreiseitiger Finanzbericht für das erste Quartal 2024 wurde über LoadPdf hochgeladen. Seite eins enthält die Managementzusammenfassung mit KPI-Kennzahlen, Seite zwei enthält Umsatztabellen nach Produktlinie und Region, und Seite drei behandelt die operativen Verarbeitungsvolumina – jeder Seitentyp erzeugt eine unterschiedliche Zeit pro Seite, die Sie in den Fortschritts-Callbacks beobachten können.

quarterly_report.pdf: Dreiseitiger Finanzbericht für das erste Quartal 2024 (Zusammenfassung, Umsatzaufschlüsselung, operative Kennzahlen), der zur Veranschaulichung `OcrProgress` Rückrufe in Echtzeit pro Seite verwendet wird.

:path=/static-assets/ocr/content-code-examples/how-to/debugging-progress-monitoring.cs
using IronOcr;

var ocr = new IronTesseract();

ocr.OcrProgress += (sender, e) =>
{
    Console.WriteLine(
        $"[OCR] {e.ProgressPercent}% complete | " +
        $"Page {e.PagesComplete}/{e.TotalPages} | " +
        $"Elapsed: {e.Duration.TotalSeconds:F1}s"
    );
};

using var input = new OcrInput();
input.LoadPdf("quarterly_report.pdf");

OcrResult result = ocr.Read(input);
Console.WriteLine($"Finished in {result.Pages.Count()} pages, confidence: {result.Confidence:P1}");
$vbLabelText   $csharpLabel

Ausgabe

Terminalausgabe mit Anzeige der OcrProgress-Ereignis-Callbacks pro Seite, inklusive Fortschrittsanzeige in Prozent und verstrichener Zeit für ein dreiseitiges PDF

Integrieren Sie dieses Ereignis in Ihre Protokollierungsinfrastruktur, um die Dauer von OCR-Aufträgen zu verfolgen und Unterbrechungen zu erkennen. Wenn die verstrichene Zeit einen Schwellenwert überschreitet, ohne dass der Fortschritt in Prozent ansteigt, kann die Pipeline den Auftrag zur Untersuchung kennzeichnen. Dies ist besonders nützlich für die Stapelverarbeitung von PDFs, bei der eine einzige fehlerhafte Seite den gesamten Vorgang zum Stillstand bringen kann.

Die Fortschrittsüberwachung zeigt den Ausführungsstatus an, aber ein Fehler auf Dateiebene kann die gesamte Batchverarbeitung vorzeitig stoppen, wenn er nicht isoliert wird.

Wie gehe ich mit Fehlern in Batch-OCR-Pipelines um?

Im Produktionsbetrieb sollte der Fehler einer einzelnen Datei nicht den gesamten Batch stoppen. Isolieren Sie Fehler pro Datei, protokollieren Sie Fehler mit Kontext und erstellen Sie am Ende einen zusammenfassenden Bericht. Das Beispiel verarbeitet einen Ordner mit gescannten Dokumenten, der eine Rechnung, eine Bestellung und einen Servicevertrag enthält, Plus eine absichtlich beschädigte Datei, um den Fehlerpfad auszulösen. Nachfolgend ist ein repräsentatives Beispiel dargestellt:

Eingabe

Ein Ordner mit PDFs wurde an Directory.GetFiles übergeben – darunter eine Rechnung, eine Bestellung, ein Servicevertrag und eine absichtlich beschädigte Datei. Die beiden unten aufgeführten Beispiele veranschaulichen die Dokumentenvielfalt, die die Pipeline in einem Durchlauf verarbeitet.

:path=/static-assets/ocr/content-code-examples/how-to/debugging-batch-pipeline.cs
using IronOcr;
using IronOcr.Exceptions;

var ocr = new IronTesseract();
Installation.LogFilePath = "batch_debug.log";
Installation.LoggingMode = Installation.LoggingModes.File;

string[] files = Directory.GetFiles("scans/", "*.pdf");
int succeeded = 0, failed = 0;
double totalConfidence = 0;
var failures = new List<(string File, string Error)>();

foreach (string file in files)
{
    try
    {
        using var input = new OcrInput();
        input.LoadPdf(file);

        OcrResult result = ocr.Read(input);
        totalConfidence += result.Confidence;
        succeeded++;

        Console.WriteLine($"OK: {Path.GetFileName(file)} — {result.Confidence:P1}");
    }
    catch (IronOcrInputException ex)
    {
        failed++;
        failures.Add((file, $"Input error: {ex.Message}"));
        Console.Error.WriteLine($"FAIL: {Path.GetFileName(file)} — {ex.Message}");
    }
    catch (IronOcrProductException ex)
    {
        failed++;
        failures.Add((file, $"Engine error: {ex.Message}"));
        Console.Error.WriteLine($"FAIL: {Path.GetFileName(file)} — {ex.Message}");
    }
    catch (Exception ex)
    {
        failed++;
        failures.Add((file, $"Unexpected: {ex.Message}"));
        Console.Error.WriteLine($"FAIL: {Path.GetFileName(file)} — {ex.GetType().Name}: {ex.Message}");
    }
}

// Summary report
Console.WriteLine($"\n--- Batch Summary ---");
Console.WriteLine($"Total: {files.Length} | Passed: {succeeded} | Failed: {failed}");
if (succeeded > 0)
    Console.WriteLine($"Average confidence: {totalConfidence / succeeded:P1}");

foreach (var (f, err) in failures)
    Console.WriteLine($"  {Path.GetFileName(f)}: {err}");
$vbLabelText   $csharpLabel

Ausgabe

Terminalausgabe mit den Ergebnissen der Batch-Pipeline, einschließlich der Zeichenanzahl pro Datei, der Konfidenzwerte, eines Fehlers aufgrund einer beschädigten PDF-Datei und einer Zusammenfassungszeile.

Der äußere Catch-Block behandelt unvorhergesehene Fehler wie Netzwerk-Timeouts bei gemeinsam genutztem Speicher, Berechtigungsprobleme oder Speichermangel bei großen TIFF-Dateien. Bei jedem Fehler werden der Dateipfad und die Fehlermeldung für die Zusammenfassung protokolliert, während die Schleife die Verarbeitung der verbleibenden Dateien fortsetzt. Die Protokolldatei unter batch_debug.log erfasst Details auf Engine-Ebene für jede Datei, die interne Diagnosen auslöst.

Für die nicht-blockierende Ausführung in Diensten oder Webanwendungen unterstützt IronOCR ReadAsync , das die gleiche try-catch-Struktur verwendet.

Wenn die Pipeline fehlerfrei läuft, der extrahierte Text aber trotzdem fehlerhaft ist, liegt die Ursache fast immer in der Bildqualität und nicht im Code. So lässt sich das Problem lösen.

Wie kann ich die Genauigkeit der OCR-Texturierung verbessern?

Sind die Konfidenzwerte durchgehend niedrig, liegt das Problem am Quellbild und nicht am OCR-System. IronOCR bietet Vorverarbeitungswerkzeuge, um dieses Problem zu beheben:

Für spezifische Bereitstellungsprobleme unterhält IronOCR spezielle Leitfäden zur Fehlerbehebung für Azure Functions , Docker und Linux sowie zur allgemeinen Einrichtung der Umgebung .

Wohin soll ich als Nächstes reisen?

Nachdem Sie nun wissen, wie man IronOCR zur Laufzeit debuggt, erkunden Sie Folgendes:

Für den produktiven Einsatz müssen Sie eine Lizenz erwerben, um Wasserzeichen zu entfernen und die volle Funktionalität zu nutzen.

Curtis Chau
Technischer Autor

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

Weiterlesen
Bereit anzufangen?
Nuget Downloads 5,556,263 | Version: 2026.3 gerade veröffentlicht
Still Scrolling Icon

Scrollst du immer noch?

Sie brauchen schnell einen Beweis? PM > Install-Package IronOcr
Führen Sie ein Beispiel aus und beobachten Sie, wie Ihr Bild zu durchsuchbarem Text wird.