Nick's .NET Travels

Continually looking for the yellow brick road so I can catch me a wizard....

View Model States and Connecting them to Xamarin Forms Visual States using BuildIt

In my previous post on Getting Started with Visual States in Xamarin Forms using BuildIt.Forms I showed a very basic example of defining and triggering Visual States within a Xamarin Forms application. However, most applications have more complexity where each page is typically data bound to a corresponding ViewModel and it is the ViewModel which encapsulated the logic of the application.

Let me walk through working with a ViewModel using the same basic example I started in my previous post. In this case I’m going to add another panel to the page which will be displayed after the user clicks the Login button, effectively simulating the experience of showing a progress indicator whilst the application is authenticating the user.

<!-- Authenticating Prompt -->
<Grid BackgroundColor="LightPink"
         x:Name="AuthenticatingIndicator"
         IsVisible="false">
     <Label Text="Attempting to authenticate you..."
             HorizontalTextAlignment="Center"
             VerticalOptions="Center" />
</Grid>
<!-- END Authenticating Prompt –>

In this case I’m going to add a new VisualStateGroup to define the visual states to hide and show the AuthenticatingIndicator Grid.

<vsm:VisualStateGroup Name="AuthenticationStates">
     <vsm:VisualState Name="Authenticating">
         <vsm:VisualState.Setters>
             <vsm:Setter Element="{x:Reference AuthenticatingIndicator}"
                         Property="IsVisible"
                         Value="true" />
         </vsm:VisualState.Setters>
     </vsm:VisualState>
     <vsm:VisualState Name="NotAuthenticating" />
</vsm:VisualStateGroup>

A VisualStateGroup is designed to hold mutually exclusive states. A page can have any number of VisualStateGroups, and at any given point in time the current state of the page can consist of being in one VisualState from each group. In this scenario we have broken the authenticating states away from the loading states because in theory you might want to disply both the AuthenticatingIndicator, as well as the LoadingIndicator.

The last piece of XAML that I need to update is to attach an event handler to the Clicked event of the Button:

<Button Text="Login"
         Clicked="LoginPressed" />

And in the code behind, define the corresponding LoginPressed method (and yes, those MVVM purist will argue that this would be better using the Command property through to the ViewModel but we’ll leave that for another post):

protected async void LoginPressed(object sender, EventArgs e)
{
}

Now that we have the XAML defined, it’s time to look at how we can drive this from our ViewModel. In my case the page I’m working with is called MainPage.xaml, so I’m going to define a class called MainViewModel in a separate .NET Standard library. I’m not going to add a reference to BuildIt.Forms to the .NET Standard library because that would bring in a reference to Xamarin Forms, which should not be referenced by the library that holds your ViewModels – they should be abstracted away from any concrete interface, which includes Xamarin Forms, even though it is itself an abstraction from the native platform interfaces. What I am going to reference is the BuildIt.States library, which is a .NET Standard library that has no reference to any specific user interface framework, making it perfect for managing states within your ViewModel.

Alongside the MainViewModel class I’m also going to define an enumeration where the names match the corresponding visual states: the enum type name has to match the VisualStateGroup name and the enum values have to match the VisualState name.

public enum AuthenticationStates
{
     Base,
     Authenticating,
     NotAuthenticating
}

The enum also has an additional value, Base, which is will be the default enum value. The name of this value is irrelevant but it’s important to have it as the first value and should not correspond to any VisualState name.

The MainViewModel class includes a StateManager property. In this case the constructor calls the extension method DefineAllStates to define states for each value of the AuthenticationState enum. The BuildIt States library has a host of great features that are worth explaining but I’ll save that topic for another post. The important thing is that each of the states for the AuthenticationState enum are defined.

public class MainViewModel
{
     public IStateManager StateManager { get; } = new StateManager();

    public MainViewModel()
     {
         StateManager.Group<AuthenticationStates>().DefineAllStates();
     }

    public async Task Login()
     {
         await StateManager.GoToState(AuthenticationStates.Authenticating);

        await Task.Delay(2000);

        await StateManager.GoToState(AuthenticationStates.NotAuthenticating);
     }
}

The Login method simply calls the GoToState method prior to calling Task.Delay, to simulate attempting to authenticate the user, and then again calling GoToState to change the state back to the NotAuthenticating state.

Now that we have our MainViewModel defined, I need to connect it to my MainPage. For real applications we work on at Built to Roam, we use frameworks such as MvvmCross to connect the View and ViewModels. However, for brevity I’m going to simply create an instance of the MainViewModel as part of the MainPage:

private MainViewModel ViewModel { get; } = new MainViewModel();

And then set the instance as the BindingContext of the page, in the constructor:

public MainPage()
{
     InitializeComponent();

    BindingContext = ViewModel;
}

Lastly, I’ll update the LoginPressed method to call the method on the MainViewModel:

protected async void LoginPressed(object sender, EventArgs e)
{
     await ViewModel.Login();
}

At this point we’re almost done: We have a ViewModel that defines the states of the application in a way that they can be tested in absence of any user interface implementation, and the View (in this case the MainPage) will invoke the Login method to trigger the state changes. The only missing component is connecting the Visual States defined on the MainPage XAML, with the states defined in the MainViewModel. This is done using the Bind method within the OnAppearing override:

await VisualStateManager.Bind(this, ViewModel.StateManager);

Now I’m ready to go – at this point the user experience is entirely defined in XAML, with all my logic, including the states, encapsulated within my ViewModel, ready to be tested.

Getting Started with Visual States in Xamarin Forms using BuildIt.Forms

Over the past couple of months we’ve been working on getting the BuildIt.Forms library to a point where it was stable enough to promote and talk about. With the recent release of the 2.4 update for Xamarin Forms, we’re finally able to push out a stable release.

The BuildIt.Forms library brings with it quite a few features but probably the best reason to use the library is the support it adds for defining Visual States within your Xamarin Forms application within the XAML, just like you would if you were building using XAML for UWP (or any other XAML platform such as WPF etc). We’ve tried to stay as true as possible to the syntax for Visual States used on other platforms but like all things Xamarin Forms there are some differences that you’ll need to get your head around.

Ok, before we jump in, let’s take a back step and look at what a Visual State really is, and why you’d want to use them. Let’s start with a very simple example – imagine you have a page within your application that needs to load some data and you want to provide a visual cue that something is happening. In this case I’m going to add a simple overlay with some text indicating that information is being loaded:

<!-- Loading Prompt -->
<Grid BackgroundColor="LightGray"
         x:Name="LoadingIndicator"
         IsVisible="false">
     <Label Text="Loading..."
             HorizontalTextAlignment="Center"
             VerticalOptions="Center" />
</Grid>
<!-- END Loading Prompt –>

Note that the default IsVisible value is false, meaning that the LoadingIndicator Grid will not be visible. In the codebehind of the page I can then add code that would show the LoadingIndicator Grid, simulate loading content (ie Task.Delay), and then hide the LoadingIndicator Grid.

protected override async void OnAppearing()
{
     base.OnAppearing();

    LoadingIndicator.IsVisible = true;

    await Task.Delay(2000);

    LoadingIndicator.IsVisible = false;
}

Of course in a real application you wouldn’t do this, as there should be at least a ViewModel that would do the loading but we’ll come back to the use of ViewModels later. For the moment, it’s enough to point out that we controlling the appearance of individual elements based on the state of the page (ie showing the LoadingIndicator when the page is in the loading state). What would be great is if we could declare these states in XAML, which is where the BuildIt Forms library comes in.

I’ll add a few namespaces to the XAML for the page (mainly so I don’t forget to add them later when we talk about animations and other controls in the BuildIt Forms library):

