PommaLabs.MimeTypes 2.9.4

MIME Types

MIME content type definitions mapped with file extensions and file signatures.

This project was inspired by the following open source projects:

• https://github.com/wagesj45/MimeTypeList
• https://github.com/samuelneff/MimeTypes
• https://github.com/hey-red/MimeTypesMap
• https://github.com/neilharvey/FileSignatures

Moreover, this project heavily relies on the following open source projects:

• mime-types-data, used to retrive data for the map.
• DotLiquid, used to process Liquid templates.
• OpenMcdf, used to inspect OLECF files.

Using DotLiquid, this project simply generates a map of MIME types and extensions starting from the data gathered by mime-types-data, a project maintained by Ruby community.

This project also contains a (not exhaustive) map of file signatures, which can be used, along with file name, in order to better understand the MIME type of a file.

Table of Contents

• Install
• Usage
  • Getting the MIME type of a file name
  • Getting the MIME type of a file stream
  • Getting the MIME type of a file stream and file name
  • Getting the extension of a MIME type
  • Getting the encoding of a MIME type
  • MIME type constants
  • Extension constants
• Maintainers
• Contributing
  • Editing
  • Restoring dependencies
  • Running tests
  • Updating autogenerated files
• License

Install

NuGet package PommaLabs.MimeTypes is available for download:

dotnet add package PommaLabs.MimeTypes

Usage

Include the following using statement in your class:

using PommaLabs.MimeTypes;

Then, follow examples below to understand available APIs.

Getting the MIME type of a file name

Console.WriteLine("txt -> " + MimeTypeMap.GetMimeType("a.txt")); // "txt -> text/plain"

Pass in a file name and get a MIME type back.

If a file path is passed in instead of a simple file name, it will be automatically deduced.

If no MIME type is found then an exception is thrown, unless throwIfMissing is set to false. In that case, the generic application/octet-stream MIME type is returned.

Getting the MIME type of a file stream

using var fs = File.OpenRead("a.jpg");
Console.WriteLine("jpg -> " + MimeTypeMap.GetMimeType(fs)); // "jpg -> image/jpeg"

Pass in a file stream and get a MIME type back. This method uses a very comprehensive list to decode file signatures and a few other inspection strategies, which are:

• OLECF files are opened using OpenMcdf library and a few probe streams are used to identify following file formats: .doc, .msg, .ppt, .vsd, .xls.
• OpenDocument files are opened as a ZIP archive and mimetype file is searched. If it is found, it contains the correct MIME type.
• Office Open XML files are opened as a ZIP archive and specific files are looked for in order to determine the MIME type.

For text files, a generic text/plain MIME type is returned. Following empiric check is done to determine if a file is textual: if a file contains two consecutive NULLs in its first 512 bytes, then it is probably binary.

However, when a text/plain MIME type is returned, file name should also be used in order to receive a more specific MIME type. The empiric check is not perfect at all and might yield wrong results. The same also happens for image/tiff and application/zip, whose signature is shared among many different MIME types.

If no MIME type is found then an exception is thrown, unless throwIfMissing is set to false. In that case, the generic application/octet-stream MIME type is returned.

Getting the MIME type of a file stream and file name

var fn = "a.css";
using var fs = File.OpenRead(fn);
Console.WriteLine("css -> " + MimeTypeMap.GetMimeType(fs, fn)); // "css -> text/css"

This family of methods combines a file signature check with a file extension lookup. This is done in order to improve the quality of the result MIME type, which benefits of the file extension check when the signature is shared among many MIME types.

For example, text files and ZIP archives benefit from this double check. A CSS file would be detected as text/plain by the signature check, while extension lookup correctly yields text/css MIME type.

If no MIME type is found then an exception is thrown, unless throwIfMissing is set to false. In that case, the generic application/octet-stream MIME type is returned.

Getting the extension of a MIME type

Console.WriteLine("audio/wav -> " + MimeTypeMap.GetExtension("audio/wav")); // "audio/wav -> .wav"
Console.WriteLine("audio/wav -> " + MimeTypeMap.GetExtensionWithoutDot("audio/wav")); // "audio/wav -> wav"

Pass in a MIME type and get an extension back. If the MIME type is not registered, an error is thrown.

If the MIME type is not found then an exception is thrown, unless throwIfMissing is set to false. In that case, the generic .bin extension is returned.

To get all the extensions linked to a specific MIME type:

MimeTypeMap.GetExtensions("image/jpeg"); // [".jpg", ".jpeg", ".jpe"]
MimeTypeMap.GetExtensionsWithoutDot("image/jpeg"); // ["jpg", "jpeg", "jpe"]

