Xamarin (Android & iOS) Tutorial

Open the App

Navigate to the directory where the Realm CLI created the template app and open the realm-todo-app.sln solution in Visual Studio.

Explore the App Structure

In Visual Studio, take a few minutes to explore how the solution is organized. This is a standard multi-platform solution, based on a template provided by Visual Studio, that has been modified for our specific use. The solution has 3 projects:

You will perform all of the steps in this tutorial within the shared realm-tutorial-dotnet project. Specifically, you will be working in the following files:

Run the App

Without making any changes to the code, you should be able to run the app in either the Android emulator or the iOS Simulator, or on a physical device. When you installed the template app, the Realm CLI also set up a new backend for you and populated the realm.json file with the correct app ID.

Run the app, register a new user account, and then add a new Item to your todo list.

Check the Backend

Log in to Atlas App Services. In the Atlas tab, click on Browse Collections. In the list of databases, find and expand the todo database, and then the Item collection. You should see the document you created in this collection.

Add a New Property

Now that you have confirmed everything is working as expected, we can add changes. In this tutorial, we have decided that we want to add a "Priority" property to each Item so that we can filter Items by their priorities. The Priority property will be mapped to a PriorityLevel enum to constrain the possible values.

To do this, follow these steps:

1. Expand the realm-todo-dotnet project.

2. Expand the Models folder and open the Item class file.

3. Add the following public property:

   [MapTo("priority")]
   public int? Priority { get; set; }

4. Also add a PriorityLevel enum below the Item class:

   public enum PriorityLevel
   {
      Severe = 0,
      High = 1,
      Medium = 2,
      Low = 3
   }

Set the Priority when Creating a New Item

1. In NewItemPopup.xaml.cs, add a new public property under the existing ItemName and IsOK properties:

   public string ItemName { get; set; }
   public bool IsOK { get; set; }
   public int Priority { get; set; }

2. Open the NewItemPopup.xaml file. This file defines the UI element for creating a new Item. We will add two UI elements: a label and a Picker that enables the user to choose which priority level to set on the new Item. Locate the OK button, and insert the following code above it:

   <Label FontSize="18" HorizontalTextAlignment="Left" Text="Priority:"/>
   <Picker x:Name="newItemPriority">
      <Picker.Items>
            <x:String>Severe</x:String>
            <x:String>High</x:String>
            <x:String>Medium</x:String>
            <x:String>Low</x:String>
      </Picker.Items>
   </Picker>

3. Now switch back to the NewItemPopup.xaml.cs file. Find the OK_Button_Clicked event handler, which currently sets the ItemName and IsOK properties. Add a line to also set the Priority property:

   this.Priority = newItemPriority.SelectedIndex;

   Note

   Using SelectedIndex

   Because we ordered the priorities in the Picker element from highest to lowest, the lower the selected item's index, the higher that Item's priority is: 0 for Severe, 1 for High, etc. Therefore, the index matches the PriorityLevel enum values.

4. Finally, open the ItemPage.xaml.cs file, and find the Popup_Popped event handler, which fires when the NewItemPopup is closed. In this method, we create a new Item and save it to the realm. Where we set the other Item properties, add a line of code to set the new Priority property:

   var newItem = new Item()
   {
       OwnerId = _user.Id.ToString(),
       Summary = popup.ItemName,
       IsComplete = false,
       Priority = popup.Priority
   };

Run and Test

At this point, you can run the application again. Log in using the account you created earlier in this tutorial. You will see the one Item you previously created. Add a new Item, and you will see that you can now set the priority. Choose High for the priority and save the Item.

Now switch back to the Atlas data page in your browser, and refresh the Item collection. You should now see the new Item with the priority field added and set to 1. You will also notice that the existing Item now also has a priority field, and it is set to null, as shown in the following screenshot:

Update the subscription

In the ItemPage.xaml.cs file, we define the Flexible Sync subscription that defines which documents we sync with the user's device & account. Find the AddSubscriptionsToRealm method. Within the subscriptions.Update() method, you can see that we are currently subscribing to all documents where the OwnerId property matches the authenticated user. We want to maintain that, but only sync Items that are marked as High or Severe priority.

As you may recall, the Priority field is of type int, where the highest priority ("Severe") has a value of 0, and the lowest priority ("Low") has a value of 3. We can make direct comparisons between an int and the Priority property. To do so, edit the LINQ statement to include documents where the priority is equal to or less than PriorityLevel.High (or 1), as shown here:

subscriptions.Update(() =>
   {
       var defaultSubscription = _itemsRealm.All<Item>()
           .Where(t => t.OwnerId == _user.Id
           && t.Priority <= (int)PriorityLevel.High
           );
   });

Run and Test

Run the application again. Log in using the account you created earlier in this tutorial. You would expect to see the Item you most recently created, since it has a priority of "High" (1). But it is not in the list. If you check your application logs, you will see an entry that looks something like this:

"Client provided query with bad syntax: unsupported query for table "Item":
   key "priority" is not a queryable field" (error_code=300, query_version=1)

This message tells us that we have added a field to our subscription without configuring Flexible Sync to use that field.

Update Flexible Sync on the Server

1. Switch back to the Atlas page in your browser. Select the Atlas App Services tab and open the app you are using.

2. In the left-hand navigation, choose Device Sync, and then click OK in the dialog box about Development Mode being enabled.

3. Scroll down to the Select Queryable Fields section. In the dropdown labeled Select or create a queryable field, choose "priority". The priority field will be added to the fields shown:

   

4. Save your changes.

Test the changes

Return to your mobile app. To ensure the subscription is re-run, log out the current user, and then log in again. After an initial moment when Realm resyncs the document collection, you will see the new Item of High priority that you created.

If you want to further test the functionality, you can create Items of various priorities. You will see that a new Item with a lower priority briefly appears in the list of Items and then disappears. Realm creates the Item locally, syncs it with the backend, and then filters out the Item because it doesn't meet the subscription rules.

You'll note, too, that the document you initially created is not synced, because it has a priority of null. If you want this Item to be synced, you can edit the document in the Atlas UI and add a value for the priority field, or you can change your subscription to include documents with null values:

subscriptions.Update(() =>
   {
      var defaultSubscription = _itemsRealm.All<Item>()
           .Where(t => t.OwnerId == _user.Id
           && (t.Priority == null || t.Priority <= 1));
       subscriptions.Add(defaultSubscription);
   });