Updated Resilient Networking with Xamarin

Rob Gibbons wrote a fantastic blog post back in 2015 on how best to write network requests layers for your Xamarin Apps. I’ve personally used this approach many times, but I felt that it needed updating for 2018, so here it is. A slightly updated approach to resilient networking services with Xamarin. And when I say ‘slightly update’, I honestly mean it’s a minor change!

we-dont-throw

Refit

For those of you who are familiar with Rob’s approach, he uses pulls together a few libraries to create a robust networking layer. One of the critical elements of his strategy is the use of Refit. Refit is a REST library which allows us to interact with remote APIs with minimal boiler-plate code. It makes heavy use of generics and abstractions to define our REST API calls as a C# Interfaces which are then used with am instance HTTPClient to handle all the requests. All serialisation is dealt with for us! I still believe Refit to be a great library to use so we’ll keep this as the core of this pattern.

Let’s have a look at an example interface for use with Refit.

public interface IBeerServiceAPI`
{
    [Get("/beer/")]
    Task GetBeers();
}

We use attributes to define the request type as well as its path (relative to the HTTPClients base URL).

We then define what we expect back from the API and leave Refit to handle making the call, deserialising the response and handing it back to us as a concrete type.

To expand on this, we can add many more types of requests.

[Get("/beer/{id}/")]
Task GetBeerById(string id);

[Post("/beer/")]
Task CreateBeer([Body] Beer beer);

[Delete("/beer/{id}/")]
Task DeleteBeer(string id);

[Put("/beer/{id}/")]
Task UpdateBeer(string id, [Body] Beer beer);

We can now use the interface to make calls to our remote endpoint. I usually place these methods within a class that is unique to the service I’m calling. I’m this example; it’d be a “BeersService.”

//Create new beer item
public async Task<Beer> CreateBeerAsync(Beer beer)
 {
    var apiInstance = RestService.For<IBeerServiceAPI>(Helpers.Constants.BaseUrl);
    return await apiInstance.CreateBeer(beer);
}

//Get by ID
public async Task<Beer> GetBeerByIdAsync(string id)
{
    var apiInstance = RestService.For<IBeerServiceAPI>(Helpers.Constants.BaseUrl);
    return await apiInstance.GetBeerById(id);
}

That’s all it takes for us to starts interacting with a remote API. If you’re wondering how to test this, it’s incredibly easy to swap out implementations with mock services when using this architecture!

Resiliency

Building a resilient networking service requires a few things. We need to understand what our current connectivity looks like, as well as find a solution for caching data locally to ensure our app still ‘works’ in offline situations.

We can achieve both of these tasks by leveraging packages from Motz. He’s created a plugin for checking connectivity status as well as developed a library for caching.

Lets first take a look at connectivity status.

You’ll want to add the Connectivity Plugin nuget package to every client project in the solution as well as the PCL. The following platforms are supported:

  • Xamarin.iOS
  • tvOS (Xamarin)
  • Xamarin.Android
  • Windows 10 UWP
  • Xamarin.Mac
  • .NET 4.5/WPF
  • .NET Core
  • Samsung Tizen

To use the connectivity plugin, we can simple make the following call:

var isConnected = CrossConnectivity.Current.IsConnected;

Caching

Now that we can check for connectivity, we detect that we’re offline. Let’s have a look at how to implement that.

public async Task<List<Beer>> GetBeersAsync()
{
    Handle online/offline scenario
    if (!CrossConnectivity.Current.IsConnected)
    {
        //If no connectivity, we need to fail... :(
        throw new Exception("No connectivity");
    }
    //Create an instance of the Refit RestService for the beer interface.
    var apiInstance = RestService.For<IBeerServiceAPI>(Helpers.Constants.BaseUrl);
    var beers = await apiInstance.GetBeers());

    return beers;
}

Returning no results for most requests isn’t a great solution. We can dramatically improve the user experience by keeping a cache of data to show in offline situations. To implement that, we’re going to use Monkey Cache. To use Monkey Cache, we have to first configure the ApplicationId.  A folder created for your app on disk with the ApplicationId, so you should avoid changing it.

Barrel.ApplicationId = "your_unique_name_here";

Adding Monkey Cache is super simple. First, of, we want to define a key. Think of this as the collection (barrel) name. After that, we implement the necessary logic to handle caching.

public async Task<List<Beer>> GetBeersAsync()
{
    var key = "Beers";

    Handle online/offline scenario
    if (!CrossConnectivity.Current.IsConnected && Barrel.Current.Exists(key))
    {
        //If no connectivity, we'll return the cached beers list.
        return Barrel.Current.Get<List<Beer>>(key);
    }

    //If the data isn't too old, we'll go ahead and return it rather than call the backend again.
    if (!Barrel.Current.IsExpired(key) && Barrel.Current.Exists(key))
    {
        return Barrel.Current.Get<List<Beer>>(key);
    }            

    //Create an instance of the Refit RestService for the beer interface.
    var apiInstance = RestService.For<IBeerServiceAPI>(Helpers.Constants.BaseUrl);
    var beers = await apiInstance.GetBeers());

    //Save beers into the cache
    Barrel.Current.Add(key: key, data: beers, expireIn: TimeSpan.FromHours(5));

    return beers;
}

Polly

Returning to Rob’s original post, we’ll want to add Polly. Polly helps us handle network requests sanely. It allows us to retry, and process failures robustly.

We’re going to use Polly to define a retry logic that forces the service to retry five times, each time waiting twice as long as before.

public async Task<List<Beer>> GetBeersAsync()
{
    var key = "Beers";

    Handle online/offline scenario
    if (!CrossConnectivity.Current.IsConnected && Barrel.Current.Exists(key))
    {
        //If no connectivity, we'll return the cached beers list.
        return Barrel.Current.Get<List<Beer>>(key);
    }

    //If the data isn't too old, we'll go ahead and return it rather than call the backend again.
    if (!Barrel.Current.IsExpired(key) && Barrel.Current.Exists(key))
    {
        return Barrel.Current.Get<List<Beer>>(key);
    }            

    //Create an instance of the Refit RestService for the beer interface.
    var apiInstance = RestService.For<IBeerServiceAPI>(Helpers.Constants.BaseUrl);

    //Use Polly to handle retrying (helps with bad connectivity) 
    var beers = await Policy
        .Handle<WebException>()
        .Or<HttpRequestException>()
        .Or<TimeoutException>()
        .WaitAndRetryAsync
        (
            retryCount: 5,
            sleepDurationProvider: retryAttempt => TimeSpan.FromSeconds(Math.Pow(2, retryAttempt))
        ).ExecuteAsync(async () => await apiInstance.GetBeers());


    //Save beers into the cache
    Barrel.Current.Add(key: key, data: beers, expireIn: TimeSpan.FromSeconds(5));

    return beers;
}

Wrapping Up

This is a great way to implement your networking layer within your apps as it can sit within a .NET Standard library and be used in all your client apps.

If you’d like to see a more real-world example of this approach, then check out the Mobile Cloud Workshop I created with Robin-Manuel. The Xamarin.Forms app uses this approach and, it’s been working very well for us!

Big thanks to Rob for the original post and documenting such a simple solution to complex problem!

Auto Layout 101 with Xamarin

Until recently I’d done an amazing job of avoiding Auto Layouts on anything other than demo apps, instead opting to create my layouts with springs and structs. All my apps within the App Store use the old approach, which although being exceptionally easy to create, its limited when running across all the different form factors that iOS runs on.

With multitasking on the iPad requiring Auto Layouts, I thought its probably about time that I took the time to learn to love the contraversal layout engine.

What is Auto Layout?

Auto Layout is a constraints based layout system for iOS, tvOS and OS X. It allows me to create adaptive user interaces that respond appropriatly to changes in screen size and orientation.

Auto Layouts is supported in both Xamarin Studio and Visual Studio when using Xamarin.iOS but will not be applicable to Xamarin.Forms developers. Xamarin.Forms developers dont need to worry as Forms apps already work fantasticlly on iPad with multitasking!

Layout contraints

Contraints are a mathematical representation of the relationship between views. The NSLayoutContraint class is used to create contraints on both iOS and OS X but for the most part, you’ll want to create contraints using our iOS Designer rather than programatically as its much easier.

Auto Layout has a number of constraints which include size, alignment and spacing. By providing each view within a scene with constraints, Auto Layout will determine the frame of each view at runtime.

One really important tip which will help you solve Auto Layout issues is to remember: Most controls will require constraints that define its height, width, x position and y position. 

Getting Started

To get started, I want to center a UIView within my scene. I want to remain in the center of the scene no matter what size of device its running on.

Screen Shot 2015-11-25 at 15.13.13

Above you can see that I’ve added a UIView to my scene and set its background colour to blue. Although it looks like its center to my scene, no iOS device actually has this form factor. We can use the View As drop down to simulate the different size. Lets see how this would look on a 5s with no constraints.

Screen Shot 2015-11-25 at 15.13.41

We can see that my UIView isn’t position correctly! To resolve this, lets go ahead and add some contraints.

I’m going to lock its height and width. To do this, I’ll click the handle bar button.

handlebars

This has now locked the width and height of my view so that no matter what device I’m running on, the box will always remain the same dimentions. You’ll note that the lines are currently orange. This means that the control contains some errors with its contraints.

If you recall back to my pro tip, you’ll know that we’re only 50% of the way to completing the contraints for this view. We have yet to provide Auto Layouts with any information on where to position this view.

To do this, I clicked on the orange button in the middle of the view and connect it to the verticle line running through the scene. I repeat this for the horizontal line. This is telling Auto Layout that I want this views X and Y to be centered on the center of the super view.

center

When the view has 4 contraints (width, height, x and y), you’ll see the lines now turn to blue. This marks a valid set of contraints for the view and lets us know everything is valid. If you see orange lines, its Auto Layouts telling you that somethings gone wrong. Dont worry if you see orange whilst your still editing, its perfectly normal.

Screen Shot 2015-11-25 at 15.18.44

Wrapping up

This is a crazy simple demo of Auto Layouts but provides you with the basic you need to get started.

Come back in a few weeks to see more Auto Layout goodness as I convert an existing login screen to use Auto Layout.

 

 

Watch out, we support WatchKit!

Screen-Shot-2015-01-17-at-22.25.41-e1421668170621

Xamarin have just announced preview support for Apple Watch and I can’t express how excited I was over the weekend playing with our internal preview build. At this moment time, getting started with Apple Watch can be little confusing, what with the need for 3 different project types to get a hello world sample running! You can see this in the below screenshot of Xamarin Studio. This complexity increases the learning curve so I’ve done my best to try and help.

I’ve created a simple Hello World Apple Watch sample solution which you can download from my GitHub.

One Solution – Three Projects – One Watch App!

Even a basic Apple Watch app requires 1 part App Extension, 1 part Watch App and finally 1 part Unified iOS App. When combined with the correct Bundle Identifiers, you’ve got yourself the beginnings of Apple Watch support. At this moment in time, you’ll need to be editing your storyboard in Xcode rather than Xamarin Studio or Visual Studio. I believe our engineers are hard at work on integrating Apple Watch UI storyboard support in VS and XS much like we have for iPhone and iPad.

Screen-Shot-2015-01-19-at-16.37.23

 Learn more with some awesome documentation!

Xamarin has some excellent documentation on Apple Watch which I highly recommend you thoroughly read.

Cross-Platform Desktop UIs with C#

xplatDesktop

I’ve spent the last 4 weeks traveling Europe for the Xamarin European roadshow, and have had the opportunity to meet a few thousand C# developers who share a passion for cross-platform development.

In almost every city, I’ve been asked to recommend a Xamarin.Forms style library for developing desktop applications. In this blog post I’m going to give an overview of the different options available to desktop developers who wish to target Windows, Mac and Linux.

Traditional Approach

The first approach is what we’ve named at Xamarin the ‘traditional’ approach. You’ve probably seen this approach, but for mobile. The general idea is that you should implement your user interface uniquely for each platform you wish to target. This means on Mac, you would use Cocoa (Xamarin.Mac), Windows would use WPF and Linux would use Gtk (Gtk#). This approach will guarantee that your desktop application looks and behaves as the platform users expect. It also means that your application looks great if Apple, Microsoft or the OpenSource community decide to update the look and feel of the underlying OS. It’s also worth noting that with this approach you gain 100% access to every UI control and API available in the UI libraries, and won’t be limited in your ability to create beautiful experiences for your users.

In case you’re in any doubt, this is the approach I recommend you take when developing your apps. This is actually the approach Xamarin has started to use for our new products. You can see this in action with our Profiler and Android Simulator; both of these use WPF on Windows, and Xamarin.Mac (Cocoa) on OS X.

XWT

Much like Xamarin.Forms, Xwt allows you to use one API that maps to the native widgets of the platform. This means your application when running on Windows will be using WPF widgets, on Mac its Cocoa, and Linux is Gtk. This results in a 100% native user interface on three platforms from one codebase. Much like Xamarin.Forms, because its aim is to create a unified API for all desktop platforms, it only maps to a subset of widgets and properties. It’s worth noting that with Xwt you still have the ability to implement a native widget which isn’t mapped as part of the API.

For all platforms you can use the native engine, or the Gtk engine. If you’re wondering what a Gtk app looks like on Windows and Mac, then I recommend downloading Xamarin Studio. This is primarily built using Gtk, and in areas actually uses Xwt. On Windows the native engine is WPF, on OS X its Cocoa, and on Linux it remains Gtk (using Gtk#).

Webview

One other option you might want to consider, is using a WebView for your user interface whilst maintaining a C# backend. This is the approach that Rdio has taken for their OS X client, and to a novice it’s difficult to spot that it’s not a native app. This approach can produce some great looking applications which can even run in the Cloud, but it would be difficult to claim you’ve created an application when the reality is you’ve packaged up a website.

QtSharp

Although this approach is not yet ready for consumption, I thought I would mention it as it’s a project on GitHub that excites me. Much like Xamarin.Mac is a binding to the Cocoa framework, a group of enterprising .Net developers are aiming to create a .Net binding to the Qt library. Having used Qt in a previous life, I can confirm that the UIs can often be a little hit or miss (because it’s a lowest common denominator approach). That said, if you’re developing an internal application, or willing to take the time to craft the UI for each platform (different layouts for each platform) then it can work really well.

The project is still in its infancy, and many developers have tried and failed at this approach. Its not ready for production as yet (it doesn’t appear to even be close) but its a great start. My fingers are crossed that the developers continue to invest their time in the project, and the .Net community gains access to one of the most widely used cross-platform user interfaces frameworks in existence.

Renaming your Xamarin.Mac App

Apple has a number of guidelines and rules for developers looking to publish their Apps to Apple’s app ecosystem. One of these rules relates to the name of your app. To give you a quick overview of how some developers can have issues with theses rules, I’ve gone ahead and listed a few of them below:

  • Apps with names, descriptions, screenshots, or previews that are not relevant to the content and functionality of the App will be rejected.
  • App names in iTunes Connect and as displayed on a device should be similar, so as to not cause confusion
  • Apps that misspell Apple product names in their App name (i.e., GPS for Iphone, iTunz) will be rejected.

If your App has any of the following issues then Apple will reject your binary and ask you to change the app name. In this tutorial, I will show you the properties you need to change your app name.

Menubar & About dialog

To update the name in the Finder menu bar and the About dialog, you will need to update the Bundle Name which can be found in your projects Info.plist (you will need to select the ‘Source’ tab).

xamMacRenameInfo

Dock

To update the name displayed in the Dock (on hovering over the app icon), you will need to change the “Assembly name.” To do this, you will need to navigate to the project options (right click the project and select “Options”). You will find the Assembly name property under the “Output” tab.

xamMacProperties

Installer Package

If you’re producing an installer package for your App, you will need to edit the project name in order for the generated package to have your new name. To do this, simply right click on the project and select “Rename”.