Cómo trabajar con el Aspose.Imaging FOSS Core API en .NET

Aspose.Imaging FOSS para la superficie pública de .NET está compuesta por tres clases: ImageProbe, ImageInfo y ImageFormat. Esta guía muestra cómo instalar el paquete y usar las tres juntas para detectar un formato y leer los metadatos de encabezado de un archivo, un flujo y una matriz de bytes.

Guía paso a paso

Paso 1: Instalar el paquete

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

El paquete está dirigido a net8.0 y netstandard2.0 y no tiene dependencias externas en tiempo de ejecución.

Paso 2: Importar el espacio de nombres

Agrega una única directiva using — expone ImageProbe, ImageInfo y ImageFormat, toda la superficie API, por lo que no hay nada más que importar:

using Aspose.Imaging.Foss;

Paso 3: Sondear un archivo por ruta

ImageProbe.ProbeFile lee solo lo suficiente del encabezado del archivo para rellenar un resultado ImageInfo — nunca decodifica los datos de píxeles:

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

Paso 4: Sondear un flujo o una matriz de bytes

Cuando la imagen ya está en memoria o proviene de un flujo (una carga, una respuesta de red), utiliza las sobrecargas que aceptan esos directamente en lugar de escribir primero en un archivo temporal:

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 con flujos tanto buscables como no buscables.

Paso 5: Usa DetectFormat cuando solo necesites el formato

Si solo necesitas ramificar según el formato y no requieres dimensiones, profundidad de bits o recuento de fotogramas, DetectFormat omite el resto del análisis del encabezado:

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

Paso 6: Leer los campos ImageInfo anulables de forma segura

Width, Height, BitDepth y FrameCount son anulables — se rellenan solo cuando el encabezado del formato detectado realmente contiene ese valor. Format es el único campo que siempre se establece una vez que se reconoce el encabezado:

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 comunes y soluciones

El formato se muestra como ImageFormat.Unknown. La cabecera del archivo no coincide con ninguno de los 11 formatos reconocidos (PNG, JPEG, GIF, BMP, WebP, ICO, TIFF, PSD, EMF, WMF, DICOM). Confirma que el archivo es realmente uno de esos formatos — ImageProbe nunca lanza una excepción por una cabecera no reconocida, informa Unknown en su lugar.

Width/Height are null aunque Format está configurado. No todas las cabeceras de formato contienen cada campo, y un archivo truncado puede cortarse antes de los bytes de un campo. Comprueba Format primero, luego trata el resto como opcional.

Calling Probe when DetectFormat lo haría. Probe and ProbeFile analizar el encabezado completo; DetectFormat solo lee lo suficiente para identificar el formato. Use DetectFormat si nunca lo lees Width/Height/BitDepth/FrameCount.

Esperando datos de píxeles decodificados. ImageProbe nunca decodifica, renderiza o convierte contenido de imagen — solo lee los metadatos del encabezado. La decodificación y las operaciones a nivel de píxel requieren el SDK comercial Aspose.Imaging.

Preguntas frecuentes

¿Qué ocurre si examino un archivo truncado o corrupto?

ImageProbe nunca lanza una excepción con entrada malformada o truncada. Devuelve un ImageInfo parcial — Format se establece siempre que se reconozca el marcador de formato del encabezado, incluso si el resto del archivo está recortado.

¿Es ImageProbe thread-safe?

Sí. ImageProbe es estático y no mantiene estado mutable entre llamadas, por lo que las llamadas concurrentes desde varios hilos son seguras.

¿Puedo crear un ImageInfo directamente, sin examinar un archivo real?

Sí. El constructor de ImageInfo es público y solo requiere format — útil para crear dobles de prueba: new ImageInfo(ImageFormat.Png, width: 64, height: 48).

¿Necesito liberar algo?

No. ImageProbe no contiene recursos IDisposable propios. Si pasas un Stream que tú mismo abriste, sigues siendo responsable de desecharlo.