This guide will walk you through the process of converting a Xamarin app to a Crosslight app. At the end of this walkthrough, you'll have a resulting project similar to Xamarin's default app with shared PCL, powered with Crosslight.

Xamarin's default template shows a button with a counter that is incremented every time it is clicked. This walkthrough will try to retain the same original functions as Xamarin's default templates, transformed to an app with strong MVVM pattern using Crosslight. This will be your first Crosslight app.

If you would to skip the following steps altogether, it is highly recommended to use the Crosslight Project Wizard to jump-start your project if you're on Windows. Or if you're on Mac, you can simply download the finished project and use it as your starter template.

Samples:

XamarinToCrosslight.zip

Follow these steps:

Preparing the Solution

Let's start by creating a new, vanilla Cross-platform Shared project with Xamarin Studio.

Mac

On Mac, open Xamarin Studio and hit New Solution. Choose Cross-platform, App, Single View App.

Hit Next. On the next window, give it app name of XamarinToCrosslight, ensure that both Target Platforms are selected, and choose to use Portable Class Library.

Hit Next. Your project is now (not quite yet) ready.

Windows

On Visual Studio, choose File, New, Project.

In the New Project dialog, choose Visual C#, Cross-Platform, Blank App (Native Portable). Give it a name of XamarinToCrosslight (or whatever you like).

Hit OK

You'll end up with 3 platform-specific projects and one PCL (Portable Class Library). Remove WinPhone project for now, as we're currently deprecating support for WinPhone in favor of Windows 10. This walkthrough will be updated later when Crosslight adds support for Windows 10.

Your project is now ready.

Tidying Up the Solution Structure (Mac only)

On Mac, if you take a look at the solution structure, you'll see that it's a bit messed up.

As you can see, the Android project resides in the Droid folder, the iOS project resides in the iOS folder, but not with the PCL project. This might be fixed by Xamarin one day. For now, let's fix it manually. Close Xamarin Studio. Create a new folder called Core.

Next, move all the highlighted files to the Core folder. 

Reopen the solution. You'll get an error similar to the following.

Let's fix the broken solution manually. To do this, simply delete the XamarinToCrosslight project from the solution, and re-add them manually.

To re-add the project, simply right-cilck on the solution and choose Add, Add Existing Project.

Choose the XamarinToCrosslight.csproj that exists inside the Core folder that we've just created.

Now your project is ready.

Adding Crosslight References via NuGet

To use Crosslight, simply resolve Crosslight NuGet packages available from nuget.org. Let's learn how to do this on both Mac and Windows.

Mac

  1. Copy and extract the Intersoft.PackageManagement.Extensions.0.1.zip to /Users/(username)/Library/Application Support/XamarinStudio-5.0/LocalInstaller/AddIns/. You can skip this step if you have installed Crosslight using the Mobile Studio 2016 (or newer) installer. You can also verify that this is installed through Xamarin Studio, Add-in Manager
     
  2. Open Xamarin Studio. You should see that a new Intersoft Package Console Extension is installed.
     
  3. To install Crosslight NuGet Packages to your project, select your project in the window that appears and execute this command.

    Install-Package Intersoft.Crosslight -allProjects

    As shown in the following shot:

  4. This will install Crosslight to all projects in your solution.
  5. Next, install Intersoft.Crosslight.Android.v7 NuGet package onto your Android project by selecting the XamarinToCrosslight.Droid project and execute the following command.

    Install-Package Intersoft.Crosslight.Android.v7

    As shown in the following shot:
     

  6. After you've installed both Intersoft.Crosslight and Intersoft.Crosslight.Android.v7 NuGet packages, you should see the references appear in your projects.

Windows

  1. Right-click on your solution and choose Manage NuGet Packages for Solution.
     
  2. In the window that appears, search for intersoft.crosslight. Select all projects, and click Install.
  3. You can monitor the package installation progress from the Output window of Visual Studio.
     
  4. Next, install the Intersoft.Crosslight.Android.v7 NuGet package onto XamarinToCrosslight.Droid project.
  5. You should now have Crosslight references in your project.
     

Fixing the Core Project

