Monday, April 24, 2017

My favourite Visual Studio Snippets

It happens a fair bit: there’s a small identical piece of code that you have to need to include in each project you work on. Sometimes you can copy and paste from an old project or you simply write it from scratch. You do this over and over so much that you get used to writing it.

Fortunately, Visual Studio “snippets” can tame this monster. Simply type a keyword and hit tab twice and – bam! – code magically appears. But if you’re like me, the thought of deviating from your project to write a snippet can seem tedious. Lucky for you, you don’t have to write them, you can just borrow my favourite snippets.

vmbase

My vmbase snippet includes some common boilerplate code for INotifyPropertyChanged. It includes the SetField<T> method you may see in a few of my posts. After adding this snippet, be sure to decorate your class with INotifyPropertyChanged.

<?xml version="1.0" encoding="utf-8" ?>
<CodeSnippets  xmlns="http://schemas.microsoft.com/VisualStudio/2005/CodeSnippet">
    <CodeSnippet Format="1.0.0">
        <Header>
            <Title>Base ViewModel implementation</Title>
            <Shortcut>vmbase</Shortcut>
            <Description>Inserts SetField and NotifyPropertyChanged</Description>
            <Author>BCook</Author>
            <SnippetTypes>
                <SnippetType>Expansion</SnippetType>
            </SnippetTypes>
        </Header>
        <Snippet>
            <Imports>
                <Import>
                    <Namespace>System.Collections.Generic</Namespace>
                </Import>
                <Import>
                    <Namespace>System.ComponentModel</Namespace>
                </Import>
                <Import>
                    <Namespace>System.Runtime.CompilerServices</Namespace>
                </Import>

            </Imports>
            <Declarations>
            </Declarations>
            <Code Language="csharp"><![CDATA[
            protected bool SetField<T>(ref T field, T value, [CallerMemberName] string propertyName = null)
            {
                if (!EqualityComparer<T>.Default.Equals(field, value))
                {
                    field = value;
                    NotifyPropertyChanged(propertyName);
                    return true;
                }
                
                return false;
            }
            
            protected void NotifyPropertyChanged([CallerMemberName] string propertyName = null)
            {
                var handler = PropertyChanged;
                if (handler != null)
                {
                    handler(this, new PropertyChangedEventArgs(propertyName));
                }
            }
$end$]]>
            </Code>
        </Snippet>
    </CodeSnippet>
</CodeSnippets>

propvm

The propvm snippet is similar to other “prop” snippets. It creates a property with a backing field and uses the SetField<T> method for raising property change notifications.

<?xml version="1.0" encoding="utf-8" ?>
<CodeSnippets  xmlns="http://schemas.microsoft.com/VisualStudio/2005/CodeSnippet">
    <CodeSnippet Format="1.0.0">
        <Header>
            <Title>Define a Property with SetField</Title>
            <Shortcut>propvm</Shortcut>
            <Description>Code snippet for a ViewModel property</Description>
            <Author>Bryan Cook</Author>
            <SnippetTypes>
                <SnippetType>Expansion</SnippetType>
            </SnippetTypes>
        </Header>
        <Snippet>
            <Declarations>
                <Literal>
                    <ID>type</ID>
                    <ToolTip>Property Type</ToolTip>
                    <Default>string</Default>
                </Literal>
                <Literal>
                    <ID>property</ID>
                    <ToolTip>Property Name</ToolTip>
                    <Default>MyProperty</Default>
                </Literal>
                <Literal>
                    <ID>field</ID>
                    <ToolTip>Field Name</ToolTip>
                    <Default>myProperty</Default>
                </Literal>
            </Declarations>
            <Code Language="csharp"><![CDATA[
private $type$ _$field$;

public $type$ $property$
{
    get { return _$field$; }
    set { SetField(ref _$field$, value); }
}
$end$]]>
            </Code>
        </Snippet>
    </CodeSnippet>
</CodeSnippets>

propbp

Similar to the propdp snippet which creates WPF dependency properties, propbp creates a Xamarin.Form BindableProperty.

<?xml version="1.0" encoding="utf-8" ?>
<CodeSnippets  xmlns="http://schemas.microsoft.com/VisualStudio/2005/CodeSnippet">
    <CodeSnippet Format="1.0.0">
        <Header>
            <Title>Define a Xamarin.Forms Bindable Property</Title>
            <Shortcut>propbp</Shortcut>
            <Description>Code snippet for Xamarin.Forms Bindable Property</Description>
            <Author>Bryan Cook</Author>
            <SnippetTypes>
                <SnippetType>Expansion</SnippetType>
            </SnippetTypes>
        </Header>
        <Snippet>
            <Imports>
                <Import>
                    <Namespace>Xamarin.Forms</Namespace>
                </Import>
            </Imports>
            <Declarations>
                <Literal>
                    <ID>type</ID>
                    <ToolTip>Property Type</ToolTip>
                    <Default>string</Default>
                </Literal>
                <Literal>
                    <ID>property</ID>
                    <ToolTip>Property Name</ToolTip>
                    <Default>MyProperty</Default>
                </Literal>
                <Literal>
                    <ID>owner</ID>
                    <ToolTip>Owner Type for the BindableProperty</ToolTip>
                    <Default>object</Default>
                </Literal>
            </Declarations>
            <Code Language="csharp"><![CDATA[
#region $property$
public static BindableProperty $property$Property =
    BindableProperty.Create(
        "$property$",
        typeof($type$),
        typeof($owner$),
        default($type$),
        defaultBindingMode: BindingMode.OneWay,
        propertyChanged: On$property$Changed);
        
private static void On$property$Changed(BindableObject sender, object oldValue, object newValue)
{
}
#endregion

public $type$ $property$
{
    get { return ($type$)GetValue($property$Property); }
    set { SetValue($property$Property, value); }
}

$end$]]>
            </Code>
        </Snippet>
    </CodeSnippet>
</CodeSnippets>

testma

Visual Studio ships with a super helpful testm snippet which generates a MSTest test method for you. My simple testma snippet creates an asynchronous test method.

<?xml version="1.0" encoding="utf-8" ?>
<CodeSnippets  xmlns="http://schemas.microsoft.com/VisualStudio/2005/CodeSnippet">
    <CodeSnippet Format="1.0.0">
        <Header>
            <Title>Async Test Method</Title>
            <Shortcut>testma</Shortcut>
            <Description>Inserts Test Method with async keyword</Description>
            <Author>BCook</Author>
            <SnippetTypes>
                <SnippetType>Expansion</SnippetType>
            </SnippetTypes>
        </Header>
        <Snippet>
            <Imports>
                <Import>
                    <Namespace>Microsoft.VisualStudio.TestTools.UnitTesting</Namespace>
                </Import>
                <Import>
                    <Namespace>System.Threading.Tasks</Namespace>
                </Import>
            </Imports>
            <References>
                <Reference>
                    <Assembly>Microsoft.VisualStudio.QualityTools.UnitTestFramework.dll</Assembly>
                </Reference>
            </References>        
            <Declarations>
                <Literal>
                    <ID>method</ID>
                    <ToolTip>MethodName</ToolTip>
                    <Default>TestMethodName</Default>
                </Literal>
                <Literal Editable="false">
                    <ID>TestMethod</ID>
                    <Function>SimpleTypeName(global::Microsoft.VisualStudio.TestTools.UnitTesting.TestMethod)</Function>
                </Literal>                
            </Declarations>
            <Code Language="csharp"><![CDATA[
            [$TestMethod$]
            public async Task $method$()
            {
                // await ...
                Assert.Fail();
            }
            
$end$]]>
            </Code>
        </Snippet>
    </CodeSnippet>
