/managedcode-mimetypes

name: managedcode-mimetypes
description: "Use ManagedCode.MimeTypes when a .NET application needs consistent MIME type detection, extension mapping, and content-type decisions for uploads, downloads, or HTTP responses. USE FOR: integrating ManagedCode.MimeTypes into upload or download flows; mapping file extensions to content types in APIs or background processing; reviewing content-type. DO NOT USE FOR: unrelated stacks; generic tasks that do not need this specific guidance. INVOKES: inspect the repository context, edit targeted files, and run relevant build, test, lint, or validation commands when changes are made."
compatibility: "Requires a .NET application that integrates ManagedCode.MimeTypes or evaluates MIME type mapping behavior."

ManagedCode.MimeTypes

Trigger On

• integrating `ManagedCode.MimeTypes` into upload or download flows
• mapping file extensions to content types in APIs or background processing
• reviewing content-type handling for files, blobs, or attachments
• documenting a reusable MIME-type decision point in a .NET application

Install

dotnet add package ManagedCode.MimeTypes --version 10.1.1

Use `PackageReference` when the repository centralizes dependency versions:

<PackageReference Include="ManagedCode.MimeTypes" Version="10.1.1" />

The current package targets .NET 8, 9, and 10. Keep the version in the repository's existing central package-management file when one is present.

Workflow

1. Identify where the application needs stable MIME-type decisions:

• upload validation
• download response headers
• storage metadata
• attachment processing

2. Centralize content-type mapping instead of scattering ad-hoc string tables across the codebase. 3. Use one library boundary for extension and MIME lookups. 4. Validate the extensions and media types that matter to the product. 5. Document any product-specific overrides separately from the library defaults.

Read MIME Metadata

Map file names, URLs, and compound extensions through the generated catalog:

using ManagedCode.MimeTypes;

var reportType = MimeHelper.GetMimeType("report.pdf");
var archiveType = MimeHelper.GetMimeType("archive.tar.gz");
var imageType = MimeHelper.GetMimeType("https://cdn.example.test/avatar.png?v=2");
var jpegExtensions = MimeHelper.GetExtensions("image/jpeg");

Use registry metadata when the application needs provenance or registration details:

if (MimeHelper.TryGetMimeTypeInfoByExtension("report.pdf", out var info))
{
    Console.WriteLine($"{info.Mime} registered={info.IsIanaRegistered}");
}

Write Application Mappings

Register product-specific mappings at startup and remove them only when the owning application lifecycle requires it:

MimeHelper.RegisterMimeType("acme", "application/x-acme");
var customType = MimeHelper.GetMimeType("invoice.acme");

MimeHelper.UnregisterMimeType("acme");

Runtime registrations affect extension and reverse lookup, but do not synthesize full IANA registry metadata.

Validate Upload Content

Treat the extension and declared content type as claims. Inspect the signature before accepting security-sensitive uploads:

using var stream = upload.OpenReadStream();

if (!MimeHelper.MatchesMimeTypeByContent(stream, upload.ContentType) ||
    !MimeHelper.MatchesExtensionByContent(upload.FileName, stream))
{
    throw new InvalidOperationException("Upload content does not match its declared type.");
}

`GetMimeTypeByContent` and the `Matches*ByContent` helpers inspect known prefixes and restore the position of seekable streams. They are not full document parsers, malware scanners, or proof that the remainder of a file is valid.

Settings and Tradeoffs

• Unknown extensions resolve to `MimeHelper.DefaultMimeType`, initially `application/octet-stream`; use `SetDefaultMimeType` only when the whole application owns a different fallback contract.
• Prefer `MimeHelper.Instance` through `IMimeHelper` when dependency injection and test substitution are useful; use static calls for small, deterministic mapping boundaries.
• In `10.1.1`, catalog JSON is processed by the source generator at build time; generated MIME constants do not initialize the registry. The first lookup initializes frozen/immutable indexes, and reverse lookups reuse cached collections. Use `MimeHelper.WarmUp()` at application startup when predictable first-request latency matters; measure cold initialization separately from steady-state lookups.
• Re-run product-specific mapping tests after catalog updates; preferred mappings can change without an API change.
• Never trust MIME classification alone for authorization, file execution, archive extraction, or active-content rendering.

flowchart LR
  A["File name or extension"] --> B["ManagedCode.MimeTypes lookup"]
  B --> C["Resolved MIME type"]
  C --> D["Upload validation, storage metadata, or HTTP response"]

Deliver

• guidance on where MIME lookup belongs in application code
• recommendations for centralized content-type decisions
• validation expectations for real file types used by the product

Validate

• MIME mapping is not duplicated across multiple services or controllers
• important file types are verified explicitly
• response or storage code uses the resolved type consistently
• `dotnet restore` resolves `ManagedCode.MimeTypes` `10.1.1` or the repository-approved newer version
• focused tests cover known extensions, unknown fallbacks, reverse lookup, upload signature mismatches, and any runtime registrations
• `dotnet test` passes for the projects that own upload, download, or storage behavior

Sources

• [10.1.1 release](https://github.com/managedcode/MimeTypes/releases/tag/v10.1.1)
• [Initialization and performance](https://github.com/managedcode/MimeTypes#initialization-and-performance)