Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

.NET 6.0 TFMs #174

Merged
merged 24 commits into from
Feb 19, 2021
Merged

.NET 6.0 TFMs #174

Changes from 13 commits
Commits
Show all changes
24 commits
Select commit Hold shift + click to select a range
f42f327
Add initial draft for .NET 6.0 TFMs
terrajobst Feb 2, 2021
c616b42
Address minor feedback on wording
terrajobst Feb 5, 2021
ccf4f1c
Remove watchOS because we scoped this out from .NET 6
terrajobst Feb 5, 2021
95b11cb
Resolve open issues
terrajobst Feb 5, 2021
665cf78
Add section on APIs and RIDs
terrajobst Feb 5, 2021
24ee92c
Expand on RIDs
terrajobst Feb 5, 2021
7110009
Include RIDs for Android, macOS, iOS, and tvOS
terrajobst Feb 8, 2021
beb388e
There was no .NET Core 3.2 (ayayyay!)
terrajobst Feb 8, 2021
077eabd
Address Alexander's feedback
terrajobst Feb 8, 2021
d3d7d8c
Add section for platform annotations
terrajobst Feb 8, 2021
76d9135
Clarify merged vs. individual bindings
terrajobst Feb 8, 2021
ee14a32
Add user experience and requirement around Mac Catalyst and Xamarin iOS
terrajobst Feb 8, 2021
b953b89
Fix wording
terrajobst Feb 8, 2021
ae07c4a
Clarified annotations for bindings vs BCL APIs
terrajobst Feb 8, 2021
90bcc19
Add open question based on Frank's feedback
terrajobst Feb 8, 2021
13cb286
Fix typo
terrajobst Feb 8, 2021
589fbc4
Fix API name
terrajobst Feb 8, 2021
1d40848
Sort RIDs for Mac Catalyst to match the other platforms
terrajobst Feb 8, 2021
deec01a
Add iOS 14 and tvOS 14
terrajobst Feb 8, 2021
b199c76
Close italics
terrajobst Feb 9, 2021
0b22921
Clarify how xmarin.ios relates to net5.0 in Mac Catalyst
terrajobst Feb 12, 2021
c7aa606
List precedence rules for all new TFMs
terrajobst Feb 16, 2021
3cddc29
Update accepted/2021/net6.0-tfms/net6.0-tfms.md
terrajobst Feb 17, 2021
e9393d4
Include xamarin.macos and xamarin.tvos in precedence rules
terrajobst Feb 18, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
329 changes: 329 additions & 0 deletions accepted/2021/net6.0-tfms/net6.0-tfms.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,329 @@
# .NET 6.0 Target Frameworks

