IRONSOFTWAREHOME
VÍDEOS

Migrando do Windows.Media.Ocr para o IronOCR

Kannaopat Udonpant
Kannapat Udonpant
Updated: 1 de agosto de 2026

Este guia fornece um caminho de migração passo a passo para desenvolvedores .NET que estão migrando do Windows.Media.Ocr para o IronOCR . Este documento aborda a remoção de namespaces, alterações em arquivos de projeto, exemplos de migração de código para os padrões que surgem com mais frequência durante a migração e uma lista de verificação prática para validar a transição concluída.

Por que migrar do Windows.Media.Ocr (OCR UWP/WinRT)?

O Windows.Media.Ocr funciona bem dentro de suas limitações. Esses limites são estreitos, e os projetos rotineiramente os ultrapassam. Os motivos pelos quais as equipes migram se enquadram em categorias previsíveis.

O Windows TFM bloqueia todos os alvos que não são Windows. O arquivo do projeto deve declarar um net*-windows* Moniker de Framework de Destino antes que o namespace Windows.Media.Ocr se resolva em tempo de compilação. Essa declaração não é uma bandeira de tempo de execução — é uma restrição de construção que se propaga para todos os projetos que referenciam o seu. Uma biblioteca de serviços OCR compartilhada, uma API web, um processo em segundo plano implantado no Linux — todos eles herdam a restrição. Remover significa remover o Windows.Media.Ocr.

A disponibilidade de idioma é determinada em tempo de execução pelo sistema operacional, não em tempo de compilação pelo desenvolvedor. OcrEngine.TryCreateFromLanguage retorna nulo quando o pacote de idioma solicitado está ausente da máquina host. O desenvolvedor não pode instalar um pacote de idioma a partir do código, incluir um com o binário da aplicação ou fornecer um modelo de fallback. Em ambientes automatizados — agentes de compilação, executores de CI, VMs mínimas na nuvem, contêineres — os pacotes de idiomas raramente são instalados. Falhas de produção causadas pela falta de um pacote de idiomas não são reproduzíveis analisando o código; Eles exigem a inspeção da configuração do sistema operacional da máquina de destino.

Sem pré-processamento significa que não há caminho de recuperação para entrada subótima. A API aceita um SoftwareBitmap e produz texto. A melhoria da qualidade da imagem entre esses dois pontos é de inteira responsabilidade do desenvolvedor, utilizando APIs separadas do componente de imagem do Windows, que são exclusivas do Windows. Fotografias tiradas com celular, digitalizações desalinhadas em scanners de mesa e documentos fotocopiados comprometem a precisão silenciosamente, sem nenhum mecanismo integrado para diagnosticar ou melhorar o resultado.

O PDF é o formato de documento mais comum em fluxos de trabalho Enterprise . O Windows.Media.Ocr não possui um caminho de entrada para PDF. O processamento de um PDF digitalizado requer um renderizador externo, rasterização página por página e montagem manual do resultado. Esse renderizador adiciona uma dependência, considerações de licenciamento e uma superfície de falha separada — exatamente a complexidade que uma biblioteca "gratuita e integrada" deveria evitar.

A implantação no servidor não é estruturalmente suportada. O Windows.Media.Ocr destina-se a aplicações cliente. Executá-lo no Windows Server requer o pacote de recursos Experiência de Área de Trabalho, o que aumenta o custo da máquina virtual e a complexidade da infraestrutura. A implantação do Docker é impossível. O Azure Functions no Linux, o AWS Lambda e qualquer carga de trabalho em contêineres baseada em Linux simplesmente não podem referenciar a API.

A pilha assíncrona do WinRT é incompatível com os padrões do .NET padrão. Seis ou mais chamadas encadeadas de awaitStorageFile, stream, BitmapDecoder, SoftwareBitmap, verificação de nulo, RecognizeAsync — são necessárias antes que um único caractere seja lido. Integrar essa cadeia em um serviço em segundo plano, um loop Parallel.ForEach ou um controlador ASP.NET padrão é complicado. A maquinaria do WinRT IAsyncOperation fica por baixo, e a interação com o modelo Task do .NET cria casos extremos sutis em contextos não-UI.

O problema fundamental

A disponibilidade de idiomas no Windows.Media.Ocr é uma incógnita em tempo de execução que não pode ser resolvida no momento da implantação:

// 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.");
// Não recovery path. Não bundled model. Não fallback.
C#
// 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);
C#

##IronOCR vs Windows.Media.Ocr (OCR para UWP/WinRT): Comparação de Recursos

A tabela abaixo abrange toda a superfície de capacidade relevante para as decisões de migração.

RecursoWindows.Media.OcrIronOCR
Plataforma: Windows 10/11SimSim
Plataforma: Windows ServerVagas limitadas (necessária experiência com computadores).Sim
Plataforma: LinuxNãoSim
Plataforma: macOSNãoSim
Plataforma: contêineres DockerNãoSim
Plataforma: Azure Functions (Linux)NãoSim
Plataforma: AWS LambdaNãoSim
Requisito do projeto TFMnet*-windows* necessárioNenhum (TFMs padrão)
InstalaçãoIntegrado ao Windows (sem NuGet)Pacote único do NuGet (IronOcr)
Entrada de imagem (JPG, PNG, BMP)Sim (via pipeline WinRT)Sim
Entrada de PDFNãoSim (nativo)
Entrada TIFF de várias páginasNãoSim
Entrada de fluxo e matriz de bytesNão (somente StorageFile)Sim
Fonte linguísticaPacotes de idiomas instalados pelo sistema operacionalMais de 125 pacotes NuGet incluídos
Portabilidade linguísticaNão (dependente da máquina)Sim (implantar com o aplicativo)
Simultaneidade multilíngueNãoSim
Pré-processamento: correção de inclinaçãoNãoSim (input.Deskew())
Pré-processamento: redução de ruídoNãoSim (input.DeNoise())
Pré-processamento: contrasteNãoSim (input.Contrast())
Pré-processamento: binarizarNãoSim (input.Binarize())
Saída em PDF pesquisávelNãoSim (result.SaveAsSearchablePdf())
Pontuações de confiança por palavraNãoSim (word.Confidence)
Saída estruturada (parágrafos, linhas, palavras)Somente linhasPáginas, Parágrafos, Linhas, Palavras, Caracteres
Leitura de código de barras durante OCRNãoSim
OCR baseado em regiãoNãoSim (CropRectangle)
Caminho OCR síncronoNãoSim
Processamento paralelo seguro para threadsLimitadoCompleto
Apoio comercialNão (equipe da plataforma Windows)Sim
Modelo de licenciamentoGratuito (integrado ao Windows)Perpetual ($999 Lite, $1,499 Pro, $2,999 Enterprise)

Guia rápido: Migração do Windows.Media.Ocr (OCR UWP/WinRT) para o IronOCR

Passo 1: Substitua o pacote NuGet

O pacote Windows.Media.Ocr não possui um pacote NuGet — ele faz parte do Windows Runtime e é resolvido através do TFM do Windows. Remover isso significa remover as referências de namespace específicas do Windows e, quando possível, o TFM do Windows do arquivo de projeto.

Remova os namespaces Windows.Media.Ocr de todos os arquivos de origem:

# Audit all files referencing Windows OCR namespaces
grep -r "Windows.Media.Ocr\|Windows.Graphics.Imaging\|Windows.Storage" --include="*.cs" .
SHELL

Instale o IronOCR:

dotnet add package IronOcr

O pacote IronOCR do NuGet tem como alvo net6.0, net7.0, net8.0 e net9.0 sem TFMs específicos de plataforma. Após remover os namespaces de OCR do Windows, atualize o <TargetFramework> no arquivo do projeto de net8.0-windows10.0.19041.0 para net8.0 (ou a versão apropriada), desde que nenhuma outra API WinRT permaneça no projeto.

Etapa 2: Atualizar Namespaces

Substitua os três namespaces do OCR do Windows por um único namespace do IronOCR:

// Before (Windows.Media.Ocr)
using Windows.Media.Ocr;
using Windows.Graphics.Imaging;
using Windows.Storage;
using Windows.Globalization;

// After (IronOCR)
using IronOcr;
C#

Etapa 3: Inicializar a licença

Adicione a chamada de inicialização da licença uma vez no início do aplicativo — em Program.cs, Startup.cs, ou no construtor de host da aplicação:

IronOcr.License.LicenseKey = "YOUR-LICENSE-KEY";

