Owner Immo Landwerth
In .NET 5.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.
Sophia is building an application for Android. From her experience with
Xamarin.Android 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 'monoandroid' instead of the project target framework 'net6.0-android'. 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 .NET 6, but for the time being she's unblocked and can continue to develop her app.
- Support the definition of frameworks relevant for Xamarin development
- Re-design the TFM syntax
- MSBuild / SDK team
- NuGet team
- Project system team
- Xamarin team
| TFM | Compatible With |
|---|---|
| net6.0 | (subsequent version of net5.0) |
| net6.0-windows | (subsequent version of net5.0-windows) |
| net6.0-android | monoandroid |
| (+everything else inherited from net6.0) | |
| net6.0-ios | everything inherited from net6.0 (only) |
| net6.0-macos | everything inherited from net6.0 (only) |
| net6.0-maccatalyst | everything inherited from net6.0 (only) |
| net6.0-tvos | everything inherited from net6.0 (only) |
| net6.0-tizen | tizen |
| (+everything else inherited from net6.0) |
The built-in compatibility rules of the netX.Y-platform TFMs make a
TFM automatically compatible with:
- Itself
- Earlier versions of itself
- The corresponding
netX.YTFM - Earlier versions of the corresponding
netX.YTFM
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-android project referencing a NuGet package should behave as
follows:
- It should prefer
monoandroidassets overnetcoreapp,netstandard, andnet5.0assets.- However, it should still prefer
net6.0assets overmonoandroid. - It also shouldn't be compatible with any other existing Xamarin TFM (such
as
xamarin.mac)
- However, it should still prefer
- Generate NuGet warning NU1701 when a
monoandroidasset is being used- Package 'packageId' was restored using 'monoandroid' instead the project target framework 'net6.0-android'. This package may not be fully compatible with your project.
- Should only use compatible
net5.0based TFMs, namelynet5.0,net6.0, andnet6.0-android.
The net6.0-ios, net6.0-tvos and net6.0-macos TFMs are not compatible
with the previous xamarin* versions, because they contain breaking changes
that makes existing assets unusable.
This reasoning results in these precedence rules:
net6.0-ios
net6.0-iosnet6.0net5.0netcoreapp3.1–1.0netstandard2.1–1.0net4.x–1.0(warning)
net6.0-maccatalyst
net6.0-maccatalystnet6.0net5.0netcoreapp3.1–1.0netstandard2.1–1.0net4.x– `1.0 (NU1701 warning)
net6.0-macos
net6.0-macosnet6.0net5.0netcoreapp3.1–1.0netstandard2.1–1.0net4.x–1.0(NU1701 warning)
net6.0-tvos
net6.0-tvosnet6.0net5.0netcoreapp3.1–1.0netstandard2.1–1.0net4.x–1.0(NU1701 warning)
net6.0-android
net6.0-androidnet6.0monoandroid12.0-1.0(no warning)net5.0netcoreapp3.1–1.0netstandard2.1–1.0net4.x–1.0(NU1701 warning)
The currently supported monoandroid TFMs are:
monoandroid1.0monoandroid4.4monoandroid4.4.87monoandroid5.0monoandroid5.1monoandroid6.0monoandroid7.0monoandroid7.1monoandroid8.0monoandroid8.1monoandroid9.0monoandroid10.0monoandroid11.0monoandroid12.0
net6.0-tizen
net6.0-tizennet6.0tizen(no warning)net5.0netcoreapp3.1–1.0netstandard2.1–1.0net4.x–1.0(NU1701 warning)
We need to add platform detection APIs for Mac Catalyst:
namespace System
{
public partial class OperatingSystem
{
public static bool IsMacCatalyst();
public static bool IsMacCatalystVersionAtLeast(int major, int minor = 0, int build = 0);
}
}It seems the Xamarin team wants to have a single assembly with bindings for the
iOS platforms (e.g. Mac Catalyst and iOS). The APIs should be annotated with
[SupportedOSPlatform] and don't need any [UnsupportedOSPlatform] (the
absence of a platform is interpreted as the platform not being supported). For
instance:
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.
This is slightly different for cross-platform BCL APIs. Here we'd follow the path we took for Blazor WebAssembly and mark APIs that don't work in Xamarin with attributes like `[UnsupportedOSPlatform("iOS")].
We need to add RIDs for all these platforms:
net6.0-androidandroidandroid-armandroid-arm64android-x64android-x86android.21android.21-armandroid.21-arm64android.21-x64android.21-x86android.22android.22-armandroid.22-arm64android.22-x64android.22-x86android.23android.23-armandroid.23-arm64android.23-x64android.23-x86android.24android.24-armandroid.24-arm64android.24-x64android.24-x86android.25android.25-armandroid.25-arm64android.25-x64android.25-x86android.26android.26-armandroid.26-arm64android.26-x64android.26-x86android.27android.27-armandroid.27-arm64android.27-x64android.27-x86android.28android.28-armandroid.28-arm64android.28-x64android.28-x86android.29android.29-armandroid.29-arm64android.29-x64android.29-x86android.30android.30-armandroid.30-arm64android.30-x64android.30-x86
net6.0-iosiosios-armios-arm64ios-x64ios-x86ios.8ios.8-armios.8-arm64ios.8-x64ios.8-x86ios.9ios.9-armios.9-arm64ios.9-x64ios.9-x86ios.10ios.10-armios.10-arm64ios.10-x64ios.10-x86ios.11ios.11-arm64ios.11-x64ios.12ios.12-arm64ios.12-x64ios.13ios.13-arm64ios.13-x64ios.14ios.14-arm64ios.14-x64
net6.0-maccatalystmaccatalyst-arm64maccatalyst-x64maccatalyst.13-arm64maccatalyst.13-x64maccatalyst.14-arm64maccatalyst.14-x64
net6.0-macososxosx-arm64osx-x64osx.10.10osx.10.10-arm64osx.10.10-x64osx.10.11osx.10.11-arm64osx.10.11-x64osx.10.12osx.10.12-arm64osx.10.12-x64osx.10.13osx.10.13-arm64osx.10.13-x64osx.10.14osx.10.14-arm64osx.10.14-x64osx.10.15osx.10.15-arm64osx.10.15-x64osx.10.16osx.10.16-arm64osx.10.16-x64osx.11.0osx.11.0-arm64osx.11.0-x64
net6.0-tvostvostvos-arm64tvos-x64tvos.10tvos.10-arm64tvos.10-x64tvos.11tvos.11-arm64tvos.11-x64tvos.12tvos.12-arm64tvos.12-x64tvos.13tvos.13-arm64tvos.13-x64tvos.14tvos.14-arm64tvos.14-x64
net6.0-tizentizentizen-armeltizen-arm64tizen-x86tizen.4.0.0tizen.4.0.0-armeltizen.4.0.0-arm64tizen.4.0.0-x86tizen.5.0.0tizen.5.0.0-armeltizen.5.0.0-arm64tizen.5.0.0-x86tizen.5.5.0tizen.5.5.0-armeltizen.5.5.0-arm64tizen.5.5.0-x86tizen.6.0.0tizen.6.0.0-armeltizen.6.0.0-arm64tizen.6.0.0-x86tizen.6.5.0tizen.6.5.0-armeltizen.6.5.0-arm64tizen.6.5.0-x86
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.
Looks like Apple refers to it as "Mac Catalyst".
net6.0-ios (and the other Apple TFMs, net6.0-tvos and net6.0-macos)
contains breaking changes that makes binaries built for
existing Xamarin TFMs unusable.
The expectation is that 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