How to Work with the Aspose.Imaging FOSS Core API in .NET

Aspose.Imaging FOSS for .NET’s public surface is made up of three classes: ImageProbe, ImageInfo, and ImageFormat. This guide walks through installing the package and using all three together to detect a format and read header metadata from a file, a stream, and a byte array.

Step-by-Step Guide

Step 1: Install the Package

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

The package targets net8.0 and netstandard2.0 and has zero external runtime dependencies.

Step 2: Import the Namespace

Add a single using directive — it exposes ImageProbe, ImageInfo, and ImageFormat, the entire API surface, so there is nothing else to import:

using Aspose.Imaging.Foss;

Step 3: Probe a File by Path

ImageProbe.ProbeFile reads just enough of the file header to populate an ImageInfo result — it never decodes pixel data:

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

Step 4: Probe a Stream or Byte Array

When the image is already in memory or came from a stream (an upload, a network response), use the overloads that accept those directly instead of writing to a temporary file first:

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) works with both seekable and non-seekable streams.

Step 5: Use DetectFormat When You Only Need the Format

If you only need to branch on the format and don’t need dimensions, bit depth, or frame count, DetectFormat skips the rest of the header parse:

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

Step 6: Read the Nullable ImageInfo Fields Safely

Width, Height, BitDepth, and FrameCount are nullable — they’re populated only when the detected format’s header actually carries that value. Format is the one field always set once the header is recognized:

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

Common Issues and Fixes

Format shows as ImageFormat.Unknown. The file’s header doesn’t match any of the 11 recognized formats (PNG, JPEG, GIF, BMP, WebP, ICO, TIFF, PSD, EMF, WMF, DICOM). Confirm the file is genuinely one of those formats — ImageProbe never throws for an unrecognized header, it reports Unknown instead.

Width/Height are null even though Format is set. Not every format’s header carries every field, and a truncated file may cut off before a field’s bytes. Check Format first, then treat the rest as optional.

Calling Probe when DetectFormat would do. Probe and ProbeFile parse the full header; DetectFormat only reads enough to identify the format. Use DetectFormat if you never read Width/Height/BitDepth/FrameCount.

Expecting decoded pixel data. ImageProbe never decodes, renders, or converts image content — it only reads header metadata. Decoding and pixel-level operations require the commercial Aspose.Imaging SDK.

Frequently Asked Questions

What happens if I probe a truncated or corrupted file?

ImageProbe never throws on malformed or truncated input. It returns a partial ImageInfo — Format is set whenever the header’s format marker was recognized, even if the rest of the file is cut short.

Is ImageProbe thread-safe?

Yes. ImageProbe is static and holds no mutable state between calls, so concurrent calls from multiple threads are safe.

Can I construct an ImageInfo directly, without probing a real file?

Yes. ImageInfo’s constructor is public with only format required — useful for building test doubles: new ImageInfo(ImageFormat.Png, width: 64, height: 48).

Do I need to dispose of anything?

No. ImageProbe holds no IDisposable resources of its own. If you pass a Stream you opened yourself, you remain responsible for disposing it.