xmlns:ctrl="clr-namespace:BuildIt.Forms.Controls;assembly=BuildIt.Forms.Controls"
xmlns:vsm="clr-namespace:BuildIt.Forms;assembly=BuildIt.Forms.Core"
xmlns:anim="clr-namespace:BuildIt.Forms.Animations;assembly=BuildIt.Forms.Core"

Next, immediately inside the root tag of the page, I’ll define two visual states:

<vsm:VisualStateManager.VisualStateGroups>
     <vsm:VisualStateGroups>
         <vsm:VisualStateGroup Name="LoadingStates">
             <vsm:VisualState Name="Loading">
                 <vsm:VisualState.Setters>
                     <vsm:Setter Element="{x:Reference LoadingIndicator}"
                                 Property="IsVisible"
                                 Value="true" />

                 </vsm:VisualState.Setters>
             </vsm:VisualState>
             <vsm:VisualState Name="Loaded" />
         </vsm:VisualStateGroup>
     </vsm:VisualStateGroups>
</vsm:VisualStateManager.VisualStateGroups>

The important things to note are the names of the states: Loading and Loaded, and the use of a Setter element to adjust the IsVisible property on the LoadingIndicator element. Note that I didn’t need to set the IsVisible property to false in the Loaded state – this is because the default value of the IsVisible property on the LoadingIndicator is set to false, and the Visual State manager is clever enough to remember that when switching between states.

Now that we have visual states defined, let’s switch to the code behind and adjust the code to use the visual states:

protected override async void OnAppearing()
{
     base.OnAppearing();
    await VisualStateManager.GoToState(this, "Loading");
    await Task.Delay(2000);
     await VisualStateManager.GoToState(this, "Loaded");
}

It looks like we haven’t made any great improvements but here’s where the power is – let’s add some content to the screen that will be shown when the loading is complete:

<!-- Login Prompt -->
<Grid x:Name="LoginPrompt"
         IsVisible="False">
     <StackLayout>
         <Label Text="Username:" />
         <Editor />
         <Label Text="Password:" />
         <Editor />
         <Button Text="Login" />
     </StackLayout>
</Grid>
<!-- END Login Prompt –>

In the past, this would have required more code in the code behind to adjust the IsVisible property on the LoginPrompt Grid in order to show the content. With visual states, there is no need to alter the logic of the application, I just need to adjust the Loaded visual state by adding a Setter to set the IsVisible property to true.

<vsm:VisualState Name="Loaded">
     <vsm:VisualState.Setters>
         <vsm:Setter Element="{x:Reference LoginPrompt}"
                     Property="IsVisible"
                     Value="true" />

     </vsm:VisualState.Setters>
</vsm:VisualState>

At the moment I have built an interface that provides useful feedback to the user about the loading state of the application. However, there is a rather abrupt change between the LoadingIndicator Grid and the LoginPrompt. It would be nice to be able to add animations to make the transition smoother. Again without adjusting the logic of the application I can do this by adding animations directly to the visual states. The following animation can be added after the Setters of the Loading state.

<vsm:VisualState.LeavingAnimations>
     <anim:AnimationGroup>
         <anim:AnimationGroup.PreAnimations>
             <anim:FadeAnimation Duration="500"
                                 Opacity="0"
                                 Element="{x:Reference LoadingIndicator}" />
         </anim:AnimationGroup.PreAnimations>
     </anim:AnimationGroup>
</vsm:VisualState.LeavingAnimations>

In this case the animation will be run prior to (ie a PreAnimation) any state change away from (ie a LeavingAnimation) the Loading state, and will fade the LoadingIndicator Grid out to 0 Opacity over a duration of 500 milliseconds.

In this post I’ve covered the basics of creating Visual States. In my next post I’ll cover using states in a ViewModel and how you can link them to the Visual States on the page to give you a more testable application.

Getting Started: Xamarin Forms with .NET Standard 2.0

