Hello, Mac

Getting started with Xamarin.Mac development

PDF for offline use:
Sample Code:
Related SDKs:

Let us know how you feel about this.

Thanks for the feedback!

This guide walks through creating your first Xamarin.Mac application, and in the process introduces the development toolchain, including Xamarin Studio, Xcode and Interface Builder. It also introduces Outlets and Actions, which expose UI controls to code, and finally, it illustrates how to build, run and test a Xamarin.Mac application.


This article will cover the following topics in detail:


Xamarin.Mac allows you to develop fully native Mac applications in C# and .NET using the same OS X libraries and interface controls that are used when developing in Objective-C and Xcode. Because Xamarin.Mac integrates directly with Xcode, you can use Xcode's Interface Builder to create your User Interfaces (or optionally create them directly in C# code).

Additionally, since Xamarin.Mac application are written in C# and .NET, common, backend code can be shared with Xamarin.iOS and Xamarin.Android mobile apps; all while delivering a native experience on each platform.

This article will introduce you to the key concepts needed to create a Mac Application using Xamarin.Mac, Xamarin Studio and Xcode's Interface Builder by walking you through the process of building a simply Hello, Mac application that counts the number of times a button has been clicked:

We’ll cover the following concepts:

  • Xamarin Studio – Introduction to the Xamarin Studio and how to create Xamarin.Mac applications with it.
  • Anatomy of a Xamarin.Mac Application – What a Xamarin.Mac application consists of.
  • Xcode’s Interface Builder – How to use Xcode’s Interface Builder to define your application’s User Interface.
  • Outlets and Actions – How to use Outlets and Actions to wire up controls in the User Interface.
  • Deployment/Testing – How to run and test your application.


The following is required to develop a Mac OS X application with Xamarin.Mac:

  • A Mac computer running Mac OS X Yosemite(10.10) or greater.
  • Xcode 7 and above (Although it is recommended to install the latest stable version from the App Store.)
  • Latest version of Xamarin.Mac and Xamarin Studio.

Running Mac applications created with Xamarin.Mac have the following system requirements:

  • A Mac computer running Mac OS X 10.7 or greater.

Starting a new Xamarin.Mac App in Xamarin Studio

As stated above, we’ll create a Mac application called Hello_Mac that adds a single button and label to the main window. When the button is clicked, the label will display the number of times it has been clicked.

To get started, let's do the following:

  1. Start Xamarin Studio:
  2. Click on the New Solution... link in the upper left hand corner of the screen to open the New Project dialog box:
  3. Select Mac > App > Cocoa App and click the Next button:
  4. Enter Hello_Mac for the App Name, and keep everything else as default. Click Next:
  5. If we were creating a solution that would house several different Projects, we might want to set a different Solution Name here, but for the sake of this example, we'll leave it set to the default of being the same as the Project Name:
  6. Click the Create button.

Xamarin Studio will create the new Xamarin.Mac application and display the default files that get added to your application's solution:

Xamarin Studio uses Solutions and Projects, the exact same way that Visual Studio does. A solution is a container that can hold one or more projects; projects can include applications, supporting libraries, test applications, etc. In this case, Xamarin Studio has created both a solution and an application project for you.

If you wanted to, you could create one or more code library projects that contain common, shared code. These library projects can be consumed by the application project or shared with other Xamarin.Mac application projects (or Xamarin.iOS and Xamarin.Android based on the type of code), just as you would if you were building a standard .NET application.

Anatomy of a Xamarin.Mac Application

If you’re familiar with iOS programming, you’ll notice a lot of similarities here. In fact, iOS uses the CocoaTouch framework, which is a slimmed-down version of Cocoa, used by Mac, so a lot of concepts will cross over here.

