Walkthrough: Deploy .NET JMS Clients to iOS or Android Using Xamarin
In this walkthrough, you will learn how to deploy an existing Microsoft .NET JMS web client as a Xamarin app for iOS and Android. This procedure demonstrates how you can build a Microsoft .NET JMS client using the Kaazing Gateway Microsoft .NET JMS client library and then use Xamarin to deploy the client as an app on iOS or Android devices.
This topic walks you through the following subjects:
- What You Will Accomplish
- Before You Begin
- Download the Kaazing Library and Demo Files and Xamarin
- Configure Xamarin Studio
- Build the Xamarin Apps
- Run and Test the Xamarin Apps in iOS Simulator or Android Emulator
At the end of this walkthrough, a Xamarin .NET JMS demo created using the Kaazing Gateway Microsoft .NET JMS libraries runs as an app on iOS and Android, connects to a publicly available message broker and Gateway, and sends and receives JMS messages using a native or emulated WebSocket connection. Users can run the iOS or Android app on any iOS or Android device and connect via the Gateway to the message broker.
This walkthrough uses the Xamarin JMS demo available on Github at https://github.com/kaazing/xamarin.client.tutorials/tree/develop/jms, but the steps outlined in this walkthrough are the same for other Xamarin JMS client applications built with the Kaazing Enterprise Xamarin Client SDK.
Before starting this walkthrough you need the following:
- Kaazing Enterprise .NET SDK (includes Xamarin). See Setting Up the Gateway and Clients.
- Kaazing Xamarin Demo on Github at https://github.com/kaazing/xamarin.client.tutorials.
- Xamarin Studio Community if you are developing on Mac OS, or Xamarin for Visual Studio if you are developing on Windows.
- A Xamarin account. To create a Xamarin account, see https://store.xamarin.com/Login?from=%2faccount%2f.
- iOS SDK (optional). The iOS SDK is required in order to use the iOS Simulator.
- Android SDK (optional). The Android SDK is required in order to use the Android Emulator. For the Android SDK, see https://developer.android.com/sdk/index.html.
Learn about supported browsers, operating systems, and platform versions in Release Notes.
The following steps link to resources to take you through the installation of the software required for deploying Xamarin apps. If you already have this software installed, you can simply note the locations of the installed software for later use.
- Download the Kaazing Enterprise .NET SDK (includes Xamarin) as described in Setting Up the Gateway and Clients.
- Download the Kaazing Xamarin Demos on Github at https://github.com/kaazing/xamarin.client.tutorials.
- Download and install Xamarin Studio Community if you are developing on Mac OS, or Xamarin for Visual Studio if you are developing on Windows.
The following steps configure Xamarin Studio Community on Mac OSX for building iOS and Android apps.
- Launch Xamarin Studio Community.
Add the the Kaazing Xamarin JMS tutorial.
- In Xamarin Studio, click Open.
- Navigate to the location of the Xamarin tutorials in your copy of the Kaazing Xamarin demo: xamarin.client.tutorials/jms.
Click the file named jms.client.xamarin.demo.sln and click Open. Xamarin Studio loads the demos for Android and iOS. The following demos are loaded:
Add the Kaazing Enterprise .NET client libraries to the demos:
- Expand the demo you want to build and run.
- Right-click References and click Edit References.
- In the Edit References dialog, click the .Net Assembly tab.
- Click Browse and navigate to the location of the Kaazing .NET client libraries, for example:
- Click both Kaazing.Gateway.dll and Kaazing.JMS.dll, and then click Add.
- Click OK. In the References folder, you will now see Kaazing.JMS and Kaazing.WebSocket.
- KaazingJMSXamarinDemo.Android and KaazingJMSXamarinDemo.iOS.Classic both share KaazingJMSXamarinDemo.Common. The UI is defined once using Xamarin.Forms in KaazingJMSXamarinDemo.Common and is reused by the iOS and Android projects. Similarly, the code that handles user events in KaazingJMSXamarinDemo.Common is reused by the iOS and Android projects. This method demonstrates how to develop an app using C# and deploy the same app to both iOS and Android.
- The Xamarin.Forms package is not available for the Unified API. As a result, KaazingJMSXamarinDemo.iOS.Unified defines its own UI using a storyboard and has code for dealing with user events. KaazingJMSXamarinDemo.iOS.Unified is not sharing or reusing the code from KaazingJMSXamarinDemo.Common like KaazingJMSXamarinDemo.Android and KaazingJMSXamarinDemo.iOS.Classic are. For more information, see http://forums.xamarin.com/discussion/24616/xamarin-forms-and-ios-unified-api.
The following steps build the Xamarin apps for iOS and Android using the Xamarin project you created.
- For Android, right-click the Android tutorials named KaazingJMSXamarinDemo.Android, and then click Build KaazingJMSXamarinDemo.Android.
- For iOS, right-click either the iOS tutorials named KaazingJMSXamarinDemo.iOS.Unified, KaazingJMSXamarinDemo.Common, or KaazingJMSXamarinDemo.iOS.Classic, and then click Build Project_Name.
Xamarin Studio informs you that the project is built. If you encounter Kaazing Gateway .NET library errors, ensure that you have included the libraries in the Reference folder for the demo as described in Configure Xamarin.Notes:
- If you receive provisioning errors for iOS apps, such as
Warning: No installed provisioning profiles match the bundle identifier. (KaazingJMSXamarinDemo.iOS.Classic, see Device Provisioning from Xamarin.
- If you receive Android API errors, run the Android SDK Manager from Xamarin Studio (Tools > Open Android SDK Manager) and add the required SDK version.
The following steps run the Xamarin app and test the connection to the Gateway and Apache ActiveMQ.Note: The iOS SDK is required in order to use the iOS Simulator. For the iOS SDK, see https://developer.apple.com/xcode/. The Android SDK is required in order to use the Android Emulator. For the Android SDK, see https://developer.android.com/sdk/index.html. Learn about supported browsers, operating systems, and platform versions in Release Notes.
For information on using the Android Emulator in Xamarin Studio, see the Xamarin article here: http://developer.xamarin.com/guides/android/getting_started/installation/configure_emulator/.
Start the Android virtual device you will use for testing.
- Right-click the Android demo, click Run With, and then select an emulator device.
For the demo, you need to run a virtual device with Android 6.0 - API 23 or later. In you do not have a virtual device with this requirement (in the Android Virtual Device Manager, you will see the message
No system images installed for this target), then you need to install Android 6.0 (API 23) using the Android SDK Manager and update your virtual device. Here is an example virtual device setup:
- Device: Nexus 5
- Target: Android 6.0 - API 23
- CPU/ABI: ARM (armeabi-v7a)
The target Adroid framework for the project must match the Android framework in the virtual device. To see the target framework for your project, right-click the project, click Options, and click Android Application. To change the target framework of your virtual device, you can run the Android Device Manager from the Tools menu of the Android SDK Manager.
- Right-click the Android demo, click Run With, and then select an emulator device.
For iOS, see the iOS Simulator guide here: https://developer.apple.com/library/ios/documentation/IDEs/Conceptual/iOS_Simulator_Guide/Introduction/Introduction.html.
- Run the iOS demo. In Xamarin Studio, right-click the iOS demo, click Run With, and then click an iOS Simulator (for example, iPhone 6 / iOS 8.1). The iOS Simulator opens and displays the demo.
The following steps test the Xamarin app on the iOS Simulator or Android Emulator.
In the demo running in the iOS Simulator or Android Emulator, enter the locationNote: If you decide to use a local Gateway, the Android Emulator or device will not allow the use of localhost. For the Android, change the value of the accept tag in the configuration file of the Gateway to the local IP address of the Gateway, and enter the IP address in the Location field of the app.
wss://demos.kaazing.com/jmsand click Connect. The demo connects to the publicly available message broker and Gateway.
- Click Subscribe. You are subscribed to the topic destination.
- Click Send. The message is sent to the message broker and the subscription is updated with the received message.