Introducing Pontoon – A flexible bridge to the Universal Windows Platform

I first created the “Charming” libraries for Windows Phone in order to add some APIs which were added to Windows 8 but not available on phone. Many of the early ones replicated the “Charms” related functionality (Sharing/Search/Settings) hence the silly name.

When I created version 9 about a year ago I consolidated lots of separate libraries into just two – InTheHand and InTheHand.UI. The latter contained UI specific functionality such as MessageDialog, ToastNotification and ApplicationSettings. Following this I extended the library with support for iOS and Android using Xamarin and exposing the same UWP style API.

As I’ve been doing Xamarin development recently I’m constantly having to look for or write wrappers for native APIs to use across platforms. You sometimes find libraries which claim to provide a cross-platform API but actually only support iOS and Android. I looked at the large codebase I already had and thought about other areas which could be implemented across all the Windows and Xamarin platforms. Among the Windows platforms I added Win32 support so you can use these same APIs from Console, WinForms or WPF applications on versions prior to Windows 10. Since a lot of desktop apps still support Windows Vista and 7 this was very important to provide future code compatibility with Windows 10.

I’d toyed with changing the name before because it’s now irrelevant in an OS which no longer has the concept of Charms. I thought about the Windows 10 “bridges” – to take Desktop Apps, iOS and Silverlight to UWP and thought what I have here is effectively another bridge. It’s a flexible one though and it also works in both directions. You can code C# on numerous platforms and that code will be instantly portable to UWP. You can also use your UWP knowledge to easily target some of the more fiddly aspects of Xamarin platforms consistently. If you consider a Xamarin Forms application which might target iOS, Android and Windows once you step beyond laying out forms with the built in controls and basic page navigation there is no common API to work with Settings, Files, Geolocation, Network connectivity and more. If you are able to find a NuGet library which supports all the platforms you need you’ll have to learn a whole new API too. One word which kept springing to mind with the concept of a flexible bridge is Pontoon and so this is what I chose. Wikipedia says “A pontoon bridge, also known as a floating bridge, uses floats or shallow-draft boats to support a continuous deck for pedestrian and vehicle travel”. Although I renamed the GitHub repository this is a direct continuation of the Charming codebase but there will be a few breaking changes hence the new NuGet package and major version change.

If you are interesting in contributing to the library please do get in touch. There are a number of open issues which are still to be addressed and many more API areas which would make sense to implement in this way. I’ve consciously avoided most UI areas because this is something you’ll need to approach differently for each platform (unless you use Xamarin Forms) and I didn’t want introduce any additional dependencies. There are some UI elements such as StatusBar, MessageDialog, Toast/Badge notifications, CameraCaptureUI etc. I consider these to be part of the “Chrome” rather than your app UI – they will all have a very different look and feel depending on the platform but perform the same functions.

I’m still working on a sample application. I’ll probably use Xamarin Forms in order to create a simple UI to surface as much of this functionality as possible.

As always I welcome all constructive feedback – please use GitHub to raise any issues.

NuGet: https://www.nuget.org/packages/InTheHand.Pontoon/

GitHub: https://github.com/inthehand/Pontoon

Docs: http://inthehand.github.io/

 

Xamarin Free For All!