Uma chave de avaliação gratuita está disponível na página de licenciamento do IronOCR e remove a marca d'água de avaliação para fins de teste.

Exemplos de migração de código

Substituindo a cadeia assíncrona WinRT em um serviço em segundo plano

O Windows.Media.Ocr requer um mínimo de seis operações assíncronas encadeadas antes que o reconhecimento comece. Em um serviço em segundo plano que processa uma fila de documentos, essa cadeia funciona dentro de um loop — e a disposição de SoftwareBitmap, a verificação de nulo e a interop de IAsyncOperation do WinRT adicionam atrito em cada iteração.

Abordagem do Windows.Media.Ocr:

// 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;
}
C#

Abordagem IronOCR:

// 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;
}
C#

A versão do IronOCR elimina a ida-e-volta de StorageFile, o BitmapDecoder, o ciclo de vida de SoftwareBitmap e a proteção de verificação de nulo. Para serviços nativos assíncronos, o IronOCR fornece um caminho assíncrono que se integra de forma limpa em pipelines baseados em Task, sem a sobrecarga de interop do WinRT. O guia de configuração do IronTesseract aborda recomendações sobre o ciclo de vida da instância para cenários de filas de alto rendimento.

Eliminação da conversão de bitmap por software para dados de imagem na memória

Aplicações que já têm dados de imagem na memória — de um download de rede, um blob de banco de dados ou um callback de captura de câmera — devem converter esses dados em um SoftwareBitmap antes que Windows.Media.Ocr possa processá-los. Esse caminho de conversão passa por BitmapDecoder, que requer um stream, o que significa copiar o array de bytes para um MemoryStream. O IronOCR aceita diretamente matrizes de bytes e fluxos de dados.

Abordagem do Windows.Media.Ocr:

// 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;
}
C#

Abordagem IronOCR:

// 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;
}
C#

O caminho Windows.Media.Ocr requer InMemoryRandomAccessStream — um tipo WinRT que não pode ser instanciado fora do Windows — além de DataWriter, BitmapDecoder e SoftwareBitmap. O caminho do IronOCR usa OcrInput.LoadImage(byte[]) e produz o resultado em duas linhas. Consulte o guia de entrada de streams para padrões de carregamento baseados em Stream, que seguem a mesma simplicidade da entrada de array de bytes.

Processamento de documentos multilíngues sem coordenação do sistema operacional

Um fluxo de faturamento multilíngue que precisa reconhecer textos em inglês, francês e alemão em uma única passagem enfrenta um impasse arquitetônico com o Windows.Media.Ocr. A API permite apenas um idioma por instância do mecanismo. O processamento de um documento com idiomas mistos exige um mecanismo de reconhecimento de idioma único que utilize a melhor estimativa possível ou a execução do reconhecimento três vezes e a fusão dos resultados — nenhuma das quais produz uma saída confiável.

Abordagem do Windows.Media.Ocr:

// 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;
}
C#

Abordagem IronOCR:

// 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;
}
C#

O IronOCR combina modelos de linguagem em uma única etapa de reconhecimento, eliminando a necessidade de adivinhar qual idioma uma determinada região utiliza. O guia de OCR multilíngue aborda a instalação de pacotes de idiomas e os valores de enum OcrLanguage para todos os 125+ idiomas suportados. O índice de idiomas lista o catálogo completo, incluindo os alfabetos CJK, árabe, hebraico, devanágari e cirílico.

Habilitando OCR no servidor com processamento paralelo

O Windows.Media.Ocr não pode ser executado em um contexto de servidor no Linux, não pode ser chamado de um controlador ASP.NET Core padrão em um host multiplataforma e tem comportamento indefinido quando chamado de threads que não são da interface do usuário em cenários de servidor. Uma equipe que migra um endpoint de OCR de um aplicativo desktop exclusivo para Windows para uma API web escalável se depara com todas as três restrições simultaneamente.

Abordagem do Windows.Media.Ocr:

// 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.");
}
C#

Abordagem IronOCR:

// 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
    });
}
C#

Este controlador pode ser implementado no Linux App Service, Docker e AWS Lambda sem necessidade de modificações. O guia de implantação do Docker cobre a única dependência apt-get necessária na imagem base do Linux. O guia de implantação do Azure e o guia da AWS explicam detalhadamente a configuração específica de cada nuvem.

