PolySharp 1.5.0

What is it? 🚀

PolySharp provides generated, source-only polyfills for C# language features, to easily use all runtime-agnostic features downlevel. The package is distributed as a source generator, so that it will automatically detect which polyfills are needed depending on the target framework and project in use: just add a reference to PolySharp, set your C# language version to latest, and have fun!

Documentation 📖

PolySharp includes the following polyfills:

• Nullability attributes (for nullable reference types):
  • [AllowNull]
  • [DisallowNull]
  • [DoesNotReturn]
  • [DoesNotReturnIf]
  • [MaybeNull]
  • [MaybeNullWhen]
  • [MemberNotNull]
  • [MemberNotNullWhen]
  • [NotNull]
  • [NotNullIfNotNull]
  • [NotNullWhen]
• Index and Range (see indices and ranges)
• [UnscopedRef] (see low-level struct improvements)
• Required members (see required modifier)
  • [RequiredMember]
  • [SetsRequiredMembers]
• [CompilerFeatureRequired] (needed to support several features)
• [IsExternalInit] (needed for init-only properties)
• [SkipLocalsInit] (see docs)
• Interpolated string handlers (see docs)
  • [InterpolatedStringHandler]
  • [InterpolatedStringHandlerArgument]
• [CallerArgumentExpression] (see docs)
• [RequiresPreviewFeatures] (needed for preview features)
• [AsyncMethodBuilder] (needed for custom method builder types)

To leverage them, make sure to bump your C# language version. You can do this by setting the <LangVersion> MSBuild property in your project. For instance, by adding <LangVersion>11.0</LangVersion> (or your desired C# version) to the first <PropertyGroup> of your .csproj file. For more info on this, see here, but remember that you don't need to manually copy polyfills anymore: simply adding a reference to PolySharp will do this for you automatically.

It also includes the following optional runtime-supported polyfills:

• Reflection annotation attributes (see docs):
  • [DynamicallyAccessedMembers]
  • [DynamicDependency]
  • [RequiresUnreferencedCode]
  • [UnconditionalSuppressMessage]
• [StackTraceHidden] (see here)
• [UnmanagedCallersOnly] (see docs))
• Platform support annotation attributes (see docs):
  • [ObsoletedOSPlatform]
  • [SupportedOSPlatform]
  • [SupportedOSPlatformGuard]
  • [TargetPlatform]
  • [UnsupportedOSPlatform]
  • [UnsupportedOSPlatformGuard]

Options ⚙️

PolySharp's generation can be configured through some MSBuild properties to set in consuming projects.

The following properties are available:

• "PolySharpUsePublicAccessibilityForGeneratedTypes": makes all generated types public.
• "PolySharpIncludeRuntimeSupportedAttributes": enables polyfills for (dummy) runtime-supported attributes too.
• "PolySharpExcludeGeneratedTypes": excludes specific types from generation (';' or ',' separated type names).
• "PolySharpIncludeGeneratedTypes": only includes specific types for generation (';' or ',' separated type names).