Polyfill

Source only package that exposes newer .NET and C# features to older runtimes.

The package targets netstandard2.0 and is designed to support the following runtimes.

net461, net462, net47, net471, net472, net48, net481
netcoreapp2.0, netcoreapp2.1, netcoreapp3.0, netcoreapp3.1
net5.0, net6.0, net7.0, net8.0, net9.0

API count: 415

See Milestones for release notes.

TargetFrameworks

Some polyfills are implemented in a way that will not have the equivalent performance to the actual implementations.

For example the polyfill for StringBuilder.Append(ReadOnlySpan<char>) on netcore2 is:

public StringBuilder Append(ReadOnlySpan<char> value)
    => target.Append(value.ToString());

Which will result in a string allocation.

As Polyfill is implemented as a source only nuget, the implementation for each polyfill is compiled into the IL of the resulting assembly. As a side-effect that implementation will continue to be used even if that assembly is executed in a runtime that has a more efficient implementation available.

As a result, in the context of a project producing nuget package, that project should target all frameworks from the lowest TargetFramework up to and including the current framework. This way the most performant implementation will be used for each runtime. Take the following examples:

If a nuget's minimum target is net6, then the resulting TargetFrameworks should also include net7.0 and net8.0
If a nuget's minimum target is net471, then the resulting TargetFrameworks should also include net472 and net48"

Nuget

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

SDK / LangVersion

This project uses features from the current stable SDK and C# language. As such consuming projects should target those:

LangVersion

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <LangVersion>latest</LangVersion>

global.json

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

Consuming and type visibility

The default type visibility for all polyfills is internal. This means it can be consumed in multiple projects and types will not conflict.

Consuming in an app

If Polyfill is being consumed in a solution that produce an app, then it is recommended to use the Polyfill nuget only in the root "app project" and enable PolyPublic.

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

Then all consuming projects, like tests, will not need to use the Polyfill nuget.

Consuming in a library

If Polyfill is being consumed in a solution that produce a library (and usually a nuget), then the Polyfill nuget can be added to all projects.

If, however, InternalsVisibleTo is being used to expose APIs (for example to test projects), then the Polyfill nuget should be added only to the root library project.

Included polyfills

ModuleInitializerAttribute

ModuleInitializerAttribute

Reference: Module Initializers

static bool InitCalled;

[Test]
public void ModuleInitTest() =>
    Assert.True(InitCalled);

[ModuleInitializer]
public static void ModuleInit() =>
    InitCalled = true;

^{snippet source | anchor}

IsExternalInit