Geração de PDFs pesquisáveis ​​a partir de arquivos digitalizados

O Windows.Media.Ocr produz cadeias de texto simples. Não tem formato de saída além de OcrResult.Text e a geometria da linha em OcrResult.Lines. Converter um arquivo digitalizado em PDFs pesquisáveis ​​— um requisito comum para sistemas de gerenciamento de documentos e fluxos de trabalho de conformidade — requer uma biblioteca de terceiros para construir a camada de saída do PDF. O IronOCR gera PDFs pesquisáveis ​​nativamente.

Abordagem do Windows.Media.Ocr:

// 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;
}
C#

Abordagem IronOCR:

// 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)");
    }
}
C#

A chamada SaveAsSearchablePdf incorpora uma camada de texto sobre a imagem escaneada original, preservando a fidelidade visual enquanto permite busca de texto completo e Ctrl+F em qualquer visualizador de PDF. O guia prático em PDF, com função de busca, aborda opções para incorporação de fontes, posicionamento de camadas de texto e saída em várias páginas. O guia de entrada de PDF aborda PDFs protegidos por senha e a seleção de intervalo de páginas para arquivos grandes.

Extração de dados estruturados com coordenadas em nível de palavra

Windows.Media.Ocr expõe OcrResult.Lines com texto em nível de linha e retângulos delimitadores. A geometria por palavra existe em OcrLine.Words com OcrWord.BoundingRect, mas não existem parágrafos, pontuações de confiança ou dados em nível de caractere. Para extração de campos de formulário ou análise de itens de fatura, a geometria da linha é insuficiente — são necessários limites de parágrafo e índices de confiança de palavras para distinguir campos estruturados do texto circundante.

Abordagem do Windows.Media.Ocr:

// 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;
}
C#

Abordagem IronOCR:

// 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}%)")));
            }
        }
    }
}
C#

O modelo de resultado estruturado — Pages, Paragraphs, Lines, Words, Characters — fornece os dados de coordenada e confiança necessários para extração de campos de formulário, análise de faturas e análise de layout de documentos. O guia de leitura de resultados documenta todo o gráfico de objetos OcrResult. O guia de pontuação de confiança explica como usar os valores de confiança por palavra para sinalizar extrações incertas para revisão humana.

Referência de mapeamento da API Windows.Media.Ocr para IronOCR

