Category Archives: Programming

General programming stuff

Calling C/C++ libraries from Xamarin code

The Xamarin platform allows developing iOS and Android applications entirely in C#. Sometimes, however, some legacy code may be too large or complex to make porting it to C# for your mobile app worthwhile. Most examples found online show you how to use existing Objective-C libraries in Xamarin.iOS and existing Java libraries in Xamarin.Android. However, it is entirely possible to call C code from a Xamarin app. Microsoft’s recent support for C/C++ on iOS and Android in Visual Studio can make this a simple task.

You will need the sources for the code you want to call to compile it for iOS and Android. The code cannot access any libraries which you only have binaries for that have been compiled for other platforms.

To get started, create a new C++ cross-platform project using Visual Studio 2015.
Create new cross-platform project
You will need to have the corresponding Visual Studio package installed to have this option available.
Visual Studio Setup Cross-Platform Mobile C++
This will create three projects: one for Android, one for iOS, and a shared project.
Project structure

It is important to understand the shared project concept for this. The code in the shared project does not result in a DLL or library being generated. A shared project can hold any type of file. Projects referencing the shared project can access code from any file in the shared project. The code will then be compiled in the context of the referencing project. If code is not referenced, it is not compiled. For this reason, it is necessary to have calls into all code needed contained in the platform-specific projects. This means that the platform-specific C/C++ projects need to contain code, too. This code can be identical in the Android and iOS projects and reside in the same files. Unlike in .NET projects, file linking is not needed for C++ projects; source code files do not have to reside inside a project’s folder or subfolder.

In the example, I’ve created a simple function clib_add_internal() that add two integers and resides in the shared project.


This code is called from a function in the platform-specific projects.

For the example code, this doesn’t make any sense. For a real project, you will put any call that needs to be directly invoked from the .NET code (your interface) into the platform-specific projects while underlying code can reside in the shared project.

The calls from .NET will be using P/Invoke since C++/CLI is not available on iOS or Android. So the basic P/Invoke rules apply for your interface’s code: Either the code is plain C or, if you are using C++, the calls are either plain functions or static methods and contain only POC parameters and return values.

For the iOS project, the output format needs to be changed to a static library (.a file) since iOS does not allow dynamically loading code. For Android, a dynamic library (.so) should be built.

iOS Settings
Android Settings

While the Android library can be compiled within Visual Studio, compiling the iOS library needs a connection to a build agent on the Mac. This is not the regular Xamarin.iOS installation on a Mac but a Microsoft tool that is installed on OS X using npm. Visual Studio will communicate with this tool through TCP/IP.

Connection to build host

To call the native code, create a Xamarin project for iOS and Android each. Include the native libraries in the respective Xamarin projects.

On iOS, if you’re targeting multiple processor architectures (either supporting pre-iPhone 5s or supporting the simulator), you can build the iOS project for multiple platforms using the dropdown in the toolbar. Then, combine the libraries into one using lipo according the Xamarin docs. On Android, you’ll need to modify the .csproj according to the Xamarin documentation to specify the .so files for each platform.

The calls into the native code are regular P/Invoke calls (although DLLs don’t play a role here). On Android, you specify the name of the shared library.

On iOS, use the special Mono name __Internal to call into the static library.

And that’s it! You can find the example code at https://github.com/lothrop/XamarinNative. In the example, I put the C# marshaling code into another shared project that is referenced by the Xamarin.iOS and Xamarin.Android projects.

iOS User Interfaces with MvvmCross

When using MvvmCross in a cross-platform mobile project you have the choice of four different approaches for creating the iOS user interface. Xamarin.Forms is one of those approaches that can be a good choice for many use cases (even if there is not graphical designer at this point). However, if your view has very specific visual requirements, it may be necessary to create a native view. There are three different ways you can do this:

  • Hand-coded: Create all visual elements in code. This approach is more widespread on iOS than on most other popular platforms. It gives you the advantage of having the maximum control possible over your user interface.
  • XIB files: XIB files are XML files that describe the visual elements. XIB files are typically not edited by hand but created using Xcode’s Interface Builder. Since Xamarin 4, XIB files can also be visually created and modified in Xamarin Studio or Visual Studio.
  • Storyboard files: This is the newest approach. Storyboards are also XML files visually edited with Xcode, Xamarin Studio, or Visual Studio yet they contain not only a single view but a series of views along with the workflow to navigate between these views.

