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.
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
- 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.
- Open Xamarin Studio. You should see that a new Intersoft Package Console Extension is installed.
To install Crosslight NuGet Packages to your project, select your project in the window that appears and execute this command.
As shown in the following shot:
- This will install Crosslight to all projects in your solution.
Next, install Intersoft.Crosslight.Android.v7 NuGet package onto your Android project by selecting the XamarinToCrosslight.Droid project and execute the following command.
As shown in the following shot:
- After you've installed both Intersoft.Crosslight and Intersoft.Crosslight.Android.v7 NuGet packages, you should see the references appear in your projects.
Windows
- Right-click on your solution and choose Manage NuGet Packages for Solution.
- In the window that appears, search for intersoft.crosslight. Select all projects, and click Install.
- You can monitor the package installation progress from the Output window of Visual Studio.
- Next, install the Intersoft.Crosslight.Android.v7 NuGet package onto XamarinToCrosslight.Droid project.
- 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.
Start by creating a folder named Infrastructure folder and add an Empty Class, name it AppService.cs.
Replace the entire code as follows.
AppService.csThis 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.
Create a new folder called ViewModels and create an empty class, name the class SimpleViewModel.cs.
Replace the entire class as follows.
SimpleViewModel.csIn 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.
Create a new folder called BindingProviders, add a new Empty Class with the name SimpleBindingProvider.cs. Replace the entire code as follows.
SimpleBindingProvider.csIn 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.
- 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:
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.
LaunchActivity.csThis Activity will act as the initial splash screen when the Android project is launched, and this Activity also defines the application icon.
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.
MainActivity.csThis Activity will act as the "container" for the Fragment, which we're going to create next.
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.
SimpleFragment.csThis 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.
Next, create a new folder called Infrastructure and add an Empty Class, name it AppInitializer.cs.
Replace the entire contents as follows.AppInitializer.csThis 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.
Next, open up AndroidManifest.xml inside the Properties folder and add the following theme to your application.
Here's the full AndroidManifest.xml file.
AndroidManifest.xmlNow, 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.colors.xmlCrosslight 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.
- 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:
Create a new folder called ViewControllers, and move the existing ViewController.cs file to the folder.
Replace the content as follows.ViewController.csThe 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.
- Next, create a new Views folder and drag the Main.storyboard into the newly created folder.
- 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. 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.AppInitializer.csThis 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.
Next, open and modify AppDelegate.cs located in the root folder as follows.
AppDelegate.csCrosslight.iOS wraps the native UIApplicationDelegate to add many functionalities under the hood.
- 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.