Let’s take a look at the files in the project:

  • Main.cs – This contains the main entry point of the application. When the application is launched, this contains the very first class and method that is run.
  • AppDelegate.cs – This file contains the main application class that is responsible for listening to events from the operating system.
  • Info.plist – This file contains application properties such as the application name, icons, etc.
  • MainMenu.xib – This defines the Application Menu and it's layout and structure for your application. .xib files (also referred to as Nibs for legacy reasons), are XML files that contain the definition of views (User Interface elements). This file can be created and maintained by Interface Builder inside of Xcode.
  • MainWindow.cs – This is the class that represents the main window and controls the lifecycle of it.
  • MainWindow.designer.cs – This file contains plumbing code that helps you integrate with the main screen’s user interface.
  • MainWindow.xib – The UI for the main window. Again, this file can be created and maintained by Interface Builder inside of Xcode.
  • MainWindowController.cs – This is the controller for the main window. Controllers will be covered in detail in another article, but for now, a controller can be thought of the main engine of any particular view.

In the following sections, we'll take a quick look through some of these files. We’ll explore them in more detail later, but it’s a good idea to understand their basics now.


The Main.cs file is very simple. It contains a static Main method which creates a new Xamarin.Mac application instance and passes the name of the class that will handle OS events, which in our case is the AppDelegate class:

using System;
using System.Drawing;
using Foundation;
using AppKit;
using ObjCRuntime;

namespace Hello_Mac
        class MainClass
                static void Main (string[] args)
                        NSApplication.Init ();
                        NSApplication.Main (args);


The AppDelegate.cs file contains our AppDelegate class, which is responsible for creating our window and listening to OS events:

using System;
using System.Drawing;
using Foundation;
using AppKit;
using ObjCRuntime;

namespace Hello_Mac
        public partial class AppDelegate : NSApplicationDelegate
                MainWindowController mainWindowController;

                public AppDelegate ()

                public override void FinishedLaunching (NSObject notification)
                        mainWindowController = new MainWindowController ();
                        .MakeKeyAndOrderFront (this);

This code is probably unfamiliar unless you’ve built an iOS application before, but it’s fairly simple. Let’s examine the important lines.

First, let’s take a look at the two class-level variable declarations:

MainWindowController mainWindowController;

Cocoa (and by derivation, CocoaTouch) uses what’s known as the Model View Controller (MVC) pattern. The MainWindowController declaration represents the object controls the actual application window. Generally, for every window you create (and for many other things within windows), there is a controller, which is responsible for the window’s life cycle, such as showing it, adding new views (controls) to it, etc.

Next, we have the FinishedLaunching method. This method runs after the application has been instantiated, and it’s responsible for actually creating the application window and beginning the process of displaying the view in it.

The first line instantiates a new instance of our main window controller:

mainWindowController = new MainWindowController ();

Next, we tell the main window (the Window property on the controller) that it should be in focus and accept user input (Key), and appear in the front of any other windows:

mainWindowController.Window.MakeKeyAndOrderFront (this);


As we’ve already seen, the MainWindowController class is our main window’s controller. That means it’s responsible for the life cycle of the main window. We’re going to examine this in detail later, for now let's just take a quick look at it:

using System;
using System.Collections.Generic;
using System.Linq;
using Foundation;
using AppKit;