</CodeSnippets>

Installing Snippets

To install the snippets:

  1. Copy/paste each snippet into a dedicated file on your hard-drive, eg propbp.snippet
  2. In Visual Studio, select Tools –> Code Snippets Manager
  3. Click the Import button
  4. Navigate to the location where you put the snippets
  5. Select one or more snippet files.
  6. Click Open and Ok.

To use them, simply type the keyword for the snippet (as defined in the ShortCut element in the snippet) and press the tab key twice.

Note: If you have resharper installed, the default tab/tab keyboard shortcut might not be enabled.

Any feedback is greatly welcomed.

Enjoy.

submit to reddit

Monday, April 17, 2017

DataBinding for Custom Xamarin.Forms controls

In my last post we looked at obtaining a reference to controls from within our ViewModel. While this approach is a good workaround for non-MVVM friendly user controls a better long term strategy is to adapt these controls to support the MVVM features you need. Today's post will take a quick stab at adding binding support to the Map control.

If you follow Xamarin’s walk-through for the Map control it shows pins are added directly to the control from the code-behind. This post will use a more MVVM-friendly approach by adding a few bindable properties to the custom control so that we can manipulate the Map using data in the ViewModels only. We'll design our custom Map to dynamically add and remove pins, and to set focus and center on a specific pin.

Create a Custom Control

Because we’re not changing the behaviour or appearance of the control we simply need to derive from the Map control and Xamarin.Forms will use its default renderer to display the control. If we wanted to change the behavior or layout of the pins, things get a bit more complicated and we’d need to create a custom renderer for each platform. Xamarin has a good tutorial on how to create custom renderers.

Here’s the starting point for our custom map.

namespace XF.CaliburnMicro1.Controls
{
    using Xamarin.Forms;
    using Xamarin.Forms.Maps;
    
    public class CustomMap : Map
    {
    
    }
    
}

Add Bindable Properties

Although the Map control has several bindable properties already (HasScrollEnabled, HasZoomEnabled, IsShowingUser, MapType) it does not support properties for the Pins or currently selected pin. These are easy to add:

public static BindableProperty PinsItemsSourceProperty =
    BindableProperty.Create(
        "PinsItemsSource",
        typeof(IEnumerable<Pin>),
        typeof(CustomMap),
        default(IEnumerable<Pin>),
        propertyChanged: OnPinsItemsSourcePropertyChanged);

public static BindableProperty SelectedItemProperty =
    BindableProperty.Create(
        "SelectedItem",
        typeof(Pin),
        typeof(CustomMap),
        null,
        defaultBindingMode: BindingMode.TwoWay,
        propertyChanged: OnSelectedItemChanged
        );

public Pin SelectedItem
{
    get { return (Pin)GetValue(SelectedItemProperty); }
    set { SetValue(SelectedItemProperty, value); }
}

public IEnumerable<Pin> PinsItemsSource
{
    get { return (IEnumerable<Pin>)GetValue(PinsItemsSourceProperty); }
    set { SetValue(PinsItemsSourceProperty, value); }
}

Add Property Changed Callbacks

Similar to WPF’s DependencyProperties, BindableProperties have the ability to invoke a callback when new values are assigned through data bindings. The callback function for the data-bound pin collection is pretty straight forward — it assigns the new value to a property on the control. The real magic for the collection is that it uses Caliburn.Micro’s BindableCollection<T> – a thread-safe implementation of ObservableCollection<T> – which we use to listen for changes to the collection. Whenever the collection changes we copy the Pin to the Control’s default Pins collection.

private static void OnPinsItemsSourcePropertyChanged(BindableObject bindable, object oldValue, object newValue)
{
    var control = (CustomMap)bindable;

    control.PinsCollection = newValue as IObservableCollection<Pin>;
}

private IObservableCollection<Pin> _collection;

protected IObservableCollection<Pin> PinsCollection
{
    get { return _collection; }
    set
    {
        if (_collection != null)
        {
            _collection.CollectionChanged -= OnObservableCollectionChanged;
        }

        _collection = value;

        if (_collection != null)
        {
            _collection.CollectionChanged += OnObservableCollectionChanged;
        }
    }
}

private void OnObservableCollectionChanged(object sender, NotifyCollectionChangedEventArgs e)
{
    if (e.Action == NotifyCollectionChangedAction.Add)
    {
        foreach (Pin pin in e.NewItems)
        {
            pin.Clicked += OnPinClicked;
            Pins.Add(pin);
        }
    }

    if (e.Action == NotifyCollectionChangedAction.Remove)
    {
        foreach (Pin pin in e.NewItems)
        {
            pin.Clicked -= OnPinClicked;
            Pins.Remove(pin);
        }
    }
}

We’ll also take this time to associate the Pin’s Click event to our SelectedItem property.

private void OnPinClicked(object sender, EventArgs e)
{
    SelectedItem = (Pin)sender;
}

And since we’re setting the SelectedItem, let’s center the view on the selected pin. Because the binding mode of the property is set to TwoWay this callback is invoked from both changes in the control or from the ViewModel.

private static void OnSelectedItemChanged(BindableObject bindable, object oldValue, object newValue)
{
    var map = (CustomMap)bindable;
    var pin = newValue as Pin;
    if (pin != null)
    {
        Distance distance = map.VisibleRegion.Radius;
        MapSpan region = MapSpan.FromCenterAndRadius(pin.Position, distance);
        map.MoveToRegion(region);
    }
}

Putting it all together

Now to see this in action, let’s demonstrate a View with our custom map and a few buttons on it. We’ll wire the buttons to a command that sets the SelectedItem.

<?xml version="1.0" encoding="utf-8" ?>
<ContentView xmlns="http://xamarin.com/schemas/2014/forms"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             xmlns:maps="clr-namespace:Xamarin.Forms.Maps;assembly=Xamarin.Forms.Maps"
             xmlns:controls="clr-namespace:XF.CaliburnMicro1.Controls"
             x:Class="XF.CaliburnMicro1.Views.Tab3View"            
             >

    <StackLayout VerticalOptions="FillAndExpand">

        <Grid HeightRequest="150">
            <Grid.RowDefinitions>
                <RowDefinition />
                <RowDefinition />
            </Grid.RowDefinitions>
            <Grid.ColumnDefinitions>
                <ColumnDefinition />
                <ColumnDefinition />
                <ColumnDefinition />
            </Grid.ColumnDefinitions>

            <Button Grid.Row="0" Grid.Column="0" Command="{Binding SelectPinCommand}" CommandParameter="1" Text="1" />
            <Button Grid.Row="0" Grid.Column="1" Command="{Binding SelectPinCommand}" CommandParameter="2" Text="2" />
            <Button Grid.Row="1" Grid.Column="0" Command="{Binding SelectPinCommand}" CommandParameter="3" Text="3" />
            <Button Grid.Row="1" Grid.Column="1" Command="{Binding SelectPinCommand}" CommandParameter="4" Text="4" />

            <Button Grid.Row="1" Grid.Column="2" Command="{Binding NewPinCommand}" Text="Add Pin" />
        </Grid>

        <controls:CustomMap 
            IsShowingUser="true"
            MapType="Street"
            PinsItemsSource="{Binding Pins}"
            SelectedItem="{Binding SelectedPin}" 
            VerticalOptions="FillAndExpand"
          />
        
    </StackLayout>    
    