**PM** [Immo Landwerth](https://github.com/terrajobst)

In [.NET 5.0][net5.0] we defined a new syntax for target frameworks (TFM) that
makes it unnecessary for both tools and humans to use a decoder ring, such as
the .NET Standard version table, to figure out what is compatible with what. In
this document, we're listing which TFMs we're adding in .NET 6.0.

## Scenarios and User Experience

### Using an existing library in Mac Catalyst

Sophia is building an application for Mac Catalyst. From her experience with
Xamarin iOS she knows the library `Xamarin.FFImageLoading` and wants to use it.
The package installs successfully, but upon building she gets the following
warning:

> Package 'Xamarin.FFImageLoading' was restored using 'xamarin.ios' instead of
> the project target framework 'net6.0-maccatalyst'. This package may not be
> fully compatible with your project.

To find out more, she visits the package's project site, which is on GitHub. She
decides to file an issue to ask whether the library will add support for Mac
Catalyst, but for the time being she's unblocked and can continue to develop her
app.

## Requirements

### Goals

* Support the definition of frameworks relevant for Xamarin development
* Mac Catalyst is able to consume libraries built for Xamarin iOS, even though
the binary might not work. The developer should get a warning, but the tools
shouldn't block it.

### Non-Goals

* Re-design the TFM syntax

## Stakeholders and Reviewers

* MSBuild / SDK team
* NuGet team
* Project system team
* Xamarin team

## Design

| TFM | Compatible With |
|--------------------|------------------------------------------|
| net6.0 | (subsequent version of net5.0) |
| net6.0-windows | (subsequent version of net5.0-windows) |
| net6.0-android | xamarin.android |
| | (+everything else inherited from net6.0) |
| net6.0-ios | xamarin.ios |
| | (+everything else inherited from net6.0) |
| net6.0-macos | xamarin.mac |
| | (+everything else inherited from net6.0) |
| net6.0-maccatalyst | xamarin.ios |
terrajobst marked this conversation as resolved.
Show resolved Hide resolved
terrajobst marked this conversation as resolved.
Show resolved Hide resolved
| | (+everything else inherited from net6.0) |
| net6.0-tvos | xamarin.tvos |
| | (+everything else inherited from net6.0) |

### Compatibility rules

The [built-in compatibility rules][net5.0] of the `netX.Y-platform` TFMs make a
TFM automatically compatible with:

1. Itself
2. Earlier versions of itself
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe we should make it clear this list order does not correspond to precedence?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I believe it is the default precedence for a regular netX.Y-platform, no?

3. The corresponding `netX.Y` TFM
4. Earlier versions of the corresponding `netX.Y` TFM

The `net5.0` TFM has the additional twist that it's compatible with
`netcoreapp3.1` (and earlier), `netstandard2.1` (and earlier) as well as .NET
Framework (`net4x` and earlier, but under a warning). The .NET Framework
compatibility is achieved as a *fallback*, that is, it's only used when nothing
else applies.

We don't want to model the Xamarin TFMs as a fallback but instead want them to
apply **before** `netcoreapp` and `netstandard`. Usually the existence of the
Xamarin TFM implementation is to bait a `netstandard` API and switch the
platform specific implementation. Most of the Plugin type packages use this
pattern and in fact the `netstandard` "implementation" is more like a reference
assembly with just stubs that throw at runtime. `Xamarin.Essentials` is a good
example of this. The same rational can be applied to `netcoreapp` where this
would logically be the server implementation (or maybe a .NET Core 3.x desktop
implementation).

A `net6.0-maccatalyst` project referencing a NuGet package should behave as
follows:

* It should prefer `xamarin.ios` assets over `netcoreapp` and `netstandard`
assets.
- However, it should still prefer `net5.0`/`net6.0` assets over
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This seems wrong to me but it could be because I don't understand net5/6. Why would you ever want a less platform specific implementation over a more specific implementation? I would be very surprised to reference a library and find out it can't present UI because the net5/6 was chosen over ios version.

Copy link
Member Author

@terrajobst terrajobst Feb 8, 2021 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

xamarin.ios is the old Xamarin TFM. The assumption here is that if a package is updated, it should target iOS/Catalyst using the new TFMs (net6.0-ios and net6.0-maccatalyst respectively). One could argue that net5.0 should be handled like netcoreapp/netstandard but it seems easier to explain in terms of old world/new world and we generally treat net5.0 as that point.

@marek-safar @Redth what do you think?

Copy link

@praeclarum praeclarum Feb 8, 2021 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

OK, so the requirement is that if someone updates to net5/6 then they should update their iOS TFMs too? Logical, but not obvious. Gonna have to spread that tip to the community.

Copy link
Member Author

@terrajobst terrajobst Feb 8, 2021 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

OK, so the requirement is that if someone updates to net5/6 then they should update their iOS TFMs too? Logical but no obvious.

My assumption, and I could totally be wrong here, is that we probably won't support producing the old Xamarin TFMs from the new tooling. So I'd think once you upgrade the tools to .NET 6, you're naturally already on the new TFMs anyway, which means the confusion would disappear.

Of course, this might not be true for folks hand authoring their NuSpec.

Copy link

@praeclarum praeclarum Feb 8, 2021 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I feel like this migration is going to be much slower than you think. I anticipate a lot of my apps will be mixed for years and I would prefer nugets to keep working. I'm thinking there will be a lot of nugets out there with ALL these TFMs. That said, as long as the tooling doesn't regress on the old TFMs, that old code will keep working and it's not a problem.

Edit: @terrajobst I hand author all my nuspecs. 😅

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I’m pretty satisfied with the arguments here. It’s logical and @Redth seems to have the bases covered.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I get that there are arguments for preferring platform specific over generational compatibility, but another perspective is why is a fallback, something that might work, being preferred over something that will work.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I get that there are arguments for preferring platform specific over generational compatibility, but another perspective is why is a fallback, something that might work, being preferred over something that will work.

In this case the "something that will work" while technically correct from an API availability perspective, is not really true in practice since the net5.0 assets would not contain the platform specific 'switch' implementation that is required to be useful for these platforms. So, yes, maybe things compile, but at runtime they will throw or otherwise be completely unusable. In many cases in the Xamarin ecosystem, if there are xamarinios assets in a package, it is not just adding value on top of the netstandard assets, but rather it's a full bait and switch where the netstandard assets are really just considered a reference assembly with the public API contracts and stub implementations which throw at runtime.

My recommendations:

  • net6.0-maccatalyst prefers fallback path (in order) of: net6.0, xamarinios, netstandard
  • net6.0-ios prefers the fallback path (in order) of net6.0, xamarinios, netstandard
  • The fallback paths explicitly exclude net5.0 assets

Since Xamarin was never compatible in the net5 generation of TFM's and we're already seeing some packages (such as ReactiveUI) which ship assets for both net5.0 and xamarinios today, it's important that we don't prefer net5.0 assets over xamarinios. If you have a xamarinios project today you'll get xamarinios assets instead of net5.0 assets, and changing this for projects upgraded to net6.0-ios would break/change the expected behaviour.

Copy link
Member Author

@terrajobst terrajobst Feb 12, 2021 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • net6.0-maccatalyst prefers fallback path (in order) of: net6.0, xamarinios, netstandard

This makes sense. I have updated the spec accordingly.

  • net6.0-ios prefers the fallback path (in order) of net6.0, xamarinios, netstandard

That doesn't make sense to me. Why would we want to prefer net6.0 over xamarin.ios? I thought we'd want to treat xamarin.ios as the previous version of net6.0-ios, which is basically how netcoreapp relates to net5.0.

Copy link

@nkolev92 nkolev92 Feb 12, 2021 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm probably a bit pedantic, but we should avoid using the term fallback here.
Fallback is usually correlated with AssetTargetFallback, and this isn't that. Sounds like the ask is to have explicit compatibility between these frameworks.

`xamarin.ios`.
- It also shouldn't be compatible with any other existing Xamarin TFM (such
as `xamarin.mac`)
* Generate NuGet warning [NU1701] when a `xamarin.ios` asset is being used
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

