Xuni to ComponentOne Xamarin Edition Migration Guide

May 16 2017

The new ComponentOne Xamarin Edition beta brings a number of changes, and should be a significant improvement for many Xuni customers. Moving your project from one control set isn't a very difficult process, though each has some differences in API. In this migration guide we'll look at what it takes to move from Xuni to the ComponentOne Xamarin Edition by migrating the Xuni 101 projects to use the new controls.

Control Differences

We've renamed the packages moving from Xuni to the ComponentOne Xamarin Edition so that the platform API should be more clear going forward and more closely aligns to Xamarin's. We've moved to a more consistent naming scheme for our controls based on the following pattern: C1.[Platform].[ControlName] The packages have changed their prefix if you're coming from Xuni to C1. The object names for the controls have also been realigned to have a more uniform naming scheme that is either prefixed by C1 or Flex. For instance: Calendar -> C1Calendar Xuni.Android.Calendar now corresponds to C1.Android.Calendar Xuni.iOS.Calendar now corresponds to C1.iOS.Calendar Xuni.Forms.Calendar now corresponds to C1.Xamarin.Forms.Calendar Gauges -> C1Gauge Xuni.Android.Gauges now corresponds to C1.Android.Gauge Xuni.iOS.Gauges now corresponds to C1.iOS.Gauge Xuni.Forms.Gauge now corresponds to C1.Xamarin.Forms.Gauge XuniCollectionView -> C1CollectionView Xuni.CollectionView now corresponds to C1.CollectionView FlexGrid Xuni.Android.FlexGrid now corresponds to C1.Android.Grid Xuni.iOS.FlexGrid now corresponds to C1.iOS.Grid Xuni.Forms.FlexGrid now corresponds to C1.Xamarin.Forms.Grid Core Xuni.Android.Core now corresponds to C1.Android.Core Xuni.iOS.Core now corresponds to C1.iOS.Core Xuni.Forms.Core now corresponds to C1.Xamarin.Forms.Core Minor API Changes There are some minor changes in API between ComponentOne Xamarin Edition and Xuni. These mostly amount to additions, slight changes in syntax, and use of prefix 'C1' instead of 'Xuni' in class and object names (as illustrated above).

Licensing

Xuni Enterprise and Xamarin licenses will work with Componentone Xamarin Edition so if you're already a licensed user you can move to the new platform using your Xuni key. One thing that will need to change though is that the Xuni licensing call will need to be switched with a call to the C1 Xamarin Edition license manager instead:



Xuni.Forms.Core.LicenseManager.Key = License.Key;

becomes



C1.Xamarin.Forms.Core.LicenseManager.Key = License.Key;

If you evaluated Xuni in the past, but never purchased you also can try out the beta for a limited time. The beta allows an extended evaluation that last until September 1st 2017 without a key.

Project Migration

Migrating your projects is a matter of removing Xuni references for the older controls and replacing those packages with new C1 Xamarin Edition packages from the same GrapeCity NuGet feed.

Migrating Calendar101

We'll start by examining Calendar101. Most of what needs to be changed revolves around changing the assemblies and namespace so that they match those of C1 Xamarin Edition. For example in your Xaml:


xmlns:xuni="clr-namespace:Xuni.Forms.Calendar;assembly=Xuni.Forms.Calendar"

becomes


xmlns:c1="clr-namespace:C1.Xamarin.Forms.Calendar;assembly=C1.Xamarin.Forms.Calendar"

And then the objects change as well:


<xuni:XuniCalendar x:Name="calendar"  VerticalOptions="FillAndExpand"/>

becomes


<c1:C1Calendar x:Name="calendar"  VerticalOptions="FillAndExpand"/>

In your code behind you'll need to change any Using statements:


using Xuni.Forms.Calendar;

becomes


using C1.Xamarin.Forms.Calendar;

You'll notice also that some properties have subtly changed to make them feel more naturally .NET. For instance, in the Custom Appearance sample, the Duration property for the Animations is now a TimeSpan rather than an Int.


calendar.ViewModeAnimation.Duration = 150;

becomes


calendar.ViewModeAnimation.Duration = TimeSpan.FromMilliseconds(150);

Also the CalendarDaySlot class is provided in the new 101 sample, and it allows you to further customize the appearance of your calendar. You'll need to create something similar in your old Xuni project, though this opens up new possibilities going forward. Finally the code to initialize the renderer also needs to be adjusted. Inside the AppDelegate.cs file in you iOS project you'll need to make this change:


Xuni.Forms.Calendar.Platform.iOS.Forms.Init();

becomes


C1.Xamarin.Forms.Calendar.Platform.iOS.C1CalendarRenderer.Init();

Migrating CollectionView

Next we'll examine the CollectionView. Once again you need to download the latest NuGet package of C1 Xamarin Edition and remove the Xuni package. Most of what needs to be changed revolves around changing the assemblies and namespace so that they match those of C1 Xamarin Edition. Since the CollectionView control is non-UI, we won't have to worry about the Xaml. We will have to worry about Using statements and object names in the code behind though. For instance:


using Xuni.CollectionView;

becomes


using C1.CollectionView;

And then the objects change as well:


XuniCollectionView  
XuniCursorCollectionView

becomes