Getting the encoding of MIME type

Console.WriteLine("text/plain -> " + MimeTypeMap.GetEncoding("text/plain")); // "text/plain -> quoted-printable"

Pass in a MIME type and get its encoding back. Available encodings are:

• 7bit
• 8bit
• quoted-printable
• base64

If no MIME type is found then an exception is thrown, unless throwIfMissing is set to false. In that case, the generic base64 encoding is returned.

MIME type constants

Console.WriteLine(MimeTypeMap.Application.Onenote); // "applcation/onenote"
Console.WriteLine(MimeTypeMap.Image.Png); // "image/png"
Console.WriteLine(MimeTypeMap.Video._3gpp); // "video/3gpp"

Console.WriteLine(MimeTypeMap.GetExtension(MimeTypeMap.Application.Onenote)); // ".one"
Console.WriteLine(MimeTypeMap.GetExtension(MimeTypeMap.Image.Png)); // ".png"
Console.WriteLine(MimeTypeMap.GetExtension(MimeTypeMap.Video._3gpp)); // ".3gpp"

Subtypes starting with a digit are prefixed with a _ character, since C# field names cannot start with a digit.

Extension constants

Console.WriteLine(MimeTypeMap.Extensions.One); // ".one"
Console.WriteLine(MimeTypeMap.Extensions.Png); // ".png"
Console.WriteLine(MimeTypeMap.Extensions._3gpp); // ".3gpp"

Console.WriteLine(MimeTypeMap.GetMimeType(MimeTypeMap.Extensions.One)); // "application/onenote"
Console.WriteLine(MimeTypeMap.GetMimeType(MimeTypeMap.Extensions.Png)); // "image/png"
Console.WriteLine(MimeTypeMap.GetMimeType(MimeTypeMap.Extensions._3gpp)); // "video/3gpp"

Extensions starting with a digit are prefixed with a _ character, since C# field names cannot start with a digit. For the same reason, invalid leading characters are replaced with a _ character.

Compatibility

This library tries to be as much compatible as possible with https://github.com/samuelneff/MimeTypes project, with following caveats:

• Namespace is different, in order to avoid name clashes.
• When throwIfMissing is not specified or is true, an exception will be thrown for unknown inputs.
  • This applies to both MIME type lookup and extension lookup.
• When throwIfMissing is false, an empty string will not be returned to unknown inputs:
  • Missing MIME types will receive .bin as default extension.
  • Missing extensions will receive application/octet-stream as default MIME type.
• For valid MIME types, the same extension will be returned, with following exceptions:
  • application/onenote now returns .onepkg instead of .one. Source data and Apache mime.types do not map .one extension.
  • application/x-compressed now returns .z instead of .tgz. Source data maps .tgz extension to application/x-gtar MIME type.
  • application/x-x509-ca-cert now returns der instead of cer. Apache mime.types maps .cer to application/pkix-cert MIME type.
  • audio/x-pn-realaudio-plugin now returns rmp instead of rpm. Both are valid, but rpm is commonly used by Red Hat Package Manager.
  • video/3gpp2 now returns .3g2 instead of .3gp2. Source data and Apache mime.types do not map .3gp2 extension.
  • x-world/x-vrml now returns .wrl instead of .xof. Source data and Apache mime.types do not map .xof extension.

This library might look similar to MimeTypeList package, but there are a few core differences:

• This library exposes MIME types and extensions as constants which serve the same purpose of an enum. On the other hand, MimeTypeList package uses them as a static map.
• MIME types and extensions are exposed with UPPER_CASE names.

Maintainers

@pomma89.

Contributing

MRs accepted.

Small note: If editing the README, please conform to the standard-readme specification.

Editing

Visual Studio Code, with Remote Containers extension, is the recommended way to work on this project.

A development container has been configured with all required tools.

Visual Studio Community is also supported and an updated solution file, mime-types.sln, has been provided.

Restoring dependencies

When starting the development container, dependencies should be automatically restored.

Anyway, dependencies can be restored with following command:

dotnet restore

Running tests

Tests can be run with following command:

dotnet test

Tests can also be run with following command, which collects coverage information:

./build.sh --target run-tests

Updating autogenerated files

When source data is updated, autogenerated project files need to be manually updated in order to get new or changed MIME types.

Following command updates all autogenerated files:

./build.sh --target update-maps

License

MIT © 2020-2024 PommaLabs Team and Contributors