Now that you have your solution ready, the next step would be to make each of these projects Crosslight-enabled. First, let's fix the Core PCL project. These steps applies to both Xamarin Studio and Visual Studio.

  1. Start by creating a folder named Infrastructure folder and add an Empty Class, name it AppService.cs

     

    Replace the entire code as follows.

    using System;
    using Intersoft.Crosslight;
    
    namespace XamarinToCrosslight
    {
        public sealed class CrosslightAppAppService : ApplicationServiceBase
        {
            public CrosslightAppAppService(IApplicationContext context)
                : base(context)
            {
            }
    
            protected override void OnStart(StartParameter parameter)
            {
                base.OnStart(parameter);
    
                //Specify the first ViewModel to use when launching the application.
                this.SetRootViewModel<SimpleViewModel>();
            }
        }
    }

    This is the base initializer for the Core projects, here, you can see that SimpleViewModel will be highlighted as red. Let's prepare that next. The SetRootViewModel method tells the app which ViewModel should be launched for the first time.

  2. Create a new folder called ViewModels and create an empty class, name the class SimpleViewModel.cs. 


    Replace the entire class as follows.

    using Intersoft.Crosslight;
    using Intersoft.Crosslight.Input;
    using Intersoft.Crosslight.ViewModels;
    
    namespace XamarinToCrosslight
    {
        public class SimpleViewModel : ViewModelBase
        {
            public SimpleViewModel()
            {
                this.ButtonText = "Hello World, Click Me!";
                this.Count = 0;
                this.ClickCommand = new DelegateCommand(ExecuteClick);
                this.Title = "XamarinToCrosslight";
            }
    
            private string _buttonText;
            private int _count;
    
            public string ButtonText
            {
                get
                {
                    return _buttonText;
                }
                set
                {
                    if (_buttonText != value)
                    {
                        _buttonText = value;
                        this.OnPropertyChanged("ButtonText");
                    }
                }
            }
    
            public int Count
            {
                get
                {
                    return _count;
                }
                set
                {
                    if (_count != value)
                    {
                        _count = value;
                        this.OnPropertyChanged("Count");
                    }
                }
            }
    
            public DelegateCommand ClickCommand { get; set; }
    
            public void ExecuteClick(object parameter)
            {
                this.ButtonText = ++this.Count + " clicks!";   
            }
        }
    }
    
     

    In this ViewModel, 2 VM properties: Count (int) and ButtonText (string), which will be bound to the button. In the constructor, a ClickCommand (DelegateCommand) is initialized that will handle the button click event. The Title property is also set to ensure consistent title being used for all projects.

  3. Create a new folder called BindingProviders, add a new Empty Class with the name SimpleBindingProvider.cs. Replace the entire code as follows.

    using Intersoft.Crosslight;
    
    namespace XamarinToCrosslight
    {
        public class SimpleBindingProvider : BindingProvider
        {
            public SimpleBindingProvider()
            {
                this.AddBinding("myButton", BindableProperties.TextProperty, "ButtonText");
                this.AddBinding("myButton", BindableProperties.CommandProperty, "ClickCommand");
            }
        }
    }

    In Xamarin's original sample, the button that triggers the click event is given the ID / outlet of myButton. Let's use the same identifier. Here, the SimpleBindingProvider class will provide the binding definition between the View and the SimpleViewModel. The button's text is bound to the ButtonText property defined in the SimpleViewModel, and the button's command is defined to the ClickCommand property in the SimpleViewModel.

  4. Your Core project is now ready. Let's fix the Android project next.

Fixing the Android Project