Yesterday Microsoft announced that the Xamarin platform (the ability to run C# apps on iOS and Android) would be free with all versions of Visual Studio 2015 Update 2. This is great news and takes away a barrier for developers to use their .NET skills to write cross-platform apps.

We’ve had a number of free libraries for Xamarin for a while so I just wanted to post a quick reminder:-

Charming Apps – Provides consistent UWP style APIs you can call across iOS, Android and Windows platforms for many common tasks. From reading the app manifest properties at runtime through to UI elements and integration with platform functions like SMS, Email etc.

Xamarin Forms Maps Windows Renderers – Currently Xamarin Forms Maps only has renderers for iOS, Android and Windows Phone Silverlight. This package adds renderers for WinRT and UWP platforms.

Device Picker – Currently only supporting Windows platforms this adds a UWP style device picker to Windows Phone 8.1 and Windows 8.1 projects.

We’re continuing to extend the Charming apps libraries and will monitor as Xamarin Forms evolves…

UWP and XAML CustomResource Markup

UWP doesn’t support writing custom markup extensions however there is one built in markup extension which is extensible. The CustomResource extension allows you to write XAML such as:-

<TextBlock Text="{CustomResource PortableStringResource1}"/>

In this case PortableStringResource1 is a unique key to refer to a resource in a source of your choosing. There is no out of the box implementation so you need to create your own class which derives from Windows.UI.Xaml.Resources.CustomXamlResourceLoader and provide an implementation of GetResource. Then in code which runs during your app start-up you create a new instance of your custom class and assign it to CustomXamlResourceLoader.Current. Then all requests are passed to your code to be resolved.

One place you may want to use this is where you are getting string resources from a different source than the modern resource system. In a pure UWP approach you can set an x:Uid for a XAML control then add string resources of the form MyId.SomeProperty to set the specified property from the resource. Another place you might have resources defined might be in a Portable Class Library. Because these work across multiple projects you might have string resources specified in a .resx file which you use with a number of projects (think Xamarin etc) and you may wish to also use these from a UWP client. Because of the way these resources are built into the UWP project you can access them via a Windows.ApplicationModel.Resources.ResourceLoader provided you specify the name of the resource set. This is the full namespace and classname of the generated class in the PCL. For example if your PCL has a base namespace of PortableClassLibrary and you have a resx file called StringResources.resx this is “PortableClassLibrary.StringResources”.

For the platforms where it is supported I’ve added a WindowsXamlResourceLoader class to InTheHand.UI. This can be used to refer to either resources defined in the UWP application resw or a named resource set in a referenced library. The source can be found here:-

https://github.com/inthehand/Charming/blob/master/Source/InTheHand/UI/Xaml/Resources/WindowsXamlResourceLoader.cs

An example of setting up the resource loader is called in the App.xaml.cs App() constructor:-

Windows.UI.Xaml.Resources.CustomXamlResourceLoader.Current = new InTheHand.UI.Xaml.Resources.WindowsXamlResourceLoader(typeof(PortableClassLibrary.StringResources).FullName);

The sample project for this blog contains the UwpClientApp and PortableClassLibrary projects to demonstrate the complete solution.

This is just one example of harnessing the CustomResource markup extension for your own use. You could write a resource loader to return values from any other source, you supply the glue to hook it together. The only limitation is you can’t really change the resource loader while dipping in and out of parts of your app so you need just one implementation. You could work around this by prefixing the key with different values linked to different sources…

Xamarin Forms Windows Colours

When you work with custom renderers on Xamarin Forms (and it’s very difficult not to!) you often have to convert from Xamarin Forms types to their native platform equivalent. In the iOS and Android implementations Xamarin include some extension methods to easily convert Color to the native equivalent. Being the Cinderella of the Xamarin Forms platforms Windows platforms have missed out on this so I’ve filled the gap with this handy extension method:-

https://gist.github.com/peterfoot/be89d5b3c5ac4cc16ae1

This works for Windows Phone 8.1, Windows Store and UWP targets (sorry I haven’t created the Silverlight equivalent)

WebAuthenticationBroker Hints

Anyone who has tried to use the WebAuthenticationBroker beyond the simplest of scenarios has probably run into problems and sometimes all you want is a good descriptive error message. Getting things setup just right often takes a certain amount of trial and error so I’m documenting a few things here which are the results of a certain amount of trial and a considerable amount of error. This is as much a reminder for myself the next time I try and do this as it is (hopefully) some useful extra information for you.

Single Sign-in

If you can get the stars to align correctly, your OAuth endpoint can perform single sign-in on a corporate network. If you read the documentation you’ll see you have to specify the flag WebAuthenticationOptions.UseCorporateNetwork when you call AuthenticateAsync. This can be confusing because this flag isn’t needed when debugging when your app is given Intranet access automatically. To set this flag you also need to specify Enterprise Authentication, Private Networks and Shared User Certificates capabilities in your application manifest. Once you’ve added these you can’t submit the app through the public Windows Store.

A caveat to this is that you can only do single sign-in if your “web” application is setup with a redirect Uri which is the app package identity and you use the overload of AuthenticateAsync which doesn’t take a redirect Uri. This is the Uri returned from a call to Windows.Security.Authentication.Web.WebAuthenticationBroker.GetCurrentApplicationCallbackUri() at runtime. This identity will change between a side-loaded developer signed package and one which has been distributed through the Windows Store or a private company portal.

Error Codes

A lot of errors within the WebAuthenticationBroker process will result in a return status of WebAuthenticationStatus.UserCancel. However this is not always because the user has explicitly cancelled the process. The ResponseErrorDetail property returns an error code to give the reason and here are some possible values:-

0x800c0019 – An SSL failure. A common cause of this is that the clock is not set correctly on your phone/PC and it can often occur when your device battery went flat and it reset itself to some default date in 2014 and you’ve forgotten to correct it.

0x800c0005 – Network connection error. This is probably because you have no mobile signal and no WiFi.

This isn’t an exhaustive list but knowing the common error codes allows you to write a descriptive message for the user to hopefully resolve the problem themselves.

InTheHand.UI v9.0

I’ve updated InTheHand on NuGet and added the accompanying library containing UI functionality (InTheHand.UI). The main shared piece of functionality here is the MessageDialog (ala Windows.UI.Popups) and this works across all the Windows platforms (Including Windows Phone Silverlight) and iOS and Android. The appearance of the dialog is as the native experience with one exception…

MessageDialog.UWP.Native

We noticed on Windows 10 that the appearance of MessageDialog changed for our 8.1 app, rather than being a band across the width of the screen it was now a true floating window in its own right but this had one negative aspect – the title text appeared twice on the dialog. Users reported this as confusing and there is currently no workaround directly. In UWP apps there is now a ContentDialog control which is used for popping up content with up to two action buttons (you may recall this from Windows Phone 8.1) and so our implementation wraps this API on Windows 10 Desktop while exposing a single MessageDialog API. To avoid breaking the API we currently fall back to the system MessageDialog if you use three Commands. You can see a taste of the various flavours below:-

MessageDialog.Montage

The other functionality within InTheHand.UI is currently specific to Windows flavours and I’ll be discussing it in a future post.