Documentation : Windows Phone 7 References

Prelude

This document will provide you with detailed documentation about creating Mobeelizer client application on Windows Phone 7 platform.

If you want only a quick glimpse see tutorial instead.

In this document we assumes that you are familiar with:

  • C# language
  • Basics of Windows Phone 7 application development
  • Key concepts of Mobeelizer platform (see)

Configure your application

Attach necessary resources

To work with Mobeelizer cloud first you have to download Mobeelizer SDK. Unpack downloaded file and unblock dll files. Add libraries as a project references, to do it right click on "References" node in solution explorer and select 'Add References'. Browse downloaded files and add all of them. 

Also you need to attach Linq to SQL library to your project. Repeat steps above but instead of clicking "Browse" tab find System.Data.Linq on the list in ".NET" tab and press "Ok".

Next, download XML file of your application created in App Designer and put it in your project. If you use default setting then name of this file should be application.xml. You can use other name - but then you have to set definitionAsset property (see below). Be sure that file "Build Action" property is set to "Content".

Modify WMAppManifest file

You have to add this three capabilities to WMAppManifest file to work wp7 SDK correctly.

<Capability Name="ID_CAP_IDENTITY_DEVICE"/>
<Capability Name="ID_CAP_NETWORKING"/>
<Capability Name="ID_CAP_PUSH_NOTIFICATION"/>

Add app.config file

In the next step you have to add app.config file. Create it in your project and set "Build Action" property to "Content". In this file you have to add mobeelizer configuration section and define some properties.

  • Add mobeelizer configuration section:
<configSections>
	<section name="mobeelizer-configuration"
    	type="Com.Mobeelizer.Mobile.Wp7.Configuration.MobeelizerConfigurationSection, wp7-sdk" />
</configSections>

 

  • Add configuration meta-data:
    To make Mobeelizer SDK works properly you have to configure some general parameters. To configure parameter add  property to created section:

<mobeelizer-configuration>
  <properties>
    <add name="METADATA_NAME" value="METADATA_VALUE"/>
  </properties>
</mobeelizer-configuration>

Available parameters are:

NameRequired

Description

modeYES

There are three possible development modes:

  • development - application works off-line. Login and synchronization methods are mocked - they do nothing but returning success status. This mode allows you to develop client application completely separate from cloud deployment and management. Defining "developmentRole" parameter is necessary with this mode.
  • test - application will connect to test environment.
  • production - application will connect to production environment.
developmentRole NO

This parameter is required only in 'development' mode - it is ignored on other modes.

Normally while login method system receives role of user. But as you can read above login method is off-line in development mode so you have to provide user role manually - as value of this parameter.

entitiesNamespaceYES

Namespace and assembly name of your model classes.

deviceYES

Name of the device category. See this document for more explanation.

definitionAssetNO

Name of the XML file with application definition. Default value is application.xml.

databaseVersionNO

Version of database. Default value is 1. When you increase this number old database is dropped and new one is created.

Create model classes 

Last thing to make your application work is to create models. For all the models you have defined in App Center and that are in downloaded XML file you have to create corresponding C# classes. While creating these classes you have to remember about few things:

  • Namespace

Must be the same as defined in "entitiesNamespace" parameter.

  • Name of class

Should be the same as name of corresponding model.

  • Extending 

Model class have to extends MobeelizerWp7Model. MobeelizerWp7Model class contains Guid property and other special properties:

NameTypeRequired

Description

GuidStringYES

Main object identifier

OwnerStringYES

Information about owner of object

ModifiedboolYES

This field will be true if record was modified by user - but not synchronized yet.

ConflictedboolYES

This field will be true if object is conflicted. See here to read more about conflicts.

DeletedboolYES

To delete entity set this field to true.

All of this properties have to be created with override statement.

 

  • Model fields

Beside special fields you have to add property for every field defined in App Designer model. Name of these properites must be the same as name of model fields - but with uppercased first letter!

Type of properties must be one of listed below:

Model typeAvailable class field types
belongs toString
booleanbool?, bool
dateDateTime?, DateTime
decimaldouble?, double
fileString
integerint?, int
textString

Not required fields cannot be defined by primitive types like int or bool. Use nulable types like int? and bool? instead.

  • LINQ to SQL attributes

Mobeelizer SDK is using Linq to SQL to store your data, you have to add mapping attributes to your model class.

    • [Table] - atribute have to be placed before class statement.
    • [Column(IsPrimaryKey = true)] - atribute have to be places before Guid property.
    • [Column()] - atribute have to be places before your model fields and other special properties.