Since you have the core project ready, let's proceed with the Android project. In this walkthrough, we're going to target the Material Android project available in Crosslight 5. Follow these steps:

  1. Create a new folder called Activities and create a new Activity (or an Empty Class) there. Give it a name of LaunchActivity.cs.


    Replace the entire contents as follows.

    using System;
    using Intersoft.Crosslight.Android;
    using Android.App;
    
    namespace XamarinToCrosslight.Droid
    {
        [Activity(Label = "XamarinToCrosslight", MainLauncher = true, NoHistory = true, Icon = "@mipmap/icon")]
        public class LaunchActivity : StartActivity
        {
        }
    }

    This Activity will act as the initial splash screen when the Android project is launched, and this Activity also defines the application icon.

  2. Next, under the same Activities folder, create a new Activity (or an Empty Class), and give it a name of MainActivity. You can simply move the existing MainActivity.cs from the root folder, or delete and create a new one.

    Replace the entire contents as follows.

    using Android.App;
    using Android.Widget;
    using Android.OS;
    using Intersoft.Crosslight.Android.v7;
    
    namespace XamarinToCrosslight.Droid
    {
        [Activity]
        public class MainActivity : AppCompatActivity<SimpleViewModel>
        {
        }
    }

    This Activity will act as the "container" for the Fragment, which we're going to create next.

  3. Create a new folder called Fragments, and add a new Fragment (or an Empty Class), name it SimpleFragment.cs.

    Replace the entire contents as follows.

    using Intersoft.Crosslight;
    using Intersoft.Crosslight.Android.v7;
    using System;
    using Android.Runtime;
    
    namespace XamarinToCrosslight.Droid
    {
        [ImportBinding(typeof(SimpleBindingProvider))]
        public class SimpleFragment : Fragment<SimpleViewModel>
        {
            public SimpleFragment()
                : base()
            {
            }
    
            public SimpleFragment(IntPtr intPtr, JniHandleOwnership handleOwnership)
                : base(intPtr, handleOwnership)
            {
            }
    
            protected override int ContentLayoutId
            {
                get
                {
                    return Resource.Layout.Main;
                }
            }
    
            protected override void Initialize()
            {
                base.Initialize();
                this.IconId = Resource.Mipmap.Icon;
            }
        }
    }

    This is the main View for the Android project. Starting from the top, the class is decorated with the ImportBindingAttribute, which tells which BindingProvider should be used with this View. The Fragment also takes in a ViewModel type, which tells the associated ViewModel with this View. Here, two constructors are needed for instantiation purposes, the ContentLayoutId specifies the main resource layout which will be rendered with this view. In the overridden Initialize method, the IconId specifies the icon to be used with the Toolbar.

  4. Next, create a new folder called Infrastructure and add an Empty Class, name it AppInitializer.cs.


    Replace the entire contents as follows.

    using System;
    using Intersoft.Crosslight;
    
    namespace XamarinToCrosslight.Droid
    {
        public sealed class AppInitializer : IApplicationInitializer
        {
            public IApplicationService GetApplicationService(IApplicationContext context)
            {
                return new CrosslightAppAppService(context);
            }
            public void InitializeApplication(IApplicationHost appHost)
            {
            }
    
            public void InitializeComponents(IApplicationHost appHost)
            {
            }
    
            public void InitializeServices(IApplicationHost appHost)
            {
            }
        }
    }

    This file corresponds with AppService.cs defined in the PCL project, so that the Android project understands which AppService to be used. In more complex projects, the AppService contains many valuable information such as server URLs, IoC services, containers, and more.

  5. Next, open up AndroidManifest.xml inside the Properties folder and add the following theme to your application.

    Here's the full AndroidManifest.xml file.

    <?xml version="1.0" encoding="utf-8"?>
    <manifest xmlns:android="http://schemas.android.com/apk/res/android" android:versionCode="1" android:versionName="1.0" package="com.intersoftsolutions.xamarintocrosslight">
    	<uses-sdk android:minSdkVersion="15" />
    	<application android:label="XamarinToCrosslight" android:theme="@style/Theme.Crosslight.Material.Light">
    	</application>
    </manifest>
  6. Now, let's add a little Material Design to our Android application. Add a new XML file called colors.xml inside the Resource/values folder.


    Replace the contents as follows.

    <?xml version="1.0" encoding="utf-8" ?>
    <resources>
      <color name="primary">#03A9F4</color> <!-- 500 -->
      <color name="primary_dark">#0288D1</color> <!-- 700 -->
      <color name="primary_text_color">#FFFFFF</color> <!-- depend on primary 500 -->
      <color name="accent">#29B6F6</color> <!-- 400 -->
      <color name="navigation_bar">#29B6F6</color> <!-- 400 -->
      <color name="action_menu_background">#03A9F4</color> <!-- 500 -->
      <color name="action_menu_text_color">#FFFFFF</color> <!-- depend on primary 500 -->
      <color name="window_dark_background">#000000</color>
      <color name="window_light_background">#FFFFFF</color>
      <color name="button_text_color">#FFFFFF</color> <!-- depend on primary 500 -->
      <color name="selection_background">#81D4FA</color> <!--- 200 -->
      <color name="group_separator_color">#AEAEAE</color>
      <color name="nav_end_background">#0277BD</color> <!-- 800 -->
      <color name="nav_center_background">#03A9F4</color> <!-- 500 -->
      <color name="nav_start_background">#29B6F6</color> <!-- 400 -->
      <color name="nav_header_title_text_color">#FFFFFF</color>
      <color name="nav_header_subtitle_text_color">#FFFFFF</color>
      <color name="progress_dialog_background">#03A9F4</color> <!-- 500 -->
      <color name="progress_text_color">#FFFFFF</color> <!-- depend on primary 500 -->
      <color name="progress_bar_color">#FFFFFF</color> <!-- depend on accent 400 -->
      <color name="progress_text_color_inverse">#29B6F6</color> <!-- 400 -->
      <color name="progress_bar_color_inverse">#29B6F6</color>  <!-- 400 -->
    </resources>

    Crosslight 5 provides pre-defined color value themes that you can customize easily through this XML. The chosen colors adheres to Android's Material Colors guidelines.

  7. Now your Android project should be ready. Run the project in an API level 22 simulator. You should get a result similar to Xamarin default. template.