Windows.Media.OcrIronOCR
OcrEngine.TryCreateFromLanguage(lang)new IronTesseract() + ocr.Language = OcrLanguage.X
OcrEngine.TryCreateFromUserProfileLanguages()new IronTesseract() (padrão em inglês; (sem retorno nulo)
engine.RecognizeAsync(softwareBitmap)ocr.Read("image.jpg") ou ocr.Read(ocrInput)
StorageFile.GetFileFromPathAsync(path)ocr.Read("path") diretamente (nenhum handle de arquivo necessário)
file.OpenAsync(FileAccessMode.Read)Eliminado — OcrInput carrega diretamente
BitmapDecoder.CreateAsync(stream)input.LoadImage(stream) via OcrInput
decoder.GetSoftwareBitmapAsync()Eliminado — não há SoftwareBitmap no IronOCR
SoftwareBitmap (tipo WinRT)Eliminado — OcrInput aceita bytes, streams, caminhos de arquivos
InMemoryRandomAccessStream (tipo WinRT)new MemoryStream() + input.LoadImage(stream)
OcrResult.TextOcrResult.Text
OcrResult.LinesOcrResult.Lines (também Pages, Paragraphs, Words, Characters)
OcrLine.TextOcrResult.Lines[i].Text
OcrLine.WordsOcrResult.Words ou page.Paragraphs[i].Words
OcrWord.BoundingRectword.X, word.Y, word.Width, word.Height
Não existe equivalenteresult.Confidence (geral) / word.Confidence (por palavra)
Não existe equivalenteresult.SaveAsSearchablePdf("output.pdf")
Não existe equivalenteinput.LoadPdf("document.pdf")
Não existe equivalenteinput.Deskew(), input.DeNoise(), input.Contrast()
Não existe equivalenteocr.Language = OcrLanguage.A + OcrLanguage.B (simultâneo)
Não existe equivalenteocr.Configuration.ReadBarCodes = true
Não existe equivalenteinput.LoadImage(byteArray)

Problemas e soluções comuns em migrações

Problema 1: O arquivo de projeto ainda requer o Windows TFM após a migração.

Windows.Media.Ocr: A declaração <TargetFramework>net8.0-windows10.0.19041.0</TargetFramework> é necessária para que os tipos do WinRT sejam resolvidos. Remover as referências a Windows.Media.Ocr sem verificar outras dependências do WinRT no mesmo projeto pode deixar o TFM (Trusted File Manager) no lugar, impedindo compilações multiplataforma.

Solução: Após remover as referências ao namespace do OCR do Windows, verifique se o projeto ainda utiliza a API WinRT antes de alterar o TFM:

# Find remaining WinRT API usage before removing the Windows TFM
grep -r "Windows\." --include="*.cs" .
grep -r "WinRT\|IAsyncOperation\|StorageFile\|SoftwareBitmap" --include="*.cs" .
SHELL

Se não houver mais referências ao WinRT, atualize o arquivo de projeto:

<!-- Before -->
<TargetFramework>net8.0-windows10.0.19041.0</TargetFramework>

<!-- After -->
<TargetFramework>net8.0</TargetFramework>
XML

Caso outros recursos do WinRT (notificações do Windows, integração com o shell, XAML) continuem em uso, abstraia a chamada de OCR por trás de uma interface e forneça implementações específicas para cada plataforma, em vez de remover o TFM de todo o projeto.

Problema 2: Verificações de mecanismo nulo não têm equivalente no IronOCR

Windows.Media.Ocr: Toda chamada para TryCreateFromLanguage e TryCreateFromUserProfileLanguages pode retornar nulo. Todo o código existente contém cláusulas de verificação de nulo que lançam exceções ou desviam o comportamento em caso de valor nulo no mecanismo.

Solução: O IronOCR lança exceções estruturadas em caso de falhas de inicialização, em vez de retornar nulo. Remova as cláusulas de verificação de nulo. Envolva em um bloco try/catch padrão se precisar expor erros de inicialização a quem chamou a chamada:

// 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);
}
C#

Problema 3: Parâmetros SoftwareBitmap em Assinaturas de Métodos Existentes

Windows.Media.Ocr: Métodos utilitários, serviços e classes de repositório podem aceitar SoftwareBitmap como tipo de parâmetro. Essas assinaturas de método não podem ser compiladas quando o TFM do Windows é removido.

Solução: Substitua os parâmetros SoftwareBitmap por byte[] ou Stream. O OcrInput do IronOCR aceita ambos diretamente. Os locais de chamada que anteriormente construíam um SoftwareBitmap podem passar seus dados subjacentes em vez disso:

// 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;
}
C#

Problema 4: Chamadores somente assíncronos não podem usar o IronOCR síncrono diretamente

Windows.Media.Ocr: Cada chamada de reconhecimento é async. Chamadores em toda a base de código usam await e retornam Task<string>. Alternar para o método síncrono de Read do IronOCR dentro de um método async funciona, mas pode introduzir chamadas bloqueantes em contextos onde async era arquitetural.

Solução: O IronOCR oferece um caminho assíncrono para quem precisar. Use Task.Run para encapsulamento com foco em CPU em métodos assíncronos existentes, ou use a API nativa assíncrona:

// 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/
C#

O guia de OCR assíncrono documenta a API assíncrona integrada para contextos em que são necessários padrões de execução "disparar e esquecer" ou de relatório de progresso.

Problema 5: O formato da etiqueta de idioma do Windows não corresponde diretamente.

Windows.Media.Ocr: Os idiomas são especificados usando tags de string BCP-47 passadas para Windows.Globalization.Language("fr-FR"). Essas tags de texto não têm equivalente direto no IronOCR.

Solução: Mapear tags de idioma BCP-47 para o enum OcrLanguage. O mapeamento é simples para idiomas comuns:

// 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.
C#

O mapeamento completo está disponível no catálogo de idiomas do IronOCR . Para idiomas não listados no enum principal, o suporte a pacotes de idiomas personalizados cobre o carregamento de arquivos .traineddata diretamente.

Problema 6: FileAccessMode.Read não tem substituto

Windows.Media.Ocr: file.OpenAsync(FileAccessMode.Read) é um padrão de abertura de arquivo específico do WinRT. O enum FileAccessMode não existe no .NET padrão.

