Update 2017/10/15: This walk through is now available as a Visual Studio Template! More details here: https://marketplace.visualstudio.com/items?itemName=BryanBCook.XamarinFormsCaliburnMicroStarterKit
Let me say this: Xamarin.Forms is awesome.
Xamarin.Forms is a great way to build native iOS and Android applications using C# and XAML. But if you’re just starting out, you’ll find that the most of the documentation out there, including Charles Petzold’s fantastic book, are lacking great examples on how to do MVVM, which is XAMLs strongest feature.
Last year when Caliburn.Micro finally released version 3.0 with support with Xamarin.Forms I was disappointed that there wasn’t much documentation to support it as well.
So with that said, lets build a Xamarin.Forms app using Caliburn.Micro.
Create Project
Good news here is that Visual Studio will do most of the work for us. To create a blank Xamarin.Forms project, choose File –> New Project. Then select the template Visual C# –> Cross Platform –> Blank App (Xamarin.Forms Portable).
If you specify the project name XF.CaliburnMicro, Visual Studio will create several projects:
- XF.CaliburnMicro (Portable) – This is the PCL library that will hold our Views and ViewModels and core services and interfaces
- XF.CaliburnMicro.Droid – Our Android application
- XF.CaliburnMicro.iOS – Our iPhone / iPad application
- XF.CaliburnMicro.UWP (Universal Windows) – Our Windows 10 desktop/tablet/mobile application.
- XF.CaliburnMicro.Windows (Windows 8.1) – A Windows 8.1 app, for those of us that didn’t take the free upgrade.
- XF.CaliburnMicro.WinPhone (Windows Phone 8.1) – A Windows Phone 8.1 Silverlight/XAML application.
Note: You’ll likely be prompted to specify a Windows 10 version. For now, don’t worry about this, just click OK.
Also note that I’m only going to focus on Android, iOS and UWP, so feel free to delete XF.CaliburnMicro.Windows and XF.Caliburn.WinPhone.
Compile and Run
Now would be a good time to make sure everything compiles and your machine is good to go. Xamarin.Forms requires a few dependencies to get up and running, so before we start messing things up this would be a good time for a sanity test.
For simplicity sake, let’s focus only on getting our Android emulator running. If you’re able to see the default Forms page, we’re good.
Moving along…
Reference NuGet Packages
It’s time to add Caliburn.Micro to the project. There are three key NuGet packages we’re interested in:
- Caliburn.Micro
- Caliburn.Micro.Core
- Caliburn.Micro.XamarinForms
What seems a bit counter intuitive is that the Caliburn.Micro package is platform specific, so it cannot be referenced by the PCL library.
The best way to add these to your project is to right-click the solution and choose Manage NuGet Packages for Solution. Search for “Caliburn.Micro.XamarinForms” and add it to all projects. It’ll bring in the Caliburn.Micro.Core dependency.
Search for “Caliburn.Micro.Core” and add it to the PCL “XF.CaliburnMicro (Portable)” project.
Setup basic View and ViewModel
Caliburn uses conventions to automatically map Views to ViewModels and vice-versa, so you’ll need to create two folders Views and ViewModels in the XF.XamarinForms (Portable) project.
The ViewModels\MainViewModel is pretty straight forward:
using Caliburn.Micro;
using System.Runtime.CompilerServices;
namespace XF.CaliburnMicro1.ViewModels
{
public class MainViewModel : Screen
{
private string _mainText;
public MainViewModel()
{
MainText = "Hello World!";
}
public string MainText
{
get { return _mainText; }
set
{
SetField(ref _mainText, value);
}
}
protected bool SetField<T>(ref T field, T value, [CallerMemberName] string propertyName = null)
{
if (!object.Equals(field, value))
{
field = value;
NotifyOfPropertyChange(propertyName);
return true;
}
return false;
}
}
}
And the Views\MainView.xaml is an empty screen created using Project –> Add New Item –> Forms Xaml Page:
<?xml version="1.0" encoding="utf-8" ?>
<ContentPage xmlns="http://xamarin.com/schemas/2014/forms"
xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
x:Class="XF.CaliburnMicro1.Views.MainView">
<Label Text="{Binding MainText}" VerticalOptions="Center" HorizontalOptions="Center" />
</ContentPage>
Introduce Caliburn.Micro
If you’ve worked with Caliburn.Micro in the past, you would normally configure a Bootstrapper as the primary entry point for the application. In Xamarin.Forms, the closest equivalent is the App class that is created in the PCL project. We’ll use it to setup our Inversion of Control (IoC) container and register ViewModels, services and abstractions.
Caliburn.Micro ships with a simple IoC container, aptly named SimpleContainer, which offers simple functionality to register and resolve dependencies. It is possible to replace this container with a different one if you prefer, but in my experience the SimpleContainer does exactly what we need.
namespace XF.CaliburnMicro1
{
using Caliburn.Micro;
using Caliburn.Micro.Xamarin.Forms;
using Xamarin.Forms;
using XF.CaliburnMicro1.ViewModels;
public class App : FormsApplication
{
private readonly SimpleContainer container;
public App(SimpleContainer container)
{
this.container = container;
// TODO: Register additional viewmodels and services
container
.PerRequest<MainViewModel>();
Initialize();
DisplayRootViewFor<MainViewModel>();
}
protected override void PrepareViewFirst(NavigationPage navigationPage)
{
container.Instance<INavigationService>(new NavigationPageAdapter(navigationPage));
}
protected override void OnStart()
{
// Handle when your app starts
}
protected override void OnSleep()
{
// Handle when your app sleeps
}
protected override void OnResume()
{
// Handle when your app resumes
}
}
}
Next Steps
At this point, the solution doesn’t compile, and that’s because we’ve changed the signature of the App class and we’ll have to adjust our iOS, Android and UWP projects to suit. Admittedly, it’s an awkward place to stop a blog post, but there’s a lot more to cover. Over the next few blog posts, we’ll setup the platform specific projects with their Caliburn parts and we’ll update the links below.
0 comments:
Post a Comment