Come lavorare con il Aspose.Imaging FOSS Core API in .NET

Aspose.Imaging FOSS per la superficie pubblica di .NET è composta da tre classi: ImageProbe, ImageInfo e ImageFormat. Questa guida mostra come installare il pacchetto e utilizzare tutte e tre insieme per rilevare un formato e leggere i metadati dell’intestazione da un file, da uno stream e da un array di byte.

Guida passo-passo

Passo 1: Installa il pacchetto

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

Il pacchetto è destinato a net8.0 e netstandard2.0 e non ha dipendenze runtime esterne.

Passo 2: Importa lo spazio dei nomi

Aggiungi una singola direttiva using — espone ImageProbe, ImageInfo e ImageFormat, l’intera superficie API, quindi non c’è nient’altro da importare:

using Aspose.Imaging.Foss;

Passo 3: Analizza un file per percorso

ImageProbe.ProbeFile legge solo la parte necessaria dell’intestazione del file per popolare un risultato ImageInfo — non decodifica mai i dati dei pixel:

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

Passo 4: Analizza uno stream o un array di byte

Quando l’immagine è già in memoria o proviene da uno stream (un upload, una risposta di rete), utilizza gli overload che li accettano direttamente invece di scrivere prima su un file temporaneo:

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) funziona sia con stream ricercabili che non ricercabili.

Passo 5: Usa DetectFormat quando ti serve solo il formato

Se ti serve solo distinguere in base al formato e non ti servono dimensioni, profondità di colore o conteggio dei fotogrammi, DetectFormat salta il resto dell’analisi dell’intestazione:

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

Passo 6: Leggi in modo sicuro i campi ImageInfo nullable

Width, Height, BitDepth e FrameCount sono nullable — vengono popolati solo quando l’intestazione del formato rilevato contiene realmente quel valore. Format è l’unico campo sempre impostato una volta riconosciuta l’intestazione:

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

Problemi comuni e soluzioni

Il formato appare come ImageFormat.Unknown. L’intestazione del file non corrisponde a nessuno degli 11 formati riconosciuti (PNG, JPEG, GIF, BMP, WebP, ICO, TIFF, PSD, EMF, WMF, DICOM). Verifica che il file sia effettivamente uno di questi formati — ImageProbe non genera mai un’eccezione per un’intestazione non riconosciuta, segnala Unknown invece.

Width/Height are null anche se Format è impostato. Non tutte le intestazioni dei formati contengono tutti i campi, e un file troncato può terminare prima dei byte di un campo. Controlla Format prima, poi tratta il resto come opzionale.

Calling Probe when DetectFormat basterebbe. Probe and ProbeFile analizza l’intera intestazione; DetectFormat legge solo quanto basta per identificare il formato. Usa DetectFormat se non leggi mai Width/Height/BitDepth/FrameCount.

In attesa di dati pixel decodificati. ImageProbe non decodifica, non renderizza né converte il contenuto dell’immagine — legge solo i metadati dell’intestazione. La decodifica e le operazioni a livello di pixel richiedono il SDK commerciale Aspose.Imaging.

Domande frequenti

Cosa succede se interrogo un file troncato o corrotto?

ImageProbe non genera eccezioni su input malformato o troncato. Restituisce un ImageInfo parziale — Format è impostato ogni volta che il marcatore di formato dell’intestazione è stato riconosciuto, anche se il resto del file è stato tagliato.

È ImageProbe thread-safe?

Sì. ImageProbe è statico e non mantiene alcuno stato mutabile tra le chiamate, quindi le chiamate concorrenti da più thread sono sicure.

Posso costruire un ImageInfo direttamente, senza interrogare un file reale?

Sì. Il costruttore di ImageInfo è pubblico e richiede solo format — utile per creare doppi di test: new ImageInfo(ImageFormat.Png, width: 64, height: 48).

Devo liberare qualcosa?

No. ImageProbe non contiene risorse IDisposable proprie. Se passi un Stream che hai aperto tu, rimani responsabile della sua eliminazione.