Reference: init (C# Reference)

class InitSample
{
    public int Member { get; init; }
}

^{snippet source | anchor}

Nullable attributes

Reference: Nullable reference types

Required attributes

Reference: C# required modifier

public class Person
{
    public Person()
    {
    }

    [SetsRequiredMembers]
    public Person(string name) =>
        Name = name;

    public required string Name { get; init; }
}

^{snippet source | anchor}

CompilerFeatureRequiredAttribute

CompilerFeatureRequiredAttribute

Indicates that compiler support for a particular feature is required for the location where this attribute is applied.

CollectionBuilderAttribute

CollectionBuilderAttribute

Can be used to make types compatible with collection expressions

ConstantExpectedAttribute

ConstantExpectedAttribute

Indicates that the specified method parameter expects a constant.

SkipLocalsInit

SkipLocalsInitAttribute

Reference: SkipLocalsInitAttribute

the SkipLocalsInit attribute prevents the compiler from setting the .locals init flag when emitting to metadata. The SkipLocalsInit attribute is a single-use attribute and can be applied to a method, a property, a class, a struct, an interface, or a module, but not to an assembly. SkipLocalsInit is an alias for SkipLocalsInitAttribute.

class SkipLocalsInitSample
{
    [SkipLocalsInit]
    static void ReadUninitializedMemory()
    {
        Span<int> numbers = stackalloc int[120];
        for (var i = 0; i < 120; i++)
        {
            Console.WriteLine(numbers[i]);
        }
    }
}

^{snippet source | anchor}

Index and Range

Reference: Indices and ranges

If consuming in a project that targets net461 or net462, a reference to System.ValueTuple is required. See References: System.ValueTuple.

[TestFixture]
class IndexRangeSample
{
    [Test]
    public void Range()
    {
        var substring = "value"[2..];
        Assert.AreEqual("lue", substring);
    }

    [Test]
    public void Index()
    {
        var ch = "value"[^2];
        Assert.AreEqual('u', ch);
    }

    [Test]
    public void ArrayIndex()
    {
        var array = new[]
        {
            "value1",
            "value2"
        };

        var value = array[^2];

        Assert.AreEqual("value1", value);
    }
}

^{snippet source | anchor}

OverloadResolutionPriority

Release Notes

C# introduces a new attribute, System.Runtime.CompilerServices.OverloadResolutionPriority, that can be used by API authors to adjust the relative priority of overloads within a single type as a means of steering API consumers to use specific APIs, even if those APIs would normally be considered ambiguous or otherwise not be chosen by C#'s overload resolution rules. This helps framework and library authors guide API usage as they APIs as they develop new and better patterns.

The OverloadResolutionPriorityAttribute can be used in conjunction with the ObsoleteAttribute. A library author may mark properties, methods, types and other programming elements as obsolete, while leaving them in place for backwards compatibility. Using programming elements marked with the ObsoleteAttribute will result in compiler warnings or errors. However, the type or member is still visible to overload resolution and may be selected over a better overload or cause an ambiguity failure. The OverloadResolutionPriorityAttribute lets library authors fix these problems by lowering the priority of obsolete members when there are better alternatives.

Usage

[TestFixture]
public class OverloadResolutionPriorityAttributeTests
{
    [Test]
    public void Run()
    {
        int[] arr = [1, 2, 3];
        //Prints "Span" because resolution priority is higher
        Method(arr);
    }

    [OverloadResolutionPriority(2)]
    static void Method(ReadOnlySpan<int> list) =>
        Console.WriteLine("Span");

    [OverloadResolutionPriority(1)]
    static void Method(int[] list) =>
        Console.WriteLine("Array");
}

^{snippet source | anchor}

UnscopedRefAttribute

UnscopedRefAttribute

Reference: Low Level Struct Improvements

struct UnscopedRefUsage
{
    int field1;

    [UnscopedRef] ref int Prop1 => ref field1;
}

^{snippet source | anchor}

RequiresPreviewFeaturesAttribute

CallerArgumentExpressionAttribute

CallerArgumentExpressionAttribute

Reference: CallerArgumentExpression

static class FileUtil
{
    public static void FileExists(string path, [CallerArgumentExpression("path")] string argumentName = "")
    {
        if (!File.Exists(path))
        {
            throw new ArgumentException($"File not found. Path: {path}", argumentName);
        }
    }
}

static class FileUtilUsage
{
    public static string[] Method(string path)
    {
        FileUtil.FileExists(path);
        return File.ReadAllLines(path);
    }
}

^{snippet source | anchor}

Extensions

The class Polyfill includes the following extension methods:

Important

The methods using AppendInterpolatedStringHandler parameter are not extensions because the compiler prefers to use the overload with string parameter instead.

Extension methods

bool

bool TryFormat(bool, Span<char>, int) reference

byte

bool TryFormat(byte, Span<char>, int, ReadOnlySpan<char>, IFormatProvider?) reference

CancellationToken

CancellationTokenRegistration Register(CancellationToken, Action<object?, CancellationToken>, object?) reference
CancellationTokenRegistration UnsafeRegister(CancellationToken, Action<object?>, object?) reference
CancellationTokenRegistration UnsafeRegister(CancellationToken, Action<object?, CancellationToken>, object?) reference

CancellationTokenSource

Task CancelAsync(CancellationTokenSource) reference

ConcurrentBag

void Clear<T>(ConcurrentBag<T>) reference

ConcurrentDictionary<TKey, TValue>

TValue GetOrAdd<TKey, TValue, TArg>(ConcurrentDictionary<TKey, TValue>, TKey, Func<TKey, TArg, TValue>, TArg) where TKey : notnull reference

ConcurrentQueue

void Clear<T>(ConcurrentQueue<T>) reference

DateOnly

bool TryFormat(DateOnly, Span<char>, int, ReadOnlySpan<char>, IFormatProvider?) reference

DateTime

DateTime AddMicroseconds(DateTime, double) reference
int Microsecond(DateTime) reference
int Nanosecond(DateTime) reference
bool TryFormat(DateTime, Span<char>, int, ReadOnlySpan<char>, IFormatProvider?) reference

DateTimeOffset

DateTimeOffset AddMicroseconds(DateTimeOffset, double) reference
int Microsecond(DateTimeOffset) reference
int Nanosecond(DateTimeOffset) reference
bool TryFormat(DateTimeOffset, Span<char>, int, ReadOnlySpan<char>, IFormatProvider?) reference

decimal

bool TryFormat(decimal, Span<char>, int, ReadOnlySpan<char>, IFormatProvider?) reference

Dictionary<TKey, TValue>

bool Remove<TKey, TValue>(Dictionary<TKey, TValue>, TKey, TValue) where TKey : notnull reference
bool TryAdd<TKey, TValue>(Dictionary<TKey, TValue>, TKey, TValue) where TKey : notnull reference

double

bool TryFormat(double, Span<char>, int, ReadOnlySpan<char>, IFormatProvider?) reference

Encoding

int GetBytes(Encoding, ReadOnlySpan<char>, Span<byte>) reference
string GetString(Encoding, ReadOnlySpan<byte>) reference

EventInfo

NullabilityState GetNullability(EventInfo)
NullabilityInfo GetNullabilityInfo(EventInfo)
bool IsNullable(EventInfo)

FieldInfo

NullabilityState GetNullability(FieldInfo)
NullabilityInfo GetNullabilityInfo(FieldInfo)
bool IsNullable(FieldInfo)

float

bool TryFormat(float, Span<char>, int, ReadOnlySpan<char>, IFormatProvider?) reference

Guid

bool TryFormat(Guid, Span<char>, int, ReadOnlySpan<char>) reference

HashSet

bool TryGetValue<T>(HashSet<T>, T, T) reference

HttpClient

Task<byte[]> GetByteArrayAsync(HttpClient, string, CancellationToken) reference
Task<byte[]> GetByteArrayAsync(HttpClient, Uri, CancellationToken) reference
Task<Stream> GetStreamAsync(HttpClient, string, CancellationToken) reference
Task<Stream> GetStreamAsync(HttpClient, Uri, CancellationToken) reference
Task<string> GetStringAsync(HttpClient, string, CancellationToken) reference
Task<string> GetStringAsync(HttpClient, Uri, CancellationToken) reference

HttpContent

Task<byte[]> ReadAsByteArrayAsync(HttpContent, CancellationToken) reference
Task<Stream> ReadAsStreamAsync(HttpContent, CancellationToken) reference
Task<string> ReadAsStringAsync(HttpContent, CancellationToken) reference

IDictionary<TKey, TValue>

ReadOnlyDictionary<TKey, TValue> AsReadOnly<TKey, TValue>(IDictionary<TKey, TValue>) where TKey : notnull reference

IEnumerable

IEnumerable<(TFirst First, TSecond Second, TThird Third)> Zip<TFirst, TSecond, TThird>(IEnumerable<TFirst>, IEnumerable<TSecond>, IEnumerable<TThird>) reference
IEnumerable<(TFirst First, TSecond Second)> Zip<TFirst, TSecond>(IEnumerable<TFirst>, IEnumerable<TSecond>) reference

IEnumerable

IEnumerable<KeyValuePair<TKey, TAccumulate>> AggregateBy<TSource, TKey, TAccumulate>(IEnumerable<TSource>, Func<TSource, TKey>, TAccumulate, Func<TAccumulate, TSource, TAccumulate>, IEqualityComparer<TKey>?) where TKey : notnull reference
IEnumerable<KeyValuePair<TKey, TAccumulate>> AggregateBy<TSource, TKey, TAccumulate>(IEnumerable<TSource>, Func<TSource, TKey>, Func<TKey, TAccumulate>, Func<TAccumulate, TSource, TAccumulate>, IEqualityComparer<TKey>?) where TKey : notnull reference
IEnumerable<TSource> Append<TSource>(IEnumerable<TSource>, TSource) reference
IEnumerable<TSource[]> Chunk<TSource>(IEnumerable<TSource>, int) reference
IEnumerable<KeyValuePair<TKey, int>> CountBy<TSource, TKey>(IEnumerable<TSource>, Func<TSource, TKey>, IEqualityComparer<TKey>?) where TKey : notnull reference
IEnumerable<TSource> DistinctBy<TSource, TKey>(IEnumerable<TSource>, Func<TSource, TKey>) reference
IEnumerable<TSource> DistinctBy<TSource, TKey>(IEnumerable<TSource>, Func<TSource, TKey>, IEqualityComparer<TKey>) reference
TSource ElementAt<TSource>(IEnumerable<TSource>, Index) reference
TSource? ElementAtOrDefault<TSource>(IEnumerable<TSource>, Index) reference
IEnumerable<TSource> Except<TSource>(IEnumerable<TSource>, TSource) reference
IEnumerable<TSource> Except<TSource>(IEnumerable<TSource>, TSource, IEqualityComparer<TSource>?) reference
IEnumerable<TSource> Except<TSource>(IEnumerable<TSource>, IEqualityComparer<TSource>, TSource[]) reference
IEnumerable<TSource> ExceptBy<TSource, TKey>(IEnumerable<TSource>, IEnumerable<TKey>, Func<TSource, TKey>) reference
IEnumerable<TSource> ExceptBy<TSource, TKey>(IEnumerable<TSource>, IEnumerable<TKey>, Func<TSource, TKey>, IEqualityComparer<TKey>?) reference
TSource FirstOrDefault<TSource>(IEnumerable<TSource>, Func<TSource, bool>, TSource) reference
TSource FirstOrDefault<TSource>(IEnumerable<TSource>, TSource) reference
IEnumerable<(int Index, TSource Item)> Index<TSource>(IEnumerable<TSource>) reference
TSource LastOrDefault<TSource>(IEnumerable<TSource>, TSource) reference
TSource LastOrDefault<TSource>(IEnumerable<TSource>, Func<TSource, bool>, TSource) reference
TSource? Max<TSource>(IEnumerable<TSource>, IComparer<TSource>?) reference
TSource? MaxBy<TSource, TKey>(IEnumerable<TSource>, Func<TSource, TKey>) reference
TSource? MaxBy<TSource, TKey>(IEnumerable<TSource>, Func<TSource, TKey>, IComparer<TKey>?) reference
TSource? Min<TSource>(IEnumerable<TSource>, IComparer<TSource>?) reference
TSource? MinBy<TSource, TKey>(IEnumerable<TSource>, Func<TSource, TKey>) reference
TSource? MinBy<TSource, TKey>(IEnumerable<TSource>, Func<TSource, TKey>, IComparer<TKey>?) reference
TSource SingleOrDefault<TSource>(IEnumerable<TSource>, Func<TSource, bool>, TSource) reference
TSource SingleOrDefault<TSource>(IEnumerable<TSource>, TSource) reference
IEnumerable<TSource> SkipLast<TSource>(IEnumerable<TSource>, int) reference
IEnumerable<TSource> Take<TSource>(IEnumerable<TSource>, Range) reference
IEnumerable<TSource> TakeLast<TSource>(IEnumerable<TSource>, int) reference
HashSet<TSource> ToHashSet<TSource>(IEnumerable<TSource>, IEqualityComparer<TSource>?) reference
bool TryGetNonEnumeratedCount<TSource>(IEnumerable<TSource>, int) reference

IList

ReadOnlyCollection<T> AsReadOnly<T>(IList<T>) reference

int

bool TryFormat(int, Span<char>, int, ReadOnlySpan<char>, IFormatProvider?) reference

IReadOnlyDictionary<TKey, TValue>

TValue? GetValueOrDefault<TKey, TValue>(IReadOnlyDictionary<TKey, TValue>, TKey) where TKey : notnull reference
TValue GetValueOrDefault<TKey, TValue>(IReadOnlyDictionary<TKey, TValue>, TKey, TValue) where TKey : notnull reference

KeyValuePair<TKey, TValue>

void Deconstruct<TKey, TValue>(KeyValuePair<TKey, TValue>, TKey, TValue) reference

List

void AddRange<T>(List<T>, ReadOnlySpan<T>) reference
void CopyTo<T>(List<T>, Span<T>) reference
void InsertRange<T>(List<T>, int, ReadOnlySpan<T>) reference

long

bool TryFormat(long, Span<char>, int, ReadOnlySpan<char>, IFormatProvider?) reference

MemberInfo

NullabilityState GetNullability(MemberInfo)
NullabilityInfo GetNullabilityInfo(MemberInfo)
bool HasSameMetadataDefinitionAs(MemberInfo, MemberInfo) reference
bool IsNullable(MemberInfo)

ParameterInfo

NullabilityState GetNullability(ParameterInfo)
NullabilityInfo GetNullabilityInfo(ParameterInfo)
bool IsNullable(ParameterInfo)

Process

Task WaitForExitAsync(Process, CancellationToken) reference

PropertyInfo

NullabilityState GetNullability(PropertyInfo)
NullabilityInfo GetNullabilityInfo(PropertyInfo)
bool IsNullable(PropertyInfo)

Random

void NextBytes(Random, Span<byte>) reference
void Shuffle<T>(Random, T[]) reference
void Shuffle<T>(Random, Span<T>) reference

ReadOnlySpan

bool EndsWith(ReadOnlySpan<char>, string, StringComparison) reference
SpanLineEnumerator EnumerateLines(ReadOnlySpan<char>) reference
bool SequenceEqual(ReadOnlySpan<char>, string) reference
bool StartsWith(ReadOnlySpan<char>, string, StringComparison) reference

ReadOnlySpan

bool Contains<T>(ReadOnlySpan<T>, T) where T : IEquatable<T> reference
bool EndsWith<T>(ReadOnlySpan<T>, T) where T : IEquatable<T>? reference
SpanSplitEnumerator<T> Split<T>(ReadOnlySpan<T>, T) where T : IEquatable<T> reference
SpanSplitEnumerator<T> Split<T>(ReadOnlySpan<T>, ReadOnlySpan<T>) where T : IEquatable<T> reference
SpanSplitEnumerator<T> SplitAny<T>(ReadOnlySpan<T>, ReadOnlySpan<T>) where T : IEquatable<T> reference
SpanSplitEnumerator<T> SplitAny<T>(ReadOnlySpan<T>, SearchValues<T>) where T : IEquatable<T> reference
bool StartsWith<T>(ReadOnlySpan<T>, T) where T : IEquatable<T>? reference

Regex

ValueMatchEnumerator EnumerateMatches(Regex, ReadOnlySpan<char>) reference
ValueMatchEnumerator EnumerateMatches(Regex, ReadOnlySpan<char>, int) reference
bool IsMatch(Regex, ReadOnlySpan<char>, int) reference
bool IsMatch(Regex, ReadOnlySpan<char>) reference

sbyte

bool TryFormat(sbyte, Span<char>, int, ReadOnlySpan<char>, IFormatProvider?) reference

short

bool TryFormat(short, Span<char>, int, ReadOnlySpan<char>, IFormatProvider?) reference

SortedList<TKey, TValue>

TKey GetKeyAtIndex<TKey, TValue>(SortedList<TKey, TValue>, int) reference
TValue GetValueAtIndex<TKey, TValue>(SortedList<TKey, TValue>, int) reference

Span

bool EndsWith(Span<char>, string) reference
SpanLineEnumerator EnumerateLines(Span<char>) reference
bool SequenceEqual(Span<char>, string) reference
bool StartsWith(Span<char>, string) reference
Span<char> TrimEnd(Span<char>) reference
Span<char> TrimStart(Span<char>) reference

Span

bool Contains<T>(Span<T>, T) where T : IEquatable<T> reference

Stream

Task CopyToAsync(Stream, Stream, CancellationToken) reference
ValueTask DisposeAsync(Stream) reference
ValueTask<int> ReadAsync(Stream, Memory<byte>, CancellationToken) reference
ValueTask WriteAsync(Stream, ReadOnlyMemory<byte>, CancellationToken) reference

string

bool Contains(string, string, StringComparison) reference
bool Contains(string, char) reference
void CopyTo(string, Span<char>) reference
bool EndsWith(string, char) reference
int GetHashCode(string, StringComparison) reference
string[] Split(string, char, StringSplitOptions) reference
string[] Split(string, char, int, StringSplitOptions) reference
bool StartsWith(string, char) reference
bool TryCopyTo(string, Span<char>) reference

StringBuilder

StringBuilder Append(StringBuilder, ReadOnlySpan<char>) reference
StringBuilder Append(StringBuilder, AppendInterpolatedStringHandler) reference
StringBuilder Append(StringBuilder, IFormatProvider?, AppendInterpolatedStringHandler) reference
StringBuilder Append(StringBuilder, StringBuilder.AppendInterpolatedStringHandler) reference
StringBuilder Append(StringBuilder, IFormatProvider?, StringBuilder.AppendInterpolatedStringHandler) reference
StringBuilder AppendJoin(StringBuilder, string, string[]) reference
StringBuilder AppendJoin(StringBuilder, string, Object[]) reference
StringBuilder AppendJoin(StringBuilder, char, string[]) reference
StringBuilder AppendJoin(StringBuilder, char, object[]) reference
StringBuilder AppendJoin<T>(StringBuilder, char, T[]) reference
StringBuilder AppendJoin<T>(StringBuilder, string, T[]) reference
StringBuilder AppendLine(StringBuilder, AppendInterpolatedStringHandler) reference
StringBuilder AppendLine(StringBuilder, IFormatProvider?, AppendInterpolatedStringHandler) reference
StringBuilder AppendLine(StringBuilder, StringBuilder.AppendInterpolatedStringHandler) reference
StringBuilder AppendLine(StringBuilder, IFormatProvider?, StringBuilder.AppendInterpolatedStringHandler) reference
void CopyTo(StringBuilder, int, Span<char>, int) reference
bool Equals(StringBuilder, ReadOnlySpan<char>) reference
ChunkEnumerator GetChunks(StringBuilder) reference
StringBuilder Replace(StringBuilder, ReadOnlySpan<char>, ReadOnlySpan<char>) reference
StringBuilder Replace(StringBuilder, ReadOnlySpan<char>, ReadOnlySpan<char>, int, int) reference

Task

Task WaitAsync(Task, CancellationToken) reference
Task WaitAsync(Task, TimeSpan) reference
Task WaitAsync(Task, TimeSpan, CancellationToken) reference

Task

Task<TResult> WaitAsync<TResult>(Task<TResult>, CancellationToken) reference
Task<TResult> WaitAsync<TResult>(Task<TResult>, TimeSpan) reference
Task<TResult> WaitAsync<TResult>(Task<TResult>, TimeSpan, CancellationToken) reference

TaskCompletionSource

void SetCanceled<T>(TaskCompletionSource<T>, CancellationToken) reference

TextReader

ValueTask<int> ReadAsync(TextReader, Memory<char>, CancellationToken) reference
Task<string> ReadLineAsync(TextReader, CancellationToken) reference
Task<string> ReadToEndAsync(TextReader, CancellationToken) reference

TextWriter

Task FlushAsync(TextWriter, CancellationToken) reference
void Write(TextWriter, StringBuilder?) reference
void Write(TextWriter, ReadOnlySpan<char>) reference
Task WriteAsync(TextWriter, StringBuilder?, CancellationToken) reference
ValueTask WriteAsync(TextWriter, ReadOnlyMemory<char>, CancellationToken) reference
void WriteLine(TextWriter, ReadOnlySpan<char>) reference
ValueTask WriteLineAsync(TextWriter, ReadOnlyMemory<char>, CancellationToken) reference

TimeOnly

bool TryFormat(TimeOnly, Span<char>, int, ReadOnlySpan<char>, IFormatProvider?) reference

TimeSpan

int Microseconds(TimeSpan) reference
int Nanoseconds(TimeSpan) reference
bool TryFormat(TimeSpan, Span<char>, int, ReadOnlySpan<char>, IFormatProvider?) reference

Type

MethodInfo? GetMethod(Type, string, int, BindingFlags, Type[]) reference
bool IsAssignableFrom<T>(Type)
bool IsAssignableTo<T>(Type)
bool IsAssignableTo(Type, Type?) reference
bool IsGenericMethodParameter(Type) reference

uint

bool TryFormat(uint, Span<char>, int, ReadOnlySpan<char>, IFormatProvider?) reference

ulong

bool TryFormat(ulong, Span<char>, int, ReadOnlySpan<char>, IFormatProvider?) reference

ushort

bool TryFormat(ushort, Span<char>, int, ReadOnlySpan<char>, IFormatProvider?) reference

XDocument

Task SaveAsync(XDocument, XmlWriter, CancellationToken) reference
Task SaveAsync(XDocument, Stream, SaveOptions, CancellationToken) reference
Task SaveAsync(XDocument, TextWriter, SaveOptions, CancellationToken) reference

Static helpers

EnumPolyfill

TEnum[] GetValues<TEnum>() where TEnum : struct, Enum reference
bool IsDefined<TEnum>(TEnum) where TEnum : struct, Enum reference
string[] GetNames<TEnum>() where TEnum : struct, Enum reference
TEnum Parse<TEnum>(string) where TEnum : struct, Enum reference
TEnum Parse<TEnum>(string, bool) where TEnum : struct, Enum reference
TEnum Parse<TEnum>(ReadOnlySpan<char>) where TEnum : struct, Enum reference
TEnum Parse<TEnum>(ReadOnlySpan<char>, bool) where TEnum : struct, Enum reference
bool TryParse<TEnum>(ReadOnlySpan<char>, TEnum) where TEnum : struct, Enum reference
bool TryParse<TEnum>(ReadOnlySpan<char>, bool, TEnum) where TEnum : struct, Enum reference

RegexPolyfill

bool IsMatch(ReadOnlySpan<char>, string, RegexOptions, TimeSpan) reference
bool IsMatch(ReadOnlySpan<char>, string, RegexOptions) reference
bool IsMatch(ReadOnlySpan<char>, string) reference
ValueMatchEnumerator EnumerateMatches(ReadOnlySpan<char>, string) reference
ValueMatchEnumerator EnumerateMatches(ReadOnlySpan<char>, string, RegexOptions, TimeSpan) reference
ValueMatchEnumerator EnumerateMatches(ReadOnlySpan<char>, string, RegexOptions) reference

StringPolyfill

string Join(char, string[]) reference
string Join(char, object[]) reference
string Join(char, string?[], int, int) reference
string Join<T>(char, IEnumerable<T>) reference

BytePolyfill

bool TryParse(string?, IFormatProvider?, byte) reference
bool TryParse(ReadOnlySpan<byte>, IFormatProvider?, byte) reference
bool TryParse(ReadOnlySpan<char>, byte) reference
bool TryParse(ReadOnlySpan<char>, IFormatProvider?, byte) reference
bool TryParse(ReadOnlySpan<byte>, NumberStyles, IFormatProvider?, byte) reference
bool TryParse(ReadOnlySpan<byte>, byte) reference
bool TryParse(ReadOnlySpan<char>, NumberStyles, IFormatProvider?, byte) reference

GuidPolyfill

bool TryParse(string?, IFormatProvider?, Guid) reference
Guid CreateVersion7() reference
Guid CreateVersion7(DateTimeOffset) reference
bool TryParseExact(ReadOnlySpan<char>, ReadOnlySpan<char>, Guid) reference
bool TryParse(ReadOnlySpan<char>, IFormatProvider?, Guid) reference
bool TryParse(ReadOnlySpan<char>, Guid) reference

DateTimePolyfill

bool TryParse(string?, IFormatProvider?, DateTime) reference
bool TryParse(ReadOnlySpan<char>, IFormatProvider?, DateTime) reference
bool TryParse(ReadOnlySpan<char>, DateTime) reference
bool TryParse(ReadOnlySpan<char>, IFormatProvider?, DateTimeStyles, DateTime) reference
bool TryParseExact(ReadOnlySpan<char>, string, IFormatProvider?, DateTimeStyles, DateTime) reference
bool TryParseExact(ReadOnlySpan<char>, ReadOnlySpan<char>, IFormatProvider?, DateTimeStyles, DateTime) reference

DateTimeOffsetPolyfill

bool TryParse(string?, IFormatProvider?, DateTimeOffset) reference
bool TryParse(ReadOnlySpan<char>, IFormatProvider?, DateTimeOffset) reference
bool TryParse(ReadOnlySpan<char>, DateTimeOffset) reference
bool TryParse(ReadOnlySpan<char>, IFormatProvider?, DateTimeStyles, DateTimeOffset) reference
bool TryParseExact(ReadOnlySpan<char>, string, IFormatProvider?, DateTimeStyles, DateTimeOffset) reference
bool TryParseExact(ReadOnlySpan<char>, ReadOnlySpan<char>, IFormatProvider?, DateTimeStyles, DateTimeOffset) reference

DoublePolyfill

bool TryParse(string?, IFormatProvider?, double) reference
bool TryParse(ReadOnlySpan<byte>, IFormatProvider?, double) reference
bool TryParse(ReadOnlySpan<char>, double) reference
bool TryParse(ReadOnlySpan<char>, IFormatProvider?, double) reference
bool TryParse(ReadOnlySpan<byte>, NumberStyles, IFormatProvider?, double) reference
bool TryParse(ReadOnlySpan<byte>, double) reference
bool TryParse(ReadOnlySpan<char>, NumberStyles, IFormatProvider?, double) reference

IntPolyfill

bool TryParse(string?, IFormatProvider?, int) reference
bool TryParse(ReadOnlySpan<byte>, IFormatProvider?, int) reference
bool TryParse(ReadOnlySpan<char>, int) reference
bool TryParse(ReadOnlySpan<char>, IFormatProvider?, int) reference
bool TryParse(ReadOnlySpan<byte>, NumberStyles, IFormatProvider?, int) reference
bool TryParse(ReadOnlySpan<byte>, int) reference
bool TryParse(ReadOnlySpan<char>, NumberStyles, IFormatProvider?, int) reference

LongPolyfill

bool TryParse(string?, IFormatProvider?, int) reference
bool TryParse(ReadOnlySpan<byte>, IFormatProvider?, int) reference
bool TryParse(ReadOnlySpan<char>, int) reference
bool TryParse(ReadOnlySpan<char>, IFormatProvider?, int) reference
bool TryParse(ReadOnlySpan<byte>, NumberStyles, IFormatProvider?, int) reference
bool TryParse(ReadOnlySpan<byte>, int) reference
bool TryParse(ReadOnlySpan<char>, NumberStyles, IFormatProvider?, int) reference

SBytePolyfill

bool TryParse(string?, IFormatProvider?, sbyte) reference
bool TryParse(ReadOnlySpan<byte>, IFormatProvider?, sbyte) reference
bool TryParse(ReadOnlySpan<char>, sbyte) reference
bool TryParse(ReadOnlySpan<char>, IFormatProvider?, sbyte) reference
bool TryParse(ReadOnlySpan<byte>, NumberStyles, IFormatProvider?, sbyte) reference
bool TryParse(ReadOnlySpan<byte>, sbyte) reference
bool TryParse(ReadOnlySpan<char>, NumberStyles, IFormatProvider?, sbyte) reference

ShortPolyfill

bool TryParse(string?, IFormatProvider?, short) reference
bool TryParse(ReadOnlySpan<byte>, IFormatProvider?, short) reference
bool TryParse(ReadOnlySpan<char>, short) reference
bool TryParse(ReadOnlySpan<char>, IFormatProvider?, short) reference
bool TryParse(ReadOnlySpan<byte>, NumberStyles, IFormatProvider?, short) reference
bool TryParse(ReadOnlySpan<byte>, short) reference
bool TryParse(ReadOnlySpan<char>, NumberStyles, IFormatProvider?, short) reference

UIntPolyfill

bool TryParse(string?, IFormatProvider?, uint) reference
bool TryParse(ReadOnlySpan<byte>, IFormatProvider?, uint) reference
bool TryParse(ReadOnlySpan<char>, uint) reference
bool TryParse(ReadOnlySpan<char>, IFormatProvider?, uint) reference
bool TryParse(ReadOnlySpan<byte>, NumberStyles, IFormatProvider?, uint) reference
bool TryParse(ReadOnlySpan<byte>, uint) reference
bool TryParse(ReadOnlySpan<char>, NumberStyles, IFormatProvider?, uint) reference

ULongPolyfill

bool TryParse(string?, IFormatProvider?, ulong) reference
bool TryParse(ReadOnlySpan<byte>, IFormatProvider?, ulong) reference
bool TryParse(ReadOnlySpan<char>, ulong) reference
bool TryParse(ReadOnlySpan<char>, IFormatProvider?, ulong) reference
bool TryParse(ReadOnlySpan<byte>, NumberStyles, IFormatProvider?, ulong) reference
bool TryParse(ReadOnlySpan<byte>, ulong) reference
bool TryParse(ReadOnlySpan<char>, NumberStyles, IFormatProvider?, ulong) reference

UShortPolyfill

bool TryParse(string?, IFormatProvider?, ushort) reference
bool TryParse(ReadOnlySpan<byte>, IFormatProvider?, ushort) reference
bool TryParse(ReadOnlySpan<char>, ushort) reference
bool TryParse(ReadOnlySpan<char>, IFormatProvider?, ushort) reference
bool TryParse(ReadOnlySpan<byte>, NumberStyles, IFormatProvider?, ushort) reference
bool TryParse(ReadOnlySpan<byte>, ushort) reference
bool TryParse(ReadOnlySpan<char>, NumberStyles, IFormatProvider?, ushort) reference

Guard

void FileExists(string)
void DirectoryExists(string)
void NotEmpty(string?)
void NotEmpty<T>(ReadOnlySpan<T>)
void NotEmpty<T>(Span<T>)
void NotEmpty<T>(Memory<T>?)
void NotEmpty<T>(Memory<T>)
void NotEmpty<T>(ReadOnlyMemory<T>?)
void NotEmpty<T>(ReadOnlyMemory<T>)
void NotEmpty<T>(T?) where T : IEnumerable
T NotNull<T>(T?) where T : class
string NotNull(string?)
string NotNullOrEmpty(string?)
T NotNullOrEmpty<T>(T?) where T : IEnumerable
Memory<char> NotNullOrEmpty(Memory<char>?)
ReadOnlyMemory<char> NotNullOrEmpty(ReadOnlyMemory<char>?)
string NotNullOrWhiteSpace(string?)
Memory<char> NotNullOrWhiteSpace(Memory<char>?)
ReadOnlyMemory<char> NotNullOrWhiteSpace(ReadOnlyMemory<char>?)
void NotWhiteSpace(string?)
void NotWhiteSpace(ReadOnlySpan<char>)
void NotWhiteSpace(Memory<char>?)
void NotWhiteSpace(ReadOnlyMemory<char>?)
void NotWhiteSpace(Span<char>)

Lock

void Enter()
bool TryEnter()
bool TryEnter(TimeSpan)
bool TryEnter(int)
void Exit()
Scope EnterScope()

KeyValuePair

KeyValuePair<TKey, TValue> Create<TKey, TValue>(TKey, TValue) reference

TaskCompletionSource

References

If any of the below reference are not included, the related polyfills will be disabled.

System.ValueTuple

If consuming in a project that targets net461 or net462, a reference to System.ValueTuple nuget is required.

<PackageReference Include="System.ValueTuple"
                  Version="4.5.0"
                  Condition="$(TargetFramework.StartsWith('net46'))" />

System.Memory

If using Span APIs and consuming in a project that targets netstandard, netframework, or netcoreapp2*, a reference to System.Memory nuget is required.

<PackageReference Include="System.Memory"
                  Version="4.5.5"
                  Condition="$(TargetFrameworkIdentifier) == '.NETStandard' or
                             $(TargetFrameworkIdentifier) == '.NETFramework' or
                             $(TargetFramework.StartsWith('netcoreapp2'))" />

System.Threading.Tasks.Extensions

If using ValueTask APIs and consuming in a project that target netframework, netstandard2, or netcoreapp2, a reference to System.Threading.Tasks.Extensions nuget is required.

<PackageReference Include="System.Threading.Tasks.Extensions"
                  Version="4.5.4"
                  Condition="$(TargetFramework) == 'netstandard2.0' or
                             $(TargetFramework) == 'netcoreapp2.0' or
                             $(TargetFrameworkIdentifier) == '.NETFramework'" />

Nullability

Example target class

Given the following class

class NullabilityTarget
{
    public string? StringField;
    public string?[] ArrayField;
    public Dictionary<string, object?> GenericField;
}

^{snippet source | anchor}

NullabilityInfoContext

[Test]
public void Test()
{
    var type = typeof(NullabilityTarget);
    var arrayField = type.GetField("ArrayField")!;
    var genericField = type.GetField("GenericField")!;

    var context = new NullabilityInfoContext();

    var arrayInfo = context.Create(arrayField);

    Assert.AreEqual(NullabilityState.NotNull, arrayInfo.ReadState);
    Assert.AreEqual(NullabilityState.Nullable, arrayInfo.ElementType!.ReadState);

    var genericInfo = context.Create(genericField);

    Assert.AreEqual(NullabilityState.NotNull, genericInfo.ReadState);
    Assert.AreEqual(NullabilityState.NotNull, genericInfo.GenericTypeArguments[0].ReadState);
    Assert.AreEqual(NullabilityState.Nullable, genericInfo.GenericTypeArguments[1].ReadState);
}

^{snippet source | anchor}

NullabilityInfoExtensions

Enable by adding and MSBuild property PolyNullability

<PropertyGroup>
  ...
  <PolyNullability>true</PolyNullability>
</PropertyGroup>

NullabilityInfoExtensions provides static and thread safe wrapper around NullabilityInfoContext. It adds three extension methods to each of ParameterInfo, PropertyInfo, EventInfo, and FieldInfo.

GetNullabilityInfo: returns the NullabilityInfo for the target info.
GetNullability: returns the NullabilityState for the state (NullabilityInfo.ReadState or NullabilityInfo.WriteState depending on which has more info) of target info.
IsNullable: given the state (NullabilityInfo.ReadState or NullabilityInfo.WriteState depending on which has more info) of the info:
- Returns true if state is NullabilityState.Nullable.
- Returns false if state is NullabilityState.NotNull.
- Throws an exception if state is NullabilityState.Unknown.

Guard

Enable by adding and MSBuild property PolyGuard

<PropertyGroup>
  ...
  <PolyGuard>true</PolyGuard>
</PropertyGroup>

Guard is designed to be a an alternative to the ArgumentException.ThrowIf* APIs added in net7.

ArgumentException.ThrowIfNullOrEmpty reference
ArgumentException.ThrowIfNullOrWhiteSpace reference
ArgumentNullException.ThrowIfNull reference

With the equivalent Guard APIs:

Guard.NotNullOrEmpty
Guard.NotNullOrWhiteSpace
Guard.NotNull

Polyfills.Guard provides the following APIs:

Guard

void DirectoryExists(String)
void FileExists(String)
void NotEmpty(String)
void NotEmpty<T>(ReadOnlySpan<T>)
void NotEmpty<T>(Span<T>)
void NotEmpty<T>(Nullable<Memory<T>>)
void NotEmpty<T>(Memory<T>)
void NotEmpty<T>(Nullable<ReadOnlyMemory<T>>)
void NotEmpty<T>(ReadOnlyMemory<T>)
void NotEmpty<T>(T) where T : Collections.IEnumerable
T NotNull<T>(T)
String NotNull(String)
String NotNullOrEmpty(String)
T NotNullOrEmpty<T>(T) where T : Collections.IEnumerable
Memory<Char> NotNullOrEmpty(Nullable<Memory<Char>>)
ReadOnlyMemory<Char> NotNullOrEmpty(Nullable<ReadOnlyMemory<Char>>)
String NotNullOrWhiteSpace(String)
Memory<Char> NotNullOrWhiteSpace(Nullable<Memory<Char>>)
ReadOnlyMemory<Char> NotNullOrWhiteSpace(Nullable<ReadOnlyMemory<Char>>)
void NotWhiteSpace(String)
void NotWhiteSpace(ReadOnlySpan<Char>)
void NotWhiteSpace(Nullable<Memory<Char>>)
void NotWhiteSpace(Nullable<ReadOnlyMemory<Char>>)
void NotWhiteSpace(Span<Char>)

Alternatives

PolyShim

https://github.com/Tyrrrz/PolyShim

PolySharp

https://github.com/Sergio0694/PolySharp

Theraot.Core

https://github.com/theraot/Theraot

Combination of

Reason this project was created instead of using the above

PolySharp uses c# source generators. In my opinion a "source-only package" implementation is better because:

Simpler implementation
Easier to debug if something goes wrong.
Uses less memory at compile time. Since there is no source generator assembly to load.
Faster at compile time. Since no source generator is required to execute.

The combination of the other 3 packages is not ideal because:

Required multiple packages to be referenced.
Does not cover all the scenarios included in this package.

Notes

.NET 9.0 Preview 1 API Changes

Icon

Crack designed by Adrien Coquet from The Noun Project.

License

xackus/Polyfill

ErrorLooks like something went wrong!

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

Error
Looks like something went wrong!

Packages