Microsoft Learn

Developing for macOS with .NET MAUI

This tutorial will guide you through the process of developing and deploying .NET MAUI applications specifically for the macOS platform. .NET MAUI (Multi-platform App UI) allows you to build native applications for Windows, macOS, Android, and iOS from a single shared codebase.

Prerequisites

Before you begin, ensure you have the following installed:

• Visual Studio 2022 version 17.3 or later with the .NET Desktop Development workload.
• The latest .NET MAUI workload. You can install it via the Visual Studio Installer or using the .NET CLI:

  dotnet workload install maui

• Xcode 13.3 or later.
• An Apple Developer Account (required for deploying to physical devices or the App Store).

Setting up your macOS Development Environment

Visual Studio for Mac provides an integrated experience for developing .NET MAUI applications on macOS. Ensure you have the necessary workloads installed.

Creating a new .NET MAUI Project for macOS

To create a new project:

1. Open Visual Studio.
2. Click on "Create a new project".
3. Search for ".NET MAUI App" and select it.
4. Click "Next".
5. Configure your project name and location, then click "Create".

Targeting macOS in your Project

By default, new .NET MAUI projects include support for multiple platforms. To verify or configure macOS as a target:

1. Right-click on your project in the Solution Explorer.
2. Select "Properties".
3. Navigate to the ".NET MAUI" tab.
4. Ensure "macOS" is checked under the "Supported platforms" section.

Running your MAUI App on macOS

You can run your application directly from Visual Studio on macOS:

1. Select "Mac Catalyst" or "macOS" from the target framework dropdown in the toolbar.
2. Click the "Run" button (the green triangle).

Your application will be deployed and launched on your Mac.

Platform-Specific Code for macOS

While .NET MAUI aims for maximum code sharing, you might need to write platform-specific code. You can use preprocessor directives or platform-specific file extensions.

#if MACCATALYST
    // Code specific to Mac Catalyst
    #elif MACOS
    // Code specific to native macOS
    #endif

For example, a file named MyView.macabi.cs will be compiled only for Mac Catalyst.

Packaging and Distribution

To distribute your macOS application, you'll typically create an archive (`.zip` file) or a signed installer package. This often involves using Xcode's archiving tools or the .NET CLI.

You'll need an Apple Developer account to sign your application for distribution through the Mac App Store or for direct download.

Troubleshooting Common Issues

• Build errors: Ensure your Xcode installation is up-to-date and correctly configured. Check your project properties for correct target frameworks.
• Deployment issues: Verify your Apple Developer certificates and provisioning profiles are correctly set up if you are testing on a physical device or preparing for distribution.