Working with Telerik Platform Data

Working with Telerik Platform Data

The Backend Services .NET SDK makes it easier for you to work with the Telerik Platform document based JSON data in .NET Framework's strongly types languages.

Most .NET developers will prefer to define a class for each Telerik Platform content type that they want to use in an app. Once you have the definitions, the Backend Services .NET SDK will take care of calling the Backend Services RESTful API and translating the data to/from instances of your classes.

While having a class for each content type is the most common approach, the SDK allows you to also consume data in a more dynamic, Dictionary-like manner. You can even opt for a hybrid approach where you define some of the content type items in a class while accessing the others dynamically.

Defining a Data Class

A data class is a class that represent a single record from a content type. For example, if you have a content type named Books, you will need a data class to represent a single book in your .NET application.

Most data classes would inherit the DataItem class. It gives you the following features:

  • Working with Telerik Platform system fields
  • Updating items only by setting properties
  • Accessing dynamic properties

An exception are data classes for content types representing data from Data Connectors.

Alternatively, you could implement the IDataItem interface. Although you get the same functionality, it is recommended to always extend DataItem, unless your object model does not allow for that.

The next snippet shows what the class for the sample content type Book could look like if it extends DataItem.

public class Book : DataItem
{
    private string title;
    public string Title
    {
        get
        {
            return this.title;
        }
        set
        {
            this.title = value;
            this.OnPropertyChanged("Title");
        }
    }
    private string author;
    public string Author
    {
        get
        {
            return this.author;
        }
        set
        {
            this.author = value;
            this.OnPropertyChanged("Author");
        }
    }
    private DateTime publicationDate;
    public DateTime PublicationDate
    {
        get
        {
            return this.publicationDate;
        }
        set
        {
            this.publicationDate = value;
            this.OnPropertyChanged("PublicationDate");
        }
    }
}

Hiding Properties from the Server

By default, all public properties that you add to the class will end up on the server as content type item fields if set. This happens even if the name of the property is not defined in your Telerik Platform data model.

This is why the Backend Services .NET SDK allows you to mark properties with the ServerIgnore attribute. It means that the property is a helper property which does not need to go to the server. The SDK ignores such properties when creating or updating data on the server.

public class Book : DataItem
{
    [ServerIgnore]
    public string ClientOnlyProperty
    {
        get
        {
            return "some custom logic here";
        }
    }
}

Controlling Read-Write Property Attributes

Ignoring a property is helpful but you may want to be even more granular when defining the relationship of a property with its server counterpart. The ServerProperty attribute allows you to set the following settings:

Value Type Description
WriteToServer bool Indicated whether the entitled property will be stored on the server or not. Useful in cases where you have a value calculated client-side that must not be stored on the server.
ReadFromServer bool Indicates whether the entitled property will be read from the server or not. Useful when you store sensitive information like passwords that you don't want reaching the client.
public class Book : DataItem
{
    [ServerProperty(ReadFromServer = true, WriteToServer = false)]
    public string ClientOnlyProperty
    {
        get
        {
            return "some custom logic here";
        }
    }
}

Using Different Names on the Client and the Server

Another popular scenario is when you want the names that you use in .NET to differ from the server names. The Backend Services .NET SDK allows you to map:

  • Properties to their matching server field using the ServerProperty attribute
  • Class names to their matching sever content types using the ServerType attribute

This is how to use the ServerProperty attribute:

public class Book : DataItem
{
    [ServerProperty("publication_date")]
    public DateTime PublicationDate
    {
        get
        {
            return this.publicationDate;
        }
        set
        {
            this.publicationDate = value;
            this.OnPropertyChanged();
        }
    }
}

This is what the ServerProperty will look like when you add the ReadFromServer and WriteToServer values:

[ServerProperty(ServerPropertyName = "PublicationDate", ReadFromServer = false, WriteToServer = true)]
public Date PublicationDate
{ 
    get; set;
};

The next code snippet shows how to use the ServerType attribute. Normally, if you want a type to store information about books for example, you will name it Books in Telerik Platform. However, it makes more sense to name your .NET class Book because it represents a single book record.

[ServerType("Books")] 
public class Book : DataItem
{
    ...
}

Defining a Data Class for Data Connectors Content Types

