ImageFormatInfo Class

Describes an ImageFormat: its display name, its media (MIME) types and its file extensions, and maps an extension or a media type back to its format.

public sealed class ImageFormatInfo

Remarks

The mapping is a fixed table of this version of the library: an extension or a media type belongs to exactly one format, so a lookup is never ambiguous. Variants of a format share the entry of their format: an animated PNG (.apng) is ImageFormat.Png, a Netpbm bitmap (.pbm) is ImageFormat.Pnm, a JPEG 2000 codestream (.j2k) is ImageFormat.Jpeg2000. Use ImageEncoder.FromFileExtension to get the encoder an extension selects, variant included, and ImageEncoder.Create for the default encoder of a format.

Loading never uses this table: formats are detected from content (Image.DetectFormat). It is meant to name output files, to set a Content-Type, or to choose an encoder from a request.

The formats of the codecs an application registers (CustomImageCodec) are described by instances created with the public constructor: their ImageFormatInfo.Format is ImageFormat.Custom, and they are not part of the table (ImageFormatInfo.All, ImageFormatInfo.Get, ImageFormatInfo.TryGetByFileExtension and ImageFormatInfo.TryGetByMimeType only know the built-in formats).

Instances are immutable and shared; this type is thread-safe.

Constructors

NameDescription
ImageFormatInfo(string, IEnumerable<string>, IEnumerable<string>)Initializes the description of a format that a CustomImageCodec reads or writes.

ImageFormatInfo(string, IEnumerable<string>, IEnumerable<string>)

ImageFormatInfo.cs

Initializes the description of a format that a CustomImageCodec reads or writes.

public ImageFormatInfo(string name, IEnumerable<string> mimeTypes, IEnumerable<string> fileExtensions)

Parameters

name string
The display name of the format, such as Farbfeld.
mimeTypes IEnumerable<string>
The media types of the format, the preferred one first: at least one, in ASCII, such as image/x-farbfeld. They are stored in lower case.
fileExtensions IEnumerable<string>
The file extensions of the format, the preferred one first: at least one, in ASCII, with or without the leading period (.ff or ff). They are stored in lower case with their leading period.

Exceptions

ArgumentNullException
An argument or one of its items is null.
ArgumentException
name is empty or white space, a list is empty, a media type is not a type/subtype pair of ASCII characters without white space or parameters, or an extension is empty or contains another character than an ASCII letter, digit, -, _ or +.

Remarks

The ImageFormatInfo.Format of the description is ImageFormat.Custom.

Properties

NameDescription
AllGets the descriptions of every built-in format, in the order of ImageFormat (ImageFormat.Unknown and ImageFormat.Custom excluded).
DefaultFileExtensionGets the preferred file extension of the format, the first of ImageFormatInfo.FileExtensions, in lower case with its leading period (.png, .jpg, .tiff).
FileExtensionsGets the file extensions recognized by ImageFormatInfo.TryGetByFileExtension, in lower case with their leading period, the preferred one first.
FormatGets the described format: ImageFormat.Custom for the format of a CustomImageCodec.
MimeTypeGets the preferred media type of the format, the first of ImageFormatInfo.MimeTypes: the type registered with IANA when there is one (image/png, image/avif, image/jxl), otherwise the type of the freedesktop.org shared MIME database (image/x-tga, image/x-exr).
MimeTypesGets the media types recognized by ImageFormatInfo.TryGetByMimeType, in lower case, the preferred one first. The others are aliases in common use (image/x-icon) and the types of variants of the format (image/apng, image/heic-sequence).
NameGets the display name of the format, such as PNG or JPEG XL.

Gets the descriptions of every built-in format, in the order of ImageFormat (ImageFormat.Unknown and ImageFormat.Custom excluded).

public static IReadOnlyList<ImageFormatInfo> All { get; }

DefaultFileExtension

ImageFormatInfo.cs

Gets the preferred file extension of the format, the first of ImageFormatInfo.FileExtensions, in lower case with its leading period (.png, .jpg, .tiff).

public string DefaultFileExtension { get; }

Property value

string

FileExtensions

ImageFormatInfo.cs

Gets the file extensions recognized by ImageFormatInfo.TryGetByFileExtension, in lower case with their leading period, the preferred one first.

public IReadOnlyList<string> FileExtensions { get; }

Property value

IReadOnlyList<string>

Remarks

Every extension selects an encoder in ImageEncoder.FromFileExtension, except the extensions of files the library reads but does not write: .jpx and .jpf (the extended file format of JPEG 2000) and .ktx2 (KTX 2.0).

Gets the described format: ImageFormat.Custom for the format of a CustomImageCodec.

public ImageFormat Format { get; }

Property value

ImageFormat

Gets the preferred media type of the format, the first of ImageFormatInfo.MimeTypes: the type registered with IANA when there is one (image/png, image/avif, image/jxl), otherwise the type of the freedesktop.org shared MIME database (image/x-tga, image/x-exr).

public string MimeType { get; }

Property value

string

Gets the media types recognized by ImageFormatInfo.TryGetByMimeType, in lower case, the preferred one first. The others are aliases in common use (image/x-icon) and the types of variants of the format (image/apng, image/heic-sequence).

public IReadOnlyList<string> MimeTypes { get; }

Property value

IReadOnlyList<string>

Gets the display name of the format, such as PNG or JPEG XL.

public string Name { get; }

Property value

string

Methods

NameDescription
Get(ImageFormat)Gets the description of a format.
ToString()Returns the display name of the format.
TryGetByFileExtension(ReadOnlySpan<char>, ImageFormatInfo?)Finds the format of a file extension.
TryGetByMimeType(ReadOnlySpan<char>, ImageFormatInfo?)Finds the format of a media (MIME) type.

Get(ImageFormat)

ImageFormatInfo.cs

Gets the description of a format.

public static ImageFormatInfo Get(ImageFormat format)

Parameters

format ImageFormat
The format.

Returns

ImageFormatInfo The description.

Exceptions

ArgumentOutOfRangeException
format is ImageFormat.Unknown, ImageFormat.Custom (use CustomImageCodec.FormatInfo) or not a defined value.

Returns the display name of the format.

public override string ToString()

Returns

string The value of ImageFormatInfo.Name.

TryGetByFileExtension(ReadOnlySpan<char>, ImageFormatInfo?)

ImageFormatInfo.cs

Finds the format of a file extension.

public static bool TryGetByFileExtension(ReadOnlySpan<char> extension, out ImageFormatInfo? info)

Parameters

extension ReadOnlySpan<char>
The extension, with or without its leading period (.jpg or jpg), compared without regard to ASCII case. A path is not an extension: use Path.GetExtension first.
info ImageFormatInfo?
The description of the format, or null when the extension is not recognized.

Returns

bool true if the extension belongs to a supported format.

TryGetByMimeType(ReadOnlySpan<char>, ImageFormatInfo?)

ImageFormatInfo.cs

Finds the format of a media (MIME) type.

public static bool TryGetByMimeType(ReadOnlySpan<char> mimeType, out ImageFormatInfo? info)

Parameters

mimeType ReadOnlySpan<char>
The media type, compared without regard to ASCII case, such as image/png. Parameters and surrounding white space are ignored, so the value of a Content-Type header can be given as is (image/png; q=0.9).
info ImageFormatInfo?
The description of the format, or null when the type is not recognized.

Returns

bool true if the media type belongs to a supported format.