Now that you have your Android project ready, let's move on to iOS.

Fixing the iOS Project

Although you can create iOS files within Visual Studio, it is recommended to use a Mac with Xcode and Xamarin Studio, so you can get a more refined control over what's happening with your storyboard view. Let's create the iOS project by following these steps:

  1. Create a new folder called ViewControllers, and move the existing ViewController.cs file to the folder.

    Replace the content as follows.

    using System;
    using UIKit;
    using Intersoft.Crosslight.iOS;
    using Intersoft.Crosslight;
    
    namespace XamarinToCrosslight.iOS
    {
        [Storyboard("Main")]
        [ImportBinding(typeof(SimpleBindingProvider))]
        public partial class ViewController : UIViewController<SimpleViewModel>
        {
            public ViewController(IntPtr handle)
                : base(handle)
            {		
            }
        }
    }
    
    

    The ViewController is class is decorated with the ImportBindingAttribute to tell which BindingProvider should be used. The UIViewController(TViewModel) also takes in the SimpleViewModel that was previously defined in the Core PCL project. As you can see, with Crosslight, the ViewController definition is greatly reduced. To add storyboard support to the ViewController, the class is decorated with the StoryboardAttribute that takes in the name of the storyboard file. In addition, a new constructor that takes in one IntPtr object should be defined. To learn more about Universal Storyboard support, check out this document: Working with iOS Universal Storyboards.

  2. Next, create a new Views folder and drag the Main.storyboard into the newly created folder.
  3. Let's edit the storyboard file using XCode Interface Editor. Right-click on the Main.storyboard file and choose Xcode Interface Builder.
     
    Set the ViewController's custom class as ViewController (should be there by default), and the Storyboard ID as ViewController, as shown in the following image.

    Remove the existing outlet for the button by right-clicking on the Button view and select x button. Also, remove the existing entries for the button outlet.

    Set a new outlet for the button by holding the Control button on your Mac and drag the button onto the code editor, with ViewController.h in view.
     
    Set the new outlet as myButton. This corresponds to the SimpleBindingProvider view outlet set earlier in the PCL project. Save the file and go back to Xamarin Studio.
  4. Create a new folder called Infrastructure, and create a new Empty Class inside the folder. Name it AppInitializer.cs.


    Replace the contents with the following.

    using System;
    using Intersoft.Crosslight;
    
    namespace XamarinToCrosslight.iOS
    {
        public sealed class AppInitializer : IApplicationInitializer
        {
            public IApplicationService GetApplicationService(IApplicationContext context)
            {
                return new CrosslightAppAppService(context);
            }
    
            public void InitializeApplication(IApplicationHost appHost)
            {
            }
    
            public void InitializeComponents(IApplicationHost appHost)
            {
            }
    
            public void InitializeServices(IApplicationHost appHost)
            {
            }
        }
    }

    This file corresponds with AppService.cs defined in the PCL project, so that the iOS project understands which AppService to be used. In more complex projects, the AppService contains many valuable information such as server URLs, IoC services, containers, and more.

  5. Next, open and modify AppDelegate.cs located in the root folder as follows.

    using Foundation;
    using UIKit;
    using IntersoftCore = Intersoft.Crosslight.iOS;
    
    namespace XamarinToCrosslight.iOS
    {
        // The UIApplicationDelegate for the application. This class is responsible for launching the
        // User Interface of the application, as well as listening (and optionally responding) to application events from iOS.
        [Register("AppDelegate")]
        public class AppDelegate : IntersoftCore.UIApplicationDelegate
        {  
        }
    }

    Crosslight.iOS wraps the native UIApplicationDelegate to add many functionalities under the hood.

  6. Your iOS project should be ready now. Run the project and you should get a result similar as follows.
     

Conclusion

Congratulations! You've just successfully transformed a shared native PCL project from Xamarin to a Crosslight project, making it your first Crosslight app. Now that you have a basic idea of how Crosslight works, we highly recommend you to explore many other features available in Crosslight by going through these samples in order:

If you would to skip this process altogether, it is highly recommended to use the Crosslight Project Wizard to jump-start your project, if you're on Windows. Or if you're on Mac, you can simply download the finished project and use it as your starter template. Should you have any further questions, don't hesitate to chat with us in our website.

In the next tutorial, you'll learn in depth how data binding works in Crosslight.

Sample

You can also find the resulting sample here: XamarinToCrosslight.zip. Simply open this sample with Xamarin Studio or Visual Studio and run the project.

 

Related Topics