Como trabalhar com o Aspose.Imaging FOSS Core API em .NET

Aspose.Imaging FOSS para a superfície pública de .NET é composta por três classes: ImageProbe, ImageInfo e ImageFormat. Este guia mostra como instalar o pacote e usar as três juntas para detectar um formato e ler metadados de cabeçalho de um arquivo, um fluxo e um array de bytes.

Guia passo a passo

Etapa 1: Instalar o pacote

git clone https://github.com/aspose-imaging-foss/Aspose.Imaging-FOSS-for-.NET.git
cd Aspose.Imaging-FOSS-for-.NET
dotnet build

O pacote tem como alvo net8.0 e netstandard2.0 e não possui dependências externas de tempo de execução.

Etapa 2: Importar o namespace

Adicione uma única diretiva using — ela expõe ImageProbe, ImageInfo e ImageFormat, toda a superfície API, então não há mais nada para importar:

using Aspose.Imaging.Foss;

Etapa 3: Sondar um Arquivo por Caminho

ImageProbe.ProbeFile lê apenas o suficiente do cabeçalho do arquivo para preencher um resultado ImageInfo — nunca decodifica dados de pixel:

var info = ImageProbe.ProbeFile("photo.jpg");
Console.WriteLine($"{info.Format}: {info.Width}x{info.Height}, {info.BitDepth}-bit");

Etapa 4: Sondar um Stream ou Array de Bytes

Quando a imagem já está na memória ou veio de um stream (um upload, uma resposta de rede), use as sobrecargas que aceitam esses diretamente em vez de gravar primeiro em um arquivo temporário:

byte[] bytes = File.ReadAllBytes("photo.jpg");
var infoFromBytes = ImageProbe.Probe(bytes);

using var stream = File.OpenRead("photo.jpg");
var infoFromStream = ImageProbe.Probe(stream);

Probe(stream) funciona tanto com streams buscáveis quanto com streams não buscáveis.

Etapa 5: Use DetectFormat Quando Você Só Precisa do Formato

Se você só precisa ramificar com base no formato e não precisa de dimensões, profundidade de bits ou contagem de quadros, DetectFormat pula o restante da análise do cabeçalho:

var format = ImageProbe.DetectFormat(bytes);
if (format == ImageFormat.Dicom)
{
    // route to DICOM-specific handling
}

Etapa 6: Leia os campos ImageInfo anuláveis com segurança

Width, Height, BitDepth e FrameCount são anuláveis — são preenchidos apenas quando o cabeçalho do formato detectado realmente contém esse valor. Format é o único campo sempre definido assim que o cabeçalho é reconhecido:

var info = ImageProbe.ProbeFile("scan.dcm");
if (info.Width.HasValue && info.Height.HasValue)
{
    Console.WriteLine($"{info.Format}: {info.Width}x{info.Height}");
}
else
{
    Console.WriteLine($"{info.Format}: dimensions not available in this header");
}

Problemas comuns e correções

O formato aparece como ImageFormat.Unknown. O cabeçalho do arquivo não corresponde a nenhum dos 11 formatos reconhecidos (PNG, JPEG, GIF, BMP, WebP, ICO, TIFF, PSD, EMF, WMF, DICOM). Confirme se o arquivo é realmente um desses formatos — ImageProbe nunca lança para um cabeçalho não reconhecido, ele relata Unknown em vez disso.

Width/Height are null mesmo que Format está definido. Nem todo cabeçalho de formato contém todos os campos, e um arquivo truncado pode ser cortado antes dos bytes de um campo. Verifique Format primeiro, então trate o resto como opcional.

Calling Probe when DetectFormat seria suficiente. Probe and ProbeFile analisar o cabeçalho completo; DetectFormat lê apenas o suficiente para identificar o formato. Use DetectFormat se você nunca ler Width/Height/BitDepth/FrameCount.

Esperando dados de pixel decodificados. ImageProbe nunca decodifica, renderiza ou converte conteúdo de imagem — ele apenas lê metadados do cabeçalho. Decodificação e operações em nível de pixel requerem o SDK comercial Aspose.Imaging.

Perguntas Frequentes

O que acontece se eu sondar um arquivo truncado ou corrompido?

ImageProbe nunca lança exceção em entrada malformada ou truncada. Ele retorna um ImageInfo parcial — Format é definido sempre que o marcador de formato do cabeçalho foi reconhecido, mesmo que o restante do arquivo seja cortado.

O ImageProbe é thread-safe?

Sim. ImageProbe é estático e não mantém estado mutável entre chamadas, portanto chamadas concorrentes de múltiplas threads são seguras.

Posso construir um ImageInfo diretamente, sem sondar um arquivo real?

Sim. O construtor de ImageInfo é público e requer apenas format — útil para construir doubles de teste: new ImageInfo(ImageFormat.Png, width: 64, height: 48).

Preciso descartar algo?

Não. ImageProbe não contém recursos IDisposable próprios. Se você passar um Stream que abriu, continua responsável por descartá-lo.