.NET release notes Xcode 13.3

We're excited to announce our first SDK release for .NET! After many years of work we've moved to .NET, where among other things we'll get an updated Base Class Library, which is unified across all .NET platforms.

Note: these are the base SDKs that add support for the platforms in question, if you are looking for .NET MAUI (which is built on top of our SDKs), go here instead: https://docs.microsoft.com/en-us/dotnet/maui/.

Getting Started | What's New | Known Issues | Feedback | FAQ

Requirements

It's highly recommended to use Xcode 13.3+ (which requires macOS 12.0 (Monterey)). Earlier versions of Xcode may work, but some featuers won't be available.

With the release the minimum supported OS versions can be targeted for apps:

• iOS: 10.0
• macOS: 10.14
• tvOS: 10.0
• Mac Catalyst: 13.1

Note: while we support macOS 10.14, we're only testing on OS versions that Apple supports. At the time of this writing this means we're only testing on macOS 11.0+.

Getting started

In contrast to how Xamarin.iOS and Xamarin.Mac were shipped (as installable *.pkg files), our .NET SDKs are shipped as workloads in the .NET world. This means that the first step is to getting started is to install .NET 6.0.300 (or later).

Then install the workload corresponding with the desired platform:

$ dotnet workload install ios # other workloads: macos, tvos, and maccatalyst

Create new app from a template with:

$ dotnet new ios # 'dotnet new --list --tag Mobile' will show all available templates

Finally build and run the new app in the simulator

$ dotnet run

What's New in this Release

This release contains SDKs for the following four platforms: iOS, tvOS, Mac Catalyst and macOS, and has support and bindings for the OS versions that were shipped with Xcode 13.3:

• iOS 15.4
• macOS 12.3
• tvOS 15.4
• Mac Catalyst 15.4

Compared to the current Xamarin.iOS and Xamarin.Mac release, we've also:

• Added support for arm64 in the iOS and tvOS simulator when running on an ARM64-capable Mac.
• Added support for arm64 for macOS projects. Note that the default is to always build for x64, to build for arm64 set the runtime identifier to osx-arm64:

<RuntimeIdentifier>osx-arm64</RuntimeIdentifier>

Notable Changes

Removed OpenTK dependency

We've removed the dependency on OpenTK, a long-standing community request: https://github.com/xamarin/xamarin-macios/issues/13160

.NET linker / trimmer

.NET 6 ships with a linker which is shared between all platforms. This linker is very similar to the linker in Xamarin.iOS and Xamarin.Mac (it has the same origin), but since it's used by more platforms across Microsoft, it will be updated and improved much more.

For compatibility reasons most of the old linker modes continue to work as-is: LinkSdk, None and Full. Most of the old linker modes still work with the exception of "Platform" mode for macOS. "LinkSdk", "None" and "Full" are still available for all platforms. manual mode is also available.

macOS

The macOS SDK is using the CoreCLR runtime instead of the Mono runtime.

There are a few known incompatibilities between CoreCLR and Mono, those are listed here.

Mac Catalyst

We've added support for Mac Catalyst. Use the net6.0-maccatalyst target framework to create a Mac Catalyst app.

Conditional compilation symbols

Because iOS and Mac Catalyst are so close API-wise, we define both __IOS__ and __MACCATALYST__.

System version

The system version for Mac Catalyst (as returned by UIDevice.CurrentDevice.SystemVersion) is the macOS version the app is executing on.

However, the helper method UIDevice.CurrentDevice.CheckSystemVersion takes the corresponding iOS version (like the .NET availability API does).

Exception marshalling is enabled by default

We've enabled exception marshalling by default, because it prevents numerous potential problems (crashes, memory corruption, memory leaks, etc.)

However, there is a performance difference when calling into Objective-C code. In the future we'll make it possible to avoid this performance difference (at the cost of a slightly bigger app), but in the meantime it's possible to disable Objective-C exception marshalling by adding the following property to a PropertyGroup in your project file:

<MtouchExtraArgs>--marshal-objectivec-exceptions:disable</MtouchExtraArgs>

Release History

First release!

Breaking Changes

See Breaking Changes

Known Issues

See Known issues in .NET

Feedback

File issues here: https://github.com/xamarin/xamarin-macios/issues/new.

Frequently Asked Questions

What will happen with the old-style Xamarin.iOS and Xamarin.Mac products?

We'll continue to ship Xamarin.iOS and Xamarin.Mac separately for a while, but they will eventually be discontinued.

More information will be provided later.

How to publish from the command line

This will create an *.ipa (for iOS and tvOS) or *.pkg (for macOS and Mac Catalyst) for publishing to the App Store:

$ dotnet publish

How to create a universal app with support for multiple architectures

We support creating universal apps for the following platforms:

• iOS: ARMv7 + ARM64.
• macOS: x86_64 + ARM64.
• Mac Catalyst: x86_64 + ARM64.

In order to create a universal app, set the RuntimeIdentifiers property (plural, don't confuse with RuntimeIdentifier) to the corresponding runtime identifiers. For instance for macOS, that would be:

<PropertyGroup>
    <!-- for macOS -->
    <RuntimeIdentifiers>osx-x64;osx-arm64</RuntimeIdentifiers>
    <!-- for Mac Catalyst -->
    <RuntimeIdentifiers>maccatalyst-x64;maccatalyst-arm64</RuntimeIdentifiers>
    <!-- for iOS -->
    <RuntimeIdentifiers>ios-arm;ios-arm64</RuntimeIdentifiers>
</PropertyGroup>

How to set the Mac idiom for Mac Catalyst apps

Set the UIDeviceFamily value in the project's Info.plist to 6:

<key>UIDeviceFamily</key>
<array>
    <integer>6</integer>
</array>

Ref: https://github.com/xamarin/xamarin-macios/issues/14621