MvvmCross supports all three native approaches.

Hand-coded

This approach obviously produces the most code. It may be challenging for people new to the platform but it saves you the hassle of battling with the UI designers.

XIB files

If you’re already on Xamarin 4 and prefer a visual editor, this is likely the best choice for you. Create a new XIB View Controller file using Xamarin Studio or Visual Studio. The ViewController code will also be created for you. All you need to do for MvvmCross is to change the base class from UIViewController to MvxViewController. In the example, three UI elements were created using the designer and were given the (not so creative) names UiLabel, UiTextField, and UiButton. These elements are then referenced in the data binding code that is common to all three approaches.

Setting element names

Storyboard files

The big advantage of storyboards, the ability to design your screenflow in the designer, does not fit well with MvvmCross’s cross-platform navigation approach. If you define a transition from view A to view B in the designer it will only apply to the iOS platform. It is typically a better idea to move this navigation logic down into the cross-platform code inside your ViewModels. That is why it’s best to use a one-ViewController-per-storyboard approach when using storyboards in MvvmCross.

Setting the storyboard ID

In the editor, you need to set the storyboard ID to the name of your ViewController. As with the XIB approach, change the base class from UIViewController to MvxViewController. Create a constructor taking an IntPtr and passing that on to the base class’s constructor. The last step is to add the [MvxFromStoryboard] attribute to the class.

Summary

The good thing is: You don’t have to make this decision at project start. MvvmCross supports implementing your view with the technology that is best for each view. You only need to ensure you don’t have multiple views for the same ViewModel and the same platform.

I’ve updated the example in the MvvmCross Starter Pack Nuget (starting with 4.0.0-beta8) to use a XIB file instead of the previous hand-coded approach with absolute coordinates (from the auto layout days). That should make it easier for people to get started.

Making your iOS views scrollable

If you’re using iOS auto layout (you should) and you’ve ever tried to add a scroll view in Interface Builder or the Xamarin iOS Designer you might have noticed that it is not an easy task. If you’re interested, here are some instructions. This is especially true if you only realize that you need a scroll view after designing your view (after you’ve realized that the keyboard covers up parts of the view).

Here’s code to inject a UIScrollView at runtime to solve all your worries. Add this code to your base UIViewController for all controllers that should be vertically scrollable.

In Interface Builder or Xamarin iOS Designer you’ll need to make sure you’ve not only defined constraints for the vertical position of your elements but also a constraint to define the distance from the bottom of the bottom element to the bottom of the your view controller’s view. That way, you’ll have defined the vertical size of the scroll view’s content view.

Serial communication using Reactive Extensions

The main purpose of Reactive Extensions (Rx) is to enable processing event streams. I set out to use Reactive Extensions for receiving data on the serial port and learned some new things.

Here is the code that uses Observable.FromEventPattern<T>() to create an IObservable<T> from the .NET event SerialPort.DataReceivedEvent:

The event does not actually contain any information on the data received, it only indicates that there is data available. Reading the data is done inside the lambda expression. Reading serial data will return a list of bytes. This list may contain a complete message or just a part of a message or even multiple messages. To handle this, I want the observable to be an IObservable<byte>, i.e., it will produce a raw stream of bytes without any indication of where a message begins or ends. This is done through the extension method public static IObservable<TResult> SelectMany<TSource, TResult>(this IObservable<TSource> source, Func<TSource, IEnumerable<TResult>> selector) that is used to flatten the sequence returned by the lambda.

