.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 APIs that .NET Framework 4.6.1 doesn't support but are officially supposed to be...

Also relying on .NET Core API reference and considering the same as .NET standard could be badly surprising. For example when I take a look at the namespace list I can see System.Drawing but when clicking on it, we then realize this is an almost empty namespace containing only 6 structures.

Are there several namespaces like this? I don't know, I have to compare .NET core and .NET Framework documentation to get the answer.

ORIGINAL POST:

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

On this page there are only links to .NET Core API reference and .NET Framework API reference.

Yes I've searched and I've read others SO questions. For example this answer points to .NET Core API reference instead of .NET standard and the same in this Github issue feed

But .NET Core and .NET Standard are different. .NET Core is the implementation of .NET Standard APIs.

One of the big problem I see here is for example based on the official documentation .NET Framework 4.6.1 will implement .NET Standard 2.0

Ok great, except that the .NET Standard Github readme page is also saying

On the other hand, .NET Standard 2.0 adds many APIs that .NET Framework 4.6.1 already supports. The delta looks as follows:

• .NET Standard 2.0 adds 14,994 APIs that .NET Framework 4.6.1 already supports

• .NET Standard 2.0 only has 43 APIs that .NET Framework 4.6.1 doesn't support Originally, we planned to simply elide those APIs from .NET Standard 2.0 in order to make it easier to understand what will work on .NET Framework 4.6.1.

However, we got a lot of feedback around this. You told us that this decision makes it really hard to reason about .NET Standard versioning rules. Thus, we decided to simplify this:

• .NET Standard 2.0 will be a strict superset of .NET Standard 1.6. In other words, no breaking changes will happen between .NET Standard 2.0 and 1.x.

• .NET Framework 4.6.1 will allow referencing binaries that are compiled against .NET Standard 2.0. Considering the number of APIs that .NET Framework 4.6.1 will not support is low and that these are all brand-new APIs with low adoption we believe this is a much better trade-off.

You can use API Port to scan a given application to make sure no code in your application depends on these APIs.

So what? Their solution to this problem is to scan a given application? 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?

Also, are there other cases like this in other frameworks like Xamarin or UWP? What does that mean vNext exactly in the 2.0 column? Should I be worried of other unsupported APIs in other frameworks because Considering the number of APIs that [Framework name] will not support is low and that these are all brand-new APIs with low adoption we believe this is a much better trade-off?

The closest answer I can find to this question is by looking at the NETStandard.Library NuGet package's dependencies. However that gives me dependencies of the 1.3 version (not 1.6 or I don't really understand this section), and that doesn't give me APIs reference of the next 2.0 which are supposed to be already determined.

Can't we have a full documented list of APIs really supported for each .NET Standard version? The only goal of .NET Standard is to provide developers this very important information, so why can't I find it?

Answer 1

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 2

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 3

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.

Answer 4

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".