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 ImageFormatInfoRemarks
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
| Name | Description |
|---|---|
| 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.csInitializes the description of a format that a CustomImageCodec reads or writes.
public ImageFormatInfo(string name, IEnumerable<string> mimeTypes, IEnumerable<string> fileExtensions)Parameters
namestring- The display name of the format, such as
Farbfeld. mimeTypesIEnumerable<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. fileExtensionsIEnumerable<string>- The file extensions of the format, the preferred one first: at least one, in ASCII, with or without the leading period (
.fforff). They are stored in lower case with their leading period.
Exceptions
ArgumentNullException- An argument or one of its items is
null. ArgumentExceptionnameis empty or white space, a list is empty, a media type is not atype/subtypepair 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
| Name | Description |
|---|---|
| All | Gets the descriptions of every built-in format, in the order of ImageFormat (ImageFormat.Unknown and ImageFormat.Custom excluded). |
| DefaultFileExtension | Gets the preferred file extension of the format, the first of ImageFormatInfo.FileExtensions, in lower case with its leading period (.png, .jpg, .tiff). |
| FileExtensions | Gets the file extensions recognized by ImageFormatInfo.TryGetByFileExtension, in lower case with their leading period, the preferred one first. |
| Format | Gets the described format: ImageFormat.Custom for the format of a CustomImageCodec. |
| MimeType | 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). |
| MimeTypes | 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). |
| Name | Gets 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; }Property value
DefaultFileExtension
ImageFormatInfo.csGets 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
FileExtensions
ImageFormatInfo.csGets 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
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).
Format
ImageFormatInfo.csGets the described format: ImageFormat.Custom for the format of a CustomImageCodec.
public ImageFormat Format { get; }Property value
MimeType
ImageFormatInfo.csGets 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
MimeTypes
ImageFormatInfo.csGets 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
Methods
| Name | Description |
|---|---|
| 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.csGets the description of a format.
public static ImageFormatInfo Get(ImageFormat format)Parameters
formatImageFormat- The format.
Returns
ImageFormatInfo The description.
Exceptions
ArgumentOutOfRangeExceptionformatisImageFormat.Unknown,ImageFormat.Custom(useCustomImageCodec.FormatInfo) or not a defined value.
ToString()
ImageFormatInfo.csReturns the display name of the format.
public override string ToString()Returns
string The value of ImageFormatInfo.Name.
TryGetByFileExtension(ReadOnlySpan<char>, ImageFormatInfo?)
ImageFormatInfo.csFinds the format of a file extension.
public static bool TryGetByFileExtension(ReadOnlySpan<char> extension, out ImageFormatInfo? info)Parameters
extensionReadOnlySpan<char>- The extension, with or without its leading period (
.jpgorjpg), compared without regard to ASCII case. A path is not an extension: usePath.GetExtensionfirst. infoImageFormatInfo?- The description of the format, or
nullwhen the extension is not recognized.
Returns
bool true if the extension belongs to a supported format.
TryGetByMimeType(ReadOnlySpan<char>, ImageFormatInfo?)
ImageFormatInfo.csFinds the format of a media (MIME) type.
public static bool TryGetByMimeType(ReadOnlySpan<char> mimeType, out ImageFormatInfo? info)Parameters
mimeTypeReadOnlySpan<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 aContent-Typeheader can be given as is (image/png; q=0.9). infoImageFormatInfo?- The description of the format, or
nullwhen the type is not recognized.
Returns
bool true if the media type belongs to a supported format.