As a developer, I get compile time diagnostics for unsupported APIs

[terrajobst]

In .NET 5, we introduced a built-in platform analyzer that will check whether you call platform-specific APIs. However, this doesn't cover APIs that always throw PlatformNotSupportedException. We should mark those APIs in some fashion as well, for example, by applying ObsoleteAttribute.

We should make sure whatever mechanism we choose for detecting those APIs, that the docs also reflect this.

An example of an unmarked APIs is CSharpCodeGenerator.CreateFromBatch().

[danmoseley]

@jeffhandley is this one something you're going to drive? If so we can set you or someone as assignee I think.

[jeffhandley]

As was mentioned in #42967, we have over 4000 instances of throwing PlatformNotSupportedException. We would need to review that list and for each occurrence determine:

1. Should there be a [SupportedOSPlatform] or [UnsupportedOSPlatform] attribute applied?
   • This would apply if the member is statically (un)supported on specific platforms
   • But this cannot be used if support is conditional, unless Developers need more flexibility to annotate their code for platform supported/unsupported scenarios to reduce issues warnings noise #44922 is addressed
2. Should there be an [Obsolete] attribute?
   • This would apply if the member is no longer supported in .NET, regardless of platform

I suspect we'd want to divide this list up by area so that owners across the areas could review and address the instances in their areas. That could be done either before or after the implementation of an analyzer.

We were pondering in #42967 whether or not an analyzer for doing this would be valuable beyond the runtime team, or if this is one we should build directly into the runtime repo. I'm unsure on that myself.

[terrajobst]

Talked to @jeffhandley today. #42967 is really about us finding the issues; while that's useful that's not actually what this issue is about. This issue is about the user's experience when they call such an API. They should get a warning.

[jeffhandley]

#44916 is also filed, and this one would involve reviewing the 4000 occurrences of PNSE that exist.

[buyaa-n]

2. Should there be an [Obsolete] attribute?
   • This would apply if the member is no longer supported in .NET, regardless of platform

If we apply for those [Obsolete] attribute what we would do in case the API get supported on any of the OS in .Net core? For example i see an issue for adding support for the CSharpCodeGenerator.CreateFromBatch(). Can we remove the attribute?

[buyaa-n]

Could not we use the [SupportedOSPlatform] or [UnsupportedOSPlatform] attributes with framework names (with optional version)? (especially in case we want the PCA analyzer warn for their usages)

For example, by my understanding the above CSharpCodeGenerator.FromFileBatch() API is unsupported on .NetCore (or it is only supported on .Net framework)

[UnsupportedOSPlatform("netcoreapp")] //[UnsupportedOSPlatform("All")]
// or [SupportedOSPlatform("net46")]
private CompilerResults FromFileBatch(CompilerParameters options, string[] fileNames)
{
    throw new PlatformNotSupportedException();
}

[buyaa-n]

[Brief Meeting Note]:
We have 3 options for handling APIs not supported in .NetCore but having open issue for future support:

1. If we decide not to support the API we can close the related issue and add [Obsolete] to the API
2. Add support for AllPlatforms scenario to PCA analyzer and annotate the API with [UnsupportedOSPlatform("AllPlatforms")]
3. Leave the API un annotated until we decide if we really gonna add support for this

For the 2 API we discussed in the meeting, Regex.RegexAssemblyCompiler() and CodeDom.CSharpCodeGenerator we are leaving them unannotated until we decide to not support for sure. (Did not choose option 2 because there are too few cases found, only 2 for now)

[krwq]

@buyaa-n what's the current status of this?

[buyaa-n]

@buyaa-n what's the current status of this?

Previously detected PNSEs on cross-platform builds and filed issues with findings, yesterday started the work detecting PNSEs on targeted builds and will file/update issues with findings. Overall this issue will cover the detecting PNSEs and that work will be done within 6.0. But some of the related issues might not make 6.0, depends on the area owners

[buyaa-n]

My PNSE analysis is done and most findings are reported with separate issues referenced above. There is few APIs having an issue for future support which we decided not to annotate, for now, I did not file issue for them since the discussion we had in #50535. Here is the list of those APIs:

Assembly	API	Progress	Issue for support
System.CodeDom	'CSharpCodeGenerator.FromFileBatch(CompilerParameters, string[])' unconditionally throws PNSE, VB version too	No progress	#18768
System.Text.RegularExpressions	'RegexAssemblyCompiler.Save()' throws PNSE and has no annotation	No progress	#19838
System.Configuration.ConfigurationManager	'RsaProtectedConfigurationProvider' all APIs unconditionally throws PNSE	in PR	#19838

Some of them were missing info in the doc that they are not supported in .Net Core, a PR for updating them is up

With that, I think we can close this issue now what do you think @terrajobst @jeffhandley?

[jeffhandley]

Thanks, @buyaa-n!