Skip to content

.NET 8 release notes

Jump to bottom
Rolf Bjarne Kvinge edited this page Dec 7, 2023 · 19 revisions

We're excited to announce our .NET 8 SDK release!

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

Versions

This release consists of the following versions:

Requirements

It's highly recommended to use Xcode 15.0+ (which requires macOS 13.5 (Ventura)). Earlier versions of Xcode may work, but some features won't be available.

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

  • iOS: 11.0
  • macOS: 10.15
  • tvOS: 11.0
  • Mac Catalyst: 13.1

Note: while we support macOS 10.15, 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+.

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 8.0.100 (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 15.0:

  • iOS 17.0
  • macOS 14.0
  • tvOS 17.0
  • Mac Catalyst 17.0

What's Changed

Xcode 15

We've added support for Xcode 15 + many new APIs in iOS 17, tvOS 17, macOS 14 and Mac Catalyst 17.

Default RuntimeIdentifier(s)

The default runtime identifier(s) have changed:

  • Simulator (iOS, tvOS): if the Mac's an ARM64 machine, then iossimulator-arm64/tvossimulator-arm64. Otherwise (if it's an x86_64 Mac) then iossimulator-x64/tvossimulator-x64.
  • Device (iOS, tvOS): no change (there's only one runtime identifier for device anyways, ios-arm64/tvos-arm64).
  • Desktop: if building for Debug, and the Mac's an ARM64 machine, then osx-arm64/maccatalyst-arm64. If building for Debug, and the Mac's an x86_64 machine, then osx-x64/maccatalyst-x64. If building for Release, the default stays the same as in .NET 7 (a universal build, osx-x64;osx-arm64 and maccatalyst-x64;maccatalyst-arm64).

The default can be overridden using the RuntimeIdentifer property (when targeting a single runtime identifier) or the RuntimeIdentifiers property (when creating a universal build consisting of multiple runtime identifiers):

<PropertyGroup>
    <RuntimeIdentifiers>osx-x64;osx-arm64</RuntimeIdentifiers>
</PropertyGroup>

Overriding the default might be necessary sometimes, in particular for projects that use third-party native bindings that don't contain an arm64 slice for the simulator.

Known NuGets that don't contain the arm64 slice for the simulator:

Known NuGets that have recently added the arm64 slice for the simulator:

There are two caveats:

  • When building remotely from the command line on Windows, the architecture detection will use the architecture of the Windows machine (because the RuntimeIdentifier has to be set early in the build process, before the build can connect to the Mac to figure out its architecture).

  • When building remotely using Visual Studio on Windows, the IDE will detect the architecture of the remote Mac and set it accordingly. Overriding the default can be done by setting the ForceSimulatorX64ArchitectureInIDE property:

    <PropertyGroup>
  <ForceSimulatorX64ArchitectureInIDE>true</ForceSimulatorX64ArchitectureInIDE>
</PropertyGroup>

Ref: https://github.com/xamarin/xamarin-macios/pull/18495

RuntimeIdentifier when publishing

In previous versions of .NET, we required setting a RuntimeIdentifier manually when publishing (dotnet publish) for mobile apps. In .NET 8, we're now choosing the following default RuntimeIdentifier:

  • iOS: ios-arm64
  • tvOS: tvos-arm64

For Mac Catalyst and macOS we'll continue to select the RuntimeIdentifier(s) based on the Configuration as above (note that in .NET 8 dotnet publish defaults to the Release configuration).

NativeAOT

We've added experimental support for using NativeAOT when publishing iOS, tvOS, Mac Catalyst and macOS apps in .NET 8.

Our initial testing shows significant improvements both in size (up to 50% smaller) and startup (up to 50% faster), so we're encouraging developers to try it out and report back their findings.

More information about our NativeAOT support can be found here.

Managed Static Registrar

We've implemented a new registrar, mainly to support NativeAOT, since the existing registrars used features NativeAOT didn't support. This new registrar will typically be faster than the existing static registrar, especially when calling an exported managed method from Objective-C, but the exact performance characteristics will vary between apps.

For the adventurous soul, here's how to select the new registrar for device builds:

<PropertyGroup>
  <Registrar Condition="!$(RuntimeIdentifier.Contains('simulator'))">managed-static</Registrar>
</PropertyGroup>

The managed static registrar is currently released as a preview feature, but we hope to eventually be able to replace the existing (old) static registrar.

Note: the managed static registrar is the only registrar available when using NativeAOT (and will be selected by default in that case).

More documentation about the managed static registrar can be found here.

New Contributors

Changelog

Full changelog

Full Changelog: https://github.com/xamarin/xamarin-macios/compare/dotnet-7.0.3xx-7125...dotnet-8.0.1xx-8478

Breaking Changes

The 'createdump' utility is no longer bundled by default in macOS projects.

The 'createdump' utility (used for creating crash dumps) is no longer bundled by default in macOS projects, it's now opt-in by using the property BundleCreateDump:

<PropertyGroup>
  <BundleCreateDump>true</BundleCreateDump>
</PropertyGroup>

This is only applicable to macOS projects.

Ref: https://github.com/xamarin/xamarin-macios/pull/18960

Dropped support for 32-bit iOS architectures

The latest iOS version that supported 32-bit CPUs was iOS 10.3, and since the earliest iOS version we support in .NET 8 is iOS 11, we've dropped support for the 32-bit ios-arm and iossimulator-x86 runtime identifiers.

Known Issues

See Known issues in .NET 8.

FAQ

How to run on Device/Simulator from the command line

The general process is documented here:

https://docs.microsoft.com/en-us/dotnet/maui/ios/cli

but does not include running on an attached device.

To do that, include -p:RuntimeIdentifier=ios-arm64, along with the other parameters.

dotnet build -t:Run -f:net7.0-ios -p:RuntimeIdentifier=ios-arm64 -p:_DeviceName=MY_SPECIFIC_UUID

with MY_SPECIFIC_UUID found as described here but for your device.

Note that this does not work from Windows, only from a Mac.

Feedback

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

Contributing

Bindings

Tips & tricks

Clone this wiki locally