</ContentView>

The ViewModel is really quite simple now. We simply populate a list of Pins and change the SelectedPin to trigger changes in the View.

namespace XF.CaliburnMicro1.ViewModels
{
    using Caliburn.Micro;
    using Xamarin.Forms.Maps;
    using XF.CaliburnMicro1.Views;

    public class Tab3ViewModel : BaseScreen
    {
        private Pin _selectedPin;

        public Tab3ViewModel()
        {
            Pins = new BindableCollection<Pin>();

            SelectPinCommand = new DelegateCommand(o =>
            {
                var index = int.Parse(o.ToString());

                SelectedPin = Pins[index - 1];
            });

            NewPinCommand = new DelegateCommand((o) =>
            {
                var position = MapControl.VisibleRegion.Center;
                var pin = Create("New!", position.Latitude, position.Longitude);
                Pins.Add(pin);
                
            });

        }

        public BindableCollection<Pin> Pins { get; protected set; }

        public Pin SelectedPin
        {
            get { return _selectedPin; }
            set { SetField(ref _selectedPin, value); }
        }

        public DelegateCommand NewPinCommand { get; set; }

        public DelegateCommand SelectPinCommand { get; set; }

        protected override void OnActivate()
        {
            base.OnActivate();

            Pins.Clear();

            // top 4 largest cities in north america
            Pins.Add(Create("Mexico City", 19.4326, -99.1332));
            Pins.Add(Create("New York", 40.7128, -74.0059));
            Pins.Add(Create("Los Angeles", 34.0522, -118.2437));
            Pins.Add(Create("Toronto", 43.6532, -79.3832));
        }

        private Pin Create(string label, double lat, double longitude)
        {
            return
                  new Pin
                  {
                      Label = label,
                      Position = new Position(lat, longitude),
                      Type = PinType.Generic
                  };
        }
    }
}

And Voila! Our Map is now populated and driven using data in the ViewModel!

map-android2map-ios

Happy coding.

submit to reddit

Monday, April 10, 2017

Applying MVVM to Difficult UI Elements

It’s worth repeating: the general principle in MVVM is to separate logic from presentation code. This separation makes it easy to swap out presentation elements and unit test our control logic. The generally accepted litmus test for “good mvvm” is the View should be XAML only and all code should be contained in the view-model. Ultimately it leads to more opportunities for code-reuse and higher unit testing code coverage.

However, living up to this ideal can be difficult to achieve, especially when rogue user controls weren’t designed with MVVM in mind. The MapControl is a great example of this – it offers so many complex features (layers, pushpins, custom-shapes, etc) that it would be difficult to produce a simple abstraction.

Caliburn.Micro has a Screen ViewModel that represents important view-lifecycle events. The OnViewAttached method provides an opportunity to obtain a reference to the view and perform logic that you would normally have to do in code-behind. It feels a bit hacky (it sort of is, I’ll show some alternatives in another post) – but it’s a good workaround for difficult scenarios. Keep in mind this is an exception to the rule, something that you might use once in a while.

This recipe uses these ingredients:

  • A named element in the View
  • An interface for the View (optional)
  • Override the OnViewAttached in the ViewModel

The View

We’ll start with a XAML View that uses the Xamarin.Forms Map control. There’s a bit of work to get the Map up and running, so I’ll refer you to Xamarin’s walk-through on how to configure your project. Though most examples from Xamarin show the Map control being used from code-behind, we should be able to do anything they do in those samples from our ViewModel.

In order to access the MapControl programmatically, we have to give it an x:Name.

<?xml version="1.0" encoding="utf-8" ?>
<ContentView xmlns="http://xamarin.com/schemas/2014/forms"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             xmlns:maps="clr-namespace:Xamarin.Forms.Maps;assembly=Xamarin.Forms.Maps"             
             x:Class="XF.CaliburnMicro1.Views.Tab3View"            
             >

    <Grid VerticalOptions="FillAndExpand">
        
        <maps:Map x:Name="map"
                  IsShowingUser="True"
                  MapType="Street"
                  />
    </Grid>    
    
</ContentView>

Interface for the View

This step is optional and is largely because I don’t want to couple the View explicitly in the ViewModel. By defining an interface, I can use this technique with different Views. For example, you might subclass the Map control and use it different areas of your application. The interface approach makes it easy to access the control regardless of where it’s used in my app.

namespace XF.CaliburnMicro1.Views
{
    using Xamarin.Forms.Maps;

    public interface IMapAware
    {
        Map GetMap();
    }
}

Next we simply implement the interface on the View and return our named element.

namespace XF.CaliburnMicro1.Views
{
    using Xamarin.Forms;
    using Xamarin.Forms.Maps;

    public partial class Tab3View : ContentView, IMapAware
    {
        public Tab3View()
        {
            InitializeComponent();
        }

        public Map GetMap()
        {
            return this.map;
        }
    }
}

Access the Control from the ViewModel

The last step here assumes that we’re backing our Xamarin.Form Pages with ViewModels that derive from Caliburn.Micro’s Screen class. To access the control from the ViewModel, we override the OnViewAttached method and either cast the argument to our View or to the interface mentioned above.

In this example, I’m assigning the Control to a property on the ViewModel so that I can centralize initialization logic, such as subscribing to events and setting default properties.

namespace XF.CaliburnMicro1.ViewModels
{
   using Caliburn.Micro;
   using Xamarin.Forms.Maps;
   
   public class Tab3ViewModel : Screen
   {
      internal Map MapControl
      {
         get { return _map; }
         set
         {
            if (_map != null)
            {
               // unregister events
            }

            _map = value;

            if (_map != null)
            {
               // wire-up events
            }
         }
      }

      protected override void OnViewAttached(object view, object context)
      {
         var mapView = view as IMapAware;
         if (mapView != null)
         {
            MapControl = mapView.GetMap();
         }
      }

      protected override void OnActivate()
      {
         base.OnActivate();

         CenterMap();
      }
      
      internal void CenterMap()
      {
         var mapSpan = MapSpan.FromCenterAndRadius(
            new Position(43.6532, -79.3832),
            Distance.FromKilometers(10));
         MapControl.MoveToRegion(mapSpan);
      }
      
   }
   
}

Sweet. Now we can add our Pins to the Map from the ViewModel. In my next post, we'll look at a solution to apply our Pins using MVVM so that we don't need to manipulate the Map directly.

Happy coding.

Monday, April 03, 2017

Displaying a Xamarin.Forms ActionSheet using MVVM

When it comes to mobile applications, there are many different ways to prompt a user for input. Xamarin.Forms has adopted a technique originally introduced in iOS called an ActionSheet that can prompt the user for one or many options.

While Xamarin.iOS provides the UIAlertController to display Popups and ActionSheets, the only way to present the ActionSheet in Xamarin.Forms is through the DisplayActionSheet method on the Page object. If we want to present this dialog to our users using MVVM, accessing the Page object from the code-behind would be violating one of the MVVM best-practices, so we’d need to find another way that’s more “MVVM Friendly”. I’ve had a lot of success with the following approach. Maybe you will, too.

What’s an ActionSheet?