Solução: Substitua por System.IO.File.ReadAllBytes ou FileStream padrão. OcrInput aceita ambos:

// 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);
C#

Lista de verificação para migração do Windows.Media.Ocr (OCR UWP/WinRT)

Pré-migração

Analise o código-fonte antes de fazer alterações:

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

Registre o número de arquivos afetados, as tags de idioma em uso ("en-US", "fr-FR", etc.) e se algum tipo WinRT aparece em assinaturas de métodos públicos (esses requerem alterações na superfície da API além de reescritas internas).

Migração de código

  1. Instale o pacote NuGet IronOcr: dotnet add package IronOcr
  2. Adicione a chamada de inicialização da licença em Program.cs ou Startup.cs: IronOcr.License.LicenseKey = "YOUR-LICENSE-KEY";
  3. Remova using Windows.Media.Ocr; de todos os arquivos fonte
  4. Remova using Windows.Graphics.Imaging; de todos os arquivos fonte
  5. Remova using Windows.Storage; de todos os arquivos fonte
  6. Remova using Windows.Globalization; de todos os arquivos fonte
  7. Adicione using IronOcr; a todos os arquivos que realizam OCR
  8. Substitua cada chamada OcrEngine.TryCreateFromLanguage(new Language("xx-XX")) por new IronTesseract() e defina ocr.Language = OcrLanguage.X
  9. Substitua cada chamada OcrEngine.TryCreateFromUserProfileLanguages() por new IronTesseract()
  10. Remova todas as cláusulas de verificação de nulos nos resultados da criação do mecanismo.
  11. Substitua os parâmetros SoftwareBitmap nas assinaturas de métodos por byte[] ou Stream
  12. Substitua as cadeias de construção StorageFile + BitmapDecoder + SoftwareBitmap por OcrInput.LoadImage(path), OcrInput.LoadImage(bytes), ou OcrInput.LoadImage(stream)
  13. Substitua engine.RecognizeAsync(bitmap) por ocr.Read(path) ou ocr.Read(input)
  14. Substitua o uso de InMemoryRandomAccessStream e DataWriter por MemoryStream
  15. Substitua as strings de tag de idioma BCP-47 do Windows por valores de enum OcrLanguage; Instale os pacotes NuGet de idioma necessários.
  16. Atualize <TargetFramework> em arquivos de .csproj para remover o sufixo -windowsX.Y.Z onde nenhuma outra API do WinRT permanece

Pós-migração

  • Confirme que o projeto compila visando net8.0 (ou sua versão alvo) sem o sufixo TFM do Windows
  • Confirme que o projeto compila e roda em um ambiente Linux ou contêiner Docker usando mcr.microsoft.com/dotnet/aspnet:8.0
  • Verificar se o texto de saída do OCR corresponde aos resultados esperados para cada tipo de documento no Suite de testes.
  • Verifique se todos os idiomas anteriormente suportados produzem resultados corretos usando os pacotes NuGet de idioma do IronOCR.
  • Verificar se documentos multilíngues produzem resultados corretos em uma única passagem de reconhecimento.
  • Confirme que não ocorre NullReferenceException ou InvalidOperationException na inicialização do motor em máquinas sem pacotes de idioma do Windows instalados
  • Verifique que os valores de result.Confidence estão dentro dos intervalos esperados para documentos de entrada limpos e de baixa qualidade
  • Se o aplicativo gerar documentos, verifique se a saída SaveAsSearchablePdf abre corretamente em um visualizador de PDF e suporta busca de texto
  • Execute quaisquer caminhos de processamento paralelos ou multithread existentes e confirme a segurança das threads sob carga.
  • Implante no ambiente de destino (Docker, Azure App Service, AWS, servidor Linux) e execute pelo menos uma operação completa de OCR de ponta a ponta.

Principais benefícios da migração para o IronOCR

A implantação multiplataforma torna-se uma decisão de configuração, não uma reescrita de código. Após a migração, o componente OCR funciona de forma idêntica no Windows, Linux, macOS, Docker e em todos os principais provedores de nuvem. Mover uma carga de trabalho de OCR de uma máquina virtual Windows para um contêiner Linux com o objetivo de reduzir os custos de hospedagem é uma operação de implantação. O guia de implantação do Linux e o guia de implantação do Docker abordam a adição de uma única linha de dependência necessária nas imagens base do Linux.

