Migration criteria

[carlossanlop]

The purpose of this issue is to provide a clear explanation of the requirements a library needs to meet in order to qualify to migrate to dotnet/maintenance-packages.

Migration criteria

As described in the main README, we want this repo to be the new home of those OOB assemblies that are still in support but currently get built in a repo and branch that is out of support.

The minimum TFMs currently under support are:

• .NET Framework 4.6.2
• .NET Standard 2.0
• .NET 6.0

We found that we have created a total of 241 OOB assemblies starting in .NET Core 1.0 and up to .NET 5.0. We then filtered those packages based on the following criteria:

• At least one of the TFMs the package targets is still under support.
• The component is not being built out of main or a branch that is still serviced (.NET 6, .NET 7 and .NET 8).
• Of the supported TFM folders inside the nuget package, at least one of them does not contain just a placeholder "_._" file.
• The assembly contains an actual source code implementation.
  • The implementation is complex enough that could potentially require servicing (for example, it does not just contain extensions methods).
  • The assembly is not a pure façade.
  • The assembly is not just a ref assembly.
  • The assembly APIs are not just throwing PlatformNotSupportedException.
• When consuming the nuget package out of a console app targeting the supported TFMs of the assembly, at least one of them consumes the implementation from the package instead of ignoring it and consuming the one from the installed SDK.

Migration candidates

The criteria above helped us narrow down the list of OOB packages to migrate to dotnet/maintenance-pakages to a total of 17:

OOB Assembly	Last shipped in	Status
Microsoft.Bcl.HashCode	3.1	Migrated
Microsoft.IO.Redist	6.0	Migrated
System.Buffers	2.1	Migrated
System.Data.SqlClient	3.1	Migrated
System.Json	3.1	Migrated
System.Memory	2.1	Migrated
System.Net.WebSockets.WebSocketProtocol	5.0	Migrated
System.Numerics.Vectors	2.1	Migrated
System.Reflection.DispatchProxy	3.1	Migrated
System.Runtime.CompilerServices.Unsafe	6.0	Migrated
System.Threading.Tasks.Extensions	2.1	Migrated
System.Xml.XPath.XmlDocument	1.1	Migrated

Additionally, the next 3 assemblies target .NET Framework 4.6.2, and they contai extension methods with simple implementations. We are also including them in the migration candidate list, but with lower priority:

OOB Assembly	Last shipped in	Status
System.IO.FileSystem.AccessControl	5.0
System.IO.Pipes.AccessControl	5.0
System.Reflection.TypeExtensions	3.1

[Romfos]

Hello,

what about:

• Microsoft.CSharp
• System.ValueTuple

?

thank you

[carlossanlop]

Hi @Romfos, great questions:

• The Microsoft.CSharp nuget package has a netstandard2.0 implementation, but it is not used by any of the currently supported frameworks.
• The System.ValueTuple nuget package has a .NET Framework implementation, but it is ignored because there is an in-box façade.

[Romfos]

yea, but these packages are used as transitive dependencies

System.ValueTuple:

• This is included in .NET 4.7, but not in 4.6.2, if i right understand, and still used as transitive dependency for multiple package by this reason

Microsoft.CSharp:

• This is included in net FX (but require reference) and .NET Core, but not included in NS 2.0 (lol) and by this reason also often used as transitive dependency

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <TargetFrameworks>net462;net6.0;netstandard2.0</TargetFrameworks>
  </PropertyGroup>

  <ItemGroup Condition="'$(TargetFramework)' == 'net462'">
    <Reference Include="Microsoft.CSharp" />
  </ItemGroup>

</Project>

namespace ClassLibrary1
{
    public class Class1
    {
        static dynamic x = 1;
        static dynamic y = 2;
        static dynamic z = x + y;
    }
}

error:
error CS0656: Missing compiler required member 'Microsoft.CSharp.Ru
ntimeBinder.CSharpArgumentInfo.Create' [E:\dev\ClassLibrary1\ClassLibrary1\ClassLibrary1.csproj::TargetFramework=netsta
ndard2.0

[ViktorHofer]

This is included in net FX (but require reference) and .NET Core, but not included in NS 2.0 (lol) and by this reason also often used as transitive dependency

NS 2.0 is an API contract, not a runtime. As @carlossanlop mentioned above, assemblies from the (transitively) referenced Microsoft.CSharp package are ignored at run time as the assembly inside the framework is preferred. They are not even passed to the compiler on officially supported .NET or .NET Framework versions, as the assembly inside the framework wins over the package asset.

You can observe that behavior when running an application that (transitively) references Microsoft.CSharp. You will see that the assembly from the package never gets loaded.

This is included in .NET 4.7, but not in 4.6.2, if i right understand, and still used as transitive dependency for multiple package by this reason

System.ValueTuple indeed needs to be referenced on the lowest in supported .NET Framework version: 4.6.2 as the API got added afterwards. @carlossanlop you might want to re-evaluate System.ValueTuple here. The package implementation is used on .NET Framework 4.6.2. That said, it might fall under the following non criteria:

The implementation is complex enough that could potentially require servicing (for example, it does not just contain extensions methods).

[ericstj]

ValueTuple was absorbed into the .NETStandard 2.0 support SDK (Microsoft.NET.Build.Extensions). Separately it might be worthwhile to investigate the serviceability of Microsoft.NET.Build.Extensions, the packages that may overlap it, on all the supported frameworks that still require it.

[carlossanlop]

@Romfos we are in the early stages of writing a proper support policy document exclusively for nuget packages. Since you had good questions relevant to this topic, would you mind taking a look at that document PR and sharing your thoughts? We want to make sure the essential questions that come up to customers are easily answered in such document: dotnet/core#9206

[ViktorHofer]

@carlossanlop can you please update the table above if there are more packages that will be migrated? I'm just curious what the plan is and I think it makes sense to keep the community updated given that we got some initial feedback in this thread. Thanks

[carlossanlop]

Closing this issue as all the main OOBs have been successfully migrated. When the time comes, we can open another issue with an updated list of additional packages we would like to migrate.