In my earlier post Getting Started: Xamarin Forms with .NET Standard I covered how to create a new Xamarin Forms project which uses a .NET Standard 1.4 library to share the views between iOS, Android and UWP. At the time, whilst iOS and Android supported .NET Standard 2.0, support still wasn’t available for UWP. Almost immediately after publishing the blog post, Microsoft announced that Visual Studio 2017 preview 15.4 would allow UWP applications to reference .NET Standard 2.0 libraries. Unfortunately this didn’t work in the first drop, 15.4.0 Preview. This was just updated to 15.4.0 Preview 2 (Release Notes: https://www.visualstudio.com/en-us/news/releasenotes/vs2017-preview-relnotes), which brings with it the support we’ve been after. In this post, I’m going to repeat the previous post on getting started with .NET Standard, this time using .NET Standard 2.0 for the UI project.

Let’s walk through the basics – create a new Cross Platform App (same as before)

image

Select the Xamarin.Forms (UI Technology) and Portable Class Library (PCL) (Code Sharing Strategy) – Don’t pick the Shared Project option!

image

Select the Insider Preview version of UWP for both Minimum and Target version – this is required for .NET Standard 2.0 support. If you want to target earlier versions of Windows 10, you’ll have to stick with .NET Standard 1.4.

image

Next, we’re going to replace the PCL with a new .NET Standard library

image

I’ll copy the App.xaml, App.xaml.cs, MainPage.xaml and MainPage.xaml.cs from the PCL into the .NET Standard library, before deleting the PCL from the project (see https://nicksnettravels.builttoroam.com/post/2017/08/26/Getting-Started-Xamarin-Forms-with-NET-Standard.aspx for more detailed instructions).

The big difference is that I’m not going to change the default Target Framework, leaving it as .NET Standard 2.0.

image

Next I need to make sure I add and upgrade references to Xamarin.Forms to each of the projects – this isn’t actually required, since the stable release of Xamarin Forms will actually work with .NET Standard but I’ve been working with the pre-release version quite a bit lately, so I’ll go with that for this example.

image

I also need to remember to add a reference to the .NET Standard project to each of the head projects for iOS, Android and UWP.

image

If you attempt to build and run at this point iOS and Android should work without issue. UWP will most likely compile but will raise an exception “Could not load file or assembly ‘netstandard, Version=2.0.0.0….” at runtime.

image

Essentially the UWP project structure has evolved a little, so you need to upgrade it. Now I think that you may be able to do this via package manager but I’ve never got it to work for UWP projects, so I will make the changes manually to the csproj file. Start by deleting the project.json file from the UWP project.

Next right-click the UWP project in Solution Explorer and select unload project. Next, right-click on the UWP project node and select Edit MySecondXamarinFormsApp.UWP.csproj.

Add a new PropertyGroup – this changes the way packages are referenced, eliminating the need for the project.json file, replacing it with references within the csproj file.

<PropertyGroup>
   <RestoreProjectStyle>PackageReference</RestoreProjectStyle>
</PropertyGroup>

image

Next we need to add back the package references that were in the project.json – if you’re doing this on an existing project, you may want to keep the project.json file handy so you know which packages to add. In this case there are just two projects:

<ItemGroup>
   <PackageReference Include="Microsoft.NETCore.UniversalWindowsPlatform">
     <Version>6.0.0-preview1-25631-01</Version>
   </PackageReference>
   <PackageReference Include="Xamarin.Forms">
     <Version>2.4.0.269-pre2</Version>
   </PackageReference>
</ItemGroup>

image

Now you can right-click on the UWP project in Solution Explorer and select Reload project. Trigger a rebuild and now you should be able to run the UWP project.

image

Getting Started: Xamarin Forms with .NET Standard

With the recent release of Visual Studio 2017 v15.3 (and subsequent patch release 15.3.1 and 15.3.2…. yes, it does say something about ship quality Sad smile) came the release and support for .NET Standard 2.0. The Xamarin team also made a lot of noise about support for .NET Standard 2.0; unfortunately this doesn’t yet translate into Visual Studio templates that easily get you started. My particular annoyance is the about of steps you need to go through in order to just spin up a new Xamarin Forms application that can reference .NET Standard libraries. I thought I’d piggyback of a post done a couple of months back by Pierce Boggan. Here goes:

Start by creating a new project in Visual Studio 2017, selecting the Cross Platform App (Xamarin) project template:

image

Next, select the template you want (I’m going with the Blank App), the UI Technology and Code Sharing Strategy. As I’m going to be walking through how to use Xamarin Forms, it makes sense to pick that as the option for UI Technology. Only select the Portable Class Library option. Don’t use the Shared Project – using a shared project will lead you down the evil road of using conditional compilation which will be a maintenance nightmare, just don’t use it. I don’t care how great you think it is, don’t use it. One last time, don’t use the Shared Project option.

image

Now that I’ve expressed my opinion on code sharing strategies, let’s click the OK button and get on with building our application. As the template goes through generating the head projects for iOS, Android and UWP, it will prompt you to select the target and minimum platforms for UWP. For the most part, unless you have specific target platform requirements for UWP, you can leave the default settings.

image

The generated solution will have four projects: three head or target platform projects (for iOS, Android and UWP) and a portable class library (PCL) which contains the XAML pages that will make up your Xamarin Forms application layout. In order to proceed with .NET Standard support we need to replace the PCL with a .NET Standard library. Whilst Visual Studio used to have a mechanism for upgrading a library from a PCL to a .NET Standard library, this has been removed. Now the easiest way is to simply create a new project, and copy the relevant files into the new project. From the Add New Project dialog, select the Class Library (.NET Standard) template.

image

I use the .UI naming convention for the library that will contain my XAML pages. Other developers use .Core but my preference is to separate my XAML pages away from my view models. Whilst technically with Xamarin Forms they can reside in the same library, I prefer to have a clean separation between them. I have <applicationname>.UI with my XAML pages in it and <applicationname>.Core with my view models, services, entities, essentially all the business logic for my application.

For this example I’m going to keep it simple and we’ll just create the .UI project for the moment.

image

I don’t need the default Class1.cs, so I’ll remove that. I’ll add a reference to the .NET Standard library to all the head projects.

I’m also going to drop the .NET Standard version back from 2.0 (now the default in Visual Studio) back to 1.4. Whilst the tooling has been updated for the head projects for iOS and Android to support .NET Standard 2.0, of course, UWP is still lagging the field, as so you won’t be able to use a .NET Standard 2.0 library until that’s fixed. To be honest though, not much is lost by lowering the version of the .UI project to 1.4 since all the features of Xamarin Forms are still there.

image

Next I’m going to copy App.xaml (and App.xaml.cs) and MainPage.xaml (and MainPage.xaml.cs) from the PCL into the newly created .NET Standard library. Once I’ve copied these files across I can remove the PCL project from the solution – this will remove the references to this library from each of the head projects. After coping these files across, you may well see a compilation error similar to the following:

1>------ Build started: Project: MyFirstXamarinFormsApp.UI, Configuration: Debug Any CPU ------
1>C:\Program Files\dotnet\sdk\2.0.0\Sdks\Microsoft.NET.Sdk\build\Microsoft.NET.Sdk.DefaultItems.targets(274,5): error : Duplicate 'EmbeddedResource' items were included. The .NET SDK includes 'EmbeddedResource' items from your project directory by default. You can either remove these items from your project file, or set the 'EnableDefaultEmbeddedResourceItems' property to 'false' if you want to explicitly include them in your project file. For more information, see
https://aka.ms/sdkimplicititems. The duplicate items were: 'App.xaml'; 'MainPage.xaml'
1>Done building project "MyFirstXamarinFormsApp.UI.csproj" -- FAILED.

If you do, you just need to edit the project file for the .UI project and remove the App.Xaml and MainPage.xaml EmbeddedResource elements. The new project format includes files by default and the tooling isn’t smart enough to realise that the sample files are being added multiple times. Removing these elements will fix the compilation:

<ItemGroup>
   <EmbeddedResource Include="App.xaml">
     <Generator>MSBuild:UpdateDesignTimeXaml</Generator>
   </EmbeddedResource>
   <EmbeddedResource Include="MainPage.xaml">
     <Generator>MSBuild:UpdateDesignTimeXaml</Generator>
   </EmbeddedResource>
</ItemGroup>

The last thing to do is to make sure that the .NET Standard library references Xamarin Forms. I’m going to do that by right-clicking the solution node in Solution Explorer and selecting Manage Nuget Package for Solution.

image

I’m going to select the new prerelease version of Xamarin Forms (which is the one where they’ve apparently added .NET Standard support). In addition to adding a reference to Xamarin Forms to the UI project, I also take this opportunity to upgrade all the package references in the application. Note that I’ve even selected the Android support packages – this used to be a big No-No but with the latest version of the tooling you can now go ahead and update them, and I would definitely encourage you to do so.

image

Now, go make yourself a coffee – Nuget is slow, so slow! The good news is that once you’ve done all these steps, you’re ready to go with a .NET Standard based Xamarin Forms project. If you’re following this post to get started on your own project, you can finish up here, as you’re good to go.

Ok, so all of that, and what can we do. We’ll for a starters, it makes it super easy to add nuget packages such as BuildIt Forms which has a bunch of helper controls and features to get you building richer applications. Let’s add a reference to the BuildIt.Forms Nuget package the project:

image

After adding the reference to BuildIt.Forms we can make use the added controls. For example the ContentButton allows us to easily add a button that contains any XAML content, whilst still maintaining the pressed and hover states:

<?xml version="1.0" encoding="utf-8" ?>
<ContentPage xmlns="
http://xamarin.com/schemas/2014/forms"
              xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
              xmlns:local="clr-namespace:MyFirstXamarinFormsApp"
              xmlns:ctrls="clr-namespace:BuildIt.Forms.Controls;assembly=BuildIt.Forms.Controls"
              x:Class="MyFirstXamarinFormsApp.MainPage">
 
     <StackLayout VerticalOptions="Center"
                  HorizontalOptions="Center">
         <Label Text="Welcome to Xamarin Forms!" />
         <ctrls:ContentButton>
             <Label Text="Press m!" />
         </ctrls:ContentButton>
     </StackLayout>
</ContentPage>

I’ll cover more on the BuildIt.Forms library in coming posts.

Visual State Transitions in Xamarin Forms with Animations

In previous posts (Visual States in Xamarin.Forms using BuildIt.Forms and Xamarin.Forms Visual States with View Models) I demonstrated how the BuildIt.Forms library (https://www.nuget.org/packages/BuildIt.Forms) could be used to declare visual states for pages, and controls, within Xamarin Forms. Today we just added some basic support for animations so that as you transition between visual states you can animate elements of the screen:

The following visual states define animations for rotating a green square:

<Grid HeightRequest="100" WidthRequest="100" x:Name="AnimateGrid" HorizontalOptions="Start" BackgroundColor="Green" />

The Hide visual state defines three animations that run in parallel, with the rotation being a sequence of animations. The Show visual state has the reverse animations to return the green square to the original starting position. Unlike the setters, there’s no built in support for returning the element to its unchanged state.

<vsm:VisualStateManager.VisualStateGroups>
     <x:Array Type="{x:Type vsm:VisualStateGroup}">
         <vsm:VisualStateGroup Name="SampleStates">
             <vsm:VisualState Name="Show">
                 <vsm:VisualState.Animations>
                     <vsm:TranslateAnimation TranslationX="0" Duration="500" Target="AnimateGrid"/>
                     <vsm:FadeAnimation Opacity="1" Duration="500" Target="AnimateGrid"/>
                     <vsm:RotateAnimation Rotation="0" Duration="500" Target="AnimateGrid"/>
                 </vsm:VisualState.Animations>
             </vsm:VisualState>
             <vsm:VisualState Name="Hide">
                 <vsm:VisualState.Setters>
                     <vsm:Setter Value="false"
                                 Target="WelcomeText.IsVisible" />
                 </vsm:VisualState.Setters>
                 <vsm:VisualState.Animations>
                     <vsm:ParallelAnimation>
                         <vsm:TranslateAnimation TranslationX="200" Duration="3000" Target="AnimateGrid"/>
                         <vsm:FadeAnimation Opacity="0.2" Duration="3000" Target="AnimateGrid"/>
                         <vsm:SequenceAnimation>
                             <vsm:RotateAnimation Rotation="135" Duration="750" Target="AnimateGrid"/>
                             <vsm:RotateAnimation Rotation="0" Duration="750" Target="AnimateGrid"/>
                             <vsm:RotateAnimation Rotation="135" Duration="750" Target="AnimateGrid"/>
                             <vsm:RotateAnimation Rotation="0" Duration="750" Target="AnimateGrid"/>
                         </vsm:SequenceAnimation>
                     </vsm:ParallelAnimation>
                 </vsm:VisualState.Animations>
             </vsm:VisualState>
         </vsm:VisualStateGroup>
     </x:Array>
</vsm:VisualStateManager.VisualStateGroups>

This is how these animations play out:

animations

Adding Fluent Design Acrylic Material to UWP via Xamarin.Forms.

At Build Microsoft made a big deal out of the new Fluent Design that they’re encouraging developers to start taking advantage of. Out of the box it’s a little harder to take advantage of these features but using BuildIt.Forms it’s easy to start using acrylic material resources. Let’s extend the example I’ve covered in the last couple of posts (Visual States in Xamarin.Forms using BuildIt.Forms and Xamarin.Forms Visual States with View Models). I’ve added a Grid, that will span the whole page (the StackLayout was positioned to keep all the elements in the centre of the page) and included the BackgroundEffect to set the background of the whole page.

<Grid>
     <Grid.Effects>
         <ctrls:BackgroundEffect Resource="SystemControlAcrylicWindowBrush" />
     </Grid.Effects>

     <StackLayout VerticalOptions="Center"
                     HorizontalOptions="Center">

        <Label x:Name="WelcomeText"
                 Text="{Binding WelcomeText}" />
         <StackLayout Orientation="Horizontal">
             <Button Text="Show"
                     Clicked="ShowClicked" />
             <Button Text="Hide"
                     Clicked="HideClicked" />
         </StackLayout>
     </StackLayout>
</Grid>

The Resource attribute defines the UWP brush resource that will be used as the background. In this case the SystemControlAcrylicWindowBrush is one of the build in arcylic brushes. As you can see the page appears as translucent, allowing what’s behind the app to taint the background of the app.

image

It’s also possible to use a custom acrylic resource, defined in the App.xaml of the UWP application

<Application
     x:Class="FormsWithStates.UWP.App"
     xmlns="
http://schemas.microsoft.com/winfx/2006/xaml/presentation"
     xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
     xmlns:local="using:FormsWithStates.UWP"
     RequestedTheme="Light">
     <Application.Resources>
         <ResourceDictionary>
             <ResourceDictionary.ThemeDictionaries>
                 <ResourceDictionary x:Key="Default">
                    <AcrylicBrush x:Key="MyAcrylicBrush"
                                   BackgroundSource="HostBackdrop"
                                   TintColor="#FFFF0000"
                                   TintOpacity="0.4"
                                   FallbackColor="#FF7F0000" />

                 </ResourceDictionary>

                <ResourceDictionary x:Key="HighContrast">
                     <SolidColorBrush x:Key="MyAcrylicBrush"
                                      Color="{ThemeResource SystemColorWindowColor}" />

                 </ResourceDictionary>

                <ResourceDictionary x:Key="Light">
                     <AcrylicBrush x:Key="MyAcrylicBrush"
                                   BackgroundSource="HostBackdrop"
                                   TintColor="#FFFF0000"
                                   TintOpacity="0.4"
                                   FallbackColor="#FFFF7F7F" />

                 </ResourceDictionary>
             </ResourceDictionary.ThemeDictionaries>
         </ResourceDictionary>
     </Application.Resources>
</Application>

image

The BackgroundEffect also supports a FallbackColor attribute which can be used to set the background colour on all platforms.

Xamarin.Forms Visual States with View Models

In my previous post, Visual States in Xamarin.Forms using BuildIt.Forms, I showed how to use BuildIt.Forms (https://www.nuget.org/packages/BuildIt.Forms) to create visual states that can be used to define how the user interface changes to reflect different states of the page. The example demonstrated switching between visual states in the code behind with calls to VisualStateManager.GoToState. In this post I’m going to extend the example to allow the states to be switched from a view model.

I’ll start by creating a view model that will be data bound to the page. Usually I’d use a framework like MvvmCross to drive the view model/view instantiation but for this example I’ll keep it simple. I will however still put the view model in a separate project – again this promotes good separation between the view models and their associated view. I’ll create a new .NET Standard library, FormsWithStates.Core, and add a reference to it into the FormsWithStates.UI project.

image

I’ll add a new class to the project, MainViewModel, which will be the view model for the MainPage of the application. To track states within the view model, I need to add a reference to the BuildIt.States library on NuGet.

image

The MainViewModel will define a simple property WelcomeText to demonstrate that the view model is indeed data bound to the page. It also implements the interface IHasStates which defines a property StateManager – you can think of the IStateManager implementation as an object that can track states and state transitions.

public enum SampleStates
{
     Base,
     Show,
     Hide
}

public class MainViewModel : IHasStates
{
     public IStateManager StateManager { get; } = new StateManager();

    public string WelcomeText => "Welcome to Forms!";

    public MainViewModel()
     {
         StateManager.Group<SampleStates>().DefineAllStates();
     }

    public void Show()
     {
         StateManager.GoToState(SampleStates.Show);
     }
     public void Hide()
     {
         StateManager.GoToState(SampleStates.Hide);
     }
}

The enumeration SampleStates defines the states that the MainViewModel references – both the enumeration and the states themselves have to match the names of the visual state group and visual states defined in the XAML for the page. The final step is to link the visual states on the page to the IStateManager instance, so that when there is a state change in the IStateManager, it will be reflected on the page via a change to the visual states. This is done by the Bind method on the VisualStateManager class.

public partial class MainPage : ContentPage
{
     private MainViewModel ViewModel { get; } = new MainViewModel();
     public MainPage()
     {
         InitializeComponent();

        BindingContext = ViewModel;
         VisualStateManager.Bind(this, ViewModel.StateManager);
     }

    public void ShowClicked(object sender, EventArgs e)
     {
         ViewModel.Show();
     }
     public void HideClicked(object sender, EventArgs e)
     {
         ViewModel.Hide();
     }
}

Whilst from the perspective of a user, there is no difference (since the Show and Hide buttons do the same thing), state management has been shifted to the view model where it can be tested. This separation of views and view models is important to ensure all application logic can be tested.

Visual States in Xamarin.Forms using BuildIt.Forms

A couple of weeks ago I started building out some helpers to make working with Xamarin.Forms a little nicer (see Styling Pages and Controls in Xamarin Forms using Visual States,Rebuilding the Xamarin.Forms Button with Visual States and Control Templates and Ambient Properties in Xamarin.Forms). Since then we’ve been working on building out a library that encapsulates these features, again making it easier for us and others to build apps using Xamarin.Forms. There is now a pre-release version of BuildIt.Forms (https://www.nuget.org/packages/BuildIt.Forms) that anyone can reference to take advantage of these helpers. The library makes use of some methods/properties that are only available in the pre-release version of Xamarin.Forms, which is why we don’t have an actual release out yet.

In this post I’m going to walk through using visual states in a Xamarin.Forms project. To set the scene, I’m going to step through creating a new Xamarin.Forms project in Visual Studio 2017 (current RTM build, not the preview, although the preview build should be similar). I’ll do this in this post to make sure the basics of creating a Xamarin.Forms project that uses a .NET Standard Library instead of a PCL library is covered. I highly recommend switching to a .NET Standard library as soon as possible to avoid issues with upgrading nuget references etc (most third party library now have a .NET Standard version and it will become increasingly harder to maintain and update your old PCL libraries).

Ok, so let’s get started with a new project – I’m going with the Cross Platform App (Xamarin) template in the New Projects dialog:

image

Next, I’ll select the Blank App template, using Xamarin.Forms (UI Technology) and Portable Class Library (Code Sharing Strategy). Side note here – I highly recommend not using the Shared Project option for Code Sharing Strategy; using this option is a recipe for disaster as it promote poorly separated UI logic and allows for using conditional compilation based on #defines which is not a good strategy if you want maintainable code.

image

After clicking OK my solution has four projects: A PCL which has got the Xamarin.Forms UI defined in XAML files, and three “head” projects, one for each target platform. At this point, I would suggest running each project to make sure you have a working application before going any further (and commit this code to your source repository before going any further!)

image

Now to replace the PCL with a .NET Standard library. I’ll add a new .NET Standard class library. I like to make it clear that this library will contain the UI for my Xamarin.Forms project by using the .UI suffix. I do not include my view models in this library – I’ll talk about this in a subsequent post.

image

After creating the new class library, I just need to copy across the XAML and .cs files that were in the PCL library (App.xaml, App.xaml.cs, MainPage.xaml, MainPage.xaml.cs).  I can then remove the PCL library from the solution. Of course, I need to go through each of the head projects and add a reference to the UI project.

image

At this point I would again build and run the application on each platform – If you do this without doing anything the solution won’t compile as the UI library doesn’t have a reference to the Xamarin.Forms NuGet library. I suggest adding a reference to the Xamarin.Forms NuGet library and then upgrading any libraries where there is an update available. Again before proceeding, build and run each platform.

The next step is to add a reference to BuildIt.Forms. This is a prerelease library so you’ll need to check the “Include prerelease” option when searching. You need to add this library to all projects, even though you’ll only be adding code into the UI project – this makes sure the platform specific libraries that are included in BuildIt.Forms are correctly referenced and will be included.

image

As part of referencing BuildIt.Forms you will notice that the reference to Xamarin.Forms has also been updated to the prerelease version – as BuildIt.Forms takes advantage of some prerelease APIs this is unavoidable at the moment. The official release of BuildIt.Forms will not be available until the next drop of Xamarin.Forms where these APIs come out of prerelease.

Now we can start to make use of some of the helpers in BuildIt.Forms. In this case we’re going to use visual states in the XAML for the MainPage to hide and show a Label. The following XAML includes a Label and two Button elements. There are two visual states defined: Show and Hide (the actual names are only relevant when switching visual states, they have no bearing on what the visual states do). Note that the Show visual state doesn’t need to explicitly set the IsVisible property on the WelcomeText Label to true, since this is the default value for that property.

<?xml version="1.0" encoding="utf-8" ?>
<ContentPage xmlns="
http://xamarin.com/schemas/2014/forms"
              xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
              xmlns:vsm="clr-namespace:BuildIt.Forms.Core;assembly=BuildIt.Forms.Core"
              xmlns:local="clr-namespace:FormsWithStates"
              x:Class="FormsWithStates.MainPage">
     <vsm:VisualStateManager.VisualStateGroups>
         <x:Array Type="{x:Type vsm:VisualStateGroup}">
             <vsm:VisualStateGroup Name="SampleStates">
                <vsm:VisualState Name="Show" />
                 <vsm:VisualState Name="Hide">
                     <vsm:VisualState.Setters>
                         <vsm:Setter Value="false"
                                     Target="WelcomeText.IsVisible" />
                     </vsm:VisualState.Setters>
                 </vsm:VisualState>

             </vsm:VisualStateGroup>
         </x:Array>
     </vsm:VisualStateManager.VisualStateGroups>
     <StackLayout VerticalOptions="Center"
                  HorizontalOptions="Center">
         <Label x:Name="WelcomeText"
                Text="Welcome to Xamarin Forms!" />
         <StackLayout Orientation="Horizontal">
             <Button Text="Show"
                     Clicked="ShowClicked" />
             <Button Text="Hide"
                     Clicked="HideClicked" />
         </StackLayout>
     </StackLayout>
</ContentPage>

The code for the event handlers for the two button is relatively simple:

public void ShowClicked(object sender, EventArgs e)
{
     VisualStateManager.GoToState(this, "Show");
}
public void HideClicked(object sender, EventArgs e)
{
     VisualStateManager.GoToState(this, "Hide");

}

And the final result is an interface that shows and hides the welcome text on the page:

imageimage

Feel free to try out the BuildIt.Forms library and get started using visual states within your Xamarin.Forms project.

Ambient Properties in Xamarin.Forms

One of the aspects of XAML that is often misunderstood is that of ambient properties. Probably the best example of this is being able to set the foreground colour on a Page in UWP and for the foreground color to be set on every element on the page. Unfortunately this doesn’t seem to be something that’s available in Xamarin.Forms, which lead me to wonder how hard it would be to implement.

The implementation would be slightly different from UWP which uses the AmbientAttribute. Instead I’ll create an attached property which can be set on any element. The ForeColor will be then set on each child element, unless the TextColor is explcitly set on an element.

For example the following XAML

<StackLayout
    vsm:Ambient.ForeColor="Blue">
     <Label Text="Hello World - Blue!" />
     <Label TextColor="Red"
             Text="Hello World - Red!" />
</StackLayout>

would generate the following output

image

Over the next couple of days the Ambient.ForeColor property will be added to BuildIt.Forms, which also includes the VisualStateManager I described in my past two posts (here and here).

Rebuilding the Xamarin.Forms Button with Visual States and Control Templates

In my previous post I provided a demonstrable way that visual states could be used in a Xamarin.Forms application to adjust layout. Whilst I showed how this can be used on a page to show/hide a piece of text, it can also be used to define the different states of a button. Before I get onto using visual states within a button, I’ll first show how a ContentView can be adapted to provide the basic button behaviour, whilst allowing both Content and ControlTemplate to be defined. Ok, perhaps that doesn’t make sense but let’s walk through an example:

<controls:ContentButton Pressed="ToggleButtonPressed">
    <StackLayout>
        <Label Text="Hello!" />
        <Label Text="Hello!" />
        <Label Text="Hello!" />
        <Label Text="Hello!" />
        <Label Text="Hello!" />
        <Label Text="Hello!" />
    </StackLayout>
</controls:ContentButton>

In this code, I can add any XAML elements as Content within the ContentButton tags. The ContentButton raises a Pressed event, instead of a Click or Clicked event, to which an event handler can be attached. In the next code snippet, I’ve overridden the default ControlTemplate, wrapping the ContentPresenter in a Grid which has a yellow background.

<controls:ContentButton VerticalOptions="Center"
                        x:Name="DisabledButton"
                        HorizontalOptions="Center">
    <ContentView.ControlTemplate>
        <ControlTemplate>
            <Grid BackgroundColor="Yellow">
                <ContentPresenter x:Name="ContentPresenter"
                                    Content="{TemplateBinding Content}" />
            </Grid>
        </ControlTemplate>
    </ContentView.ControlTemplate>
    <StackLayout>
        <Label Text="Hello!" />
        <Label Text="Hello!" />
        <Label Text="Hello!" />
        <Label Text="Hello!" />
        <Label Text="Hello!" />
        <Label Text="Hello!" />
    </StackLayout>
</controls:ContentButton>

Overriding the ControlTemplate demonstrates an easy way to override the style of the button in a way that can be replicated across all instances of the button in an application.

Let’s take a look at the inner workings of the ContentButton, in particular the default ContentTemplate which is used to define different visual states of the button. In this case there are four visual states: Normal, PointerOver, Pressed and Disabled.

<ContentView.ControlTemplate>
    <ControlTemplate>
        <Grid x:Name="RootGrid" BackgroundColor="{TemplateBinding BackgroundColor}">
            <local:VisualStateManager.VisualStateGroups>
                <x:Array Type="{x:Type local:VisualStateGroup}">
                    <local:VisualStateGroup Name="CommonStates">
                        <local:VisualState Name="Normal" />
                        <local:VisualState Name="PointerOver">
                            <local:VisualState.Setters>
                                <local:Setter Value="#33000000" Target="Background.BackgroundColor" />
                            </local:VisualState.Setters>
                        </local:VisualState>
                        <local:VisualState Name="Pressed">
                            <local:VisualState.Setters>
                                <local:Setter Value="#66000000" Target="RootGrid.BackgroundColor" />
                            </local:VisualState.Setters>
                        </local:VisualState>
                        <local:VisualState Name="Disabled">
                            <local:VisualState.Setters>
                                <local:Setter Value="#33000000" Target="Background.BackgroundColor" />
                            </local:VisualState.Setters>
                        </local:VisualState>
                    </local:VisualStateGroup>
                </x:Array>
            </local:VisualStateManager.VisualStateGroups>
           
<BoxView BackgroundColor="Transparent" x:Name="Background" />
            <ContentPresenter x:Name="ContentPresenter" Content="{TemplateBinding Content}" />
        </Grid>
    </ControlTemplate>
</ContentView.ControlTemplate>

In this code you can see how the visual states (which I introduced in my previous post) are used to adjust the background colour of the BoxView that sits behind the Content of the button.

The sample project that demonstrates the ContentButton can be downloaded here

Styling Pages and Controls in Xamarin Forms using Visual States

I’ve been a bit proponent of both Xamarin and Xamarin.Forms for a long time but recently I’ve been taking another look at some of the fundamentals. Xamarin.Forms, for all its great intent is still a poor-man’s answer to declaring layout of an application in Xaml. Unlike Xaml platforms that have come before it (WPF, Silverlight, UWP), Forms doesn’t support some of even the basic features that you’d expect. On the chopping board today is the Button control – as one of the fundamental controls for any application, the Button should be able to be completely customised. Unfortunately it’s far from easy to alter the look of the basic button.

If you look at how a simple button renders on different platforms, there is a clear difference between the style of the button. The following image shows how the button control renders across UWP, iOS and Android (UWP has an extra visual state as it supports mouse/pointer over on desktop).

image

Button States Across Three Platforms

The difference in style is by design – the rendering of the button on each platform uses the built in style for each platform. This works well if you’re interesting in building a generic looking application (eg perhaps a simple LOB data capture application). However, if you want to style the button in line with your branding and the design of your application, you’re going to want to make the buttons look and behave the same across all devices. You’d think this would be as simple as defining a common style, or perhaps overriding the default layout of the button. This is in fact doable – for example on UWP you can use an implicit style to override the look of every button across the application.

Having to override the style of the button on each platform defeats the purpose of using Forms in the first place – once you’ve overridden the style, you then need to make platform specific changes every time you want to alter the style of the button control; imagine doing this for every control in your application – pretty soon, you might as well have developed the application using the traditional Xamarin model, rather than Forms. So, let’s look at the limitations of the Button control and see what we can do to address some of its shortcomings in a way that will help us build better applications quicker.

There are two issues that I have with the Button control. The first is that it’s not easy to customise the content within the Button itself. For example if you wanted to have two lines of text, with the first being centred in bold, and the second justified italics with word wrapping enabled to allow it to flow to multiple lines. In UWP this would be easy with the Button control as the Content could be customised to have multiple TextBlock elements, with the style set accordingly.

<Button>
    <StackPanel>
        <TextBlock Text="Hello World!"
                    TextAlignment="Center"
                    FontWeight="Bold" />
        <TextBlock Text="This is a short message that should word wrap with all the lines being set to justified"
                    FontStyle="Italic"
                    TextWrapping="WrapWholeWords"
                    TextAlignment="Justify" />
    </StackPanel>
</Button>

This would look similar to the following:

image

UWP Button with Custom Content

Attempting to do this with the Forms Button control is not trivial. The second issue is how the different visual states are handled. Again in UWP the different Button visual states are defined in XAML (generic.xaml) where appropriate properties are set based on the active states (eg Normal, Pressed, PointerOver). Forms doesn’t support Visual States, so attempting to define Button states declaratively is going to take more work.

My solution to these issues comes in two steps: firstly, provide a declarative way to define Visual States in XAML, similar to what’s available in UWP; and secondly to provide an alternative to the Button which can not only take custom content but also has a template that can be override to customise behaviour for different button states. If you’ve ever drilled into a control template for a UWP control, chances are that it has some visual states defined. Rather than having some predefined behaviour that’s not accessible or customisable, the various states of UWP controls are defined in XAML in the template for the control. In addition to defining the different states within a control, visual states can be used to define different states of a page too.

In this post we’ll focus on the first step, which is how to define in XAML and then apply visual states. Visual states are defined in visual state groups, and only a single state within a given states group can be active at any time (ie they’re mutually exclusive). However, it is possible that two states, from different groups can be active at any point in time.

So far we know we need visual states, defined within visual state groups. Within each visual state we need to be able to define which properties are going to change when the visual state is made active. UWP allows the property changes to be defined either as a storyboard, potentially with animation, or as a series of setters where the property is updated to the new value immediately. For the purposes of getting the basics working, we’re just going to work with property setters.

Let’s work with a very simple scenario where we have a simple Label which we need to be able to show and hide based on the state of the page:

<Label FontSize="30"
        x:Name="HelloLabel"
        Text="Hello World!" />

In our very contrived example we have a button that will be used to toggle whether the Label is visible.

private bool visible = true;
public void ToggleButtonPressed(object sender, EventArgs e)
{
    visible = !visible;
    VisualStateManager.GoToState(this, visible ? "Show":"Hide");
}

This code, by design, is similar to what you might see within a UWP application that uses visual states to control the layout – in this case showing and hiding an element. Currently visual states don’t exist in Xamarin Forms but here’s a first pass on an implementation of visual states:

<vsm:VisualStateManager.VisualStateGroups>
    <x:Array Type="{x:Type vsm:VisualStateGroup}">
        <vsm:VisualStateGroup Name="LabelStates">
            <vsm:VisualState Name="Show" />
            <vsm:VisualState Name="Hide">
                <vsm:VisualState.Setters>
                    <vsm:Setter Value="false"
                                Target="HelloLabel.IsVisible" />
                </vsm:VisualState.Setters>
            </vsm:VisualState>
        </vsm:VisualStateGroup>
    </x:Array>
</vsm:VisualStateManager.VisualStateGroups>

For those familiar with the syntax in UWP this should look familiar – there’s a few kinks to work out (for example the use of the Array tag) but in its initial form it works.

Sample project can be downloaded here

NuGet does my head in….. No thanks to Xamarin.Forms

This is a bit of a rant with hopefully a fix that will help others. Firstly, the rant:

In my post on Building Cross Platform Apps I used the new project templates in Visual Studio 2017 to create a new Xamarin.Forms application that targets iOS, Android and UWP. What I didn’t mention is the time I wasted trying to upgrade NuGet packages in order to get the thing to build and run. Namely I get the following exception when attempting to build the newly created application.

Severity    Code    Description    Project    File    Line    Suppression State
Error        Exception while loading assemblies: System.IO.FileNotFoundException: Could not load assembly 'Xamarin.Android.Support.v7.RecyclerView, Version=1.0.0.0, Culture=neutral, PublicKeyToken='. Perhaps it doesn't exist in the Mono for Android profile?
File name: 'Xamarin.Android.Support.v7.RecyclerView.dll'
   at Java.Interop.Tools.Cecil.DirectoryAssemblyResolver.Resolve(AssemblyNameReference reference, ReaderParameters parameters)
   at Xamarin.Android.Tasks.ResolveAssemblies.AddAssemblyReferences(DirectoryAssemblyResolver resolver, ICollection`1 assemblies, AssemblyDefinition assembly, Boolean topLevel)
   at Xamarin.Android.Tasks.ResolveAssemblies.Execute(DirectoryAssemblyResolver resolver)    App5.Droid           

I figured that there was something wrong with the Xamarin.Forms and/or Xamarin Android NuGet packages, so I thought I’d just go an upgrade the Xamarin.Forms NuGet package. Note: Don’t every try to upgrade the Xamarin Android packages independently – let the Xamarin.Forms NuGet package determine which versions of those libraries you need. Anyhow, unfortunately that just generates another exception:

Severity    Code    Description    Project    File    Line    Suppression State
Error        Unable to resolve dependencies. 'Xamarin.Android.Support.Compat 24.2.1' is not compatible with 'Xamarin.Android.Support.Design 24.2.1 constraint: Xamarin.Android.Support.Compat (= 24.2.1)'.            0   

At this point I was starting to get annoyed – it looks like there was already an inconsistency between the Xamarin.Forms package and the Xamarin Android packages included in the template. Luckily it was easier to fix than I thought it was. I opened up the packages.config file for the Android head project and delete the Xamarin.Android libraries.

<?xml version="1.0" encoding="utf-8"?>
<packages>
  <package id="Xamarin.Android.Support.Design" version="23.4.0.1" targetFramework="monoandroid60" />
  <package id="Xamarin.Android.Support.v4" version="23.4.0.1" targetFramework="monoandroid60" />
  <package id="Xamarin.Android.Support.v7.AppCompat" version="23.4.0.1" targetFramework="monoandroid60" />
  <package id="Xamarin.Android.Support.v7.CardView" version="23.4.0.1" targetFramework="monoandroid60" />
  <package id="Xamarin.Android.Support.v7.MediaRouter" version="23.4.0.1" targetFramework="monoandroid60" />

  <package id="Xamarin.Forms" version="2.3.2.127" targetFramework="monoandroid60" />
</packages>

Then, I just upgraded Xamarin.Forms to the latest NuGet package and all was good again. Lastly, I upgraded all the other NuGet packages (excluding the Xamarin.Android packages) to the latest stable versions.

When I grow up I want to be a .NETStandard Library!

A month or so ago we made the decision to upgrade some of the portable libraries we use for projects from being based on PCL Profiles (eg profile 111 or profile 259) across to .NET Standard. To do this, we followed the upgrade prompt in the project properties page in Visual Studio.

image

After clicking the “Target .NET Platform Standard” you can then pick which .NET Standard you want. Where possible we try for .NETStandard 1.0, which aligns with PCL Profile 259, or .NETStandard 1.1, which aligns with PCL Profile 111 (see https://docs.nuget.org/ndocs/schema/target-frameworks). The theory being that a .NETStandard 1.0 library can be consumed by any .NETStandard library 1.0 and above, as well as any PCL profile library that is profile 259 – in other words, we’re aiming for maximum reach.

Take for example, BuildIt.General, which is a general purpose utility library. This is now a .NETStandard 1.0 library….. or so we thought. I was doing some testing on the current stable version of the library to make sure it could be added into a Xamarin Forms application. In my previous post I showed how easily you can create a new Xamarin Forms project that has a PCL that contains all the UI for the application, and then head projects for each target platform (iOS, Android, UWP). Before adding in BuildIt.General I upgraded all the existing NuGet references – always good practice when creating new project (disclaimer: this sounds easier than it is due to an issue with the current Xamarin.Forms template which makes it hard to upgrade – more on this in a future post).

Next I added a reference to the BuildIt.General NuGet package – I made sure it was added to all projects as it includes a UWP library that has some useful extensions such as converters that are specific to UWP. At this point everything was able to build and I was able to run the UWP application (I didn’t get round to running the other platforms but I assumed that they would also work since I hadn’t really modified anything from what comes out of the box). I then wanted to test that I could invoke functions from the BuildIt.General library, so I added the following into the MainPage.xaml.cs file within the Xamarin.Forms PCL library:

LogHelper.Log("test");

Now, when I attempted to build the library I got the following error:

The primary reference "BuildIt.General, Version=1.0.0.20, Culture=neutral, processorArchitecture=MSIL" could not be resolved because it was built against the ".NETPortable,Version=v5.0" framework. This is a higher version than the currently targeted framework ".NETPortable,Version=v4.5,Profile=Profile259".

This completely confused me….. what’s this reference to .NETPortable and what’s the difference between v5.0 and v4.5. Immediately I thought that it was an issue with Visual Studio 2017 but after a bit of investigating it turns out that it’s a more fundamental issue with the way that we, actually MSBuild/Visual Studio, is creating the BuildIt.General library. I came across this thread which includes this comment:

image

(Oren has one of the best explanations on the whole .NET Standard v’s PCL Profile discussion at https://oren.codes/2016/06/23/portable-is-dead-long-live-netstandard/)

Anyhow, I wondered whether our library was suffering from the same ill fate. Using ILSpy I took a look at what was included as the TargetFramework and sure enough it’s listed as .NETPortable, v5.0.

image

The workaround for this was listed in this changeset. In summary it requires a change to the project file to override the default generation of the Target Framework Moniker (See bold pieces in the following extract). There are two parts to the change: the first specifies the filename where the TargetFrameworkMoniker assembly attribute will be written to, and then included in the build of the application; the second overwrites the generated TargetFrameworkMoniker.

<?xml version="1.0" encoding="utf-8"?>
<Project ToolsVersion="14.0" DefaultTargets="Build" xmlns="
http://schemas.microsoft.com/developer/msbuild/2003">
  <Import Project="$(MSBuildExtensionsPath)\$(MSBuildToolsVersion)\Microsoft.Common.props" Condition="Exists('$(MSBuildExtensionsPath)\$(MSBuildToolsVersion)\Microsoft.Common.props')" />
  <PropertyGroup>
    <MinimumVisualStudioVersion>14.0</MinimumVisualStudioVersion>
    ...
    <ProjectTypeGuids>{786C830F-07A1-408B-BD7F-6EE04809D6DB};{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}</ProjectTypeGuids>
    <TargetFrameworkProfile>
    </TargetFrameworkProfile>
    <TargetFrameworkVersion>v5.0</TargetFrameworkVersion>
   <TargetFrameworkMonikerAssemblyAttributesPath>$(IntermediateOutputPath)AssemblyTFMAttribute.cs.exclude</TargetFrameworkMonikerAssemblyAttributesPath>
    ...
  </PropertyGroup>
  ...
  <Import Project="$(MSBuildExtensionsPath32)\Microsoft\Portable\$(TargetFrameworkVersion)\Microsoft.Portable.CSharp.targets" />
  <Target Name="_SetTargetFrameworkMonikerAttribute" BeforeTargets="GenerateTargetFrameworkMonikerAttribute">
    <PropertyGroup>
      <RealTargetFrameworkMoniker>.NETStandard,Version=v1.0</RealTargetFrameworkMoniker>
      <RealTargetFrameworkMonikerDisplayName>$(RealTargetFrameworkMoniker)</RealTargetFrameworkMonikerDisplayName>
      <TargetFrameworkMonikerAssemblyAttributeText Condition="'$(RealTargetFrameworkMoniker)' != '' and '$(TargetingClr2Framework)' != 'true'">
        // &lt;autogenerated /&gt;
        using System%3b
        using System.Reflection%3b
        [assembly: global::System.Runtime.Versioning.TargetFrameworkAttribute(&quot;$(RealTargetFrameworkMoniker)&quot;, FrameworkDisplayName = &quot;$(RealTargetFrameworkMonikerDisplayName)&quot;)]
      </TargetFrameworkMonikerAssemblyAttributeText>
    </PropertyGroup>
  </Target>
</Project>

After making this change, and building a new version of the BuildIt.General library I can now see the correct Target Framework:

image

Out of interest, it appears that if you’re using the xproj project format targeting .NETStandard, it creates a library with the correct target framework. Hopefully this fix, will help you if you’re not.

Building Cross Platform Applications with Visual Studio 2017

Ok, before I jump into this, I want to point out a couple of things:

- Visual Studio 2017 is still in RC

- When you install the RC of Visual Studio 2017 and enable the options to install Xamarin, you will break any existing Xamarin support for earlier versions of Visual Studio (see https://www.visualstudio.com/en-us/news/releasenotes/vs2017-relnotes#KIXamarin).

I noticed the other day when I was creating a throwaway project is that there’s a new dialog when creating cross platform applications within Visual Studio 2017. In the New Project dialog, select the Cross Platform node and there is a single Cross Platform App option.

image

Selecting this option presents you with some project templates – there are only a couple at the moment but I’m hoping that they provide more examples.

image

Unfortunately, and it’s a little hard to see in this screenshot, for the Master Detail template, you can only select Shared Projects. Without exploring the template, I can only assume it was setup this way to share UI code that has platform specific code that compiles based on conditional flags. I really like the way that you can switch between a Forms application and a Native (and no they don’t literally mean “native” (eg Objective-C/Swift or Java/C++), they mean traditional Xamarin where you have platform specific UI.

I opted for the “Blank App (XAML)” which requires Forms, I selected PCL, but unfortunately the “Host in the cloud” option was then disabled. After hitting Accept, the new solution was created and I was immediately able to build and run the application across iOS, Android and Windows (UWP). Very nice.

Adding Xamarin Components via Visual Studio

Sometimes you’ll want to use some of the components from the Xamarin component store. This can be done directly in Visual Studio. Right-click Components node within iOS or Android project and select Get More Components

image

Once added you’ll see the component listed in Solution Explorer under the Components node. However, the Components, like NuGet packages, are located at a solution level. This makes them easy to reference from other projects.

image

In this case the Xamarin.Mobile component can be referenced by our Universal, Windows Phone 8.0, iOS and Android projects. This will make performing operations such as selecting or capturing photos much easier. However, be aware that there are some APIs that aren’t supported across all platforms. For example whilst you can reference the component from the WP8.1 application, MediaPicker fails as it’s not supported.

A Simple ViewModelLocator for Spawning ViewModels for XAML Based Applications

There are numerous frameworks out there that provide mechanisms for instantiating view models. Long again, when I first started building XAML based applications and became familiar with MVVM, I stepped through a number of different ways of creating and wiring up view models. In this post I’m going to show a very basic implementation of a locator to instantiate view models. Into the Core library I will add a ViewModelLocator class which exposes a property, Main, that will return a new instance of the MainViewModel.

public class ViewModelLocator
{
    public MainViewModel Main
    {
        get { return CreateViewModel<MainViewModel>(); }
    }

    private T CreateViewModel<T>() where T:new()
    {
        return new T();
    }
}

I’m going to want a single instance of this class to be created and kept around for the duration of my application’s lifecycle. One option would be to instantiate it within my ApplicationCore class I introduced previously. However, I actually want the instance of the ViewModelLocator to be accessible via XAML, so for this reason it makes more sense to instantiate it as a XAML resource. In the WPF and Universal (Win/WP8.1) applications I can simply add this to the app.xaml file to the Application.Resource element.

<Application.Resources>
        <core:ViewModelLocator x:Key="Locator" />
</Application.Resources>

In the MainWindow (WPF) and MainPage (Universal) I can now specify the DataContext in the opening element, removing the need to create the MainViewModel in code in the codebehind file. Eg

<Window x:Class="RealEstateInspector.Desktop.MainWindow"
        xmlns="
http://schemas.microsoft.com/winfx/2006/xaml/presentation"
        xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
        DataContext="{Binding Main, Source={StaticResource Locator}}" >

The current implementation of Xamarin.Forms doesn’t seem to support creating Application resources in XAML. However, by tweaking the App constructor, I can add an instance of the ViewModelLocator:

public App()
{
    Resources = new ResourceDictionary();
    Resources.Add("Locator", new ViewModelLocator());

    MainPage =new MainPage();
}

The syntax in the MainPage of the XForms application is similar except BindingContext replaces DataContext:

BindingContext="{Binding Main, Source={StaticResource Locator}}"

There seems to be a quirk in XForms at the moment in that the Binding expression calls to the Main property repeatedly – since it gets a different instance of the MainViewModel back each time, it ends up in an endless loop trying to get a consistent value. To prevent this, we can add a view model dictionary to the ViewModelLocator and change the behaviour to always return the same instance of the view model.

private readonly Dictionary<Type, object> viewModels = new Dictionary<Type, object>();

private T CreateViewModel<T>() where T:new()
{
    var type = typeof (T);
    object existing;
    if (!viewModels.TryGetValue(type, out existing))
    {
        existing = new T();
        viewModels[type] = existing;
    }
    return (T)existing;
}

And there you have it – view model location across all applications.

Xamarin.Forms, Windows Phone, Azure Active Directory and iOS

In my previous post I thought that there was an issue with using the Azure Active Directory Authentication Library (ADAL) and the updated Xamarin for iOS. This has been confirmed by the team at Microsoft responsible for ADAL with a view that it will be resolved in a future version (no specifics on which version or when). This is unfortunate as it means my iOS version will have to be put on hold for the timebeing.

On a different note I saw a mention in the forums that apparently Xamarin.Forms 1.4 will support Windows Phone 8.1 (and I hope as part of a universal app, also supporting Windows 8.1). Of course, there’s no timing on this one but does pose the question as to whether I should wait for the next iteration of Xamarin.Forms before proceeding with the sample apps. For the timebeing I’ll continue and see how far I get.

Active Directory Authentication with iOS with Xamarin.Forms

Essentially this doesn’t appear to currently work. Due to the alignment of iOS projects to the Unified APIs I think there is currently a compatibility issue between the ADAL prerelease library and the Xamarin.Forms implementation. I’ll come back to this once we have a resolution for this.

Adding Xamarin.Forms Support

So far I’ve only had support for the new Windows platform clients (ie Windows and Windows Phone) for my Real Estate Inspector sample app. However, to make it successful we need to target more platforms. To this end I’m going to add support for iOS, Android and Windows Phone 8.0 using Xamarin.Forms.

After installing the Xamarin tooling for Visual Studio, I added a new project using the Blank App (Xamrain.Forms Portable) template. This actually look multiple attempts as I hadn’t updated the Xamarin tooling prior to creating the projects. I would highly recommend upgrading the tooling first!

image

This will give you three target projects Driod, iOS and WinPhone, in addition to a PCL which contains the common code and ui for the applications. You should be able to build and run each of these targets – however, you’ll need to either register for a trial or have a Xamarin Business subscription. Since the UI is help in the PCL project, it’ll be the same across all the targets, although there may be platform rendering differences.

Now that we have these three targets, we’re going to have to connect up our Azure Mobile Service, work out how we’re going to deal with navigation and structure our solution to maximise code reuse across our Windows platform projects.