.NET Standard API Reference

Question

UPDATE:

So it seems to be an open issue now. So I guess until this is done I will have to rely on .NET Core API reference and pray I won\'t hit one of the 43 API

Answer 1

I'm trying to find the .NET Standard API reference.

It's here. E.g., all the APIs for netstandard1.0. It's not as nice as the MSDN docs - yet. They're working on that. But if you want a list of specific APIs, it's there.

Their solution to this problem is to scan a given application?

Well, I think that's a lot easier than examining each line of your source code and looking it up in a document...

So if I start a new project, giving the fact that I don't have code written yet, I would target .NET Standard and pray I don't end up with unsupported APIs that are supposed to be?

If you target netstandard, you won't be able to call any APIs that aren't in your netstandard version. As a general rule, you should start by targeting netstandard1.0 and only move up if you need additional APIs.

Regarding "unsupported APIs", that's a completely different question. In that case, you're talking about a platform (like Xamarin.Android 7.0 or .NET 4.6.2) that declares support for a given netstandard version but throws NotSupportedException at runtime for some of the APIs. Unfortunately, that part of the story is very much TBD. What kind of tooling we'll have is still unknown at this point. There isn't anything today.

Also are there other cases like this in other frameworks like Xamarin or UWP?

Yes. Xamarin has always had this - they never fully supported the .NET APIs. UWP will have at least the same limitations as .NET 4.6.2.

What does that mean vNext exactly in the 2.0 column?

It means netstandard2.0 isn't going to be supported by the current versions of those platforms, but they're expecting to release a future version of those platforms that will support netstandard2.0.

Should I be worried of other unsupported APIs in other frameworks

At this point, I wouldn't worry. There will eventually be some kind of a story around detecting unsupported APIs. You can get pretty far today just by running APIPort as a post-compile step.

Answer 2

netstandard2.0 is mostly determined as netstandard1.6 plus those methods in mscorlib.dll, System.dll, or System.Core.dll in both the .Net Framework 4.6.1 and the current version of Xamarin. There are still small changes happening, which can be seen via the commit and PR history at https://github.com/dotnet/standard/

The methods that existed in netstandard1.6 but aren't in .NET 4.6.1 were marked as not visible to intellisense to prevent confusion from new developers. But they do exist, so you can successfully compile if you write the code anyways. That was the compromise attained for "but it won't work on netfx" and "but I can't upgrade my netstandard1.6 library".

Answer 3

There is a fine web page maintained by a PM for the BCL (Immo Landwerth). It shows all APIs, their current implementations in all imaginable platforms (.NET Framework, .NET Core, UWP, Mono, ...) and their status in the .NET Standard Versions including the plan for 2.0.

http://apisof.net (sample for List)

Hope that helps. The fact that the standard based library may throw in certain edge cases is unfortunate. I guess there will be some tooling around it.

Delta between 1.4 and 1.5: https://github.com/dotnet/standard/blob/master/docs/versions/netstandard1.5_diff.md

Delta between 1.5 and 1.6: https://github.com/dotnet/standard/blob/master/docs/versions/netstandard1.6_diff.md

Do not worry so much about the 4.6 vs 4.6.2 issue. When I remember right they will address this issue.

About the concern regards drawing: indeed the most annoying problem. System.Drawing is based on GDI and therefore not available everywhere. There are alternatives for common task. Do not forget, that most rendering is client stuff and therefore not exactly a use case of the standard but more of an concrete app model.

Answer 4

As Martin mentioned it in his comment, the .NET API Browser is exactly what I was looking for a while ago.

You can select and filter with the .NET standard API or any Framework implementation and even select any version. That's perfect, Microsoft should have made this earlier.