O suporte a idiomas acompanha o binário do aplicativo. Os pacotes de idiomas são instalados como pacotes NuGet e a versão é fixada com o pacote IronOCR. O conjunto de linguagens que seu aplicativo pode reconhecer é definido no arquivo de projeto e é idêntico em todas as máquinas — estação de trabalho do desenvolvedor, servidor de integração contínua, servidor de teste e host de produção. Sem necessidade de coordenação com o administrador do sistema operacional, sem exceções na Política de Grupo, sem verificação de valores nulos em tempo de execução.

A precisão do OCR melhora sem ferramentas externas. O pipeline de pré-processamento — Deskew, DeNoise, Contrast, Binarize, Sharpen, Scale — roda dentro do IronOCR antes que o motor de reconhecimento veja a imagem. Documentos que apresentaram resultados degradados com o Windows.Media.Ocr devido a desalinhamento ou ruído na digitalização melhoram sem a necessidade de adicionar dependências externas de processamento de imagem. O guia de correção da qualidade da imagem e o assistente de filtros ajudam a identificar a combinação de filtros adequada para cada tipo de documento.

Os fluxos de trabalho em PDF são consolidados em uma única biblioteca. O renderizador de PDF externo, necessário para integrar o Windows.Media.Ocr com a entrada de PDF, não é mais necessário. Arquivos PDF escaneados processam através da mesma chamada IronTesseract.Read que imagens. A saída em PDF pesquisável é um método do objeto de resultado. A arquitetura de duas bibliotecas desaparece, juntamente com seu gerenciamento de versões, custos de licenciamento e superfície de implantação.

A saída estruturada permite pipelines de inteligência de documentos. A hierarquia OcrResultPages, Paragraphs, Lines, Words, Characters — com coordenadas e pontuações de confiança por elemento fornecem os dados necessários para extração de campos de fatura, análise de formulários e classificação de documentos. A saída em nível de linha do Windows.Media.Ocr é insuficiente para esses fluxos de trabalho. Com o IronOCR, a extração de palavras com filtro de confiança, a detecção de limites de parágrafos e o mapeamento de campos baseado em coordenadas são recursos de primeira classe, sem a necessidade de bibliotecas adicionais.

O licenciamento perpétuo substitui uma dependência ilimitada de infraestrutura. O custo de manutenção da instalação de pacotes de idiomas do Windows em uma frota heterogênea de máquinas, o licenciamento da Experiência de Área de Trabalho do Windows Server e a infraestrutura de CI exclusiva para Windows é real, mas difuso — aparece em chamados de TI e orçamentos de infraestrutura, não como um item específico no orçamento de OCR. Uma licença IronOCR Lite $999 elimina essa sobrecarga para um projeto de desenvolvedor único. A licença Professional de US$ 1.499 cobre dez desenvolvedores. Ambas são compras únicas com um ano de atualizações incluído.

Observe: Tesseract e Windows Media OCR são marcas registradas de seus respectivos proprietários. Este site não é afiliado, endossado ou patrocinado pelo Google ou Microsoft. Todos os nomes de produtos, logotipos e marcas são propriedade de seus respectivos proprietários. As comparações são apenas para fins informativos e refletem informações disponíveis publicamente no momento da redação.

Artigos relacionados

Key in blue circle

Obtenha sua chave de avaliação gratuita de 30 dias instantaneamente.

Your trial license will be sent to your email address

Sem limitações. 100% desbloqueado. Sem cartão de crédito.

bullet_checkedNão é necessário cartão de crédito nem criação de conta.Sem limitações. 100% desbloqueado. Sem cartão de crédito.
  • Logo Aetna
  • Logo NASA
  • Logo GE
  • Logo Porsche
  • Logo USDA
  • Logo Qatar
Join Millions of Engineers who’ve tried IronPDF
Agende sua consulta sem compromisso.
Preencha o formulário abaixo ou envie um e-mail para sales@ironsoftware.com
Os seus dados serão sempre mantidos em sigilo.
Aprovado por milhões de engenheiros em todo o mundo.
Logotipos dos clientes da Iron Software
Obtenha sua chave de avaliação gratuita de 30 dias instantaneamente.
Não é necessário cartão de crédito nem criação de conta.