namespace Hello_Mac
        public partial class MainWindowController : AppKit.NSWindowController
                #region Constructors

                // Called when created from unmanaged code
                public MainWindowController (IntPtr handle) : base (handle)
                        Initialize ();

                // Called when created directly from a XIB file
                [Export ("initWithCoder:")]
                public MainWindowController (NSCoder coder) : base (coder)
                        Initialize ();

                // Call to load from the XIB/NIB file
                public MainWindowController () : base ("MainWindow")
                        Initialize ();

                // Shared initialization code
                void Initialize ()


                //strongly typed window accessor
                public new MainWindow Window {
                        get {
                                return (MainWindow)base.Window;

The Window property is a convenience property that casts the base.Window property to a strongly-typed version of the actual Window class. This allows you to easily access any custom properties or methods of the window without having to cast it every time.


The designer file for the Main Window class is empty right now, but it will be automatically populated by Xamarin Studio as we create our User Interface with Interface Builder inside of Xcode:

namespace Hello_Mac

        // Should subclass MonoMac.AppKit.NSWindow
        public partial class MainWindow

        // Should subclass MonoMac.AppKit.NSWindowController
        public partial class MainWindowController

We aren’t usually concerned with designer files, as they’re just automatically managed by Xamarin Studio and just provide the requisite pluming code that allows access to controls that we add to any window or view in our application.

Now that we have created our Xamarin.Mac application and we have a basic understanding of its components, let’s jump over to Xcode and create our User Interface using Interface Builder.

Introduction to Xcode and Interface Builder

As part of Xcode, Apple has created a tool called Interface Builder, which allows you to create your User Interface visually in a designer. Xamarin.Mac integrates fluently with Interface Builder, allowing you to create your UI with the same tools that Objective-C users do.

To get started, let's double-click the MainWindow.xib file in the Solution Explorer to open it for editing in Xcode and Interface Builder:

This should launch Xcode and look something like the following:

Before we start to design our interface, let's do a quick overview of Xcode to orient ourselves with the main features that we will be using.

Note: You don't have to use Xcode and Interface Builder to create the User Interface for your Xamarin.Mac application, the UI can be created directly from C# code but that is beyond the scope of this article. For the sake of simplicity, we'll be using Interface Builder to create our User Interface throughout the rest of this tutorial.

Components of Xcode

When you open a .xib file in Xcode from Xamarin Studio, it opens with a Project Navigator on the left, the Interface Hierarchy and Interface Editor in the middle, and a Properties & Utilities section on the right:

Let's take a look at what each of these Xcode sections does and how we will use them to create the interface for our Xamarin.Mac application.

Project Navigation

When you open a .xib file for editing in Xcode, Xamarin Studio creates a Xcode Project File in the background to communicate changes between itself and Xcode. Later, when you switch back to Xamarin Studio from Xcode, any changes made to this project are synchronized with your Xamarin.Mac project by Xamarin Studio.

The Project Navigation section allows you to navigate between all of the files that make up this shim Xcode Project. Typically, you will only be interested in the .xib files in this list such as MainMenu.xib and MainWindow.xib.

Interface Hierarchy

The Interface Hierarchy section allows you to easily access several key properties of the User Interface such as it's Placeholders and main Window. You can also use this section to access the individual elements (views) that make up your user interface and the adjust the way that they are nested by dragging them around within the hierarchy.

Interface Editor

The Interface Editor section provides the surface on which you graphically layout your User Interface. You'll drag elements from the Library section of the Properties & Utilities section to create your design. As you add user interface elements (views) to the design surface, they will be added to the Interface Hierarchy section in the order that they appear in the Interface Editor.

Properties & Utilities

The Properties & Utilities section is devided into two main sections that we will be working with, Properties (also called Inspectors) and the Library:

Initially this section is almost empty, however if you select an element in the Interface Editor or Interface Hierarchy, the Properties section will be populated with information about the given element and properties that you can adjust.

Within the Properties section, there are 8 different Inspector Tabs, as shown in the following illustration:

Properties & Utilities

From left-to-right, these tabs are:

  • File Inspector – The File Inspector shows file information, such as the file name and location of the Xib file that is being edited.
  • Quick Help – The Quick Help tab provides contextual help based on what is selected in Xcode.
  • Identity Inspector – The Identity Inspector provides information about the selected control/view.
  • Attributes Inspector – The Attributes Inspector allows you to customize various attributes of the selected control/view.
  • Size Inspector – The Size Inspector allows you to control the size and resizing behavior of the selected control/view.
  • Connections Inspector – The Connections Inspector shows the Outlet and Action connections of the selected controls. We’ll examine Outlets and Actions in just a moment.
  • Bindings Inspector – The Bindings Inspector allows you to configure controls so that their values are automatically bound to data models.
  • View Effects Inspector – The View Effects Inspector allows you to specify effects on the controls, such as animations.

In the Library section, you can find controls and objects to place into the designer to graphically build your user interface:

Creating the Interface

Now that we’re familiar with the Xcode IDE and Interface Builder, let’s create the user interface of our main view.

Do the following:

  1. In Xcode, drag a Push Button from the Library Section:
  2. Drop the button onto the Window in the Interface Editor:
  3. Click on the Title property in the Attribute Inspector and change the button's title to Click Me:
  4. Drag a Label from the Library Section:
  5. Drop the label onto the Window beside the button in the Interface Editor:
  6. Grab the right handle on the label and drag it until it is near the edge of the window:
  7. With the label still selected in the Interface Editor, switch to the Size Inspector:
  8. In the Autosizing Box click the Dim Red Bracket at the right and the Dim Red Horizontal Arrow in the center:
  9. This ensures that the label will stretch to grow and shrink as the window is resized in the running application. The Red Brackets and the top and left of the Autosizing Box box tell the label to be stuck to its given X and Y locations.
  10. Save your changes to the User Interface

As you were resizing and moving controls around, you should have noticed that Interface Builder gives you helpful snap hints that are based on OS X Human Interface Guidelines. These guidelines will help you create high quality applications that will have a familiar look and feel for Mac users.

If you look in the Interface Hierarchy section, notice how the layout and hierarchy of the elements that make up our user Interface are shown:

From here you can select items to edit or drag to reorder UI elements if needed. For example, if a UI element was being covered by another element, you could drag it to the bottom of the list to make it the top-most item on the window.

Now that we have our User Interface created, we need to expose the UI items so that Xamarin.Mac can access and interact with them in C# code. The next section, Outlets and Actions, shows how to do this.

Outlets and Actions

So what are Outlets and Actions? In traditional .NET User Interface programming, a control in the User Interface is automatically exposed as a property when it’s added. Things work differently in Mac, simply adding a control to a view doesn’t make it accessible to code. The developer must explicitly expose the UI element to code. In order do this, Apple gives us two options:

  • Outlets – Outlets are analogous to properties. If you wire up a control to an Outlet, it’s exposed to your code via a property, so you can do things like attach event handlers, call methods on it, etc.
  • Actions – Actions are analogous to the command pattern in WPF. For example, when an Action is performed on a control, say a button click, the control will automatically call a method in your code. Actions are powerful and convenient because you can wire up many controls to the same Action.

In Xcode, Outlets and Actions are added directly in code via Control-dragging. More specifically, this means that in order to create an Outlet or Action, you choose which control element you’d like to add an Outlet or Action, hold down the Control button on the keyboard, and drag that control directly into your code.

For Xamarin.Mac developers, this means that you drag into the Objective-C stub files that correspond to the C# file where you want to create the Outlet or Action. Xamarin Studio created a file called MainWindow.h as part of the shim Xcode Project it generated to use the Interface Builder:

This stub .h file mirrors the MainWindow.designer.cs that is automatically added to a Xamarin.Mac project when a new NSWindow is created. This file will be used to synchronize the changes made by Interface Builder and is where we will create our Outlets and Actions so that UI elements are exposed to C# code.

Adding an Outlet

With a basic understanding of what Outlets and Actions are, let's create an Outlet to expose the Label we created to our C# code.

Do the following:

  1. In Xcode at the far right top-hand corner of the screen, click the Double Circle button to open the Assistant Editor:
  2. The Xcode will switch to a split-view mode with the Interface Editor on one side and a Code Editor on the other.
  3. Notice that Xcode has automatically picked the MainWindowController.m file in the Code Editor, which is incorrect. If you remember from our discussion on what Outlets and Actions are above, we need to have the MainWindow.h selected.
  4. At the top of the Code Editor click on the Automatic Link and select the MainWindow.h file:
  5. Xcode should now have the correct file selected:
  6. The last step was very important! If you don't have the correct file selected, you won't be able to create Outlets and Actions or they will be exposed to the wrong class in C#!
  7. In the Interface Editor, hold down the Control key on the keyboard and click-drag the label we created above onto the code editor just below the @interface MainWindow : NSWindow { } code:
  8. A dialog box will be displayed. Leave the Connection set to Outlet and enter ClickedLabel for the Name:
  9. Click the Connect button to create the Outlet:
  10. Save the changes to the file.

Adding an Action

Next, let's expose our button to our C# code. Just like the Label above, we could wire the button up to an Outlet. Since we only want to respond to the button being clicked, let's use an Action instead.

Do the following:

  1. Make sure we are still in the Assistant Editor and the MainWindow.h file is visible in the Code Editor.
  2. In the Interface Editor, hold down the Control key on the keyboard and click-drag the button we created above onto the code editor just below the @property (assign) IBOutlet NSTextField *ClickedLabel; code:
  3. Change the Connection type to Action:
  4. Enter ClickedButton as the Name:
  5. Click the Connect button to create Action:
  6. Save the changes to the file.

With our User Interface wired-up and exposed to C# code, let's switch back to Xamarin Studio and let it synchronize the changes we made in Xcode and Interface Builder.

NOTE: It probably took a long time to create the User Interface and Outlets and Actions for our first application, and it may seem like a lot of work, but we’ve introduced a lot of new concepts and we’ve spent a lot of time covering new ground. Once you’ve practiced for a while working with Interface Builder, this interface and all its Outlets and Actions can be created in just a minute or two.

Synchronizing Changes with Xcode

When we switch back to Xamarin Studio from Xcode, any changes that we have made in Xcode will automatically be synchronized with our Xamarin.Mac project.

If you select the MainWindow.designer.cs in the Solution Explorer you'll be able to see how our Outlet and Action have been wired up in our C# code:

Notice how the two definitions in the MainWindow.designer.cs file:

AppKit.NSTextField ClickedLabel { get; set; }

[Action ("ClickedButton:")]
partial void ClickedButton (Foundation.NSObject sender);

Line up with the definitions in the MainWindow.h file in Xcode:

@property (assign) IBOutlet NSTextField *ClickedLabel;
- (IBAction)ClickedButton:(id)sender;

As you can see, Xamarin Studio listens for changes to the .h file, and then automatically synchronizes those changes in the respective .designer.cs file to expose them to your application. You may also notice that MainWindow.designer.cs is a partial class, so that Xamarin Studio doesn't have to modify MainWindow.cs which would overwrite any changes that we have made to the class.

You normally will never need to open the MainWindow.designer.cs yourself, it was presented here for educational purposes only.

NOTE: In most situations, Xamarin Studio will automatically see any changes made in Xcode and sync them to your Xamarin.Mac project. In the off occurrence that synchronization doesn't automatically happen, switch back to Xcode and them back to Xamarin Studio again. This will normally kick off a synchronization cycle.

Writing the Code

With our User Interface created and it's UI elements exposed to code via Outlets and Actions, we are finally ready to write the code to bring the program to life.

In our application, every time the first button is clicked, we’re going to update our label to show how many times the button has been clicked. In order to accomplish this, we need to open the MainWindow.cs file for editing by double-clicking it in the Solution Explorer:

First, we need to create a class-level variable in our MainWindow class to track the number of clicks that have happened. Edit the class definition and make it look like the following:

namespace Hello_Mac
    public partial class MainWindow : NSWindow
        private int numberOfTimesClicked = 0;

Next, in the same class (MainWindow), we need to override the AwakeFromNib method and add some code to set the initial message for our label:

public override void AwakeFromNib ()
    base.AwakeFromNib ();

    // Set the initial value for the label
    ClickedLabel.StringValue = "Button has not been clicked yet.";

We need to use AwakeFromNib, instead of another method such as Initialize, because AwakeFromNib is called after the OS has loaded and instantiated the User Interface from the .xib file. If we tried to access the label control before the .xib file has been fully loaded and instantiated, we’d get a NullReferenceException error because the label control would not be created yet.

Next, we need to add the code to respond to the user clicking the button. Add the following partial class to the MainWindow class:

partial void ClickedButton (Foundation.NSObject sender) {

    // Update counter and label
    ClickedLabel.StringValue = string.Format("The button has been clicked {0} time{1}.",++numberOfTimesClicked, (numberOfTimesClicked < 2) ? "" : "s");

This code attaches to the Action that we created in Xcode and Interface Builder and will be called any time the user clicks our button.

With everything in place, we are now ready to build and test our Xamarin.Mac application.

Testing the Application

It’s time to build and run our application to make sure it runs as expected. We can build and run all in one step, or we can build it without running it.

Whenever we build an application, we can choose what kind of build we want:

  • Debug – A debug build is compiled into an .app (application) file with a bunch of extra metadata that allows us to debug what’s happening while the application is running.
  • Release – A release build also creates an .app file, but it doesn’t include debug information, so it’s smaller and executes faster.

You can select the type of build from the Configuration Selector at the upper left hand corner of the Xamarin Studio screen:

Building the Application

In our case, we just want a debug build, so let’s make sure that Debug is selected. Let's build our application first by either pressing ⌘B, or from the Build menu, choose Build All.

If there weren't any errors, you’ll see a Build Succeeded message in Xamarin Studio's status bar. If there were errors, review your project and make sure that you’ve followed the steps correctly. Start by confirming that your code (both in Xcode and in Xamarin Studio) matches the code in the tutorial.

Running the Application

To run the application, we have three options:

  • Press ⌘+Enter.
  • From the Run menu, choose Debug.
  • Click the Play button in the Xamarin Studio toolbar (just above the Solution Explorer).

The application will build (if it hasn’t been built already), start in debug mode and display it's main interface window:

If you click the button a few times the label should be updated with the count:

Congratulations! We covered a lot of ground here, but if you followed this tutorial from start to finish, you should now have a solid understanding of the components of a Xamarin.Mac application as well as the tools used to create them.

Where to Next

Now that you have the basics of working with a Xamarin.Mac application down, we suggest that you take a look at the following documents to get a deeper understanding:

  • Windows - This article covers working with Windows and Panels in a Xamarin.Mac application. It covers creating and maintaining Windows and Panels in Xcode and Interface builder, loading Windows and Panels from .xib files, using Windows and responding to Windows in C# code.
  • Dialogs - This article covers working with Dialogs and Modal Windows in a Xamarin.Mac application. It covers creating and maintaining Modal Windows in Xcode and Interface builder, working with standard dialogs, displaying and responding to Windows in C# code.
  • Alerts - This article covers working with Alerts in a Xamarin.Mac application. It covers creating and displaying Alerts from C# code and responding to Alerts.
  • Menus - Menus are used in various parts of a Mac application's user interface; from the application's main menu at the top of the screen to pop-up and contextual menus that can appear anywhere in a window. Menus are a integral part of a Mac application's user experience. This article covers working with Cocoa Menus in a Xamarin.Mac application.
  • Toolbars - This article covers working with Toolbars in a Xamarin.Mac application. It covers creating and maintaining Toolbars in Xcode and Interface builder, how to expose the Toolbar Items to code using Outlets and Actions, enabling and disabling Toolbar Items and finally responding to Toolbar Items in C# code.
  • Table Views - This article covers working with Table Views in a Xamarin.Mac application. It covers creating and maintaining Table Views in Xcode and Interface builder, how to expose the Table View Items to code using Outlets and Actions, populating Table Items and finally responding to Table View Items in C# code.
  • Outline Views - This article covers working with Outline Views in a Xamarin.Mac application. It covers creating and maintaining Outline Views in Xcode and Interface builder, how to expose the Outline View Items to code using Outlets and Actions, populating Outline Items and finally responding to Outline View Items in C# code.
  • Source Lists - This article covers working with Source Lists in a Xamarin.Mac application. It covers creating and maintaining Source Lists in Xcode and Interface builder, how to expose the Source Lists Items to code using Outlets and Actions, populating Source List Items and finally responding to Source List Items in C# code.
  • Working with Images - This article covers working with Images and Icons in a Xamarin.Mac application. It covers creating and maintaining the images needed to create your application's Icon and using Images in both C# code and Xcode's Interface Builder.

We also suggest taking a look at the Mac Samples Gallery, it includes a wealth of ready-to-use code that can help you get a Xamarin.Mac project off the ground quickly.


In this article we cover the basics of a standard Xamarin.Mac application. We covered creating a new application in Xamarin Studio, designing the user interface in Xcode and Interface Builder, exposing our UI elements to C# code using Outlets and Actions, adding code to work with our UI elements and finally, building and testing a Xamarin.Mac application.