Jak pracować z Aspose.Imaging FOSS Core API w .NET

Aspose.Imaging FOSS dla publicznego interfejsu .NET składa się z trzech klas: ImageProbe, ImageInfo i ImageFormat. Ten przewodnik opisuje instalację pakietu oraz użycie wszystkich trzech razem, aby wykryć format i odczytać metadane nagłówka z pliku, strumienia i tablicy bajtów.

Przewodnik krok po kroku

Krok 1: Zainstaluj pakiet

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

Pakiet jest skierowany do net8.0 i netstandard2.0 oraz nie ma żadnych zewnętrznych zależności w czasie wykonywania.

Krok 2: Zaimportuj przestrzeń nazw

Dodaj pojedynczą dyrektywę using — udostępnia ImageProbe, ImageInfo i ImageFormat, całą powierzchnię API, więc nie ma nic więcej do zaimportowania:

using Aspose.Imaging.Foss;

Krok 3: Sprawdź plik według ścieżki

ImageProbe.ProbeFile odczytuje tylko tyle nagłówka pliku, aby wypełnić wynik ImageInfo — nigdy nie dekoduje danych pikseli:

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

Krok 4: Sprawdź strumień lub tablicę bajtów

Gdy obraz jest już w pamięci lub pochodzi ze strumienia (przesyłanie, odpowiedź sieciowa), użyj przeciążeń, które przyjmują je bezpośrednio, zamiast najpierw zapisywać do tymczasowego pliku:

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) działa zarówno ze strumieniami z możliwością przewijania, jak i bez takiej możliwości.

Krok 5: Użyj DetectFormat, gdy potrzebujesz jedynie formatu

Jeśli potrzebujesz jedynie rozróżnić format i nie potrzebujesz wymiarów, głębi bitowej ani liczby klatek, DetectFormat pomija dalsze przetwarzanie nagłówka:

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

Krok 6: Bezpiecznie odczytywać pola Nullable ImageInfo

Width, Height, BitDepth i FrameCount są nullable — są wypełniane tylko wtedy, gdy nagłówek wykrytego formatu rzeczywiście zawiera tę wartość. Format jest jedynym polem zawsze ustawionym po rozpoznaniu nagłówka:

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

Typowe problemy i rozwiązania

Format wyświetla się jako ImageFormat.Unknown. Nagłówek pliku nie pasuje do żadnego z 11 rozpoznanych formatów (PNG, JPEG, GIF, BMP, WebP, ICO, TIFF, PSD, EMF, WMF, DICOM). Upewnij się, że plik rzeczywiście jest jednym z tych formatów — ImageProbe nigdy nie wyrzuca błędu dla nierozpoznanego nagłówka, zgłasza Unknown zamiast tego.

Width/Height are null mimo że Format jest ustawione. Nie każdy nagłówek formatu zawiera wszystkie pola, a obcięty plik może skończyć się przed bajtami pola. Sprawdź Format najpierw, a potem traktuj resztę jako opcjonalną.

Calling Probe when DetectFormat zrobiłoby. Probe and ProbeFile parsować pełny nagłówek; DetectFormat odczytuje tylko tyle, aby zidentyfikować format. Użyj DetectFormat jeśli nigdy nie odczytasz Width/Height/BitDepth/FrameCount.

Oczekuje zdezakodowanych danych pikseli. ImageProbe nigdy nie dekoduje, nie renderuje ani nie konwertuje zawartości obrazu — odczytuje tylko metadane nagłówka. Dekodowanie i operacje na poziomie pikseli wymagają komercyjnego Aspose.Imaging SDK.

Najczęściej zadawane pytania

Co się stanie, jeśli sprawdzę przycięty lub uszkodzony plik?

ImageProbe nigdy nie zgłasza wyjątku przy nieprawidłowym lub przyciętym wejściu. Zwraca częściowy ImageInfo — Format jest ustawiany, gdy tylko znacznik formatu nagłówka zostanie rozpoznany, nawet jeśli reszta pliku jest obcięta.

Czy ImageProbe jest bezpieczny wątkowo?

Tak. ImageProbe jest statyczny i nie przechowuje zmiennego stanu pomiędzy wywołaniami, więc równoczesne wywołania z wielu wątków są bezpieczne.

Czy mogę bezpośrednio skonstruować ImageInfo, bez sprawdzania rzeczywistego pliku?

Tak. Konstruktor ImageInfo jest publiczny i wymaga jedynie format — przydatny do budowania podwójników testowych: new ImageInfo(ImageFormat.Png, width: 64, height: 48).

Czy muszę zwolnić cokolwiek?

Nr ImageProbe nie zawiera własnych zasobów IDisposable. Jeśli przekażesz Stream, które sam otworzyłeś, pozostajesz odpowiedzialny za jego zwolnienie.