Wie man mit dem Aspose.Imaging FOSS Core API in .NET arbeitet

Aspose.Imaging FOSS für die öffentliche Oberfläche von .NET besteht aus drei Klassen: ImageProbe, ImageInfo und ImageFormat. Dieser Leitfaden führt durch die Installation des Pakets und die gleichzeitige Verwendung aller drei, um ein Format zu erkennen und Header-Metadaten aus einer Datei, einem Stream und einem Byte-Array zu lesen.

Schritt-für-Schritt-Anleitung

Schritt 1: Paket installieren

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

Das Paket richtet sich an net8.0 und netstandard2.0 und hat null externe Laufzeitabhängigkeiten.

Schritt 2: Namespace importieren

Fügen Sie eine einzelne using-Direktive hinzu – sie gibt ImageProbe, ImageInfo und ImageFormat frei, die gesamte API-Oberfläche, sodass es nichts Weiteres zu importieren gibt:

using Aspose.Imaging.Foss;

Schritt 3: Datei anhand des Pfads untersuchen

ImageProbe.ProbeFile liest gerade genug vom Dateikopf, um ein ImageInfo-Ergebnis zu füllen – es dekodiert niemals Pixeldaten:

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

Schritt 4: Stream oder Byte-Array untersuchen

Wenn das Bild bereits im Speicher ist oder von einem Stream stammt (ein Upload, eine Netzwerkantwort), verwenden Sie die Überladungen, die diese direkt akzeptieren, anstatt zunächst in eine temporäre Datei zu schreiben:

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) funktioniert sowohl mit seekbaren als auch mit nicht-seekbaren Streams.

Schritt 5: Verwenden Sie DetectFormat, wenn Sie nur das Format benötigen

Wenn Sie nur nach dem Format verzweigen müssen und keine Abmessungen, Bit-Tiefe oder Frame-Anzahl benötigen, überspringt DetectFormat den Rest der Header-Analyse:

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

Schritt 6: Nullable ImageInfo-Felder sicher lesen

Width, Height, BitDepth und FrameCount sind nullable — sie werden nur befüllt, wenn der Header des erkannten Formats tatsächlich diesen Wert enthält. Format ist das eine Feld, das immer gesetzt wird, sobald der Header erkannt ist:

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

Häufige Probleme und Lösungen

Format wird angezeigt als ImageFormat.Unknown. Der Header der Datei stimmt mit keinem der 11 erkannten Formate (PNG, JPEG, GIF, BMP, WebP, ICO, TIFF, PSD, EMF, WMF, DICOM) überein. Stellen Sie sicher, dass die Datei tatsächlich eines dieser Formate ist — ImageProbe wirft nie bei einem nicht erkannten Header, sondern meldet Unknown stattdessen.

Width/Height are null obwohl Format ist gesetzt. Nicht jeder Header eines Formats enthält jedes Feld, und eine abgeschnittene Datei kann vor den Bytes eines Feldes enden. Prüfen Format zuerst, dann den Rest als optional behandeln.

Calling Probe when DetectFormat würde es tun. Probe and ProbeFile den gesamten Header analysieren; DetectFormat liest nur so viel, um das Format zu identifizieren. Verwenden DetectFormat wenn Sie nie lesen Width/Height/BitDepth/FrameCount.

Erwartet dekodierte Pixeldaten. ImageProbe decodiert, rendert oder konvertiert Bildinhalte nie — es liest nur Header-Metadaten. Decodierung und pixelbezogene Vorgänge erfordern das kommerzielle Aspose.Imaging SDK.

Häufig gestellte Fragen

Was passiert, wenn ich eine gekürzte oder beschädigte Datei untersuche?

ImageProbe wirft bei fehlerhafter oder gekürzter Eingabe niemals eine Ausnahme. Es gibt ein partielles ImageInfo zurück — Format wird gesetzt, sobald das Formatkennzeichen des Headers erkannt wurde, selbst wenn der Rest der Datei abgeschnitten ist.

Ist ImageProbe thread-sicher?

Ja. ImageProbe ist statisch und hält keinen veränderbaren Zustand zwischen Aufrufen, sodass gleichzeitige Aufrufe aus mehreren Threads sicher sind.

Kann ich ein ImageInfo direkt konstruieren, ohne eine reale Datei zu untersuchen?

Ja. Der Konstruktor von ImageInfo ist öffentlich und erfordert nur format — nützlich zum Erstellen von Test-Doubles: new ImageInfo(ImageFormat.Png, width: 64, height: 48).

Muss ich irgendetwas freigeben?

Nr. ImageProbe enthält keine eigenen IDisposable-Ressourcen. Wenn Sie ein Stream übergeben, das Sie selbst geöffnet haben, bleiben Sie für dessen Freigabe verantwortlich.