From a NuGet perspective this would need to be hard-coded into the product, one of the designs of NET5 was for the SDK & runtime to be able to add new platform implementations without NuGet's support, but that can't be the case here.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agreed. As I said on email, I'm not particularly fond of this either. But I can get behind this because this doesn't introduce new crazy rules between the new TFMs but between a new TFM and an old TFM. I can justify that with our obligation to existing customers.

Copy link

@nkolev92 nkolev92 Feb 12, 2021 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If xamarin.ios is preferred over netcoreapp, I think that the warning is not ideal. Same reasoning as above applies, it's not really a fallback, it's just how compatibility is in this case.

Copy link
Member Author

@terrajobst terrajobst Feb 16, 2021 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The problem I see is this:

  1. Silently using the .NET Core assets is unlikely to result in a workable application due to bait & switch
  2. Silently using xamarin.ios, while having a higher chance of working, might not work either because Mac Catalyst isn't 100% compatible with iOS.

So it seems to me the precedence rules + warning is best user experience we can deliver.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Given 1, why not warn in the case of .NET Core assets older than 3.1 as well?

The thing that stands out to me is the following (actual names abstracted)

Given A:

A - works
A' - works
B - works (with a warning)
C - not likely to work (no warning).

I know it's an oversimplification, but just curious :)