Before we dive into the MVVM component, let’s take a closer look at the ActionSheet. An ActionSheet prompts the user to choose a selection from a list but also provides two specific options: Cancel and Destruction.  The “Cancel” option is obvious, but perhaps the “Destruction” option may not. In iOS, this term represents a destructive operation that is highlighted in red. For example, an actionsheet shown to users during a photo editing session may show a list of file sizes (“Small”, “Medium”, “Large”), a “Cancel” button and a destructive operation, “Discard Changes”.

Options, Options, Options…

To show the ActionSheet using bindings from our ViewModel, we have a few options:

  1. Implement a custom control. We could implement a custom control to house our logic to launch the ActionSheet, but this feels a bit awkward, especially since it wouldn’t actually render anything. We’d also run into issues about where to put the Control in the logical tree.
  2. Custom Behaviour. This seems like the best approach, but the way behaviours are implemented in Xamarin.Forms isn’t exactly how they’re done in WPF, and I discovered first hand a few issues where bindings were being fired multiple times, etc. Which led me to…
  3. Attached Properties. Perhaps the precursor to Behaviors, Attached Properties provide us with a mechanism to store state in the visual elements and then define callbacks for when those values change. This technique isn’t as clean as I’d like but it works really well.

Show me the Codes

As mentioned above, my preferred approach to show the ActionSheet works on this basic principle:

  • Bind some data that we want to show using some Attached Properties,
  • Trigger the ActionSheet when one of the BindableProperty changes,
  • Use the VisualTreeHelper mentioned in my last post to find the Page element,
  • Display the ActionSheet using the Page.DisplayActionSheet method.

We’ll expose the following properties:

  • Parameters: rather than binding all the various display values as separate values, we bundle them up into a single class (see ActionSheetParameters below)
  • IsVisible: the BindableProperty that will be used to trigger the alert.
  • Result: the BindableProperty that will contain the user’s selection.
  • ResultCommand: an alternative to using the Result property if you want to be notified by Command when the user selects a value.

The end result looks like this:


namespace XF.CaliburnMicro1.Controls
{
    using System.Windows.Input;
    using Xamarin.Forms;

    public class ActionSheet
    {
        #region Parameters
        public static BindableProperty ParametersProperty =
            BindableProperty.CreateAttached(
                "Parameters", 
                typeof(ActionSheetParameters), 
                typeof(ActionSheet), 
                default(ActionSheetParameters));

        public static ActionSheetParameters GetParameters(BindableObject bindable)
        {
            return (ActionSheetParameters)bindable.GetValue(ParametersProperty);
        }

        public static void SetParameters(BindableObject bindable, ActionSheetParameters value)
        {
            bindable.SetValue(ParametersProperty, value);
        }
        #endregion

        #region Result
        public static BindableProperty ResultProperty =
            BindableProperty.CreateAttached(
                "Result", 
                typeof(string), 
                typeof(ActionSheet), 
                default(string), 
                defaultBindingMode: BindingMode.TwoWay);

        public static string GetResult(BindableObject bindable)
        {
            return (string)bindable.GetValue(ResultProperty);
        }

        public static void SetResult(BindableObject bindable, string value)
        {
            bindable.SetValue(ResultProperty, value);
        }
        #endregion

        #region Command
        public static BindableProperty CommandProperty =
            BindableProperty.CreateAttached(
                "Command",
                typeof(ICommand),
                typeof(ActionSheet),
                null);

        public static ICommand GetCommand(BindableObject bindable)
        {
            return (ICommand)bindable.GetValue(CommandProperty);
        }

        public static void SetCommand(BindableObject bindable, string value)
        {
            bindable.SetValue(CommandProperty, value);
        } 
        #endregion

        #region IsVisible
        public static BindableProperty IsVisibleProperty =
           BindableProperty.CreateAttached(
               "IsVisible", 
               typeof(bool), 
               typeof(ActionSheet), 
               default(bool), 
               propertyChanged: OnShowDialog, 
               defaultBindingMode: BindingMode.TwoWay);

        public static bool GetIsVisible(BindableObject bindable)
        {
            return (bool)bindable.GetValue(IsVisibleProperty);
        }

        public static void SetIsVisible(BindableObject bindable, bool value)
        {
            bindable.SetValue(IsVisibleProperty, value);
        }
        #endregion

        private static async void OnShowDialog(BindableObject bindable, object oldValue, object newValue)
        {
            bool showAlert = (bool)newValue;
            if (showAlert)
            {
                var page = VisualTreeHelper.GetParent<Page>((Element)bindable);

                ActionSheetParameters args = GetParameters(bindable);
                
                if (page != null && args != null)
                {
                    string result = await page.DisplayActionSheet(args.Title, args.Cancel, args.Destruction, args.Buttons);

                    SetResult(bindable, result); // pass result back to binding

                    // pas result back to viewmodel using command
                    ICommand command = GetCommand(bindable);
                    if (result != null && command != null)
                    {
                        command.Execute(result);
                    }

                    SetIsVisible(bindable, false); // reset the dialog
                }
            }
        }
    }

    public class ActionSheetParameters
    {
        /// <summary>
        /// Action sheet title
        /// </summary>
        public string Title { get; set; }

        /// <summary>
        /// Cancel button title
        /// </summary>
        public string Cancel { get; set; }

        /// <summary>
        /// Destructive action title
        /// </summary>
        public string Destruction { get; set; }

        /// <summary>
        /// List of Buttons
        /// </summary>
        public string[] Buttons { get; set; }
    }
}

From the above, the work is done when the IsVisible property changes. Our ViewModel would look like this:

public class ExampleViewModel : Screen
{
    private bool _showDialog;
    private string _result;
    private ActionSheetParameters _parameters;

    public ExampleViewModel()
    {
        ShowDialogCommand = new DelegateCommand((o) =>
        {
            DialogParameters = new ActionSheetParameters
            {
                Title = "Choose your option wisely",
                Cancel = "Cancel",
                Destruction = "Self Destruct",
                Buttons = new[] { "One", "Two", "Red", "Blue" }
            };

            ShowDialog = true;
        });
    }

    public bool ShowDialog
    {
        get { return _showDialog; }
        set { SetField(ref _showDialog, value); }
    }

    public string Result
    {
        get { return _result; }
        set { SetField(ref _result, value); }
    }

    public ActionSheetParameters DialogParameters
    {
        get { return _parameters; }
        set { SetField(ref _parameters, value); }
    }

    public DelegateCommand ShowDialogCommand
    {
        get;
        protected set;
    }

    protected void SetField<T>(ref T field, T value, [CallerMemberName] string propertyName = null)
    {
        if (!Object.Equals(field, value))
        {
            field = value;
            NotifyOfPropertyChange(propertyName);
        }
    }
}

And the corresponding View:

<?xml version="1.0" encoding="utf-8" ?>
<ContentView xmlns="http://xamarin.com/schemas/2014/forms"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             xmlns:controls="clr-namespace:XF.CaliburnMicro1.Controls"
             x:Class="XF.CaliburnMicro1.Views.Tab2View"
             
             controls:ActionSheet.Parameters="{Binding DialogParameters}"
             controls:ActionSheet.Result="{Binding Result}"
             controls:ActionSheet.IsVisible="{Binding ShowDialog}"
             >

    <StackLayout>
        <Button Text="Show Dialog" Command="{Binding ShowDialogCommand}" />
        <Label Text="{Binding Result}" />
    </StackLayout>    
    
</ContentView>

