Windows.Media.Ocr'dan IronOCR'ye Geçiş
Bu kılavuz, .NET geliştiricilerinin Windows.Media.Ocr'dan IronOCR'ye geçişi için adım adım bir yol sağlar. Ad alanı kaldırma, proje dosyası değişiklikleri, geçiş sırasında en sık ortaya çıkan desenler için kod geçiş örnekleri ve tamamlanmış geçişi doğrulamak için pratik bir kontrol listesi içerir.
Neden Windows.Media.Ocr'dan (UWP/WinRT OCR) Taşınmalı
Windows.Media.Ocr, sınırları içinde iyi çalışır. Bu sınırlar dardır ve projeler rutin olarak bu sınırları aşar. Ekiplerin geçiş yapma nedenleri tahmin edilebilir kategorilere girer.
Windows TFM Her Tür Windows Olmayan Hedefi Engelliyor. Proje dosyası, net*-windows* Hedef Çerçeve Monikeri'ni, Windows.Media.Ocr ad alanı derleme zamanında çözülmeden önce beyan etmelidir. Bu beyan bir çalışma zamanı bayrağı değildir — projenizi referans alan her projeye yayılan bir yapı kısıtlamasıdır. Paylaşılan bir OCR hizmet kütüphanesi, bir web API, bir Linux'a dağıtılmış arka plan işlemi — hepsi bu sınırlamayı devralır. Bunu kaldırmak, Windows.Media.Ocr'ı kaldırmak anlamına gelir.
Dil Kullanılabilirliği Çalışma Zamanında İşletim Sistemi Tarafından Belirlenir, Yapı Zamanında Geliştirici Tarafından Değil. OcrEngine.TryCreateFromLanguage, istenen dil paketi ana bilgisayarda yok olduğunda null döndürür. Geliştirici bir dil paketini kodla yükleyemez, uygulama ikili dosyasına bir paket ekleyemez veya bir yedek model sunamaz. Otomatik ortamlarda — derleme ajanları, CI koşucuları, minimal bulut VM'leri, konteynerlar — dil paketleri nadiren kurulur. Üretim hataları, eksik bir dil paketi nedeniyle oluşur ve sadece kodu inceleyerek yeniden üretilemez; hedef makinenin OS yapılandırmasının incelenmesi gerekir.
Ön İşleme Yapılmaması Alt Optimize Girdi İçin Kurtarma Yolu Yok Anlamına Gelir. API bir SoftwareBitmap kabul eder ve metni üretir. Bu iki nokta arasındaki görüntü kalitesi iyileştirme tamamen geliştiricinin sorumluluğundadır, yalnızca Windows'a özgü olan ayrı Windows Imaging Component API'leri kullanılarak. Cep telefonu fotoğrafları, hizalanmamış düz yataklı taramalar ve fotokopili belgeler, sessizce doğruluğu azaltır ve sonucu teşhis etmek veya iyileştirmek için yerleşik bir mekanizma yoktur.
PDF, Kurumsal İş Akışlarındaki En Yaygın Belge Formatıdır. Windows.Media.Ocr'ın bir PDF giriş yolu yoktur. Taralı bir PDF'yi işlemek, harici bir renderleyici, sayfa bazlı rasterizasyon ve manuel sonuç montajı gerektirir. Bu renderleyici, bir bağımlılık, lisanslama hususları ve ayrı bir hata yüzeyi ekler — "ücretsiz ve yerleşik" bir kütüphanenin önlemek için tasarlandığı tam karmaşıklık.
Sunucu Tarafı Dağıtım, Yapısal Olarak Desteklenmez. Windows.Media.Ocr hedefler istemci uygulamalarıdır. Bunu Windows Server'da çalıştırmak, VM maliyetini ve altyapı karmaşıklığını artıran Masaüstü Deneyimi özelliği paketini gerektirir. Docker dağıtımı imkansızdır. Linux, AWS Lambda üzerindeki Azure Functions ve herhangi bir Linux tabanlı konteyner iş yükü API'yi referans almıyor.
WinRT Asenkron Yığın, Standart .NET Modelleriyle Uyumlu Değildir. Bir karakter okunmadan önce altı veya daha fazla zincirlenmiş await çağrısı - StorageFile, akış, BitmapDecoder, SoftwareBitmap, null kontrolü, RecognizeAsync - gereklidir. Bu zinciri bir arka plan hizmetine, bir Parallel.ForEach döngüsüne veya standart bir ASP.NET denetleyicisine entegre etmek zorlayıcıdır. Altında WinRT IAsyncOperation makinesi bulunur ve .NET'in Task modeliyle etkileşim, kullanıcı arayüzü dışındaki bağlamlarda ince uç durumlar oluşturur.
Temel Sorun
Windows.Media.Ocr'daki dil kullanılabilirliği, dağıtım zamanında çözülemeyecek bir çalışma zamanı bilinmezliğidir:
// Windows.Media.Ocr: language availability decided by OS admin, not the developer
// Returns null on any machine without the language pack installed
var engine = OcrEngine.TryCreateFromLanguage(
new Windows.Globalization.Language("ja-JP"));
if (engine == null)
throw new InvalidOperationException(
"Japanese OCR unavailable — install the Japanese language pack in Windows Settings.");
//Hayırrecovery path.Hayırbundled model.Hayırfallback.
// IronOCR: language availability is a NuGet package, not an OS configuration
// dotnet add package IronOcr.Languages.Japanese
var ocr = new IronTesseract();
ocr.Language = OcrLanguage.Japanese;
var result = ocr.Read("invoice.jpg"); // Works on any OS, any machine
Console.WriteLine(result.Text);
##IronOCR vs Windows.Media.Ocr (UWP/WinRT OCR): Özellik Karşılaştırması
Aşağıdaki tablo, karar vermeyi etkileyen tüm yetenek yüzeyini kapsar.
| Özellik | Windows.Media.Ocr | IronOCR |
|---|---|---|
| Platform: Windows 10/11 | Evet | Evet |
| Platform: Windows Server | Sınırlı (Masaüstü Deneyimi gerekli) | Evet |
| Platform: Linux | Hayır | Evet |
| Platform: macOS | Hayır | Evet |
| Platform: Docker konteynerleri | Hayır | Evet |
| Platform: Azure Functions (Linux) | Hayır | Evet |
| Platform: AWS Lambda | Hayır | Evet |
| Proje TFM gereksinimi | net*-windows* gerekli | Yok (standart TFM'ler) |
| Kurulum | Windows yerleşik (NuGet yok) | Tek bir NuGet paketi (IronOcr) |
| Görüntü girişi (JPG, PNG, BMP) | Evet (WinRT hattı aracılığıyla) | Evet |
| PDF girişi | Hayır | Evet (yerel) |
| Çok sayfalı TIFF girişi | Hayır | Evet |
| Akış ve bayt dizisi girişi | Hayır (sadece StorageFile) | Evet |
| Dil kaynağı | OS yüklü dil paketleri | 125'den fazla paketlenmiş NuGet paketi |
| Dil taşınabilirliği | Hayır (makine bağımlı) | Evet (uygulama ile dağıtılır) |
| Çok dillilik aynı anda | Hayır | Evet |
| Ön işleme: düz hale getirme | Hayır | Evet (input.Deskew()) |
| Ön işleme: gürültüyü azaltma | Hayır | Evet (input.DeNoise()) |
| Ön işleme: kontrast | Hayır | Evet (input.Contrast()) |
| Ön işleme: ikilileştirme | Hayır | Evet (input.Binarize()) |
| Aranabilir PDF çıktısı | Hayır | Evet (result.SaveAsSearchablePdf()) |
| Kelime başına güven puanları | Hayır | Evet (word.Confidence) |
| Yapılandırılmış çıktı (paragraflar, satırlar, kelimeler) | Sadece satırlar | Sayfalar, Paragraflar, Satırlar, Kelimeler, Karakterler |
| OCR sırasında barkod okuma | Hayır | Evet |
| Bölge tabanlı OCR | Hayır | Evet (CropRectangle) |
| Eşzamanlı OCR yolu | Hayır | Evet |
| İş parçacığı güvenli paralel işleme | Sınırlı | Tam |
| Ticari destek | Hayır (Windows platform ekibi) | Evet |
| Lisanslama modeli | Ücretsiz (Windows yerleşik) | Süresiz ($999 Lite, $1,499 Pro, $2,999 Enterprise) |
Hızlı Başlangıç: Windows.Media.Ocr (UWP/WinRT OCR) için IronOCR Göçü
Adım 1: NuGet Paketini Değiştirin
Windows.Media.Ocr'ın NuGet paketi yoktur — Windows Runtime'ın bir parçasıdır ve Windows TFM ile çözülür. Bunu kaldırmak, Windows'a özgü ad alanı referanslarını ve mümkünse proje dosyasından Windows TFM'yi kaldırmak anlamına gelir.
Tüm kaynak dosyalardan Windows.Media.Ocr ad alanlarını kaldırın:
# Audit all files referencing Windows OCR namespaces
grep -r "Windows.Media.Ocr\|Windows.Graphics.Imaging\|Windows.Storage" --include="*.cs" .
IronOCR'yi yükleyin:
IronOCR NuGet paketi, net6.0, net7.0, net8.0 ve net9.0 hedefler ve platforma özel TFM'leri içermez. Windows OCR ad alanlarını kaldırdıktan sonra, projede başka WinRT API'leri kalmıyorsa, proje dosyasındaki <TargetFramework>, net8.0-windows10.0.19041.0'den net8.0'ye (veya uygun sürüme) güncelleyin.
Adım 2: Ad Alanlarını Güncelleyin
Üç Windows OCR ad alanını tek bir IronOCR ad alanı ile değiştirin:
// Before (Windows.Media.Ocr)
using Windows.Media.Ocr;
using Windows.Graphics.Imaging;
using Windows.Storage;
using Windows.Globalization;
// After (IronOCR)
using IronOcr;
Adım 3: Lisansa İzin Verin
Lisans başlatma çağrısını uygulama başlangıcında - Program.cs, Startup.cs veya uygulama ana bilgisayar oluşturucusunda bir kere ekleyin:
IronOcr.License.LicenseKey = "YOUR-LICENSE-KEY";IronOcr.License.LicenseKey = "YOUR-LICENSE-KEY"Ücretsiz deneme anahtarı, IronOCR lisanslama sayfasından temin edilebilir ve değerlendirme amaçları için deneme filigranını kaldırır.
Kod Göç Örnekleri
Arka Plan Hizmetindeki WinRT Async Zincirini Değiştirme
Windows.Media.Ocr, tanıma başlamadan önce en az altı zincirleme eşzamansız işlemi gerektirir. Bir belge kuyruğunu işleyen arka plan hizmetinde, bu zincir bir döngü içinde çalışır — ve SoftwareBitmap imhası, null kontrolü ve WinRT IAsyncOperation ara yüzü, her tekrar sırasında zorluk yaratır.
Windows.Media.Ocr Yaklaşımı:
// Windows.Media.Ocr: full async chain required per document
// Requires net8.0-windows10.0.19041.0 TFM — cannot deploy to Linux workers
public async Task<List<string>> ProcessQueueAsync(IEnumerable<string> imagePaths)
{
var engine = OcrEngine.TryCreateFromUserProfileLanguages();
if (engine == null)
throw new InvalidOperationException("No OCR language pack installed on this machine.");
var results = new List<string>();
foreach (var path in imagePaths)
{
// Each document: 4 async steps before RecognizeAsync
var file = await StorageFile.GetFileFromPathAsync(path);
using var stream = await file.OpenAsync(FileAccessMode.Read);
var decoder = await BitmapDecoder.CreateAsync(stream);
var bitmap = await decoder.GetSoftwareBitmapAsync();
var ocrResult = await engine.RecognizeAsync(bitmap);
results.Add(ocrResult.Text);
bitmap.Dispose();
}
return results;
}
IronOCR Yaklaşımı:
// IronOCR: one call per document, no WinRT, no SoftwareBitmap, no null checks
// Runs on Windows, Linux, macOS, Docker — same binary, no TFM change
public List<string> ProcessQueue(IEnumerable<string> imagePaths)
{
var results = new List<string>();
foreach (var path in imagePaths)
{
var result = new IronTesseract().Read(path);
results.Add(result.Text);
}
return results;
}
IronOCR sürümü, StorageFile'nün yolculuğunu, BitmapDecoder'yi, SoftwareBitmap yaşam döngüsünü ve null kontrol korumasını ortadan kaldırır. Asenkron-yerel hizmetler için IronOCR bir asenkron yol sunar ve WinRT ara yüz yükü olmadan Task tabanlı boru hatlarına düzgün bir şekilde entegre olur. IronTesseract kurulum kılavuzu, yüksek hacimli kuyruk senaryoları için örnek yaşam döngüsü önerilerini kapsar.
Hafızada Görüntü Verileri İçin SoftwareBitmap Dönüşümünü Ortadan Kaldırma
Bellekte zaten görüntü verisine sahip uygulamalar — bir ağ indirmesi, bir veritabanı bloğu veya bir kamera yakalama geri çağrısı yoluyla — bu verileri SoftwareBitmap'ya dönüştürmelidir, çünkü Windows.Media.Ocr onu işleyemez. Bu dönüştürme yolu BitmapDecoder üzerinden gider, ki bu bir akış gerektirir, bu da bayt dizisini bir MemoryStream'ye kopyalamak anlamına gelir. IronOCR, bayt dizilerini ve akışları doğrudan kabul eder.
Windows.Media.Ocr Yaklaşımı:
// Windows.Media.Ocr: byte array must travel through WinRT stream → BitmapDecoder → SoftwareBitmap
public async Task<string> RecognizeFromBytesAsync(byte[] imageBytes)
{
var engine = OcrEngine.TryCreateFromUserProfileLanguages();
if (engine == null)
throw new InvalidOperationException("No OCR language available.");
// Copy byte array into InMemoryRandomAccessStream (WinRT type)
using var ras = new Windows.Storage.Streams.InMemoryRandomAccessStream();
using var writer = new Windows.Storage.Streams.DataWriter(ras);
writer.WriteBytes(imageBytes);
await writer.StoreAsync();
ras.Seek(0);
var decoder = await BitmapDecoder.CreateAsync(ras);
var bitmap = await decoder.GetSoftwareBitmapAsync();
var result = await engine.RecognizeAsync(bitmap);
bitmap.Dispose();
return result.Text;
}
IronOCR Yaklaşımı:
// IronOCR: byte array loads directly into OcrInput — no conversion, no WinRT types
public string RecognizeFromBytes(byte[] imageBytes)
{
using var input = new OcrInput();
input.LoadImage(imageBytes); // direct byte array load
var result = new IronTesseract().Read(input);
return result.Text;
}
Windows.Media.Ocr yolu InMemoryRandomAccessStream gerektirir — Windows dışarında başlatılamayan bir WinRT türü — ayrıca DataWriter, BitmapDecoder ve SoftwareBitmap gerektirir.IronOCR yolu OcrInput.LoadImage(byte[]) kullanır ve iki satırda sonucu üretir. akış girdi rehberine göz atın ve Stream tabanlı yükleme desenleri, bayt dizi girişi kadar basit bir şekilde takip eder.
OS Koordinasyonu Olmadan Çok Dilli Belge İşleme
Tek bir geçişte İngilizce, Fransızca ve Almanca metni tanıması gereken çok dilli bir fatura hattı, Windows.Media.Ocr ile mimari bir çıkmazla karşı karşıya kalır. API, bir motor örneği başına yalnızca bir dile izin verir. Karışık dilli bir belgeyi işlemek ya en iyi tahmin edilen tek dil motorunu ya da metin tanımayı üç kez çalıştırmayı ve sonuçları birleştirmeyi gerektirir — bunların hiçbiri güvenilir çıktı üretmez.
Windows.Media.Ocr Yaklaşımı:
// Windows.Media.Ocr: one language per engine, no simultaneous multi-language support
// Each language requires a separate language pack installed on the machine
public async Task<string> RecognizeMultiLanguageAsync(SoftwareBitmap bitmap)
{
// Must pick ONE language — no simultaneous recognition
var engine = OcrEngine.TryCreateFromLanguage(
new Windows.Globalization.Language("en-US"));
if (engine == null)
throw new InvalidOperationException("English language pack not installed.");
// French and German text on the same document will be misrecognized
var result = await engine.RecognizeAsync(bitmap);
return result.Text;
}
IronOCR Yaklaşımı:
// IronOCR: simultaneous multi-language recognition in a single pass
// Language packs are NuGet packages — no OS coordination required
// dotnet add package IronOcr.Languages.French
// dotnet add package IronOcr.Languages.German
public string RecognizeMultiLanguage(string documentPath)
{
var ocr = new IronTesseract();
ocr.Language = OcrLanguage.English + OcrLanguage.French + OcrLanguage.German;
var result = ocr.Read(documentPath);
// Structured output: walk paragraphs with location data
foreach (var page in result.Pages)
{
foreach (var paragraph in page.Paragraphs)
{
Console.WriteLine($"[{paragraph.X},{paragraph.Y}] {paragraph.Text}");
}
}
return result.Text;
}
IronOCR, dil modellerini tek bir tanıma geçişinde birleştirerek, belirli bir bölgenin hangi dili kullandığını tahmin etme gereksinimini ortadan kaldırır. Çok dilli OCR rehberi, dil paketi yüklemesini ve desteklenen 125+'in tümü için OcrLanguage enum değerlerini kapsar. dil endeksi, CJK yazıları, Arapça, İbranice, Devanagari ve Kiril ailelerini içeren tam kataloğu listeler.
Sunucu Tarafından OCR'i Etkinleştirme ve Paralel İşleme
Windows.Media.Ocr, Linux'te bir sunucu bağlamında çalışamaz, çapraz platformlu bir host üzerinde standart bir ASP.NET Core denetleyicisinden çağrılamaz, ve sunucu senaryolarında kullanıcı arayüzü olmayan iş parçacıklarından çağrıldığında tanımsız davranış sergiler. Sadece Windows'a özgü bir masaüstü uygulamasından ölçeklenebilir bir web API'ye bir OCR uç noktası taşıyan bir ekip, aynı anda üç kısıttan da etkilenir.
Windows.Media.Ocr Yaklaşımı:
// Windows.Media.Ocr: cannot run on Linux, Docker, or Azure Functions on Linux
// UWP/WinRT assumptions about thread context cause failures in ASP.NET pipelines
// The entire approach below is non-deployable outside Windows with Desktop Experience
[HttpPost("ocr")]
public async Task<IActionResult> RecognizeDocument(IFormFile file)
{
// WinRT requires STA thread context in some scenarios — not guaranteed in ASP.NET
// Cannot deploy this controller to a Linux App Service plan
using var stream = file.OpenReadStream();
// InMemoryRandomAccessStream is a WinRT type — does not exist on Linux
// var ras = new InMemoryRandomAccessStream(); // compile error on net8.0 TFM
return StatusCode(503, "Windows-only — cannot deploy cross-platform.");
}
IronOCR Yaklaşımı:
// IronOCR: ASP.NET Core controller running on Linux, Docker, or Windows — same code
[HttpPost("ocr")]
public async Task<IActionResult> RecognizeDocument(IFormFile file)
{
if (file == null || file.Length == 0)
return BadRequest("No file provided.");
using var memoryStream = new MemoryStream();
await file.CopyToAsync(memoryStream);
var imageBytes = memoryStream.ToArray();
using var input = new OcrInput();
input.LoadImage(imageBytes);
input.Deskew(); // straighten uploaded scans automatically
input.DeNoise(); // remove mobile camera noise
var result = new IronTesseract().Read(input);
return Ok(new
{
Text = result.Text,
Confidence = result.Confidence,
Pages = result.Pages.Count
});
}
Bu denetleyici, Linux App Service, Docker ve AWS Lambda'ya herhangi bir değişiklik yapılmadan dağıtılır. Docker dağıtım rehberi, Linux temel imajında gerekli olan tek apt-get bağımlılığı kapsar. Azure dağıtım kılavuzu ve AWS kılavuzu, buluta özgü yapılandırmayı açıklar.
Taralı Arşivlerden Aranabilir PDF'ler Oluşturma
Windows.Media.Ocr sıradan metin dizileri üretir. OcrResult.Text ve OcrResult.Lines içinde satır geometrisinin ötesinde herhangi bir çıktı formatı yoktur. Taralı bir arşivi aranabilir PDF'lere dönüştürmek — belge yönetim sistemleri ve uyum iş akışları için yaygın bir gereklilik — PDF çıktı katmanını oluşturmak için üçüncü bir kütüphane gerektirir. IronOCR, aranabilir PDF'leri yerel olarak üretir.
Windows.Media.Ocr Yaklaşımı:
// Windows.Media.Ocr: plain text output only
// Searchable PDF requires external PDF library + manual text layer construction
public async Task<string> GetTextOnlyAsync(SoftwareBitmap bitmap)
{
var engine = OcrEngine.TryCreateFromUserProfileLanguages();
if (engine == null)
throw new InvalidOperationException("No OCR language available.");
var result = await engine.RecognizeAsync(bitmap);
// result.Text is all you get
// Producing a searchable PDF requires an entirely separate library
return result.Text;
}
IronOCR Yaklaşımı:
// IronOCR: searchable PDF output is one method call on OcrResult
public void ProcessScannedArchive(IEnumerable<string> pdfPaths, string outputDirectory)
{
foreach (var sourcePdf in pdfPaths)
{
var ocr = new IronTesseract();
using var input = new OcrInput();
input.LoadPdf(sourcePdf); // native PDF input — no external renderer
input.Deskew(); // correct scan misalignment per page
input.DeNoise(); // remove scanner speckle
var result = ocr.Read(input);
var outputFileName = Path.Combine(
outputDirectory,
Path.GetFileNameWithoutExtension(sourcePdf) + "-searchable.pdf");
result.SaveAsSearchablePdf(outputFileName);
Console.WriteLine($"Processed: {sourcePdf} → {outputFileName} " +
$"({result.Pages.Count} pages, {result.Confidence:F1}% confidence)");
}
}
SaveAsSearchablePdf çağrısı, özgün taranmış görüntü üzerine bir metin katmanı yerleştirir, görsel sadakati korurken metin araması ve Ctrl+F'i herhangi bir PDF görüntüleyicide olanaklı kılar. aranabilir PDF nasıl yapılır kılavuzu, yazı tipi gömme, metin katmanı konumlandırma ve çok sayfalı çıktı için seçenekleri kapsar. PDF giriş kılavuzu, parolayla korunan PDF'ler ve büyük arşivler için sayfa aralığı seçimini kapsar.
Kelime-Düzeyi Koordinatlar ile Yapılandırılmış Veri Çıkarımı
Windows.Media.Ocr, satır düzeyinde metin ve sınırlayıcı dikdörtgenler ile OcrResult.Lines sunar. Kelime başına geometri OcrLine.Words'de OcrWord.BoundingRect ile mevcuttur, ancak paragraf, güven puanları ve karakter düzeyinde veri yoktur. Form alanı çıkarımı veya fatura satır öğesi ayrıştırması için satır geometrisi yetersizdir — yapılandırılmış alanları çevreleyen metinden ayırt etmek için paragraf sınırları ve kelime güven katsayıları gereklidir.
Windows.Media.Ocr Yaklaşımı:
// Windows.Media.Ocr: line-level geometry, no paragraph grouping, no confidence scores
public async Task<List<string>> ExtractLineTextAsync(SoftwareBitmap bitmap)
{
var engine = OcrEngine.TryCreateFromUserProfileLanguages();
if (engine == null)
throw new InvalidOperationException("No OCR language available.");
var result = await engine.RecognizeAsync(bitmap);
var lineTexts = new List<string>();
foreach (var line in result.Lines)
{
// Line text + word bounding rects — no paragraph grouping, no confidence
lineTexts.Add(line.Text);
}
return lineTexts;
}
IronOCR Yaklaşımı:
// IronOCR: full hierarchy — pages, paragraphs, lines, words, characters
// Each element carries coordinates and confidence for downstream validation
public void ExtractStructuredData(string documentPath)
{
var result = new IronTesseract().Read(documentPath);
Console.WriteLine($"Overall confidence: {result.Confidence:F1}%");
foreach (var page in result.Pages)
{
Console.WriteLine($"\n--- Page {page.PageNumber} ---");
foreach (var paragraph in page.Paragraphs)
{
Console.WriteLine($"Paragraph at ({paragraph.X},{paragraph.Y}): {paragraph.Text}");
// Filter words below confidence threshold for validation workflows
var lowConfidence = paragraph.Words
.Where(w => w.Confidence < 70)
.ToList();
if (lowConfidence.Any())
{
Console.WriteLine($" Low-confidence words: " +
string.Join(", ", lowConfidence.Select(w => $"'{w.Text}' ({w.Confidence:F0}%)")));
}
}
}
}
Yapılandırılmış sonuç modeli — Pages, Paragraphs, Lines, Words, Characters — form alanı çıkarımı, fatura ayrıştırması ve belge yerleşim analizine ihtiyaç duyulan koordinat ve güven verilerini sağlar. sonuçları oku rehberi tam OcrResult nesne grafiğini belgeler. güven skoru kılavuzu, belirsiz çıkarımları insan incelemesi için işaretlemek adına kelime başına güven değerlerinin nasıl kullanılacağını açıklar.
Windows.Media.Ocr API'den IronOCR Eşleştirme Referansı
| Windows.Media.Ocr | IronOCR |
|---|---|
OcrEngine.TryCreateFromLanguage(lang) | new IronTesseract() + ocr.Language = OcrLanguage.X |
OcrEngine.TryCreateFromUserProfileLanguages() | new IronTesseract() (İngilizce varsayılan; geri dönüş değeri yok) |
engine.RecognizeAsync(softwareBitmap) | ocr.Read("image.jpg") veya ocr.Read(ocrInput) |
StorageFile.GetFileFromPathAsync(path) | ocr.Read("path") doğrudan (dosya tutamacı gerekmez) |
file.OpenAsync(FileAccessMode.Read) | Kaldırıldı — OcrInput doğrudan yükler |
BitmapDecoder.CreateAsync(stream) | input.LoadImage(stream) aracılığıyla OcrInput |
decoder.GetSoftwareBitmapAsync() | Kaldırıldı — IronOCR'da SoftwareBitmap yok |
SoftwareBitmap (WinRT türü) | Kaldırıldı — OcrInput baytları, akışları ve dosya yollarını kabul eder |
InMemoryRandomAccessStream (WinRT türü) | new MemoryStream() + input.LoadImage(stream) |
OcrResult.Text | OcrResult.Text |
OcrResult.Lines | OcrResult.Lines (ayrıca Pages, Paragraphs, Words, Characters) |
OcrLine.Text | OcrResult.Lines[i].Text |
OcrLine.Words | OcrResult.Words veya page.Paragraphs[i].Words |
OcrWord.BoundingRect | word.X, word.Y, word.Width, word.Height |
| Eşdeğeri yok | result.Confidence (genel) / word.Confidence (kelime başına) |
| Eşdeğeri yok | result.SaveAsSearchablePdf("output.pdf") |
| Eşdeğeri yok | input.LoadPdf("document.pdf") |
| Eşdeğeri yok | input.Deskew(), input.DeNoise(), input.Contrast() |
| Eşdeğeri yok | ocr.Language = OcrLanguage.A + OcrLanguage.B (eşzamanlı) |
| Eşdeğeri yok | ocr.Configuration.ReadBarCodes = true |
| Eşdeğeri yok | input.LoadImage(byteArray) |
Yaygın Göç Sorunları ve Çözümleri
Sorun 1: Proje Dosyası, Geçiş Sonrası Hala Windows TFM Gerektiriyor
Windows.Media.Ocr: WinRT türlerinin çözülmesi için <TargetFramework>net8.0-windows10.0.19041.0</TargetFramework> bildirimi gereklidir. Windows.Media.Ocr referanslarını aynı projedeki diğer WinRT bağımlılıklarını kontrol etmeden kaldırmak, TFM'yi yerinde bırakabilir ve çapraz platform derlemelerini engelleyebilir.
Çözüm: Windows OCR alan adı referanslarını kaldırdıktan sonra, TFM'yi değiştirmeden önce projeyi kalan WinRT API kullanımlarını arayarak tarayın:
# Find remaining WinRT API usage before removing the Windows TFM
grep -r "Windows\." --include="*.cs" .
grep -r "WinRT\|IAsyncOperation\|StorageFile\|SoftwareBitmap" --include="*.cs" .
Eğer kalan WinRT referansları yoksa, proje dosyasını güncelleyin:
<!-- Before -->
<TargetFramework>net8.0-windows10.0.19041.0</TargetFramework>
<!-- After -->
<TargetFramework>net8.0</TargetFramework>
Diğer WinRT özellikleri (Windows bildirimleri, kabuk entegrasyonu, XAML) hala kullanımdaysa, TFM'yi projeden tamamen kaldırmak yerine bir arayüze arkasına OCR çağrısını soyutlayın ve platforma özgü uygulamalar sağlayın.
Sorun 2: Boş Motor Kontrolleri için IronOCR Eşdeğeri Yok
Windows.Media.Ocr: TryCreateFromLanguage ve TryCreateFromUserProfileLanguages her çağrısı null döndürebilir. Tüm mevcut kod, bir null motoru üzerinde dal veya fırlatma yapacak null kontrol koruma ifadeleri içerir.
Çözüm: IronOCR, başlatma hataları üzerinde null yerine yapılandırılmış istisnalar atar. Null kontrolü koruma ifadelerini kaldırın. Başlatma hatalarını bir arayan kullanıcısına iletmeniz gerekiyorsa, standart bir try/catch içerisine alın:
// Before: null-check pattern
var engine = OcrEngine.TryCreateFromUserProfileLanguages();
if (engine == null)
throw new InvalidOperationException("OCR unavailable.");
// After: no null — IronTesseract throws if misconfigured
try
{
var result = new IronTesseract().Read("document.jpg");
}
catch (IronOcr.Exceptions.OcrException ex)
{
// structured exception with diagnostic message
logger.LogError("OCR failed: {Message}", ex.Message);
}
Sorun 3: Mevcut Yöntem İmzağlarında SoftwareBitmap Parametreleri
Windows.Media.Ocr: Yardımcı yöntemler, hizmetler ve depo sınıfları SoftwareBitmap parametre türü olarak kabul edebilir. Windows TFM kaldırıldığında bu yöntem imzaları derlenemez.
Çözüm: SoftwareBitmap parametrelerini byte[] veya Stream ile değiştirin. IronOCR'un OcrInput her ikisini de doğrudan kabul eder. Daha önce bir SoftwareBitmap oluşturan çağrı siteleri, altında yatan verilerini iletebilir:
// Before: SoftwareBitmap parameter — cannot compile cross-platform
public async Task<string> RecognizeAsync(SoftwareBitmap bitmap) { ... }
// After: byte array parameter — compiles on all platforms
public string Recognize(byte[] imageBytes)
{
using var input = new OcrInput();
input.LoadImage(imageBytes);
return new IronTesseract().Read(input).Text;
}
Sorun 4: Yalnızca Async Olan Arayanlar, Syncron IronOCR'u Doğrudan Kullanamaz
Windows.Media.Ocr: Her tanıma çağrısı async Kod tabanı boyunca çağrı yapanlar await kullanır ve Task<string> döndürür. Bir Read yönteminin içinde IronOCR'un senkron Read yöntemine geçmek işe yarar, ancak async nın yapısal olduğu bağlamlarda engelleyici çağrılar getirebilir.
Çözüm: IronOCR, buna ihtiyaç duyan arayanlar için bir async yolu sağlar. Mevcut asenkron yöntemlerde CPU-bağlantılı sarmalamalar için Task.Run kullanın veya yerel asenkron API'yi kullanın:
// Option A: wrap synchronous call in Task.Run for async callers
public async Task<string> RecognizeAsync(string imagePath)
{
return await Task.Run(() => new IronTesseract().Read(imagePath).Text);
}
// Option B:IronOCR async path
// See: https://ironsoftware.com/csharp/ocr/how-to/async/
async OCR kılavuzu, tek başına bırakma veya ilerleme raporlama kalıplarının gerektiği bağlamlarda kullanıma hazır async API'yi belgeler.
Sorun 5: Windows Dil Etiketi Formatı Doğrudan Eşleşmez
Windows.Media.Ocr: Diller, Windows.Globalization.Language("fr-FR")'ya iletilen BCP-47 dizi etiketleri kullanılarak belirtilir. Bu dize etiketlerinin IronOCR'da doğrudan bir karşılığı yoktur.
Çözüm: BCP-47 dil etiketlerini OcrLanguage enum'a eşleyin. Yaygın diller için eşleme basittir:
// Before: BCP-47 string tags
var engine = OcrEngine.TryCreateFromLanguage(
new Windows.Globalization.Language("fr-FR"));
// After: OcrLanguage enum
var ocr = new IronTesseract();
ocr.Language = OcrLanguage.French;
// Also: OcrLanguage.German, OcrLanguage.Japanese, OcrLanguage.Arabic, etc.
IronOCR dil kataloğunda tam eşleme mevcuttur. Ana enumda listelenmeyen diller için özel dil paketi desteği,.traineddata dosyalarını doğrudan yüklemeyi kapsar.
Sorun 6: FileAccessMode.Read İçin İkame Yok
Windows.Media.Ocr: file.OpenAsync(FileAccessMode.Read), WinRT'ye özel bir dosya açma desenidir. FileAccessMode enum, standart .NET'te mevcut değildir.
Çözüm: Standart System.IO.File.ReadAllBytes veya FileStream ile değiştirin. OcrInput her ikisini de kabul eder:
// Before: WinRT file access
using var stream = await file.OpenAsync(FileAccessMode.Read);
// After: standard .NET
var imageBytes = File.ReadAllBytes(imagePath);
using var input = new OcrInput();
input.LoadImage(imageBytes);
Windows.Media.Ocr (UWP/WinRT OCR) Geçiş Kontrol Listesi
Öncesi-Geçiş
Değişiklik yapmadan önce kod tabanını denetleyin:
# Find all Windows OCR namespace usages
grep -rn "using Windows.Media.Ocr" --include="*.cs" .
grep -rn "using Windows.Graphics.Imaging" --include="*.cs" .
grep -rn "using Windows.Storage" --include="*.cs" .
grep -rn "using Windows.Globalization" --include="*.cs" .
# Find WinRT type usages
grep -rn "OcrEngine\|SoftwareBitmap\|BitmapDecoder\|StorageFile" --include="*.cs" .
grep -rn "TryCreateFromLanguage\|TryCreateFromUserProfileLanguages\|RecognizeAsync" --include="*.cs" .
grep -rn "InMemoryRandomAccessStream\|DataWriter\|FileAccessMode" --include="*.cs" .
# Find project files with Windows TFM
grep -rn "net.*-windows" --include="*.csproj" .
# Count files requiring changes
grep -rl "Windows.Media.Ocr\|Windows.Graphics.Imaging\|SoftwareBitmap" --include="*.cs" . | wc -l
Etkilenen dosya sayısını, kullanılan dil etiketlerini ("en-US", "fr-FR", vb.) ve herhangi bir WinRT türünün genel metod imzalarında bulunup bulunmadığını kaydedin (bunlar, iç yeniden yazmaların yanı sıra ek API yüzey değişiklikleri gerektirir).
Kod Geçişi
IronOcrNuGet paketini yükleyin:dotnet add package IronOcrProgram.csveyaStartup.cs'de lisans başlatma çağrısını ekleyin:IronOcr.License.LicenseKey = "YOUR-LICENSE-KEY";- Tüm kaynak dosyalardan
using Windows.Media.Ocr;'ı kaldırın - Tüm kaynak dosyalardan
using Windows.Graphics.Imaging;'i kaldırın - Tüm kaynak dosyalardan
using Windows.Storage;'i kaldırın - Tüm kaynak dosyalardan
using Windows.Globalization;'i kaldırın - OCR gerçekleştiren tüm dosyalara
using IronOcr;ekleyin - Her
OcrEngine.TryCreateFromLanguage(new Language("xx-XX"))çağrısınınew IronTesseract()ile değiştirin veocr.Language = OcrLanguage.Xayarlayın - Her
OcrEngine.TryCreateFromUserProfileLanguages()çağrısınınew IronTesseract()ile değiştirin - Motor oluşturma sonuçlarında tüm null kontrol koruyucu ifadeleri kaldırın
- Yöntem imzalarındaki
SoftwareBitmapparametrelerinibyte[]veyaStreamile değiştirin StorageFile+BitmapDecoder+SoftwareBitmapinşa zincirleriniOcrInput.LoadImage(path),OcrInput.LoadImage(bytes)veyaOcrInput.LoadImage(stream)ile değiştirinengine.RecognizeAsync(bitmap)'iocr.Read(path)veyaocr.Read(input)ile değiştirinInMemoryRandomAccessStreamveDataWriterkullanımınıMemoryStreamile değiştirin- Windows BCP-47 dil etiketi dizelerini
OcrLanguageenum değerleriyle değiştirin; gereken dil NuGet paketlerini yükleyin .csprojdosyalarındaki<TargetFramework>güncelleyin ve başka WinRT API'leri kalmadığında-windowsX.Y.Zekini kaldırın
Geçiş Sonrası
- Projenin
net8.0(veya hedef sürümünüz) hedefleyerek, Windows TFM ekini olmaksızın derlendiğini doğrulayın - Projenin bir Linux ortamında veya Docker kabında
mcr.microsoft.com/dotnet/aspnet:8.0kullanılarak çalıştığı ve derlendiğini doğrulayın - OCR çıktı metninin, test suitindeki her belge türü için beklenen sonuçlarla eşleştiğini doğrulayın
- Daha önce desteklenen tüm dillerin doğru sonuçlar ürettiğini,IronOCR dil NuGet paketlerini kullanarak doğrulayın
- Tek bir tanıma geçişinde doğru sonuçlar üreten çok dilli belgeleri doğrulayın
- Windows dil paketleri yüklenmemiş makinelerde motor başlatma sırasında
NullReferenceExceptionveyaInvalidOperationExceptionoluşmadığını doğrulayın result.Confidencedeğerlerinin temiz ve düşük kaliteli girdi belgeleri için beklenen aralıklarda olduğunu doğrulayın- Uygulama belgeleri üretiyorsa,
SaveAsSearchablePdfçıktısının bir PDF görüntüleyicide doğru şekilde açıldığını ve metin aramasını desteklediğini doğrulayın - Mevcut paralel veya çok iş parçacıklı işleme yollarını çalıştırın ve yük altında iş parçacığı güvenliğini doğrulayın
- Hedef ortamı (Docker, Azure App Service, AWS, Linux sunucusu) dağıtın ve en az bir uçtan uca OCR işlemi gerçekleştirin
IronOCR'a Geçişin Ana Faydaları
Platformlar Arası Dağıtım Bir Kod Yeniden Yazmadan Çok Konfigürasyon Kararı Haline Gelir. Geçişten sonra, OCR bileşeni Windows, Linux, macOS, Docker ve her büyük bulut sağlayıcısında aynı şekilde çalışır. Bir OCR iş yükünü bir Windows VM'den bir Linux konteynerine, barındırma maliyetini azaltmak amacıyla taşımak bir dağıtım işlemidir. Linux dağıtım kılavuzu ve Docker dağıtım kılavuzu, Linux temel görüntülere gerekli olan tek satır bağımlılık eklemesini kapsar.
Dil Desteği Uygulama İkili Dosyası ile Taşınır. Dil paketleri NuGet paketleri olarak yüklenir ve IronOCR paketi ile birlikte sabit sürüm ile gelir. Uygulamanızın hangi dilleri tanıyabileceği, proje dosyasında tanımlıdır ve her makinede aynıdır — geliştirici çalışma istasyonu, CI çalıştırıcı, sahne sunucusu ve üretim ortamı. OS yönetici koordinasyonu yok, Grup Politikası istisnası yok, çalışma zamanında null kontrol yok.
OCR Doğruluğu Dış Araçlar Olmadan Gelişir. Ön işleme hattı — Deskew, DeNoise, Contrast, Binarize, Sharpen, Scale —IronOCR içinde tanıma motoru resmi görmeden önce çalışır. Windows.Media.Ocr ile tarama kayması veya gürültü nedeniyle kötü sonuçlar üreten belgeler, harici görüntü işleme bağımlılıkları eklemeden iyileşir. görüntü kalite düzeltme kılavuzu ve filtre sihirbazı, her belge türü için doğru filtre kombinasyonunu belirlemenize yardımcı olur.
PDF İş Akışları Tek Bir Kütüphaneye Konsolide Edildi. Windows.Media.Ocr ve PDF girişi arasında köprü kurmak için gereken harici PDF renderleyicisi artık gerekmiyor. Taranmış PDF arşivler, görüntülerle aynı IronTesseract.Read çağrısından geçer. Aranabilir PDF çıktısı, sonuç nesnesinde bir yöntemdir. İki kütüphane mimarisi, versiyon yönetimi, lisans yükü ve dağıtım yüzeyi ile birlikte ortadan kalkıyor.
Yapılandırılmış Çıktı, Belge Zekası Boru Hatlarına İmkan Sağlar. OcrResult hiyerarşisi — Pages, Paragraphs, Lines, Words, Characters — eleman başına koordinatlar ve güven puanları ile fatura alanı çıkarımı, form ayrıştırması ve belge sınıflandırması için gereken veriyi sağlar. Windows.Media.Ocr'ın satır düzeyinde çıktısı, bu iş akışları için yetersizdir.IronOCR ile, güvenlikle filtrelenmiş kelime çıkarımı, paragraf sınır tespiti ve koordinat tabanlı alan haritalama, ek kütüphaneler olmadan birinci sınıf özelliklerdir.
Süresiz Lisanslama Sınırsız Bir Altyapı Bağımlılığını Değiştirir. Heterojen bir filo üzerinde Windows dil paketi kurulumunun maliyeti, Windows Sunucu Masaüstü Deneyimi lisanslaması ve yalnızca Windows'a özgü CI altyapısı gerçektir fakat dağınık — bu, IT biletleri ve altyapı bütçelerinde yer alır, OCR bütçesinde bir satır kalemi olarak değil. Tek geliştirici projeleri için bir $999IronOCR Lite lisansı, bu yükü ortadan kaldırır. $1.499 Professional lisans, on geliştiriciyi kapsar. Her ikisi de tek seferlik satın alımlar olup, bir yıllık güncellemeleri içerir.

Curtis Chau, Bilgisayar Bilimleri alanında Lisans Derecesine (Carleton Üniversitesi) sahip ve Node.js, TypeScript, JavaScript ve React konularında uzmanlaşmış ön uç geliştirmeyle ilgileniyor. Sezgisel ve estetik açıdan hoş kullanıcı arayüzleri oluşturma tutkunu, Curtis modern çerçevelerle çalışmayı ve iyi yapılandırılmış, görsel olarak çekici kılavuzlar oluşturmayı seviyor.