Copy link
Member Author

@terrajobst terrajobst Feb 17, 2021 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's not that netcoreapp/netstandard assets wouldn't work in Mac Catalyst; it's that if a package offers both xamarin.ios and netcoreapp/netstandard then the likelyhood of netcoreapp/netstandard being the right one is low. IOW, its probability isn't just a function of the project TFM and a given offered TFM, it's about which TFM to pick given a set of TFMs. And that's what the precedence rules try to accommodate.

Does that make more sense?

- Package 'packageId' was restored using 'xamarin.ios' instead the project
target framework 'net6.0-maccatalyst'. This package may not be fully
compatible with your project.
* Should only use compatible `net5.0` based TFMs, namely `net5.0`, `net6.0`, and
`net6.0-maccatalyst`.
- Specifically, it should not accept `net6.0-ios`. The expectation is that
moving forward libraries that want to work on iOS and Mac Catalyst should
use `net6.0` or multi-target for `net6.0-ios` and `net6.0-maccatalyst`

## APIs

We need to add platform detection APIs for Mac Catalyst:

```C#
namespace System
{
public partial class OperatingSystem
{
public static bool IsMacCatalyst();
public static bool IsMacCatalystVersionAtLeast(int major, int minor = 0, int build = 0);
}
}
```

## Platform support annotations

It seems the Xamarin team wants to have a single assembly with bindings for the
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can we clarify the purpose of having a single assembly?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The point I was trying to make was less about a single assembly vs multiple but a having a combined set of bindings for Mac-based platforms. Is that not accurate?

iOS platforms (e.g. Mac Catalyst and iOS). The APIs should be annotated with
`SupportedOSVersionAttribute` and don't need any `UnsupportedOSVersionAttribute`
(the absence of a platform is interpreted as the platform not being supported).
For instance:

```C#
public class SomeType
{
[SupportedOSPlatform("ios8.0")]
[SupportedOSPlatform("maccatalyst13.0")]
public void MethodSupportedOn_iOS_and_Mac_Catalyst();

[SupportedOSPlatform("ios8.0")]
public void MethodSupportedOn_iOS_Only();

[SupportedOSPlatform("maccatalyst13.0")]
public void MethodSupportedOn_Mac_Catalyst_Only();
}
```

However, from a user experience it's irrelevant if the Xamarin team provides the
bindings in separate libraries or in a single library because there is no TFM
that developers can use to build a single binary that can work in both Mac
Catalyst and iOS. A developer either has to target Mac Catalyst (via
`net6.0-maccatalyst`) or iOS (via `net6.0-ios`). Of course, the developer can
multi-target for both but that means two binaries are being produced which means
the Xamarin bindings could also be provided as separate libraries.

## RIDs

We need to add RIDs for all these platforms:

