Polyfill

Polyfill provides several mechanisms to bridge the gap between runtime versions:

• Source-only integration: Compiles directly into your project; no runtime dependency is required.
• Extensive API coverage: Includes 881 polyfilled APIs across attributes, extension methods, and static helpers.
• Conditional compilation: Only includes APIs that are missing from your specific target framework.
• Optional feature groups: Provides specialized functionality for Ensure, Guard, Nullability, ArgumentExceptions, and StringInterpolation.

Due to breaking changes in C# 14/dotnet 10 regarding how array.Reverse() is resolved (shifting from Enumerable.Reverse to an in-place Span reversal), this package includes a polyfill for the Enumerable.Reverse<T>(this T[]) overload on older target frameworks.

This polyfill is located in the System.Linq namespace to ensure it takes precedence over Polyfills (which is available via global using) when resolving extension methods from using System;.

Failure to multi-target when using Polyfill results in three main negative impacts:

1. Performance: Polyfills may use less efficient implementations than the native runtime. For example, the polyfill for StringBuilder.Append(ReadOnlySpan<char>) on netcore2 performs a ToString() call, which causes an unnecessary string allocation.
2. Assembly Size: Without multi-targeting, redundant polyfill IL is bundled into higher TFMs. An assembly using Polyfill features might grow from ~50 KB on net10 to ~230 KB on net461 if it is not properly multi-targeted.
3. Load Time and Memory: Larger assemblies with more IL take longer to load and require more memory for JIT compilation.

By default, all Polyfill types are marked as internal. This allows the package to be used across multiple projects without causing type name conflicts.

If your projects use InternalsVisibleTo (e.g., for unit testing), you may encounter type visibility conflicts. To resolve this, use the Embedded pattern: use the Polyfill source package and set <PolyUseEmbeddedAttribute>true</PolyUseEmbeddedAttribute> in a <PropertyGroup>. This ensures that the types are treated as truly embedded and remain invisible to other assemblies even when InternalsVisibleTo is present.

<PropertyGroup>
  <PolyUseEmbeddedAttribute>true</PolyUseEmbeddedAttribute>
</PropertyGroup>

You can consume Polyfill through NuGet. There are two packages available:

• Polyfill: The standard source-only package.
• PolyfillLib: A library version of the package (refer to the PolyfillLib documentation for specific usage).

Package links:

• https://nuget.org/packages/Polyfill/
• https://nuget.org/packages/PolyfillLib/

To ensure compatibility with the features used by Polyfill, it is recommended to use a recent SDK via a global.json file.

{
  "sdk": {
    "version": "10.0.300",
    "rollForward": "latestFeature"
  }
}

When working in a solution that produces an application, the recommended approach is to add the Polyfill NuGet package only to the root app project and enable the PolyPublic property.

By setting <PolyPublic>true</PolyPublic>, the polyfills become available to all downstream projects in the solution (such as test projects) without requiring them to reference the Polyfill NuGet package directly.

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <PolyPublic>true</PolyPublic>
  </PropertyGroup>
</Project>

Polyfill is a source-only package that provides newer .NET and C# features to older runtimes. Because it is source-only, it compiles directly into your consuming project and does not create a runtime dependency.

To use it, add the Polyfill package to your project. It is recommended to set your <LangVersion> to latest to take advantage of the newer C# features being polyfilled.

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <LangVersion>latest</LangVersion>
  </PropertyGroup>
  <ItemGroup>
    <PackageReference Include="Polyfill" Version="*" PrivateAssets="all" />
  </ItemGroup>
</Project>

To enable support for custom interpolated string handlers (like AppendInterpolatedStringHandler and DefaultInterpolatedStringHandler), add the PolyStringInterpolation property to your MSBuild project file:

<PropertyGroup>
  <PolyStringInterpolation>true</PolyStringInterpolation>
</PropertyGroup>

There are two ways to consume Polyfill when building a library:

1. Standard Library: If you are not using InternalsVisibleTo to expose APIs, you can add the Polyfill NuGet package to all individual projects in your solution.
2. Library with InternalsVisibleTo: If you use InternalsVisibleTo (for example, to expose internal APIs to a test project), you should add the Polyfill NuGet package only to the root library project to avoid visibility issues.