So I now have a stream of bytes. I want these bytes to be chunked into messages. For my particular protocol, messages are separated by a special byte. Separation can be done in two ways:

Here, a new observable is created using Observable.Create(). This observable subscribes to the byte stream, collects the data in a local collection and fires OnNext() whenever a message delimiter is encountered.

This version uses the Scan() operator to achieve the same thing. The output is an IObservable<IEnumerable<byte>> that fires an IEnumerable<byte> for every new message.

This code worked well up until the point I started attaching multiple observers to the message stream, one to process the messages and one to just dump received messages to a debug console. What happened then was that the code in the first code sample was called multiple times: once for each subscriber. This meant that each chunk of serial data was only received by one subscriber, not all subscribers. There are two possible solutions to this: Either introduce a Subject<IEnumerable<byte>> subscribing to serialPortSource and have consumers subscribe to the subject or use the Publish() operator that does the work for you.

Creating a new observable that produces deserialized messages from the observable producing lists of bytes is now trivial using a simple Select().

What remains is the question of how to use the received data in a typical workflow of sending out a message and receiving a response in return. Here is an example:

This example uses the Replay() operator. Replay will capture all events from the observable that are fired after the call to Connect(). After calling Connect() the call is sent to the device at the other end of the serial connection. The second await filters the incoming messages for the desired message (even using a filter criterion that was not known before the request was sent), adds a timeout, uses FirstAsync() to return an observable that only returns the first element followed by OnCompleted(), and waits for that OnCompleted() using await. Since Replay() is capturing all messages, the following await call on the observable should consider all answers from the target, whether they are received before or after the second call to await.

ALM Days 2015: Mobile in the Enterprise

The ALM Days 2015 took place on March 11 and 12 in Düsseldorf. For the first time, a mobile track was conducted. My talk had the title Mobile in the Enterprise and covered the challenges you meet when developing apps for enterprise use. The video (in German) is on Channel 9 and the slides (also in German) are on Azure.

Dariusz collected the track videos in his blog (including one in English by Xamarin’s Mike James).

The final track event was a panel discussion on cross-platform development strategies with Dariusz, Jörg, Daniel, and myself.

Unified API: 64-bit support for Xamarin.iOS

There’s a deadline coming up for all iOS developers. Starting February 1, 2015, all apps and app updates submitted to the iOS app store must be built against the iOS 8 SDK and must include 64-bit support. While this is more of a routine update procedure for Objective-C developers, it has deeper implications for Xamarin.iOS developers.

The original design of the MonoTouch API chose to use some of the builtin .NET types, such as System.Int32 (int), System.Single (float) and RectangleF. Unfortunately, these types are all either 32-bit types or consist of 32-bit types. What is needed now, though, is a type that is 32-bit on 32-bit platforms and 64-bit on 64-bit platforms.

For this reason, Xamarin introduced a breaking change that will affect all Xamarin.iOS developers. The good news is that they are using the opportunity to fix a few issues with the old API. If you’re interested in all the changes, there is an Evolve session by Miguel de Icaza available.

The new Unified API comes as an assembly called Xamarin.iOS.dll instead of the old monotouch.dll. It replaces the old numeric types as follows:

old new
System.Int32 (int) System.nint
System.UInt32 (uint) System.nuint
System.Single (float) System.nfloat
System.Drawing.PointF CoreGraphics.CGPoint
System.Drawing.SizeF CoreGraphics.CGSize
System.Drawing.RectangleF CoreGraphics.CGRect

Projects using the new Unified API need to use a new project type.

Unified API

From within the new project types, you can’t reference Classic API projects.

The word “Unified” in Unified API comes from Xamarin’s attempt to facilitate code sharing for iOS and Mac projects. This is also the reason the namespace MonoTouch was dropped entirely, making it possible to share some code between the two platforms that needed to have platform-specific implementations previously, e.g, through Shared Projects.

Updating your existing projects from Classic API to Unified API can be done by hand or semi-automated. Xamarin has published instructions for the manual steps as well as the automatic update script or update feature integrated in Xamarin Studio.

