Hide reference assemblies which are implementation detail only

[natemcmaster]

Follow-up to https://github.com/dotnet/corefx/issues/34906

Problem
It is sometimes useful to hide a reference assembly from the surface area of a shared framework. AspNetCore does not currently have a mechanism for doing this. Microsoft.NETCore.App excludes some reference assemblies even though implementations exist in the framework. IIUC this was done to provide the flexibility to change internal implementation details of the framework and maintain a consistent API contract. For instance, Microsoft.Win32.Registry.dll is in NETCore.App runtime, but hidden from the API surface because it will always throw on non-Windows platforms.

Proposal

• Review the API surface of AspNetCore.App and identify if there are assemblies in the framework which should be hidden from the API surface.
• If there are, add mechanisms to do this correctly. This would involve
  • Add a way to our projects to define which assemblies are hidden from the targeting pack
  • Ensure users can still opt-in to the hidden API.
  • Add tooling to ensure the API surface of AspNetCore.App is self-contained

Impact on consumers
If we hid API, users who still want to use it can opt-in by adding a package reference. For example, users targeting netcoreapp3.0 and NETCore.App can add a PackageReference to Microsoft.Win32.Registry to use its API.

Candidates
Without having thought through this much, here are some assemblies that we might consider hiding from the targeting pack.

• Microsoft.AspNetCore.Cryptography.Internal (API only meant for use internally by DataProtection)
• Microsoft.AspNetCore.Server.HttpSys (Windows only)
• Microsoft.AspNetCore.Server.IIS (Windows only)
• Microsoft.Win32.Registry.dll
• System.Security.AccessControl.dll
• System.Security.Cryptography.Cng.dll
• System.Security.Cryptography.Pkcs.dll
• System.Security.Cryptography.Xml.dll
• System.Security.Permissions.dll
• System.Security.Principal.Windows.dll

cc @davidfowl @DamianEdwards @ericstj @pakrym

[Eilon]

Let's discuss for preview6.

[Pilchie]

Putting into Preview 8, but it may be too late for this, as it would be a breaking change to remove these :(

[natemcmaster]

@Pilchie at this point, I would recommend closing this. I don't think there is much benefit to this, and it's more likely to cause problems.