Target Framework

Selecting the Correct Base Class Library (BCL) for Xamarin.Mac

PDF for offline use
Related Articles:

Let us know how you feel about this

Translation Quality


0/250

last updated: 2017-03

This article covers the types of Target Frameworks (Base Class Libraries) that are available in Xamarin.Mac and the implications of selecting a specific target for your Xamarin.Mac application.

Overview

When creating a new Mac application or library using Xamarin.Mac, you now have the choice of targeting either the Classic or Unified APIs as follows:

  • Classic API - This is the traditional Xamarin.Mac API that uses a namespace prefixed with MonoMac, supports the 32-bit architecture only and optionally uses the mmp packager. If possible, this API should only be used when supporting applications that need to target older versions of macOS (formerly known as Mac OS X) or hardware that cannot be upgraded to the new API.
  • Unified API - This is the new, modern API (introduced in Xamarin.Mac 1.10 and becoming stable in version 2.00) that drops the MonoMac prefix from the namespace, supports both the 32 and 64 bit architectures and requires the use of the mmp packager. If possible, all new Xamarin.Mac projects should use this version of the API and existing projects should be converted to the Unified API.

Additionally, when using the Unified API, the developer will need to select the correct Target Framework that fits their application's needs. This article covers the types of Target Frameworks available to a Unified API Xamarin.Mac project and the implications of selecting each of the given framework types.

For more information on the different between the Classic and Unified API types, please see our iOS and Mac Code Sharing and Unified API documentation.

Background

Every .NET program or library needs to target some version of the Base Class Library (BCL). This is where it pulls copies of assemblies such as System.dll, that provide the common functionality built into all .NET languages. There are multiple versions of these Target Frameworks (BCLs) in existence, several of which are subsets of other, full desktop frameworks. Given this fact, it is possible for a .NET application to be targeting a different BCL than a library that it is trying to consume.

One of the more important repercussions of choosing a Target Framework, is that all of the assemblies in a given program must target compatible BCLs. If this was not the case, you could have two assemblies linked against different versions of the System.dll assembly that might provide either different or missing functionality required by the other, consuming assembly.

Whenever possible, a Unified API Xamarin.Mac application should use the Mobile Target Framework used by Xamarin.iOS and Xamarin.Android (also known as the Xamarin.Mac Mobile Framework in Xamarin.Mac). This frameworks is a subset of the full Desktop framework, stripping out bits such as System.Configuration and System.ServiceProcess that are large, rarely used or are of no use in a mobile application environment. It also lets Xamarin do additional link time optimization during packing to further reduce your application's deliverable size.

However, there are situations where your Xamarin.Mac application might need to consume 3rd party .NET assemblies found on the web or downloaded from a NuGet repository. If these assemblies are targeting the full Desktop framework, then you will not be able to use the Xamarin.Mac Mobile Framework in your Xamarin.Mac Unified application.

To support 3rd party .NET assemblies, Xamarin added the Xamarin.Mac .NET 4.5 Framework which allows you target existing full desktop assemblies. Just like the Mobile framework, it doesn’t include the full BCL subset and is missing large, rarely used elements, such as System.Configuration and System.ServiceProcess. By choosing this option however, you lose the additional link time optimization that the Xamarin.Mac Mobile Framework provides.

Finally, if the Xamarin.Mac .NET 4.5 Framework will not work because of a missing element, you still have the option of selecting the original Mono .NET Desktop Framework (as used in the Classic API) for your Unified API Xamarin.Mac applications. However, this is not officially supported by Xamarin since it can cause problems when using the Unified API with a large number of 3rd party NuGet packages in a Xamarin.Mac project.

All three Target Framework types will be discussed in detail in the follow section.

⚠️

NOTE: An empty, stubbed-out version of the System.Configuration API has been included in Xamarin.Mac to avoid breaking some 3rd-party PCL files. So while the namespace is included, it is non-functional and should never be used in a Xamarin.Mac project.

Target Framework Types

As discussed in the Background section, there are three types of Target Frameworks that can be selected when using the Unified API in a Xamarin.Mac application:

  • Xamarin.Mac Mobile Framework - As stated above, this is the same tuned .NET framework used by Xamarin.iOS and Xamarin.Android supporting a subset of the full Desktop framework. This is the recommended framework because it provides smaller average binaries due to superior linking behavior.
  • Xamarin.Mac .NET 4.5 Framework - This framework is again, a subset of the Desktop framework. However, it trims off far less of the full Desktop framework than the Mobile framework and should "just work" with most NuGet Packages or 3rd party libraries. This allows the developer to consume standard Desktop assemblies while still using a supported framework, but this option produces larger application bundles. This is the recommended framework where 3rd party .NET assemblies are being used that are not compatible with the Xamarin.Mac Mobile Framework. For a list of supported assemblies, please see our Assemblies documentation.
  • Unsupported Framework - Selecting this option allows the developer to link against either the Mono .NET Desktop Framework or the standard .NET Desktop Framework to support legacy applications, however this is not officially supported by Xamarin. Migrating to one of the other supported Target Frameworks is highly suggested.

The type of Target Framework that you will select for your Xamarin.Mac application will be based on the type of 3rd party libraries or NuGet Package it is consuming, if any.

Setting the Target Framework Type

To change to the Target Framework type for a Xamarin.Mac project, do the following:

  1. Open the Xamarin.Mac project in Xamarin Studio.
  2. In the Solution Explorer, double-click the project file to open the Project Options dialog box.
  3. From the General tab, select the type of Target Framework that suits your application's needs:

  4. Click the OK button to save your changes.

You might need to do a Clean and then Rebuild your Xamarin.Mac project after switching the Target Framework type.

Migrating to the Unified API

When migrating to the Unified API via the Migration Wizard, by selecting Migrate to Xamarin.Mac Unified API from the Project menu, we now will ask which of our two supported frameworks you want to target:

For more information about migrating to the Unified API, please see our Updating Existing Mac Apps documentation.

Summary

This article has briefly covered the different types of Target Frameworks (Base Class Libraries) available to a Unified API version of a Xamarin.Mac application and when each type of framework should be used.

Xamarin Workbook

If it's not already installed, install the Xamarin Workbooks app first. The workbook file should download automatically, but if it doesn't, just click to start the workbook download manually.