The workflow for consuming data from Data Connectors is generally the same except for an important difference: You must extend ExternalDataItem instead of DataItem when creating entity classes.

    public class MyExternalType : ExternalDataItem
    {
        public string MyExternalProperty { get; set; }
    }

The ExternalDataItem class contains a ServerId property of type object while the Id of the DataItem class is always a Guid. For convenience, you can define your own ID property because you will most likely know the actual type of the ID field. If you go this way, include the ServerIgnore attribute with the property to prevent it from overriding the value of the ServerId property.

Creating an Access Point to a Content Type

After defining a class for each content type that you want to use, you need to create an access point to it.

The flow, which is valid for both user-defined and system content types, is as follows:

​1. Obtain an instance of the EverliveApp class. Either create it or use a singleton instance. More information about instantiating EverliveApp can be found in Getting Started with the Backend Services .NET SDK. In the following code snippets, the EverliveApp instance is named app. ​2. Using the EverliveApp object, obtain an access point to a single content type. Note how you must specify the .NET type that corresponds to your Telerik Platform content type.

var booksManager = app.WorkWith().Data<Book>();

​3. Use the obtained access point to read, create, update, or delete items. The following example reads all items in the Book content type.

var allBooks = await booksManager.GetAll().ExecuteAsync();

Working with Dynamic Data

The nature of the schema-less data storage provided by Telerik Platform means that new fields can be added any time to a content type document (or item).

To accommodate this sort of dynamic data, the SDK provides the Item class. It can work with any Telerik Platform content type, allowing you to access its data dynamically in a Dictionary-like manner.

You can opt to not define classes for your content types at all and use the Item class, or choose a hybrid approach. With it, you define some of the content type items in a class while accessing the others dynamically.

The next example shows how to work with the Books content type in a entirely dynamic way. Because this approach means not instantiating DataItem, you need to pass the content type's name as a string.

var contentTypeName = "Books";

// requestResult is of type IEnumerable<Item>
IEnumerable<Item> allBooks =  await app.WorkWith().Data(contentTypeName).GetAll().ExecuteAsync();

// fields of Item can be accessed as a dictionary
foreach (var item in allBooks )
{
    Console.WriteLine(item["ISBN"]); // dynamic property
}

Many times you want to work with typed data for convenience, but still need to handle dynamic data such as custom user fields. The next examples shows how to access dynamic data using this hybrid approach.


var allBooks = await app.WorkWith().Data<Book>().GetAll().ExecuteAsync();

foreach (var item in allBooks )
{
    Console.WriteLine(item.Author); // property of the DataItem class
    Console.WriteLine(item["ISBN"]); // dynamic property
}

How Telerik Platform Types Map to .NET Types

When creating your data classes, it is important to know what .NET type to use for each property so it is properly serialized. The following table lists the type mappings.

Telerik Platform Type .NET Property Type
Id Guid
Text string
Number int, double, Enum
Date and Time DateTime
Yes / No bool
File Guid
Geo Point Telerik.Everlive.Sdk.Core.Model.System.GeoPoint()
Object Newtonsoft.Json.Linq.JToken
Relation Guid
Relation—multiple IEnumerable<Guid>()
Array IEnumerable<T>()

Raw Request Processing

When you call EverliveApp object methods, internally the SDK translates them to HTTP requests to Telerik Platform. It then processes the response and returns it to the calling method. All processing and serialization/deserialization is transparent to the SDK consumer.

However, if you want to alter the request before it is sent or to process the raw response, you can still do so. The EverliveApp class defines a pair of events designed especially with that in mind: BeforeRequest and BeforeResponse. The following snippet shows how you subscribe to them.

private void Initialize()
{
    EverliveApp app = new EverliveApp("your-app-id");
    app.BeforeRequest += app_BeforeRequest;
    app.BeforeResponse += app_BeforeResponse;
}

void app_BeforeRequest(object sender, RequestEventArgs e)
{
    var request = e.Request;
    //Custom request processing here
}

void app_BeforeResponse(object sender, ResponseEventArgs e) {
    var request = e.Request;
    var response = e.Response;
    //Custom response processing here
}

See Also

Start a free trial Request a demo
Contact us: +1-888-365-2779
sales@telerik.com
Copyright © 2016-2017, Progress Software Corporation and/or its subsidiaries or affiliates. All rights reserved.