Mac Catalyst (Early Preview)

This guide is for super-early adopters to experience using Mac Catalyst to build iOS projects for running on macOS. This is unsupported.

For release plans, refer to the .NET roadmap.

Pre-requisites

• Install this package: Microsoft.MacCatalyst.Bundle.14.3.100-ci.main.289.pkg
• Visual Studio Code - there is no IDE or debugging support
• Terminal

Getting Started

You can either start with an existing project (and add to it), or start with a new project (and edit the csproj).

Existing project

Existing test project: https://github.com/xamarin/xamarin-macios/tree/main/tests/common/TestProjects/MyCatalystApp

Existing Xamarin.Forms test project: https://github.com/xamarin/xamarin-macios/tree/main/tests/common/TestProjects/MyCatalystFormsApp

New project

Create a Xamarin.iOS project, and modify the csproj like this (in a text editor):

• Change the Import at the bottom to point to:

<Import Project="$(MSBuildExtensionsPath)\Xamarin\MacCatalyst\Xamarin.MacCatalyst.CSharp.targets" />

• Add a reference to Xamarin.MacCatalyst:

<Reference Include="Xamarin.MacCatalyst" />

The reference to Xamarin.iOS can stay (it will be necessary if using NuGets built for Xamarin.iOS)

• Change the MinimumOSVersion key in the Info.plist to be LSMinimumSystemVersion instead.

  • Also change the value to 10.15

• Make sure you're building for iPad (or a Universal app /iPad + iPhone)

• Remove the iPhone configuration [optional]

• Search & Replace “iPhoneSimulator” → “MacCatalyst” [optional]

If you use Xamarin.Forms, you’ll have to add any references manually, like this (for example):

<ItemGroup>
    <Reference Include="System" />
    <Reference Include="System.Xml" />
    <Reference Include="System.Core" />
    <Reference Include="Xamarin.iOS" />
    <Reference Include="Xamarin.MacCatalyst" />
    <Reference Include="System.Numerics" />
    <Reference Include="System.Numerics.Vectors" />
    <Reference Include="Xamarin.Forms.Core">
      <HintPath>$(PkgXamarin_Forms)/lib/Xamarin.iOS10/Xamarin.Forms.Core.dll</HintPath>
    </Reference>
    <Reference Include="Xamarin.Forms.Xaml">
      <HintPath>$(PkgXamarin_Forms)/lib/Xamarin.iOS10/Xamarin.Forms.Xaml.dll</HintPath>
    </Reference>
    <Reference Include="Xamarin.Forms.Platform.iOS">
      <HintPath>$(PkgXamarin_Forms)/lib/Xamarin.iOS10/Xamarin.Forms.Platform.iOS.dll</HintPath>
    </Reference>
  </ItemGroup>
  <ItemGroup>
    <PackageReference Include="Xamarin.Forms" Version="5.0.0.1558-pre3" GeneratePathProperty="true" />
    <PackageReference Include="Xamarin.Essentials" Version="1.5.3.2" />
  </ItemGroup>

In most cases, you will also need to add:

    <Reference Include="Xamarin.Forms.Platform">
     <HintPath>$(PkgXamarin_Forms)/lib/Xamarin.iOS10/Xamarin.Forms.Platform.dll</HintPath>
    </Reference>

NuGet Restore

    msbuild /t:restore

Build

    msbuild path/to/myproj.csproj

Run

    open ./bin/MacCatalyst/Debug/*.app

Known issues

• Xamarin.MacCatalyst projects won’t work in any IDE (so no debugging).
• The API surface of Xamarin.MacCatalyst.dll is not complete (no need to file issues about missing or wrong API). In particular there’s no support for any AppKit types.
• “nuget restore” doesn’t work. Use “msbuild /r” instead