As part of ongoing internal discussions around dependency management and maintenance overhead reduction, we'd like to explore removing our dependency on the Polyfill NuGet package.
Context
Polyfill has been a valuable tool that allowed us to use modern .NET APIs across our multi-targeted builds (netstandard2.0, net462, net8.0, net9.0, etc.) with minimal friction. We're grateful for the work @SimonCropp and contributors have put into it — it saved us a lot of boilerplate over time.
However, as our codebase and target matrix have evolved, we've identified a few considerations that motivate this change:
- Reduced external dependencies: Fewer third-party dependencies means fewer moving parts to maintain, audit, and keep in sync across releases.
- Transparency of polyfilled behavior: Source-generated polyfills can sometimes diverge subtly from the BCL implementations they mirror (e.g.,
Task.WaitAsync, CancelAsync). Owning the polyfill surface explicitly gives us full visibility and control over the behavior shipped in our binaries.
- Simpler onboarding: Having our own minimal, well-scoped polyfill file makes it easier for contributors to understand exactly what compatibility shims are in play without needing to reference external package documentation.
Proposed approach
Replace the Polyfill package with a self-contained eng/Polyfills.cs file that provides only the type stubs and extension methods we actually need, with clear #if guards per target framework.
What this is not
This is not a reflection on the quality of Polyfill; it's a well-maintained and useful package. This is purely about reducing our external dependency surface and gaining tighter control over the compatibility layer in a large, heavily multi-targeted codebase.
As part of ongoing internal discussions around dependency management and maintenance overhead reduction, we'd like to explore removing our dependency on the Polyfill NuGet package.
Context
Polyfill has been a valuable tool that allowed us to use modern .NET APIs across our multi-targeted builds (netstandard2.0, net462, net8.0, net9.0, etc.) with minimal friction. We're grateful for the work @SimonCropp and contributors have put into it — it saved us a lot of boilerplate over time.
However, as our codebase and target matrix have evolved, we've identified a few considerations that motivate this change:
Task.WaitAsync,CancelAsync). Owning the polyfill surface explicitly gives us full visibility and control over the behavior shipped in our binaries.Proposed approach
Replace the Polyfill package with a self-contained
eng/Polyfills.csfile that provides only the type stubs and extension methods we actually need, with clear#ifguards per target framework.What this is not
This is not a reflection on the quality of Polyfill; it's a well-maintained and useful package. This is purely about reducing our external dependency surface and gaining tighter control over the compatibility layer in a large, heavily multi-targeted codebase.