I’ve updated the iOS code in MvvmCross to the Unified API. Here are some of the things I stumbled across while porting the code.

  • A few method names were fixed (e.g., UINavigationController.PopViewControllerAnimated() is now UINavigationController.PopViewController(), CGContext.SetRGBFillColor() is now CGContext.SetFillColor(), NetworkReachability.SetCallback() is now NetworkReachability.SetNotification()).
  • Some methods with callbacks were replaced with awaitable versions.
  • Some deprecated methods were removed.
  • The new numeric types look like builtin types but don’t behave like builtin numeric types (e.g., they can’t be const, you can’t use System.Math.Max() on them, etc.).
  • MonoTouch.Foundation.NSAction seems to have been dropped in favor of System.Action.

Xamarin’s current stable channel contains a preview for the Unified API. The final version is expected to hit the alpha and beta channels by early December 2014. Every existing Xamarin.iOS project will need to be updated if submitted to the App Store after February 1, 2015. It’s time to start looking at updating your projects.

Update January 18, 2015:

  • The iOS Unified API is now available on the stable channel.
  • In the meantime, Apple has further detailed its announcement regarding the submission deadline: The February 1 deadline only applies for new apps. Updates for existing apps can still be submitted as 32-bit before June 1, 2015.
  • There have been breaking changes between Xamarin’s prerelease version Xamarin.iOS 8.4 and the final version 8.6.
  • Xamarin has provided the class System.NMath for arithmetic operations on the new types nint, nuint, nfloat.
  • To submit to the app store, the app will need to also be built against for the ARM64 architecture. This can currently only be set using Xamarin Studio or directly in the .csproj file for Visual Studio users.

async/await part 2: Understanding the await keyword

In part 1 of this series we looked at the async keyword. async without await is possible (though not very useful) but await without async not. If you want to use await inside a method it must be marked as async.

The await keyword

Here is an example of a method using await:

Apart from the keywords async and await and the funny return value this looks just as you would write a synchronous method: Download a web page, then apply a regular expression to its contents to see if it matches.

And that is just the point. Although this method is asynchronous, it looks and feels like a synchronous method. But unlike its counterpart, the async method won’t block the caller until it is finished, won’t stay stuck in your mouse click event handler and, most importantly, won’t freeze the rest of your application.

How does does it work?

What happens when this method is called is that it executes just like any other method up to the point where the first await is encountered. At that point, the method returns to the caller with a Task (let’s call it method task) that contains information about the state of its work. As soon as the Task returned by GetStringAsync() completes the remainder of the method is executed. Note that all local variables are preserved and are available just as in a standard non-async method. When the method is finished with completing the remainder of its work (applying the regular expression) it will magically set the method task’s Result property to the value passed to the return statement and mark the Task as completed.

Typically, calls to async methods will be called and awaited by other async methods so the caller of our DoesWebContentMatchPatternAsync() method will not have to do anything special to receive this result. All it takes is writing await in front of the method call.

This will generate a compiler error if that method is not async.

How do I introduce await?

In practice, you’ll see this happen a lot when asyncifying existing code. The procedure is always the same:

  1. Add an await inside a method.
  2. Realize it doesn’t compile anymore because it is not async.
  3. Add async to the method’s declaration.
    1. If the return type was void, change it to Task.
    2. If the return type was of any type T, change it to Task<T>.
  4. Add the Async suffix to your method name using your favorite refactoring tool.
  5. Repeat from step 1 for the calling method.

This typically leads to async/await creeping through your entire codebase after some time but will leave a good feeling of accomplishment afterwards.

But what about exceptions?

But the magic of await doesn’t stop there. Another tedious task of asynchronous programming is catching and handling errors that occur in code running in the background. async/await handles this problem very elegantly by propagating exceptions through the Task‘s IsFaulted and Exception properties. What this means is that you can write exception handling code just as you would with synchronous code.

