Binding Troubleshooting

PDF for offline use

Let us know how you feel about this

Translation Quality


last updated: 2016-10

Some tips for troubleshooting bindings to macOS (formerly known as OS X) APIs in Xamarin.Mac.

Missing Bindings

While Xamarin.Mac covers much of the Apple APIs, sometimes you may need to call some Apple API that doesn’t have a binding yet. In other cases, you need to call third party C/Objective-C that it outside the scope of the Xamarin.Mac bindings.

If you are dealing with an Apple API, the first step is to let Xamarin know that you are hitting a section of the API that we don’t have coverage yet. File a bug on bugzilla noting the missing API. We use reports from customers to prioritize which APIs we work on next. In addition, if you have a Business or Enterprise license and this lack of a binding is blocking your progress, also follow the instructions at Support to file a ticket. We can’t promise a binding, but in some cases we can get you a work around.

Once you notify Xamarin (if applicable) of your missing binding, the next step is to consider binding it yourself. We have a full guide here and some unofficial documentation here for wrapping Objective-C bindings by hand. If you are calling a C API, you can use C#’s P/Invoke mechanism, documentation is here.

If you decide to work on the binding yourself, be aware that mistakes in the binding can produce all sorts of interesting crashes in the native runtime. In particular, be very careful that your signature in C# matches the native signature in number of arguments and the size of each argument. Failure to do so may corrupt memory and/or the stack and you could crash immediately or at some arbitrary point in the future or corrupt data.

Argument Exceptions Passing Null to a Binding

While Xamarin works to provide high quality and well tested bindings for the Apple APIs, sometimes mistakes and bugs slip in. By far the most common issue that you might run into is an API throwing ArgumentNullException when you pass in null when the underlying API accepts nil. The native header files defining the API often do not provide enough information on which APIs accept nil and which will crash if you pass it in.

If you run into a case where passing in null throws an ArgumentNullException but you think it should work, follow these steps:

  1. Check the Apple documentation and/or examples to see if you can find proof that it accepts nil. If you are comfortable with Objective-C, you can write a small test program to verify it.

  2. File a bug at

  3. Can you work around the bug? If you can avoid calling the API with null, a simple null check around the calls can be a easy work around.

  4. However, some APIs require passing in null to turn off or disable some features. In these cases, you can work around the issue by bringing up the assembly browser (see Finding the C# member for a given selector), copying the binding, and removing the null check. Please make sure to file a bug (step 2) if you do this, as your copied binding won't receive updates and fixes that we make in Xamarin.Mac, and this should be considered a short term work around.

Reporting Bugs

Occasionally you might run into a unreported bug when working with Xamarin.Mac. To help improve the product and get your issue taken care of as soon as possible, please file a bug against Xamarin.Mac at:

Include as much of the following as possible:

  • A simple example reproducing the issue. This is invaluable where possible.
  • The full stack trace of the crash.
  • The C# code surrounding the crash.

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.