C1CollectionView  
C1CursorCollectionView

That's basically the extent of the changes you'll need to make for the CollectionView. Since the control is non-UI you don't have to worry about the renderer in this case.

Migrating FlexGrid101

Migrating FlexGrid101 is more involved than the other two samples since it involves making changes for FlexGrid, CollectionView, CheckBox, and Gauge. This isn't radically different than what we've done before, but it does involve more steps. For example in your Xaml:


xmlns:xuni="clr-namespace:Xuni.Forms.Core;assembly=Xuni.Forms.Core"  
xmlns:xuni="clr-namespace:Xuni.Forms.FlexGrid;assembly=Xuni.Forms.FlexGrid"

becomes


xmlns:c1="clr-namespace:C1.Xamarin.Forms.Core;assembly=C1.Xamarin.Forms.Core"  
xmlns:c1="clr-namespace:C1.Xamarin.Forms.Grid;assembly=C1.Xamarin.Forms.Grid"

And then the objects change as well:


<xuni:XuniCheckBox "/>  
<xuni:FlexGrid />  
<xuni:XuniRadialGauge />

becomes


<c1:C1CheckBox/>  
<c1:FlexGrid />  
<c1:C1RadialGauge />

In your code behind you'll need to change any Using statements:


using Xuni.Forms.FlexGrid;  
using Xuni.CollectionView;  
using Xuni.Forms.Gauge;

becomes


using C1.Xamarin.Forms.Grid;  
using C1.CollectionView;  
using C1.Xamarin.Forms.Gauge;

We've also adjusted the CellFactory slightly by changing the CreateCell method to PrepareCell with a slightly different signature that should be easier to use.


        public override GridCellView CreateCell(GridCellType cellType, GridCellRange range)  
        {  
            var cell = base.CreateCell(cellType, range);  
            if (cellType == GridCellType.Cell && range.Column == 4)  
            {  
                var cellValue = Grid[range.Row, range.Column] as int?;  
                if (cellValue.HasValue)  
                {  
                    cell.BackgroundColor = cellValue < 50.0 ? Color.Red : Color.Green;  
                }  
            }  
            return cell;  
        }

becomes


        public override void PrepareCell(GridCellType cellType, GridCellRange range, GridCellView cell)  
        {  
            base.PrepareCell(cellType, range, cell);  
            if (cellType == GridCellType.Cell && range.Column == 4)  
            {  
                var cellValue = Grid[range.Row, range.Column] as int?;  
                if (cellValue.HasValue)  
                {  
                    cell.BackgroundColor = cellValue < 50.0 ? Color.Red : Color.Green;  
                }  
            }  
        }

Once again the code to initialize the renderers also needs to be adjusted. Inside the AppDelegate.cs file in you iOS project you'll need to make this change:


Xuni.Forms.FlexGrid.Platform.iOS.Forms.Init();  
Xuni.Forms.Gauge.Platform.iOS.Forms.Init();

becomes


C1.Xamarin.Forms.Grid.Platform.iOS.FlexGridRenderer.Init();  
C1.Xamarin.Forms.Gauge.Platform.iOS.C1GaugeRenderer.Init();

Migrating Gauge101


xmlns:xuni="clr-namespace:Xuni.Forms.Gauge;assembly=Xuni.Forms.Gauge"

becomes


xmlns:c1="clr-namespace:C1.Xamarin.Forms.Gauge;assembly=C1.Xamarin.Forms.Gauge"

And then the objects change as well:


 <xuni:XuniRadialGauge />  
 <xuni:XuniBulletGraph />  
<xuni:XuniLinearGauge />

becomes


<c1:C1RadialGauge />  
<c1:C1BulletGraph />  
<c1:C1LinearGauge />c1

In your code behind you'll need to change any Using statements:


using Xuni.Forms.Gauge;

becomes


using C1.Xamarin.Forms.Gauge;

Once again (as mentioned for Calendar), the Animation Duration properties now accept a TimeSpan rather than a double. This means:


Gauge.UpdateAnimation.Duration = _stepDuration - 500;

becomes


Gauge.UpdateAnimation.Duration = TimeSpan.FromMilliseconds(_stepDuration - 500);

Another notable change is that Gauge.GetImage() now returns a Task rather than a direct byte array. This means we'll need to change the signature for SavePictureToDisk:


void SavePictureToDisk(string filename, byte[] imageData, Page page);

becomes


  void SavePictureToDisk(string filename, Task<byte[]> imageData, Page page);

You can refer to the GitHub sample for further information on the platform implementations. Once again the code to initialize the renderers also needs to be adjusted. Inside the AppDelegate.cs file in you iOS project you'll need to make this change:


Xuni.Forms.Gauge.Platform.iOS.Forms.Init();

becomes


C1.Xamarin.Forms.Gauge.Platform.iOS.C1GaugeRenderer.Init();

Future of Xuni

As we continue to refine ComponentOne Xamarin Edition, we will gradually emphasize this control set more and more. With the full release of the ComponetOne Xamarin Edition, we will be sun-setting Xuni as a product. Since currently licensed users can move to the new platform using their existing key, we feel that this will be the best experience for users going forward. It is a more stable and better performing product that we hope everyone gives a try.

MESCIUS inc.