Log in to application

Before using any of Mobeelizer features you have to make user log in to your cloud application. Any activity - like accessing database - before login will have effect in throwing an exception!

You can do that by calling one of login static methods from Mobeelizer object. There are two version of this method:

  • asynchronous, with default environment name (see doc)

  • asynchronous, with environment name (see doc)

You have to remember, that when you log in any user for the first time your client application must be on-line (except 'development' mode.) Also first login can take long time to perform - because of initial synchronization processes that are automatically triggered after login verification. So better supply user with nice looking loading indicator. 

Also you may wonder what is the environment name. Firstly see this document to read about environments. As you can read there, when you create an app, then two environments are created - one for test and one for production purpose. They are named accordingly "test" and "production". When you want to connect to these instances use default environment name method. But if you want to connect with environment manually created - you have to provide its name.

To change user you should use logout method. Remember to finish all background processes before calling it - logging out while synchronization process can effect with unpredictable connector behavior!

Use database

Obtaining database object

Database can be accessed using object IMobeelizerDatabase which can be obtained by calling method

IMobeelizerDatabase database = Mobeelizer.GetDatabase();
Remember that to use database user have to be logged in.
You shouldn't connect to database directly without MobeelizerDatabase object! SDK will loose track of changes tracking and synchronize functionality will not work properly!

Transactions

IMobeelizerDatabase object provide method to open transaction.

IMobeelizerTransaction transaction = database.BeginTransaction();

 

IMobeelizerTransaction implements IDisposable interface which means that there are some alocated resources which have to be released. Remember to always close transaction after all operations. It is a good practise to use using statment.

using(IMobeelizerTransaction transaction = database.BeginTransaction())
{
	// your code here 
}

Basic operations

There is a great news for you, you don't have learn any new interface to operate your data. You can use well known on wp7, Linq to SQL to get data from your database. 

var query = from p in transaction.GetModelSet<Product>() select p;
IList<Product> allProducts = query.ToList();
var querySingle = from p in transaction.GetModelSet<Product>() where p.Guid == "some guid" select p;
Product product = querySingle.Single();
Product product = // create product
transaction.InsertOnSubmit(product);
transaction.SubmitChanges();
transaction.DeleteOnSubmit(product);
transaction.SubmitChanged();

Relations

To define relation you have to add 'belongs to' type field to model. Lets say you have models Order and OrderPosition. To connect these objects with relation you have to add 'belongs to' field to OrderPosition - let's name it Order.

As you can read above 'belongs to' type has to be mapped as String field. This field will contain identifier of related object. So you can write:

// ------- create new order with positions
Order order = new Order();
// fill order fields
using(var transaction = Mobeelizer.GetDatabase().BeginTransaction())
{
	transaction.GetModelSet<Order>().InsertOnSubmit(order);
	transaction.SubmitChanges();
}
OrderPosition position = new OrderPosition();
// fill position fields
position.order = order.Guid;
using(var transaction = Mobeelizer.GetDatabase().BeginTransaction())
{
	transaction.GetModelSet<OrderPosition>().InsertOnSubmit(position);
	transaction.SubmitChanges();
}
// ------- get order of position:
var positionQuery = from p in transaction.GetModelSet<OrderPosition>() where p.Guid == "positionIdentifier" select p;
OrderPosition position = positionQuery.Single();
var orderQuery = from o in transaction.GetModelSet<Order>() where o.Guid == position.Guid select o;
Order order = orderQuery.Single();

Files

All binary data are wrapped inside IMobeelizerFile object but as you read before file type has to be mapped to String. These is because linq to sql does'nt supports own type mapping. To get access to file stored in entity you need to use protected methods GetFile and SetFile. 

Lets assume that you have OrderWithAttachment object. And it have attachment field of file type. Then you can access content of file by coding:

var query = from o in transaction.GetModelSet<OrderWithAttachment>() where o.Guid == "orderIdentifier" select o;
OrderWithAttachment order = query.Single();
String jsonFileEntity = order.Attachment;
/*
	AttachmentFile is a property which use protected method GetFile(String file)
	public IMobeelizerFile AttachmentFile { get { return base.GetFile(this.Attachment); } }
*/
IMobeelizerFile attachment = order.AttachmentFile; 
String attachmentIdentifier = attachment.Guid;
String attachmentName = attachment.Name;
Stream = attachment.GetStream();