If you don’t catch the exception it will propagate to the calling method, just like with synchronous code. As long a your code is async/await all the way you won’t have to do anything differently.

Background work and the UI thread

The last piece of magic comes in the form of context synchronization. Another common pitfall in asynchronous programming comes from the fact that most UI technologies rely on a single UI thread to handle all modifications of the UI. Modifying a UI element from a different thread will typically lead to an exception being thrown. Let’s look at another piece of code using our method from above:

The code shows an event handler for a button click in a WPF code-behind (so not the place you would typically implement this functionality). The line assigning a new value to resultBox.Text is a line that has to be called from the UI thread in WPF. However, there is no code marshaling the call back to the UI context. This is because the default behavior of async/await is to try and execute the remainder of the code following an await call back into the original context for you.

This behavior is typically only needed for UI code and should be disabled for all other code as it adds overhead and may cause deadlocks. Disabling is achieved by calling ConfigureAwait(false) on the Task to be awaited:

This tells the compiler that it is OK to execute the remainder of the method (i.e., everything following the call to await) in the same context as the work done in the awaited call.

Give it a shot!

If you’re already on .NET 4.5 I suggest you give async/await a try. It will change the way you look at asynchronous programming.

async/await part 1: Understanding the async keyword

By far my favorite feature of .NET 4.5 is async/await, or, as Microsoft call it, the Task-based Asynchronous Pattern (TAP). It is something I didn’t know I was missing until I saw a recording of Anders Hejlsberg’s Build talk on the subject. Shortly after this, I had a highly asynchronous C++ embedded project that lasted for over a year where I felt miserable building state machine after state machine to handle the inherent problem of all asynchronous programs: What do you do after your asynchronous operation completes?

This blog series is aimed at C# programmers new to async/await. A general understanding of the Task class introduced with .NET 4.0 is expected. In this first part, I’ll explain the async in async/await.

What is async?

The async keyword can be used to decorate a method or lambda expression.

It is important to note that async is not a part of the method signature, so if you are implementing an interface or overriding a virtual or abstract method you have a choice of whether to use async or not.

Return types

An async method may only return void, Task or Task<T> for any concrete type T.

void as a return type should be avoided where possible and is generally only needed in event handlers, making the method a fire-and-forget method where the caller has no way of knowing when the call finished or failed.

If you write a method returning Task or Task<T> you should generally follow the convention of using the suffix Async in your method name to indicate that the method can be awaited (regardless of whether you method’s implementation uses async or not).

Task should be returned for methods that would, if they were synchronous methods, return void. Task<T> should be returned for methods that would otherwise return some type T (i.e., anything not void). Think of the Task as the object the caller can use to keep track of what ever happened to that asynchronous method he triggered.

What effect does async have?

Writing async will do two things to your method or lambda:

  1. It will allow you to write await in your method (see my next blog post in this series).
  2. If your return type is not void the compiler will automagically convert your return statement (or the missing return statement at the end of your method) into a Task<T> or Task.

For a method that does not contain any await calls, this means a completed Task will be returned without the need to explicitly specify this. For the above example this means it will behave exactly like this non-async version of it:

For a method that does contain an await in the executed path, the method will return a Task object that will turn to the IsCompleted state when the last awaited call has completed and the synchronous code following it (if any) has finished executing. (For more on this, read my next blog post in this series about the await keyword.)

Do I need async?

Methods containing only one await statement as the very last instruction in the method may generally be written without the async keyword. For example, the method

is equivalent to

Even though this yields the same result, the method declared as async seems to be the more readable version and has a slight runtime penalty. The other difference here is that if stream.FlushAsync() throws an exception and await is not used FlushTheStreamAsync() will not appear in the exception’s call stack (more on exceptions in the next blog post).

How does that help me?

As mentioned earlier, the returned Task object can be used to examine the state of the asynchronous call (still running? completed? failed? cancelled?). While this is possible using the various methods of the Task class, the easiest way to handle this is through the await keyword handled in the next blog post.