This technique works well for both iOS and Android.

Happy coding.

submit to reddit

Sunday, March 26, 2017

VisualTreeHelper for Xamarin.Forms

I enjoy working with Xamarin.Forms because it allows me to leverage my XAML background for cross-platform technologies. While Xamarin.Forms has come a long way over the last few years, there are a few gaps between WPF/Modern Apps and the Xamarin implementation of XAML.

One of those gaps is the VisualTreeHelper that ships as part of WPF. The VisualTreeHelper is especially useful when developing custom controls, Attached Properties or Behaviors. For example, an Attached Property like Grid.Row can search up the visual tree to find the parent Grid control.

While there is no implementation within Xamarin.Forms, there are some examples that offer partial solutions.

The class hierarchy for Xamarin.Forms gives us a bit of insight about the visual tree. A controls and visual elements share a common base class, Element.

Xamarin.Forms-ElementHierarchy

Here’s my implementation for GetParent<T> and GetChildren<T>:

public static class VisualTreeHelper
{
    public static T GetParent<T>(this Element element) where T : Element
    {
        if (element is T)
        {
            return element as T;
        }
        else
        {
            if (element.Parent != null)
            {
                return element.Parent.GetParent<T>();
            }

            return default(T);
        }
    }
        
    public static IEnumerable<T> GetChildren<T>(this Element element) where T : Element
    {
        var properties = element.GetType().GetRuntimeProperties();

        // try to parse the Content property
        var contentProperty = properties.FirstOrDefault(w => w.Name == "Content");
        if (contentProperty != null)
        {
            var content = contentProperty.GetValue(element) as Element;
            if (content != null)
            {
                if (content is T)
                {
                    yield return content as T;
                }
                foreach (var child in content.GetChildren<T>())
                {
                    yield return child;
                }
            }
        }
        else
        {
            // try to parse the Children property
            var childrenProperty = properties.FirstOrDefault(w => w.Name == "Children");
            if (childrenProperty != null)
            {
                // loop through children
                IEnumerable children = childrenProperty.GetValue(element) as IEnumerable;
                foreach (var child in children)
                {
                    var childVisualElement = child as Element;
                    if (childVisualElement != null)
                    {
                        // return match
                        if (childVisualElement is T)
                        {
                            yield return childVisualElement as T;
                        }

                        // return recursive results of children
                        foreach (var childVisual in childVisualElement.GetChildren<T>())
                        {
                            yield return childVisual;
                        }
                    }
                }
            } 
        }
    }
}

As the VisualTreeHelper is implemented as a static class, it can be used stand-alone or as extension methods on an object:

// from within user control...

Page page = null;
StackLayout stack = this.FindByName<StackLayout>("myStack");

// utility class
page = VisualTreeHelper.GetParent<Page>(stack);

// using extension method
page = stack.GetParent<Page>();

Well, that's it for now. My next post will show how a practical example.

Happy coding.

Monday, March 13, 2017

Applying MVVM to Xamarin.Form’s TabbedPage (Updated)

My last post showed how to setup a TabbedPage with separate View/ViewModels for each tab using Caliburn.Micro. The post used a DataTemplateSelector to resolve the tab content which isn’t the preferred technique when working with Caliburn.Micro. Today we’ll use a strategy that is more aligned to Caliburn’s philosophy and is a tiny bit more extensible.

As per the previous post, we used a DataTemplateSelector because the default TabbedPage.ItemTemplate expects a ContentPage and we wanted to use existing ContentPage items as tabs. In reality, this was a situation that occurred because our team had originally developed these pages independently and then wanted to consolidate them into a TabbedPage after the fact. If you don’t plan on navigating to these pages outside of the TabbedPage, we can build up our ContentPage inside the DataTemplate and use Caliburn.Micro’s binding syntax. This approach will require us to change our existing ContentPage(s) into ContentView(s) and since we depended on the Page objects to provide us with Title and Icon information, we’ll need to push this information into our ViewModels.

Modify ViewModels

Let’s introduce a simple interface for our ViewModels that will be tabs in our TabbedPage:


public interface ITabViewModel
{
   string Title { get; }
   string Icon { get; }
   int SortOrder { get; }
}

The changes to the ViewModel are pretty trivial. We simply implement the ITabViewModel interface:


public class Tab1ViewModel : Screen, ITabViewModel
{
   public Tab1ViewModel()
   {
      Tab1Content = "Tab 1 Content";
   }

   public string Tab1Content { get; set; }

   public string Icon => "Tab1.png";

   public int SortOrder => 0;

   public string Title => "Tab1";
}

public class Tab2ViewModel : Screen, ITabViewModel
{
   public Tab2ViewModel()
   {
      Tab2Content = "Tab 2 Content";
   }

   public string Tab2Content { get; set; }

   public string Icon => "Tab2.png";

   public int SortOrder => 0;

   public string Title => "Tab 2";
}

Next, we register our ViewModels in the App using the ITabViewModel signature:


public class App : FormsApplication
{
   private readonly SimpleContainer container;

   public App(SimpleContainer container)
   {
      this.container = container;

      // TODO: Register additional viewmodels and services
      container
         .PerRequest<Main2ViewModel>()
         .PerRequest<ITabViewModel,Tab1ViewModel>()
         .PerRequest<ITabViewModel,Tab2ViewModel>()
         ;

      Initialize();

      DisplayRootViewFor<Main2ViewModel>();
   }
 
   // snip...
}

Lastly, we can change our Screen Conductor to be less coupled to the specific ViewModels:


public class Main2ViewModel : Conductor<Screen>.Collection.OneActive
{
   public Main2ViewModel(IEnumerable<ITabViewModel> tabs)
   {
      if (tabs.Any())
      {
         foreach(var tab in tabs.OrderBy(i => i.SortOrder))
         {
            Items.Add((Screen)tab);
         }

         ActivateItem(Items[0]);
      }
   }
}

Modify Views

The changes to the view are also very trivial. We’re simply changing them from ContentPage to ContentView. There are a few attributes that aren’t available (Title, Icon) so we’ll simply remove them if present.
And then finally, we can remove our DataTemplateSelector and use the View.Model attached property to resolve our ContentView:

Main2View.xaml

<?xml version="1.0" encoding="UTF-8"?>
<TabbedPage xmlns="http://xamarin.com/schemas/2014/forms" 
            xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml" 
            xmlns:cm="clr-namespace:Caliburn.Micro.Xamarin.Forms;assembly=Caliburn.Micro.Platform.Xamarin.Forms"
            x:Class="XF.CaliburnMicro1.Views.Main2View"
            ItemsSource="{Binding Items}"
            SelectedItem="{Binding ActiveItem}"
            >
    <TabbedPage.ItemTemplate>
        <DataTemplate>
            <ContentPage Title="{Binding Title}" Icon="{Binding Icon}">
                <ContentView cm:View.Model="{Binding}" />
            </ContentPage>
        </DataTemplate>
    </TabbedPage.ItemTemplate>
</TabbedPage>

Easy peasy.

Happy coding.

submit to reddit

Sunday, March 05, 2017

Applying MVVM to Xamarin.Forms's TabbedPage

For this post I thought we'd dig into an example that came up recently with Caliburn.Micro and the TabbedPage view, specifically how to apply MVVM using Caliburn.Micro.

The TabbedPage view that ships with Xamarin.Forms is a great cross-platform page structure that presents sets of content in different tabs. The layout is surprisingly very similar between iOS, Android and Windows 10. The biggest layout difference is seen in iOS where each tab optionally has an icon.