* `net6.0-android`
- `android`
- `android-arm`
- `android-arm64`
- `android-x64`
- `android-x86`
- `android.21`
- `android.21-arm`
- `android.21-arm64`
- `android.21-x64`
- `android.21-x86`
- `android.22`
- `android.22-arm`
- `android.22-arm64`
- `android.22-x64`
- `android.22-x86`
- `android.23`
- `android.23-arm`
- `android.23-arm64`
- `android.23-x64`
- `android.23-x86`
- `android.24`
- `android.24-arm`
- `android.24-arm64`
- `android.24-x64`
- `android.24-x86`
- `android.25`
- `android.25-arm`
- `android.25-arm64`
- `android.25-x64`
- `android.25-x86`
- `android.26`
- `android.26-arm`
- `android.26-arm64`
- `android.26-x64`
- `android.26-x86`
- `android.27`
- `android.27-arm`
- `android.27-arm64`
- `android.27-x64`
- `android.27-x86`
- `android.28`
- `android.28-arm`
- `android.28-arm64`
- `android.28-x64`
- `android.28-x86`
- `android.29`
- `android.29-arm`
- `android.29-arm64`
- `android.29-x64`
- `android.29-x86`
- `android.30`
- `android.30-arm`
- `android.30-arm64`
- `android.30-x64`
- `android.30-x86`
* `net6.0-ios`
- `ios`
- `ios-arm`
- `ios-arm64`
- `ios-x64`
- `ios-x86`
- `ios.8`
- `ios.8-arm`
- `ios.8-arm64`
- `ios.8-x64`
- `ios.8-x86`
- `ios.9`
- `ios.9-arm`
- `ios.9-arm64`
- `ios.9-x64`
- `ios.9-x86`
- `ios.10`
- `ios.10-arm`
- `ios.10-arm64`
- `ios.10-x64`
- `ios.10-x86`
- `ios.11`
- `ios.11-arm64`
- `ios.11-x64`
- `ios.12`
- `ios.12-arm64`
- `ios.12-x64`
- `ios.13`
- `ios.13-arm64`
- `ios.13-x64`
* `net6.0-maccatalyst`
- `maccatalyst-arm64`
terrajobst marked this conversation as resolved.
Show resolved Hide resolved
- `maccatalyst.13-arm64`
- `maccatalyst.14-arm64`
- `maccatalyst-x64`
- `maccatalyst.13-x64`
- `maccatalyst.14-x64`
* `net6.0-macos`
- `osx`
- `osx-arm64`
- `osx-x64`
- `osx.10.10`
- `osx.10.10-arm64`
- `osx.10.10-x64`
- `osx.10.11`
- `osx.10.11-arm64`
- `osx.10.11-x64`
- `osx.10.12`
- `osx.10.12-arm64`
- `osx.10.12-x64`
- `osx.10.13`
- `osx.10.13-arm64`
- `osx.10.13-x64`
- `osx.10.14`
- `osx.10.14-arm64`
- `osx.10.14-x64`
- `osx.10.15`
- `osx.10.15-arm64`
- `osx.10.15-x64`
- `osx.10.16`
- `osx.10.16-arm64`
- `osx.10.16-x64`
- `osx.11.0`
- `osx.11.0-arm64`
- `osx.11.0-x64`
* `net6.0-tvos`
- `tvos`
- `tvos-arm64`
- `tvos-x64`
- `tvos.10`
- `tvos.10-arm64`
- `tvos.10-x64`
- `tvos.11`
- `tvos.11-arm64`
- `tvos.11-x64`
- `tvos.12`
- `tvos.12-arm64`
- `tvos.12-x64`
- `tvos.13`
- `tvos.13-arm64`
- `tvos.13-x64`

## Q & A

### Why didn't we name it `net6.0-macos-catalyst`?

We didn't want a secondary dash because it implies some relationship with
`net6.0-macos`. Also, in the past we talked about supporting prefix-based
compatibility rules with more levels, using a dash for this new TFM would make
it harder to add support for this later.

### Why didn't we name it `net6.0-catalyst`?

Looks like [Apple refers to it as "Mac Catalyst"](https://developer.apple.com/mac-catalyst/).

### Why did we make `net6.0-maccatalyst` compatible with the existing Xamarin TFMs?

It's true that for native code existing binaries don't work in Mac
Catalyst and that developers are generally expected to recompile. However, the
Xamarin team believes that enough managed code would just work that makes this
compat relationship useful. This follows the principle of the .NET Framework
compatibility mode which is:

> Instead of blocking things that might not work, unblock things that could
> work.

### Why didn't we make `net6.0-ios` compatible with `net6.0-maccatalyst`?

The expectation is that moving forward libraries that want to work on iOS and
Mac Catalyst would use `net6.0` or multi-target for `net6.0-ios` and
`net6.0-maccatalyst`

[net5.0]: ../../2020/net5/net5.md
[NU1701]: https://docs.microsoft.com/en-us/nuget/reference/errors-and-warnings/nu1701