Generic Collections

When querying the Facebook API for data with multiple values of the same type, it returns as an object that contains an array of the results and some metadata, along with a cursor indicating the next and previous results set (if any exists).

The FacebookCollection<T> abstracts the management of the results as an enumerable collection that you could use with a POCO class (using a mapper), and manages the state of the collection, allowing you to load additional items into the collection from the Facebook API and retrieve the next or previous set of items available as new collection sets.

The APIs already implemented in this library make use of that generic collection and abstract it as a new already typed collection for ease of use. In the case this library does not cover the collection you need, you can use this class to represent and manage collections easily.

The FacebookCollection Class

Then creating a new collection you would need to specify the type of the objects in the collection:

FacebookCollection<MyObject> results = new FacebookCollection<MyObject>(/*arguments*/);

To manually create a FacebookCollection let's have a look at the constructor and what you would need to pass to it in order to create a collection that will retrieve the items from Facebook API and populate:

FacebookCollection(FacebookClient client, string query, string token, Func<JToken, T> mapper, FacebookCursor cursor = null)

Parameter	Description
client	All the communication with the Facebook API is done via this simple class which abstracts the calls to the API. The FacebookCollection is no different and uses the FacebookClient to retrieve data.
query	Since were discussing here the creating of the a custom collection (and not using the existing ones in the API) you would need to supply the query for the Facebook API as described in the Facebook documentation.
token	Authorization token to make the request (if needed). The token is required when requesting data from APIs such as user information or app information. Not all APIs require a token - some information is available publicly. Consult the Facebook documentation for more information.
mapper	Your function which will be responsible parsing the information gotten back from the Facebook API into an object of your type T.
cursor	The first call does not require this object, but if you wish to navigate between results pages you would need to supply the cursor. The cursor is managed for you as part of the collection and you can find a Cursor property with the object once the collection is populated.

Abstracting a collection

Collections already part of this API (such as PlacesCollection) are abstracted for easier use. To create an abstract collection, first inherit from the FacebookCollection class:

public class CustomCollection : FacebookCollection<MyObject>

Overwrite the BeforeAsync and AfterAsync so the objects returned are cast back to your own collection object (making working with it much nicer):

public new async Task<PlacesCollection> BeforeAsync()
{
    FacebookCollection<MyObject> collection = await base.BeforeAsync();
    return (CustomCollection)collection;
}

public new async Task<PlacesCollection> AfterAsync()
{
    FacebookCollection<MyObject> collection = await base.AfterAsync();
    return (CustomCollection)collection;
}

Write your own mapper - A mapper maps the result returned by the Facebook API to your own object type:

private static MyObject MyObjectMapper(JToken data)
{
    MyObject result = new MyObject();
    /* Mapping magic here */
    return result;
}

A complete collection could be found here.