xamarinforms_tabbedpage

The above image, taken without permission from Xamarin’s documentation, shows iOS, Android and Windows 8.1 Phone. The Windows 10 version is closer to the Android version.

When looking at Xamarin’s documentation, most examples show a series of Pages defined as inline XAML, and applying an ItemTemplate assumes that each tab will have the same layout; there doesn’t seem to be a great way to swap in different pages per tab. Regardless of these short-comings, the most important point regarding these examples is that the TabbedPage view displays the the Title and Icon from the contained Page in the tab headers.

Setting up the ViewModel

The first step in setting up a TabbedPage view is to represent it as its own ViewModel. Caliburn.Micro offers a unique solution to this problem using a pattern it refers to as a Screen Conductor. To understand how this pattern works, Caliburn.Micro treats pages of your application as Screens and the base Screen class contains abstractions for the view lifecycle: OnInitialize, OnActivated, OnDeactivated. These methods, respectively, make it really easy to defer work that shouldn’t be in the constructor, to ensure the view always has the latest data, and to clean-up or prevent navigating away without saving changes. With regards to the TabbedPage, the ScreenConductor provides a simple mechanism to activate and deactivate ViewModels as you navigate between tabs.

Here we define our ScreenConductor as our Main2ViewModel, and Tab1ViewModel and Tab2ViewModel as the contained tabs.

namespace XF.CaliburnMicro1.ViewModels
{
    using Caliburn.Micro;

    public class Main2ViewModel : Conductor<Screen>.Collection.OneActive
    {
        public Main2ViewModel(Tab1ViewModel tab1, Tab2ViewModel tab2)
        {
            Items.Add(tab1);
            Items.Add(tab2);

            ActivateItem(Items[0]);
        }
    }

    public class Tab1ViewModel : Screen
    {
        public Tab1ViewModel()
        {
            DisplayName = "Tab 1";
            Tab1Content = "Tab 1 Content";
        }

        public string Tab1Content { get; set; }
    }

    public class Tab2ViewModel : Screen
    {
        public Tab2ViewModel()
        {
            DisplayName = "Tab 2";
            Tab2Content = "Tab 2 Content";
        }

        public string Tab2Content { get; set; }
    }
}

For completeness sake, these new ViewModels are registered in the App class (defined in my previous post):

public class App : FormsApplication
{
   private readonly SimpleContainer container;

   public App(SimpleContainer container)
   {
       this.container = container;

       // TODO: Register additional viewmodels and services
       container
          .PerRequest<Main2ViewModel>()
          .PerRequest<Tab1ViewModel>()
          .PerRequest<Tab2ViewModel>()
          ;

       Initialize();

       DisplayRootViewFor<Main2ViewModel>();
    }

    // snip...
}

The XAML definitions for these views are represented as a TabbedPage and two instances of ContentPage:

Main2View.xaml
<?xml version="1.0" encoding="UTF-8"?>
<TabbedPage xmlns="http://xamarin.com/schemas/2014/forms" 
            xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml" 
            xmlns:converters="clr-namespace:XF.CaliburnMicro1.Converters"
            x:Class="XF.CaliburnMicro1.Views.Main2View"
            ItemsSource="{Binding Items}"
            SelectedItem="{Binding SelectedItem}"
            >

</TabbedPage>
Tab1View.xaml
<?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.Tab1View"
             Title="{Binding DisplayName}">
  <Label Text="{Binding Tab1Content}" VerticalOptions="Center" HorizontalOptions="Center" />
</ContentPage>
Tab2View.xaml
<?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.Tab2View"
             Title="{Binding DisplayName}">
  <Label Text="{Binding Tab2Content}" VerticalOptions="Center" HorizontalOptions="Center" />
</ContentPage>

Fixing View / ViewModels for Tabs

If you run the solution as is, you’ll be disappointed. The reason for this is that while Caliburn.Micro can find the View/ViewModel for our MainPage, it doesn’t know how to resolve the View/ViewModels for the tabs. Now the solution I’m going to use leverages a DataTemplateSelector which isn’t something that is traditionally done with Caliburn.Micro. The correct approach with Caliburn.Micro is to take advantage of conventions and special attached properties (eg View.Model). However in this case, the approach I’m using allows you to use your ContentPage inside the TabbedPage or as a standalone page that you can navigate to directly. I’ll cover the other approach in an upcoming post.

We’ll define a DataTemplateSelector that can do the work of finding the View for our ViewModel:

namespace XF.CaliburnMicro1.Converters
{
    using System;
    using System.Collections.Generic;
    using Caliburn.Micro;
    using Caliburn.Micro.Xamarin.Forms;
    using Xamarin.Forms;    

    public class TabbedPageDataTemplateSelector : DataTemplateSelector
    {
        private readonly Dictionary<Type, DataTemplate> _selectors;

        public TabbedPageDataTemplateSelector()
        {
            _selectors = new Dictionary<Type, DataTemplate>();
        }

        protected override DataTemplate OnSelectTemplate(object item, BindableObject container)
        {
            Type viewModelType = item.GetType();

            DataTemplate template = null;

            // check if we've already found the datatemplate for this view
            if (!_selectors.TryGetValue(viewModelType, out template))
            {
                // use caliburn to find the View for this viewmodel
                Type viewType = ViewLocator.LocateTypeForModelType(viewModelType, null, null);

                template = new DataTemplate(() =>
                {
                    var view = Activator.CreateInstance(viewType);

                    var bindableObject = view as BindableObject;

                    if (bindableObject != null)
                    {
                        // when the view's content changes...
                        bindableObject.BindingContextChanged += (sender, args) =>
                        {
                            var page = sender as Page;

                            // leverage a caliburn view lifecyle event
                            // if the viewmodel supports it
                            var viewAware = page?.BindingContext as IViewAware;
                            viewAware?.AttachView(page);
                        };
                    }

                    return view;
                });

                // cache the datatemplate
                _selectors.Add(viewModelType, template);
            }

            // return the correct view for the viewmodel
            return template;
        }
    }
}

Then associate into the view:

<?xml version="1.0" encoding="UTF-8"?>
<TabbedPage xmlns="http://xamarin.com/schemas/2014/forms" 
            xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml" 
            xmlns:converters="clr-namespace:XF.CaliburnMicro1.Converters"
            x:Class="XF.CaliburnMicro1.Views.Main2View"
            ItemsSource="{Binding Items}"
            SelectedItem="{Binding SelectedItem}"
            >
    <TabbedPage.ItemTemplate>
        <converters:TabbedPageDataTemplateSelector />
    </TabbedPage.ItemTemplate>
</TabbedPage>

Now when we run our solution, our tabs are correctly populated.

tabbedpage-content

Happy coding!

submit to reddit

Monday, February 20, 2017

Configuring Xamarin.Forms.UWP to use Caliburn Micro

This is the fourth post in this series where we’re configuring a Xamarin.Forms application to use my favourite MVVM framework, Caliburn.Micro. Today’s post will focus on configuring a Universal Windows Application (UWP).

Here’s links to the previous posts:

  1. Getting Started with Xamarin.Forms and Caliburn.Micro
  2. Configuring Xamarin.Forms.Droid to use Caliburn.Micro
  3. Configuring Xamarin.Forms.iOS to use Caliburn.Micro

