核心 API

核心 API

Aspose.Imaging FOSS 对于 .NET 的整个公开表面 有三类： ImageProbe （静态外观）， ImageInfo （结果值），以及 ImageFormat （格式枚举）。本页介绍它们如何作为契约组合在一起，超出在 功能与特性.

三类契约

• ImageProbe — 静态、无状态。每次调用都是独立的；没有任何需要配置或释放的内容。
• ImageInfo — 封闭、不可变。所有五个属性（Format, Width, Height, BitDepth, FrameCount).
• ImageFormat — 一个枚举，每个已识别的格式对应一个值，另外 Unknown.

using Aspose.Imaging.Foss;

var info = ImageProbe.ProbeFile("photo.jpg");
ImageFormat format = info.Format;   // always set
int? width = info.Width;            // set only when the format's header carries it

直接构造 ImageInfo

ImageInfo 的构造函数是公开的 — 只需提供 format，其他所有参数默认使用 null。这对需要替代结果而不去检查真实文件的单元测试非常有用：

using Aspose.Imaging.Foss;

// Fake a PNG result for a test double, with no dimensions
var fakeInfo = new ImageInfo(ImageFormat.Png);

// Fake a fully-populated result
var fullInfo = new ImageInfo(ImageFormat.Gif, width: 64, height: 48, bitDepth: 8, frameCount: 3);

没有相应的方式来 mutate an ImageInfo 在构造之后 — 所有属性都是只读的，因此探测或构造后的实例可以安全地传递和缓存，无需防御性复制。

选择正确的重载

ProbeFile 会自行打开并读取文件——无需先打开一个 FileStream 只为调用 Probe(stream)。

批量探测目录

由于 ImageProbe 从不抛出异常，目录扫描可以在紧密循环中调用它，而无需对每个文件进行 try/catch：

using Aspose.Imaging.Foss;

foreach (var path in Directory.GetFiles("incoming"))
{
    var info = ImageProbe.ProbeFile(path);

    if (info.Format == ImageFormat.Unknown)
    {
        Console.WriteLine($"{path}: not a recognized image format, skipping");
        continue;
    }

    Console.WriteLine($"{path}: {info.Format} {info.Width}x{info.Height}");
}

任何文件的头部未匹配到 11 种已识别格式之一时，将解析为 ImageFormat.Unknown 而不是抛出异常——上述循环永远不需要 catch 块。

永不抛异常的约定

这并非偶然行为——它是 API 约定的刻意组成部分。如果已识别格式的头部在解析过程中被截断或出现畸形，ImageProbe 仍会返回一个 ImageInfo，其中 Format 被设置为它实际识别到的格式；它不会向调用方传播解析异常。只有 Format 是有保障的——将其他所有属性视为可选，无论检测到的是哪种格式。

常见问题

FAQ

我可以对 ImageInfo 或 ImageProbe 进行子类化吗？

不。ImageInfo 是 sealed，ImageProbe 是 static —— 两者都未设计用于子类化或通过继承实例化。

ImageProbe 是线程安全的吗？

ImageProbe 在调用之间不保持可变状态 —— 对 Probe、ProbeFile 或 DetectFormat 的每一次调用都是独立的，这使得多个线程的并发调用是安全的。

我需要释放任何资源吗？

不。ImageProbe 本身没有 IDisposable 资源。如果你传入了自己打开的 Stream，则仍需自行负责释放该流 —— Probe(stream) 不会关闭它。

API Reference 摘要

另请参阅

• Aspose.Imaging — Enterprise Documentation