To create new IMobeelizerFile instance you can:

// ------- create new file...
Stream contentStream = // get file content
IMobeelizerFile newAttachment = Mobeelizer.CreateFile("newAttachmentName", contentStream);
// ------- ...or use existing one
IMobeelizerFile newAttachment = Mobeelizer.CreateFile("newAttachmentName", "existingAtachmentGuid");

Remember about changing order file field:

OrderWithAttachment order = // get object from database or create new one
/*
	Setter of AttachmentFile property have to look like this:
	set { this.Attachment = base.SetFile(value); }
*/
order.AttachmentFile = newAttachment;
transaction.GetModelSet<OrderWithAttachment>.InsertOnSubmit(order);
transaction.SubmitChanges();

Synchronize data

Synchronizing data with cloud cannot be easier! Just call one of sync methods on Mobeelizer object.

Normal synchronization

To perform data synchronization call sync method.

Synchronization process can take long time, so if you want to block application on this time - better supply user with nice-looking loading indicator.

Full synchronization

Full synchronization is a process which removes all data and downloads all data from cloud. It is triggered automatically when user logs in for the first time - but you can call it manually. Just call syncAll method.

You should block all user actions for this process (database will be erased).

In full synchronization process user-modified data is not send to cloud, so all not synchronized data (with modified flag) will be lost! To prevent this perform normal synchronization before.

Broadcast notifications

You can register listener for all notifications about sync status changes. To do it create recive method and subscribe it for SyncStatusChanged event:

Mobeelizer.SyncStatusChanged += new MobeelizerSyncStatusChangedEventHandler(ReciveSyncStatusChanged);

Recive method:

private void ReciveSyncStatusChanged(MobeelizerSyncStatus status)
{
	// your reaction for sytatus change.
}

See MobeelizerSyncStatus documentation for more information about available statuses.

Push notifications

To learn about Push notification see Push notifications key concept page.

Push notifications on Windows Phone 7 devices are provided by Microsoft Push Notification Service. Basic knowledge of it's mechanisms are necessary to understand following reference documentation.

Configuring application

  • Configure application in App Designer

In App Designer in 'Create' mode click "Push notifications" button on the left. There you can enable or disable push notifications.

Registering to receive push notifications

If you want WP7 device to be able to receive push notifications you must follow instructions from Receiving Push Notifications for Windows Phone

HttpNotificationChannel pushChannel = new HttpNotificationChannel("your channel name");

Also you have to send channel uri to Mobeelizer server by calling method:

Mobeelizer.RegisterForRemoteNotifications(channelUri);

To unregister your application from receiving push navigation just call:

Mobeelizer.UnregisterForRemoteNotifications();

Sending push notification

To send Push notification call one of methods on Mobeelizer object:

As you can read here there are three types of notifications: Toast, Tile and Raw. As a developer you have to decide which type of notification you want to use in your app. For each one there are a few predefinied key value pairs that you have to add to your notification dictionary. 

  • Toast notification

 

KeyRequiredValue
X-NotificationClassYES

The batching interval that indicates when the push notification will be sent to the application from the Push Notification Service. 

  • 2 - Immediate delivery.
  • 12 - Delivered within 450 seconds.
  • 22 - Delivered within 900 seconds.
X-WindowsPhone-TargetYES"toast"
Text1NOToast title.
Text2NOToast message.
ParamNOPath of the page to be opened when user click toast prompt.
Text1 and Text2 are not required but always one of them have to be specified.

 

  • Tile notification

 

KeyRequiredValue
X-NotificationClassYES

The batching interval that indicates when the push notification will be sent to the application from the Push Notification Service. 

  • 1 - Immediate delivery.
  • 11 - Delivered within 450 seconds.
  • 21 - Delivered within 900 seconds.
X-WindowsPhone-TargetYES"token"
TitleNOFront tile title.
CountNOTile count.
BackTitleNOBack tile title.
BackgroundImageNOPath to bacground image.
BackContentNOBack tile message.
BackBackgroundImageNOPath to back background image.
There are a few not required values but remember, always one of them have to be specified.

 

  • Raw notification
KeyRequiredValue
X-NotificationClassYES

The batching interval that indicates when the push notification will be sent to the application from the Push Notification Service. 

  • 3 - Immediate delivery.
  • 13 - Delivered within 450 seconds.
  • 23 - Delivered within 900 seconds.