If you’ve ever built a WPF application, it may seem strange that we’re not going to build XAML pages for our app. Instead, we’re going to leverage the XAML defined in our PCL so that we can reuse as much of the user-interface logic as possible. The pages that we’re adding here act purely as an entry point into our Xamarin.Forms application.

Change App.xaml

Caliburn provides a base application class that we’re going to extend. In our App.xaml, we’ll change the root element to CaliburnApplication, like so:

<cm:CaliburnApplication
    x:Class="XF.CaliburnMicro1.UWP.App"
    xmlns:cm="using:Caliburn.Micro"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    RequestedTheme="Light">
    
</cm:CaliburnApplication>

Configure IoC Container

Next we’ll add the plumbing logic that we’ve added to the other applications to initialize our platform-specific IoC container. Caliburn.Micro has a customized container for UWP, called WinRTContainer, that contains a few helpful registration methods.

I’ve replaced the default App.xaml.cs with this simplified version:

namespace XF.CaliburnMicro1.UWP
{
    using System;
    using System.Collections.Generic;
    using System.Reflection;
    using Windows.ApplicationModel.Activation;
    
    using Caliburn.Micro;
    
    using XF.CaliburnMicro1.ViewModels;

    sealed partial class App
    {
        private WinRTContainer _container;

        public App()
        {
            InitializeComponent();
        }

        protected override void Configure()
        {
            _container = new WinRTContainer();
            _container.RegisterWinRTServices();

            _container.Singleton<XF.CaliburnMicro1.App>();
        }

        protected override void OnLaunched(LaunchActivatedEventArgs args)
        {
            if (args.PreviousExecutionState == ApplicationExecutionState.Running)
                return;

            Xamarin.Forms.Forms.Init(args);

            // loads our MainPage as the root frame
            DisplayRootView<MainPage>();
        }

        #region IoC Overrides
        protected override void BuildUp(object instance)
        {
            _container.BuildUp(instance);
        }

        protected override IEnumerable<object> GetAllInstances(Type service)
        {
            return _container.GetAllInstances(service);
        }

        protected override object GetInstance(Type service, string key)
        {
            return _container.GetInstance(service, key);
        }

        protected override IEnumerable<Assembly> SelectAssemblies()
        {
            return new[]
            {
                GetType().GetTypeInfo().Assembly,
                typeof(MainViewModel).GetTypeInfo().Assembly
            };
        } 
        #endregion
    }
}

Eventually, you’ll want to provide additional logic for initialization and suspension specific to UWP, but for now OnLaunched simply launches MainPage as the root window for our Xamarin.Forms app.

Customize MainPage

The Xamarin.Forms template includes a MainPage that is optimized for Xamarin.Forms, we simply need to load our App from the Singleton defined in Caliburn’s IoC Container.

namespace XF.CaliburnMicro1.UWP
{
    using Caliburn.Micro;

    public sealed partial class MainPage
    {
        public MainPage()
        {
            this.InitializeComponent();

            LoadApplication(IoC.Get<XF.CaliburnMicro1.App>());
        }
    }
}

Build and Run

Finally, before we give our UWP a spin, we need to make a minor change the deployment to the Solution.

  1. Change the start-up application to XF.CaliburnMicro.UWP (Universal Windows) and set the target platform to Any CPU
  2. Open the Configuration Manager for the solution

    uwp_configuration
  3. Specify that the solution should Deploy for Debug configuration

    image
  4. Specify Local machine as the target Device
  5. Compile and Run (F5)

You should now see our familiar View / ViewModel from the PCL should be displayed.

Windows 10:

image

Windows 10 Mobile:

image

Next Steps

We’re now set to handle iOS, Android and Universal Windows Apps using Caliburn.Micro, so that’s all for this series. Follow my Xamarin.Forms label to see more posts in this space.

Until then… Happy Coding.

submit to reddit

Configure Xamarin.Forms iOS to use Caliburn.Micro

We’re continuing with our series of getting started with Xamarin.Forms and Caliburn.Micro, check out these previous posts if you’re interested:

Today, we’ll set up our Xamarin.Forms iOS project. Unlike the Droid project, we can get our project up and running with very few changes to the default template. So we'll start this post with configuring our Visual Studio instance to talk to our Mac.

And before you ask, unfortunately, although it's C# you absolutely need a Mac to compile and run the solution. On the plus side, you can do most of your development on your PC.

Verify Prerequisite Software on your Mac

You will need the following installed on your Mac:

  • XCode 7+
  • Xamarin Studio
  • Xamarin.iOS SDK

Setup your Mac for Remote Access

Before you can configure Visual Studio to use your Mac as a Build Host, you'll need to configure your Mac to allow users to remotely login to your machine. You can get the full details following this post, but in short we can simply set up our mac using the following:

  • Press Command ⌘ + Space to bring up Spotlight Search
  • Type Remote Login to open Sharing
  • Enable Remote Login and then specify Allow access for: All Users 

Configure your Build Host

Now that your Mac will accept remote logins, we can now configure Visual Studio on the PC to use your Mac as a build host.

  • From your PC, open our XF.CaliburnMicro project.
  • In the toolbar, click on the Xamarin Mac Agent icon (also Tools –> iOS –> Xamarin Mac Agent):

    mac_agent_toolbar

  • If your mac is running, it should appear in the dialog:

    image

  • Select your Mac, click Connect…
  • You’ll be prompted to login, so provide the credentials you use when logging into the Mac
  • Once connected, the toolbar changes colour and provides the option to launch the simulator:

    mac_agent_connected_toolbar

Note this assumes that both the Mac and the PC are on the same network and that all required software is installed and configured for use.

Create and configure IoC Container

Now that we have our environment dependencies out of the way, we can turn our attention to modifying the template code to leverage Caliburn.Micro.

Similar to our Droid project, we need to set up our IoC container. For iOS, we do this by using a CaliburnAppDelegate which looks almost identical to the Application class we created for Android.

namespace XF.CaliburnMicro1.iOS
{
    using System;
    using System.Collections.Generic;
    using System.Reflection;
    
    using Caliburn.Micro;
    
    using XF.CaliburnMicro1.ViewModels;

    class CaliburnAppDelegate : CaliburnApplicationDelegate
    {
        private SimpleContainer _container;

        public CaliburnAppDelegate()
        {
            Initialize();
        }

        protected override void Configure()
        {
            _container = new SimpleContainer();
            _container.Instance(_container);

            _container.Singleton<App>();

            // TODO: Register all platform services here
        }

        protected override void BuildUp(object instance)
        {
            _container.BuildUp(instance);
        }

        protected override IEnumerable<object> GetAllInstances(Type service)
        {
            return _container.GetAllInstances(service);
        }

        protected override object GetInstance(Type service, string key)
        {
            return _container.GetInstance(service, key);
        }

        protected override IEnumerable<Assembly> SelectAssemblies()
        {
            return new[]
            {
                GetType().Assembly,
                typeof(MainViewModel).Assembly
            };
        }
    }
}

We then modify the AppDelegate to leverage our CaliburnAppDelegate, and change the start-up routine to use our App singleton.

namespace XF.CaliburnMicro1.iOS
{
    using Foundation;
    using UIKit;
    
    using Caliburn.Micro;
    using Xamarin.Forms.Platform.iOS;

    [Register("AppDelegate")]
    public partial class AppDelegate : FormsApplicationDelegate
    {
        private readonly CaliburnAppDelegate appDelegate = new CaliburnAppDelegate();

