Document whether FileExtensionContentTypeProvider is thread-safe

[mattflaschen]

Description

Please document on the class's API page whether FileExtensionContentTypeProvider is thread-safe. If so, it can be used as a singleton.

Page URL

https://learn.microsoft.com/en-us/aspnet/core/fundamentals/static-files?view=aspnetcore-10.0

Content source URL

https://github.com/dotnet/AspNetCore.Docs/blob/main/aspnetcore/fundamentals/static-files.md

Document ID

3fec6e08-fc99-7a5c-796f-3f2347cad891

Platform Id

5c42c2c8-be1b-60de-8cde-f9b8d8c24f5f

Article author

@wadepickett

Metadata

• ID: d47f38e2-bc36-cfb8-b0cc-17a534689f8b
• PlatformId: 5c42c2c8-be1b-60de-8cde-f9b8d8c24f5f
• Service: aspnet-core
• Sub-service: fundamentals

Related Issues

---

Associated WorkItem - 583095

[wadepickett]

@mattflaschen, thanks very much for bringing this up. You are right, some clarification could be added here.

We could use somthing like a note perhaps to clarify:
`> [!NOTE]

xref:Microsoft.AspNetCore.StaticFiles.FileExtensionContentTypeProvider is not thread-safe for concurrent writes. Its internal mappings dictionary is a standard Dictionary<string, string> without synchronization. If you configure the provider's mappings once at startup and only perform read operations (lookups) afterward, the provider can safely be registered as a singleton. Do not add, remove, or modify mappings after the provider is in use by concurrent requests.`

[wadepickett]

🤖 AI Triage Summary

📌 Note to community: This is an automated preliminary analysis to help our documentation team quickly review, determine scope and prioritize this issue. This report is not a resolution — it's a starting point for the documentation team to evaluate and act on.

---

This preliminary assessment report was run by: @wadepickett
Date: 2026-05-31
Issue: 37210
Model: GitHub Copilot

---

Issue Analysis: Document whether FileExtensionContentTypeProvider is thread-safe

✅ Issue Validation

Status: Valid and actionable

📋 Issue Summary

The issue requests documentation clarifying whether FileExtensionContentTypeProvider is thread-safe and whether it can safely be registered as a singleton in dependency injection. After reviewing the source code, the class uses a standard mutable Dictionary<string, string> for its Mappings property — it is not inherently thread-safe. However, if configured once at startup and used only for read operations thereafter, it is effectively safe for concurrent reads and can be used as a singleton.

📁 Potentially Affected Files

These files have been identified as possibly related to this issue and may need review.

File	Path	Lines	Section
Main article	aspnetcore/fundamentals/static-files.md	954-1000	"Map file extensions to MIME types"

📝 Preliminary Change Assessment

The following are initial observations for the documentation team to evaluate—not final decisions.

Potential documentation Updates

File: aspnetcore/fundamentals/static-files.md
Location: After line 963, within the "Map file extensions to MIME types" section, before the code sample that creates a FileExtensionContentTypeProvider instance.
Type: Note block

Current content (lines 963-964):

Use <xref:Microsoft.AspNetCore.StaticFiles.FileExtensionContentTypeProvider.Mappings%2A?displayProperty=nameWithType> to add or modify file extension to MIME content type mappings. In the followi[...]

In the issue discussion a note has been suggested by wadepickett. It could be entered on that line and look like this:
Suggested direction:

Use <xref:Microsoft.AspNetCore.StaticFiles.FileExtensionContentTypeProvider.Mappings%2A?displayProperty=nameWithType> to add or modify file extension to MIME content type mappings. In the following example, several file extensions are mapped to known MIME types:

> [!NOTE]
> <xref:Microsoft.AspNetCore.StaticFiles.FileExtensionContentTypeProvider> is **not thread-safe** for concurrent writes. Its internal mappings dictionary is a standard `Dictionary<string, string>` without synchronization. If you configure the provider's mappings once at startup and only perform read operations (lookups) afterward, the provider can safely be registered as a singleton. Do not add, remove, or modify mappings after the provider is in use by concurrent requests.

🎯 Suggested Action Plan

For documentation team review

1. Review file: aspnetcore/fundamentals/static-files.md

   • Navigate to: Line 963
   • Section: "Map file extensions to MIME types"
   • Consider: Adding a [!NOTE] block clarifying thread-safety and singleton usage guidance

2. Consider API doc update: The issue also requests the thread-safety note on the API reference page. This would require a triple-slash XML doc comment update in the ASP.NET Core product repo source, which is outside the scope of this docs repo. Consider filing or linking a companion issue on dotnet/aspnetcore.

⚠️ Review Considerations

• Verify the thread-safety characterization against the current source in dotnet/aspnetcore for the latest target framework.
• The note should apply across all supported moniker ranges since the class implementation has not changed.
• Consider whether a companion issue should be filed on dotnet/aspnetcore for adding <threadsafety> XML doc remarks to the class.

🔗 References

• Published article: https://learn.microsoft.com/en-us/aspnet/core/fundamentals/static-files?view=aspnetcore-10.0
• API reference: https://learn.microsoft.com/en-us/dotnet/api/microsoft.aspnetcore.staticfiles.fileextensioncontenttypeprovider
• Source code: FileExtensionContentTypeProvider.cs
• Content source: https://github.com/dotnet/AspNetCore.Docs/blob/main/aspnetcore/fundamentals/static-files.md