        public override bool FinishedLaunching(UIApplication app, NSDictionary options)
        {
            global::Xamarin.Forms.Forms.Init();

            LoadApplication(IoC.Get<App>());

            return base.FinishedLaunching(app, options);
        }
    }
}

Build and Run

To run your application, you’ll need to change the start project, select a target and the Device. Here I’ve selected XF.CaliburnMicro.iOS project, specified the iPhoneSimulator target and the iPhone 6s iOS 10.x simulator.

build_and_run

If everything worked, you should now see our Xamarin.Forms app backed by our Caliburn.Micro ViewModel.

 

Next Steps

So there you go! We’ve got both Android and iOS projects running. Our next post we’ll continue down this path and our Xamarin.Forms project to leverage the Universal Windows Platform which will target tablets, phones and PCs.

submit to reddit

Sunday, February 05, 2017

Configure Xamarin.Forms Droid to use Caliburn.Micro

In my last post, we created a Xamarin.Forms project and added necessary components for taking advantage of my favourite MVVM framework, Caliburn.Micro. However, the solution didn't compile because we needed to make some platform specific changes. Today we'll address this.

Add an Application

The main entry point into our Android application is the Application class as defined in the AndroidManifest.xml. By default, the Xamarin.Forms template does not include an Application class, but we’ll need one in order to hold some global state.

To register our custom application, we subclass Caliburn’s CaliburnApplication class and mark it with an [Application] attribute:

namespace XF.CaliburnMicro1.Droid
{
    using System;
    using Android.App;
    using Android.Runtime;
    using Caliburn.Micro;

    [Application]
    public class Application : CaliburnApplication
    {
        public Application(IntPtr javaReference, JniHandleOwnership transfer)
              : base(javaReference, transfer)
        {
        }

        public override void OnCreate()
        {
            base.OnCreate();

            Initialize();
        }
    }
}

Create and configure IoC

One of the main features of the CaliburnApplication is to create our platform-specific Inversion of Control (IoC) container and register any platform-specific abstractions.

There are four primary methods that we need to implement in our Application (SelectAssemblies, BuildUp, GetAllInstances, GetInstance). These methods are the backing implementation for Caliburn's IoC:

It's important to note that we register the Xamarin.Forms App as a singleton before we activate it. This is largely because we want the App to have the same lifetime as our Android Application, which avoids a few scenarios where the Android application lifecycle causes the App class to be reinitialized more than once.

Our Application class now looks like this:

namespace XF.CaliburnMicro1.Droid
{
    using System;
    using System.Collections.Generic;
    using System.Reflection;
    
    using Android.App;
    using Android.Runtime;
    
    using Caliburn.Micro;
    
    using XF.CaliburnMicro1.ViewModels;

    [Application]
    public class Application : CaliburnApplication
    {
        private SimpleContainer _container;

        public Application(IntPtr javaReference, JniHandleOwnership transfer)
              : base(javaReference, transfer)
        {
        }

        public override void OnCreate()
        {
            base.OnCreate();

            Initialize();
        }

        protected override void Configure()
        {
            _container = new SimpleContainer();

            // make the container available for resolution
            _container.Instance(_container);

            // CRITICAL! make sure our Xamarin.Forms App 
            // can only be initilized once!
            _container.Singleton<App>();

            // TODO: Register any Platform-Specific abstractions here
        }

        protected override IEnumerable<Assembly> SelectAssemblies()
        {
            // Get a list of all assemblies that will be used
            // by the IoC container
            return new[]
            {
                GetType().Assembly,
                typeof (MainViewModel).Assembly
            };
        }

        protected override void BuildUp(object instance)
        {
            _container.BuildUp(instance);
        }

        protected override IEnumerable<object> GetAllInstances(Type service)
        {
            return _container.GetAllInstances(service);
        }

        protected override object GetInstance(Type service, string key)
        {
            return _container.GetInstance(service, key);
        }
    }
}

Modify MainActivity

The last modification we need to make is a slight change to our existing MainActivity. Rather than instantiating our App class, we resolve it from the IoC container.

namespace XF.CaliburnMicro1.Droid
{
    using Android.App;
    using Android.Content.PM;
    using Android.OS;
    
    using Xamarin.Forms.Platform.Android;
    
    using Caliburn.Micro;

    [Activity(
        Label = "XF.CaliburnMicro1", 
        Icon = "@drawable/icon", 
        MainLauncher = true, 
        ConfigurationChanges = ConfigChanges.ScreenSize | ConfigChanges.Orientation)]
    public class MainActivity : FormsApplicationActivity
    {
        protected override void OnCreate(Bundle bundle)
        {
            base.OnCreate(bundle);

            global::Xamarin.Forms.Forms.Init(this, bundle);

            // Resolve the App class to use the singleton we created
            LoadApplication(IoC.Get<App>());
        }
    }
}

Compile and Run

At this point, the android project should be good to go. Set the project as the default target, and run (F5). The project should automatically be configured to deploy the app to the emulator.

Next Steps

So we have our Android application running our Caliburn.Micro flavoured Xamarin.Forms app. The next step is to configure our iOS project with similar customizations.

submit to reddit

Saturday, February 04, 2017

Getting Started with Xamarin.Forms and Caliburn.Micro

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).

image

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.

submit to reddit

Saturday, January 21, 2017

This time on a mac

There’s been less activity than normal around here. Looking back, I missed last year completely. That’s more than a blip, that’s a complete year. Not sure what happened, I think it was a perfect storm...

Those that know me know that I started practicing Karate in 2015 and my facebook feed has been filled with belt exams and karate videos. I’m highly motivated to obtain my first degree in under three years, so three times a week in evening classes and weekends makes it difficult to find a few extra cycles to experiment and blog. On the plus side, I’m probably the most fit I’ve ever been, I've dropped nearly twenty pounds, toned up and dangerous.

The other major shift for me was professionally work wasn’t selling the projects that suited my skills. I kinda had a crisis of faith of sorts, where I felt I had to choose a new religion. I switched into managing more people, bought a mac and learned Swift, and explored leveraging my .net and WPF strengths in Xamarin. Work would eventually pick up later in the year, but in true agency fashion it involved dusting off my Unity3D skills, learning how to rock a HoloLens and learn Python and Ruby while I was at it. There’s loads to blog about it.

I want to touch on the macbook reference above. I feel like I’ve made a career out of bashing apple. (I ended many arguments in the 90s with apple fanboys with my favourite argument killer: “...but it’s a mac…”) Buying a mac for me was huge slice of humble pie. I still use a PC at work, but my mac is now my playground and go to device when I want to do something that isn’t “work”. I’m writing this on a mac, trying out blogo today.

One last thing, to accompany my macbook I switched to an iPhone and parted ways with my Windows Phone. I’m no stranger to iOS as I’ve had an iPad and iPhone in the past, but I was on Windows Phone for years with three different devices. I loved the platform, and still do, but I got tired of waiting for apps that the rest of the planet had. Apply Pay and wallet are awesome. I may still buy a lumina to play with UWP with Xamarin.

So what should you expect this year around here? Well, hopefully I can make good on promises to blog more, but expect to see a combination of development and agile delivery practices. You’ll likely see some Xamarin, some UI automation, maybe a HoloLens. From an agile delivery perspective, expect some tips and tricks to bring to your team as well as a focus on DevOps and Test Automation.