Facebook

Developer Toolkit
Developed for Microsoft By Clarity Consulting Inc. -
www.claritycon.com
 Table Of Contents
Leveraging the Facebook API in 5 minutes.................................................................4
Desktop Development............................................................................. ................4
Web Development............................................................................... ....................7
Pre-requisites................................................................................................... .........12
Introduction...................................................................................... ........................12
Overview.................................................................................. ................................13
Facebook API Overview......................................................................................... .13
Using the FacebookService to Access the API........................................................13
Infinite Sessions.................................................................................................13
Facebook Desktop Development...........................................................................13
Facebook Web Development.................................................................................14
Using LINQ................................................................................................... ..........15
Detailed Class Design ................................................................................ ..............16
Facebook.Components..........................................................................................16
FacebookService Class.......................................................................................16
Facebook Data Objects..........................................................................................32
Album Class..................................................................................................... ...32
Photo Class.................................................................................................. .......34
FacebookEvent Class..........................................................................................35
Group Class................................................................................... .....................38
GroupUser Class.................................................................................. ...............40
User Class..........................................................................................................41
SchoolHistory Class............................................................................................45
HighSchool Class............................................................................... .................45
HigherEducation Class...................................................................................... ..46
Network Class................................................................................................... .46
Location Class...................................................................................................47
Work Class.................................................................................................. .......48
Code Snippets.......................................................................................................... .49
Windows Form: Application Setup.........................................................................49
Windows Form: Retrieving Friends.........................................................................49
Windows Form: Utilizing the FriendList Control......................................................49
Windows Form: Hooking a FriendList Control to a Profile Control..........................50
Web Application: Authentication Process...............................................................51
Leveraging the Facebook API in 5 minutes
Desktop Development
• Satisfy Pre-requisites described below

• Start a new Windows application project

o File – New – Project

o Windows Application

Visual C#

Visual Basic
• Add the FacebookService component from the toolbox to the Form’s
component tray

• Provide the API Key and Secret values

• Drag a FriendList from the toolbox onto the design surface for the form

• Hook up the form Load Event

o Find Load in the Event list in the property window, type Form_Load.
Press Enter.

• In the generated Form_Load method, set the Friends property of the

FriendList control to the Collection returned by calling the GetFriends method
of the FacebookService. As shown here:

Visual C#
private void Form_Load(object sender, EventArgs e)
{
friendList1.Friends = FacebookService1.GetFriends();
}
Visual Basic

Private Overloads Sub OnLoad()

friendList1.Friends = FacebookService1.GetFriends()
End Sub
• Press F5 to run the application
Web Development
• Satisfy Pre-requisites described below

• In Visual Web Developer 2005 Express edition

o File – New – Web Site

Visual C#

Visual Basic
• Switch to Design View of Default.aspx
• On Default.aspx, drag a friendlist from the toolbox

• Add the following code to the Default.aspx

• Configure the API key and secret

Visual C#
public partial class _Default : Page
{
 Facebook.Components.FacebookService _fbService = new
Facebook.Components.FacebookService();

protected void Page_Load(object sender, EventArgs e)

{

// ApplicationKey and Secret are acquired when you sign up for

_fbService.ApplicationKey = "YOURKEYHERE";
_fbService.Secret = "YOURSECRETHERE";

Visual Basic
Public Partial Class _Default
Inherits Page
Private _fbService As Facebook.Components.FacebookService = New
Facebook.Components.FacebookService()

Protected Sub Page_Load(ByVal sender As Object, ByVal e As EventArgs)

' ApplicationKey and Secret are acquired when you sign up for
_fbService.ApplicationKey = "YOURKEYHERE"
_fbService.Secret = "YOURSECRETHERE"
• Set the IsDesktopApplication property of the FacebookService component

Visual C#
_fbService.IsDesktopApplication = false;

Visual Basic
_fbService.IsDesktopApplication = False

• Check if we have already stored the Facebook session information or if the

auth_token is in the query params. We will store what we know about the
current user’s Facebook Session in a server side variable. We will then check
that variable to see if we already have established a Facebook session on
behalf of the current user.

Visual C#

string sessionKey = Session["Facebook_session_key"] as String;

string userId = Session["Facebook_userId"] as String;

// When the user uses the Facebook login page, the redirect back here
will will have the auth_token in the query params
string authToken = Request.QueryString["auth_token"];

Visual Basic
Dim sessionKey As String =
TryCast(Session("Facebook_session_key"), String)
Dim userId As String = TryCast(Session("Facebook_userId"), String)

' When the user uses the Facebook login page, the redirect back
here will will have the auth_token in the query params
 Dim authToken As String = Request.QueryString("auth_token")

• If we have an established session, set it into our instance of the service

Visual C#
if (!String.IsNullOrEmpty(sessionKey))
{
_fbService.SessionKey = sessionKey;
_fbService.UserId = userId;
}

Visual Basic

' We have already established a session on behalf of this user

If (Not String.IsNullOrEmpty(sessionKey)) Then
_fbService.SessionKey = sessionKey
_fbService.UserId = userId

• If not, check if we have the auth_token in the query params. If we do, it

means we just got called from the Facebook login page.

Visual C#
else if (!String.IsNullOrEmpty(authToken))
{
_fbService.CreateSession(authToken);
Session["Facebook_session_key"] = _fbService.SessionKey;
Session["Facebook_userId"] = _fbService.UserId;
Session["Facebook_session_expires"] = _fbService.SessionExpires;
}

Visual Basic
' This will be executed when Facebook login redirects to our page
ElseIf (Not String.IsNullOrEmpty(authToken)) Then
_fbService.CreateSession(authToken)
Session("Facebook_session_key") = _fbService.SessionKey
Session("Facebook_userId") = _fbService.UserId
Session("Facebook_session_expires") =
_fbService.SessionExpires

• If neither, we need to redirect the user to the Facebook hosted login page

Visual C#
else
{
Response.Redirect(@"http://www.Facebook.com/login.php?api_key=" +
_fbService.ApplicationKey + @"&v=1.0");
}

Visual Basic
Else
 Response.Redirect("http://www.Facebook.com/login.php?api_key=" &
_fbService.ApplicationKey & "&v=1.0")
End If

• Set the friends property of the friendlist

Visual C#
if (!IsPostBack)
{
// Use the FacebookService Component to populate Friends
MyFriendList.Friends = _fbService.GetFriends();
}

Visual Basic
If (Not IsPostBack) Then
' Use the FacebookService Component to populate Friends
MyFriendList.Friends = _fbService.GetFriends()
End If

Pre-requisites
First, you download one of the Visual Studio Express products . To develop a
desktop application, you can use Visual C# 2005 Express Edition (or later) or Visual
Basic 2005 Express Edition (or later). If you want to build a web application, you
can use Visual Web Developer 2005 Express Edition (or later).

Next, in order to use the Facebook API, you must first register for a developer
account with Facebook at http://developers.Facebook.com/account.php. You will
need to specify whether your application is a Website or a Desktop application.
After registering for your developer account, you will receive and API key and secret.
These are critical for using the Facebook API and you should keep this readily
available

Introduction
This document outlines the components and controls that are available for to help
simplify development against the Facebook API. The main component is the
FacebookService component. The FacebookService wraps the Facebook API and
provides an easy to use interface for calling the different methods currently
available in the 1.0 version of the Facebook API. In addition, some Windows and
web controls were installed which will provide a quick way to start leveraging the
Facebook data in your application. We’ve also provided you with some cool fun
samples. These can be found in <INSERT DIRECTORY HERE>. Additionally, we’ve
provide all the source code for the API, components, controls and samples for you to
explore.
Overview
All of the sections below assume that the developer has signed up for a Facebook
developer account and received an API key and secret from Facebook.

Facebook API Overview

The Facebook API is a REST interface allowing applications to post a specific
HTTP address and receive structured XML representing the requested Facebook
data. The 1.0 version of the API contains primarily Get operations, and does not
provide personal or contact information for Facebook users. The only Set type
operations that are available are CreateAlbum, UploadPhoto and AddTag.

For more information on the available functions, see the API documentation at
http://developers.Facebook.com/documentation.php?v=1.0

Using the FacebookService to Access the API

The Facebook.dll that was installed at %Program
Files%\Coding4Fun\Facebook\Binaries contains the FacebookService component.
This component contains all the methods that wrap the available API calls. To
use this component, each application must programmatically set their
application key and secret. For specifics on interacting with the
FacebookService see the Desktop and Web Development below. The methods
within the FacebookService return strongly typed data objects representing the
data. These objects are intended to simplify the developer experience using the
API.

Infinite Sessions
The Facebook API supports Infinite Sessions. What this means is that users of
custom developed Facebook desktop applications have the ability to save their
credentials and not be required to login to the application on subsequent uses.
In order for an application to take advantage of infinite sessions, the application
should check SessionExpires property of the Facebook Service after a Session is
initiated. If this property is false, the application can store the userId and
SessionKey that are associated with the user and set them on the
FacebookService whenever this user returns.

Facebook Desktop Development

To start utilizing the Facebook API, you will need to add the FacebookService
component to your project. To do this just drag an instance of FacebookService
from the toolbox onto the component tray and enter your API Key and Secret.
 The FacebookService component contains methods that wrap all of the methods
of the Facebook API. The following provides an example for getting all the
friends of the logged in user. This method returns a generic collection of User
objects. The User object is a strongly typed representation of a Facebook User
profile.

Visual C#

using System.Collections.Generic;
using System.Collections.ObjectModel;
…
Collection<User> friends = FacebookService1.GetFriends();

Visual Basic

Imports System.Collections.Generic
Imports System.Collections.ObjectModel
…
Dim friends As Collection(Of User) = FacebookService1.GetFriends()

Facebook Web Development

The authentication process for a Web Application is more involved than for a
Windows application. When the developer account is setup, the developer must
choose whether their application is a Web application or Desktop application. In the
case of a web application, the developer must specify a return url. This is the url
that users of the web application will be redirected to after logging in on the
Facebook hosted login page. For the sample web site, it is setup to return to
http://localhost/FacebookWebSample/default.aspx. To run and debug the
FacebookWebSample project, you must configure your Visual Studio Web Project to
start your web application using this address. Because of this requirement, the
simplest way to configure to run the WebSample is using IIS. (Since it runs on port
80 and handles addresses like the above)

1. Create an IIS Virtual Directory called FacebookWebSample pointed at the

location of your FacebookWebSample.
 2. Set the Web Project to start using this website.

a. Right Click FacebookWebSample in Visual Studio – Select Property

Pages

b. Select Start Options

c. Click Start URL radio button – Enter

http://localhost/FacebookWebSample/default.aspx

3. Write code to handle 3 states.

a. If we don’t have an auth_token, redirect to the Facebook hosted login

page.

b. If we have an auth_token, start a session on behalf of the user.

c. Store the user’s session information for making calls to the Facebook
service.

See the Code Snippets section for more details.

Using LINQ
The toolkit contains some sample code showing (both a web application and
Windows application version) how LINQ and Orcas can be used to provide a richer
set of development features against the Facebook API data. The samples included
will only work in “Orcas” (the codename for the next version of Visual Studio) and
show how we can right code using a syntax similar to SQL to filter and search
through the friends that are returned from Facebook. The samples leverage LINQ
over XML and run the filtering directly against the returned XML. Alternatively, the
LINQ code could just as easily have been written against the Generic Collections
returned by the our toolkit. For more information on LINQ, check out
http://msdn2.microsoft.com/en-us/netframework/aa904594.aspx. If you want to
download Orcas and try out LINQ and the enclosed samples, you can do so here,
http://msdn.microsoft.com/vstudio/express/future.

The source for these samples is installed to C:\Program

Files\Coding4Fun\Facebook\LINQ Samples

Detailed Class Design

Facebook.Components
FacebookService Class
This class contains methods that wrap the Facebook API and return
strongly typed objects representing Facebook data. Additionally, this class
has functionality to encapsulate the Facebook login process for both
Microsoft Windows-based clients and ASP.NET web based clients.
 Figure 1: FacebookService Class

1.1.1.1Property: ApplicationKey
This property is required to be set by all consuming applications. This
property should be set to the API key acquired from Facebook when
developer signed up for a Facebook developer account.

Definition: public string ApplicationKey

1.1.1.2Property: IsDesktopApplication
This property is an indicator used to determine if the consuming
application is a desktop (Windows) or web based application. This is
needed because the application secret is handled differently for
Windows and web applications.

Definition: public bool IsDesktopApplication

1.1.1.3Property: Secret
This property is required to be set by all consuming applications. This is
the secret used to encrypt parameters passed to the Facebook API. For
web applications, the secret is constant and set at the beginning of
interaction with the service. For Windows applications, an initial secret
is required to establish a session, but a new secret is acquired that
coincides with each session.

Definition: public string Secret

1.1.1.4Property: SessionExpires
This property is an indicator of whether the current session is an infinite
session or not. The value is determined after a user of the consuming
application logs in on the Facebook hosted web page. Consuming
applications can leverage an infinite session by storing the session
information locally and by passing the logon process in subsequent
interactions with the user.

Definition: public bool SessionExpires

1.1.1.5Property: SessionKey
This property stores the session key for the current user session. This
can either be set by the consuming application (which would typically be
done when the consuming application recognizes a user that has an
infinite session established) or will be set by the FacebookService after
the logon process is complete

Definition: public string SessionKey

1.1.1.6Property: UserId
This property is stored the Facebook userid. Similar to the SessionKey,
in the case of infinite sessions the comsuming application will set this
property with the known UserId, otherwise this property will be set by
the logon process.

Definition: public string ApplicationKey

1.1.1.7Method: AddTag
This method wraps the Facebook API method photos.addTag. This
method is used to add tags to any “pending” photos. A pending photo is
a photo that has been uploaded but not yet confirmed.

Definition: public void AddTag(string photoId, string tagText, string

tagUserId, int xCoord, int yCoord)

Parameters:

Parameter Description
The Facebook identifier of the pending photo to be
photoId
tagged
The message that should be associated with the tag. Use
tagText
this OR tag User Id. Not both.
tagUserId The Facebook userid of the person the tag points to
The X coord (in pixels) where the tag should begin in the
xCoord
specified picture
The Y coord (in pixels) where the tag should begin in the
yCoord
specified picture

Return Type: N/A

Exceptions:

 FacebookException: This base class of all exceptions. If

exception could not be classified, FacebookException will be
used.
 FacebookInvalidUserException: The user that the call was made
on behalf of is not valid.
 FacebookRequestLimitException: Indicates that the consuming
application has made too many Facebook API calls in short
period of time.
 FacebookServiceUnavailableException: Indicates that the
website used to host the Facebook REST client was not available.
 FacebookSigningException: Indicates that the secret or API key
were not specified or were invalid.
 FacebookTimeoutException: Indicates that the Facebook API did
not respond in a within the timeout threshhold

1.1.1.8Method: AreFriends
This method wraps the Facebook API method friends.areFriends. This
method is used to determine if two Facebook users are friends or not.
 Definition (1): public bool AreFriends(string userId1, string userId2)

Definition (2): public bool AreFriends(User user1, User user2)

Parameters (1):

Parameter Description
userId1 The Facebook identifier of the first user
userId2 The Facebook identifier of the second user

Parameters (2):

Parameter Description
The a strongly typed instance of a User representing the
user1
first Facebook user
The a strongly typed instance of a User representing the
user2
second Facebook user

Return Type: bool: true if 2 users are currently Facebook friends,

otherwise false.

Exceptions:

 FacebookException: This base class of all exceptions. If

exception could not be classified, FacebookException will be
used.
 FacebookInvalidUserException: The user that the call was made
on behalf of is not valid.
 FacebookRequestLimitException: Indicates that the consuming
application has made too many Facebook API calls in short
period of time.
 FacebookServiceUnavailableException: Indicates that the
website used to host the Facebook REST client was not available.
 FacebookSigningException: Indicates that the secret or API key
were not specified or were invalid.
 FacebookTimeoutException: Indicates that the Facebook API did
not respond in a within the timeout threshold

1.1.1.9Method: ConnectToFacebook
This method is not typically used by the consuming application. The
FacebookService will check if there is a valid session that it can use to
make API calls, if not it will invoke the ConnectToFacebook method. This
 method is only needed by desktop applications and uses a hosted web
browser to allow the user to login to the Facebook hosted login page.

Definition: public void ConnectToFacebook()

Parameters:

Parameter Description
None None

Return Type: N/A

Exceptions:

 FacebookException: This base class of all exceptions. If

exception could not be classified, FacebookException will be
used.
 FacebookInvalidUserException: The user that the call was made
on behalf of is not valid.
 FacebookRequestLimitException: Indicates that the consuming
application has made too many Facebook API calls in short
period of time.
 FacebookServiceUnavailableException: Indicates that the
website used to host the Facebook REST client was not available.
 FacebookSigningException: Indicates that the secret or API key
were not specified or were invalid.
 FacebookTimeoutException: Indicates that the Facebook API did
not respond in a within the timeout threshold

1.1.1.10Method: CreateSession
This method has a public version and a private version. The private
version is used for Windows applications and is called from
ConnectToFacebook. The public version takes in an auth token and is
used by web based applications. Web based applications get the auth
token as a url parameter after the user logins on the Facebook hosted
webpage. The web application then needs to start the session using this
method and passing in the auth token.

Definition (1): private void CreateSession()

Definition (2): public void CreateSession(string authToken)

Parameters (1):

Parameter Description
none None
 Parameters (2):

Parameter Description
The authentication token returned to the web application
authToken
from the Facebook login page.

Return Type: N/A

Exceptions:

 FacebookException: This base class of all exceptions. If

exception could not be classified, FacebookException will be
used.
 FacebookInvalidUserException: The user that the call was made
on behalf of is not valid.
 FacebookRequestLimitException: Indicates that the consuming
application has made too many Facebook API calls in short
period of time.
 FacebookServiceUnavailableException: Indicates that the
website used to host the Facebook REST client was not available.
 FacebookSigningException: Indicates that the secret or API key
were not specified or were invalid.
 FacebookTimeoutException: Indicates that the Facebook API did
not respond in a within the timeout threshold

1.1.1.11Method: GetEventMembers
This method wraps the Facebook API method events.getMembers. This
method is used to return all the users that have been invited to an event
and their current rsvp status.

Definition: public Collection<EventUser> GetEventMembers(string

eventId)

Parameters:

Parameter Description
eventId The Facebook identifier of the event

Return Type: Collection<EventUser>: A collection of EventUser.

EventUser is a simple wrapper to the User class that adds
RSVP status.

Exceptions:
  FacebookException: This base class of all exceptions. If
exception could not be classified, FacebookException will be
used.
 FacebookInvalidUserException: The user that the call was made
on behalf of is not valid.
 FacebookRequestLimitException: Indicates that the consuming
application has made too many Facebook API calls in short
period of time.
 FacebookServiceUnavailableException: Indicates that the
website used to host the Facebook REST client was not available.
 FacebookSigningException: Indicates that the secret or API key
were not specified or were invalid.
 FacebookTimeoutException: Indicates that the Facebook API did
not respond in a within the timeout threshold

1.1.1.12Method: GetEvents
This method wraps the Facebook API method events.get. This method is
used to retrieve event information. There are overrides supporting get
by event id, user id and date.

Definition (1): public Collection<FacebookEvent> GetEvents()

Definition (2): public Collection<FacebookEvent> GetEvents(string

userId)

Definition (3): public Collection<FacebookEvent>

GetEvents(Collection<string> eventList)

Definition (4): public Collection<FacebookEvent>

GetEvents(Collection<string> eventList, string userId)

Definition (5): public Collection<FacebookEvent>

GetEvents(Collection<string> eventList, string userId, DateTime?
startDate, DateTime? endDate)

Parameters (1):

Parameter Description
None Get Events that the logged in user is invited to
Parameters (2):

Parameter Description
The Facebook userId that events are retrieved for. Will
userId
return all events this person is invited to.
Parameters (3):

Parameter Description
 A collection of eventIds. Will return the event information
eventList
for each event matching an event id passed in.
Parameters (4):

Parameter Description
The Facebook userId that events are retrieved for. Will
userId return events this person is invited to that are also
specified in the eventList.
A collection of eventIds. Will return the event information
eventList for each event matching an event id passed in that has
the specified UserId invited.
Parameters (5):

Parameter Description
The Facebook userId that events are retrieved for. Will
userId return events this person is invited to that are also
specified in the eventList.
A collection of eventIds. Will return the event information
eventList for each event matching an event id passed in that has
the specified UserId invited.
Only retrieve events matching the above criteria and
startDate
starting after this date.
Only retrieve events matching the above criteria and
endDate
ending before this date.

Return Type: Collection<FacebookEvent>

Exceptions:

 FacebookException: This base class of all exceptions. If

exception could not be classified, FacebookException will be
used.
 FacebookInvalidUserException: The user that the call was made
on behalf of is not valid.
 FacebookRequestLimitException: Indicates that the consuming
application has made too many Facebook API calls in short
period of time.
 FacebookServiceUnavailableException: Indicates that the
website used to host the Facebook REST client was not available.
 FacebookSigningException: Indicates that the secret or API key
were not specified or were invalid.
 FacebookTimeoutException: Indicates that the Facebook API did
not respond in a within the timeout threshold
 1.1.1.13Method: GetFriends
This method wraps the Facebook API method friends.get. This method is
used to get all the friends of the logged in user.

Definition: public Collection<User> GetFriends()

Parameters:

Parameter Description
none Get friends of the logged in user

Return Type: Collection<User>: A collection of populated user objects

representing each of the logged in user’s friends.

Exceptions:

 FacebookException: This base class of all exceptions. If

exception could not be classified, FacebookException will be
used.
 FacebookInvalidUserException: The user that the call was made
on behalf of is not valid.
 FacebookRequestLimitException: Indicates that the consuming
application has made too many Facebook API calls in short
period of time.
 FacebookServiceUnavailableException: Indicates that the
website used to host the Facebook REST client was not available.
 FacebookSigningException: Indicates that the secret or API key
were not specified or were invalid.
 FacebookTimeoutException: Indicates that the Facebook API did
not respond in a within the timeout threshold

1.1.1.14Method: GetFriendsAppUsers
This method wraps the Facebook API method friends.getAppUsers. This
method is used to get all the friends of the logged in user that are also
users of this consuming application.

Definition: public Collection<User> GetFriendsAppUsers()

Parameters:

Parameter Description
Get friends of the logged in user that are users of this
none
application
 Return Type: Collection<User>: A collection of populated user objects
representing each of the logged in user’s friends that are
also users of this application.

Exceptions:

 FacebookException: This base class of all exceptions. If

exception could not be classified, FacebookException will be
used.
 FacebookInvalidUserException: The user that the call was made
on behalf of is not valid.
 FacebookRequestLimitException: Indicates that the consuming
application has made too many Facebook API calls in short
period of time.
 FacebookServiceUnavailableException: Indicates that the
website used to host the Facebook REST client was not available.
 FacebookSigningException: Indicates that the secret or API key
were not specified or were invalid.
 FacebookTimeoutException: Indicates that the Facebook API did
not respond in a within the timeout threshold

1.1.1.15Method: GetGroupMembers
This method wraps the Facebook API method groups.getMembers. This
method is to retrieve profile information about all Facebook users that
are members of a particular group.

Definition: public Collection<GroupUser> GetGroupMembers(string

groupId)

Parameters:

Parameter Description
groupId The Facebook identifier of the group

Return Type: Collection<GroupUser> - GroupUser is a lightweight

wrapper to user that adds a property for the users position
in the group

Exceptions:

 FacebookException: This base class of all exceptions. If

exception could not be classified, FacebookException will be
used.
 FacebookInvalidUserException: The user that the call was made
on behalf of is not valid.
  FacebookRequestLimitException: Indicates that the consuming
application has made too many Facebook API calls in short
period of time.
 FacebookServiceUnavailableException: Indicates that the
website used to host the Facebook REST client was not available.
 FacebookSigningException: Indicates that the secret or API key
were not specified or were invalid.
 FacebookTimeoutException: Indicates that the Facebook API did
not respond in a within the timeout threshold

1.1.1.16Method: GetGroups
This method wraps the Facebook API method groups.get. This method is
used to retrieve the groups matching a specific criteria.

Definition (1): public Collection<Group> GetGroups()

Definition (2): public Collection<Group> GetGroups(string userId)

Definition (3): public Collection<Group> GetGroups(Collection<string>

groupsList)

Definition (4): public Collection<Group> GetGroups(string userId,

Collection<string> groupsList)

Parameters (1):

Parameter Description
None Get all groups for the logged in user
Parameters (2):

Parameter Description
userId The Facebook userId to return groups for
Parameters (3):

Parameter Description
A collection of group ids. Return all groups matching a
groupList
group id in the list.
Parameters (4):

Parameter Description
userId The Facebook userId to return groups for
A collection of group ids. Return all groups matching a
groupList
group id in the list.
 Return Type: Collection<Group>

Exceptions:

 FacebookException: This base class of all exceptions. If

exception could not be classified, FacebookException will be
used.
 FacebookInvalidUserException: The user that the call was made
on behalf of is not valid.
 FacebookRequestLimitException: Indicates that the consuming
application has made too many Facebook API calls in short
period of time.
 FacebookServiceUnavailableException: Indicates that the
website used to host the Facebook REST client was not available.
 FacebookSigningException: Indicates that the secret or API key
were not specified or were invalid.
 FacebookTimeoutException: Indicates that the Facebook API did
not respond in a within the timeout threshold

1.1.1.17Method: GetPhotoAlbums
This method wraps the Facebook API method photos.getAlbums. This
method is used to get photo album details based on search criteria

Definition (1): public Collection<Album> GetPhotoAlbums()

Definition (2): public Collection<Album> GetPhotoAlbums(string userId)

Definition (3): public Collection<Album>

GetPhotoAlbums(Collection<string> albumList)

Definition (4): public Collection<Album> GetPhotoAlbums(string userId,

Collection<string> albumList)

Parameters (1):

Parameter Description
None Get all albums for the logged in user
Parameters (2):

Parameter Description
userId Facebook userid to retrieve all albums for
Parameters (3):

Parameter Description
albumList Collection of Facebook album ids to retrieve
Parameters (4):
Parameter Description
userId Facebook userid to retrieve albums for
albumList Collection of Facebook album ids to retrieve

Return Type: Collection<Album>

Exceptions:

 FacebookException: This base class of all exceptions. If

exception could not be classified, FacebookException will be
used.
 FacebookInvalidUserException: The user that the call was made
on behalf of is not valid.
 FacebookRequestLimitException: Indicates that the consuming
application has made too many Facebook API calls in short
period of time.
 FacebookServiceUnavailableException: Indicates that the
website used to host the Facebook REST client was not available.
 FacebookSigningException: Indicates that the secret or API key
were not specified or were invalid.
 FacebookTimeoutException: Indicates that the Facebook API did
not respond in a within the timeout threshold

1.1.1.18Method: GetPhotos
This method wraps the Facebook API method photos.get. This method is
used to get photos based on search criteria.

Definition (1): public Collection<Photo> GetPhotos(string albumId)

Definition (2): public Collection<Photo> GetPhotos(Collection<string>

photoList)

Definition (3): public Collection<Photo> GetPhotos(string albumId,

Collection<string> photoList)

Parameters (1):

Parameter Description
The Facebook identifier of the album to retrieve photos
albumId
for
Parameters (2):

Parameter Description
Collection of Facebook photo identifier to return
photoList
information about
 Parameters (3):

Parameter Description
The Facebook identifier of the album to retrieve photos
albumId
for
Collection of Facebook photo identifier to return
photoList
information about

Return Type: Collection<Photo>

Exceptions:

 FacebookException: This base class of all exceptions. If

exception could not be classified, FacebookException will be
used.
 FacebookInvalidUserException: The user that the call was made
on behalf of is not valid.
 FacebookRequestLimitException: Indicates that the consuming
application has made too many Facebook API calls in short
period of time.
 FacebookServiceUnavailableException: Indicates that the
website used to host the Facebook REST client was not available.
 FacebookSigningException: Indicates that the secret or API key
were not specified or were invalid.
 FacebookTimeoutException: Indicates that the Facebook API did
not respond in a within the timeout threshold

1.1.1.19Method: GetTags
This method wraps the Facebook API method photos.getTags. This
method is used to retrieve all tags for a particular photo.

Definition: public Collection<PhotoTag> GetTags(Collection<string>

photoList)

Parameters:

Parameter Description
photoList Collection of Facebook photo identifiers to return tags for

Return Type: Collection<PhotoTag>

Exceptions:
  FacebookException: This base class of all exceptions. If
exception could not be classified, FacebookException will be
used.
 FacebookInvalidUserException: The user that the call was made
on behalf of is not valid.
 FacebookRequestLimitException: Indicates that the consuming
application has made too many Facebook API calls in short
period of time.
 FacebookServiceUnavailableException: Indicates that the
website used to host the Facebook REST client was not available.
 FacebookSigningException: Indicates that the secret or API key
were not specified or were invalid.
 FacebookTimeoutException: Indicates that the Facebook API did
not respond in a within the timeout threshold

1.1.1.20Method: GetUserInfo
This method wraps the Facebook API method users.getInfo. This method
is used to retrieve profile information for a set of users.

Definition(1): public User GetUserInfo()

Definition(2): public Collection<User> GetUserInfo(string userIds)

Parameters(1):

Parameter Description
none Get the user profile for the logged in user
Parameters(2):

Parameter Description
userIds Comma separated list of Facebook user identifiers
Return Type: User

Exceptions:

 FacebookException: This base class of all exceptions. If

exception could not be classified, FacebookException will be
used.
 FacebookInvalidUserException: The user that the call was made
on behalf of is not valid.
 FacebookRequestLimitException: Indicates that the consuming
application has made too many Facebook API calls in short
period of time.
 FacebookServiceUnavailableException: Indicates that the
website used to host the Facebook REST client was not available.
 FacebookSigningException: Indicates that the secret or API key
were not specified or were invalid.
  FacebookTimeoutException: Indicates that the Facebook API did
not respond in a within the timeout threshold

1.1.1.21Method: UploadPhoto
This method wraps the Facebook API method photos.upload. This
method is used to upload a new photo. The uploaded photo will be
considered pending until the user utilizes the website to confirm the
photo.

Definition: public void UploadPhoto(string albumId, FileInfo

uploadFile)

Parameters:

Parameter Description
The album identifier to upload the photo to. If null, then
albumId
will upload to default album
uploadFile File containing the photo to upload.

Return Type: N/A

Exceptions:

 FacebookException: This base class of all exceptions. If

exception could not be classified, FacebookException will be
used.
 FacebookInvalidUserException: The user that the call was made
on behalf of is not valid.
 FacebookRequestLimitException: Indicates that the consuming
application has made too many Facebook API calls in short
period of time.
 FacebookServiceUnavailableException: Indicates that the
website used to host the Facebook REST client was not available.
 FacebookSigningException: Indicates that the secret or API key
were not specified or were invalid.
 FacebookTimeoutException: Indicates that the Facebook API did
not respond in a within the timeout threshold

Facebook Data Objects

Album Class
This class represents a Facebook photo album.
1.1.1.22Property: AlbumId
The Facebook identifier of the album

Definition: public string AlbumId

1.1.1.23Property: CoverPhotoId
The Facebook identifier of photo that is used as the cover photo for the
album

Definition: public string CoverPhotoId

1.1.1.24Property: CreateDate
The date that the album was created

Definition: public DateTime CreateDate

1.1.1.25Property: Description
The user entered description of the album

Definition: public string Description

1.1.1.26Property: Location
The location that the album pertains to

Definition: public string Location

 1.1.1.27Property: ModifiedDate
The date that this album was last updated

Definition: public DateTime ModifiedDate

1.1.1.28Property: Name
The name of the album

Definition: public string Name

1.1.1.29Property: OwnerUserId
The Facebook user id of the person who created the album

Definition: public string OwnerUserId

Photo Class
This class contains the information about a Facebook Photo.

1.1.1.30Property: AlbumId
A Facebook unique identifier of the album that the photo is part of.

Definition: public string AlbumId

1.1.1.31Property: Caption
The caption of the photo.

Definition: public string Caption

1.1.1.32Property: CreateDate
A date when the photo was first uploaded.
 Definition: public DateTime CreateDate

1.1.1.33Property: Link
The photo link.

Definition: public Uri Link

1.1.1.34Property: OwnerUserId
A Facebook unique identifier of user who owns the photo.

Definition: public string OwnerUserId

1.1.1.35Property: PhotoId
A Facebook unique identifier of the photo.

Definition: public string PhotoId

1.1.1.36Property: Picture
The actual image. Accessing this property will download the bytes of the
image and serialize into an image. This does require a small
performance hit.

Definition: public Image Picture

1.1.1.37Property: PictureUrl
The url of this picture

Definition: public Uri PictureUrl

FacebookEvent Class
This class represents a Facebook event.
1.1.1.38Property: Creator
The Facebook identifier of the user who created the event

Definition: public string Creator

1.1.1.39Property: Description
Description of the event

Definition: public string Description

1.1.1.40Property: EndDate
The date that the events ends

Definition: public DateTime EndDate

1.1.1.41Property: EventId
The Facebook identifier of the event.
 Definition: public string EventId

1.1.1.42Property: Host
The Facebook user id of the host of the event

Definition: public string Host

1.1.1.43Property: Location
The name of the place where the event will take place.

Definition: public string Location

1.1.1.44Property: Name
The name of the event

Definition: public string Name

1.1.1.45Property: NetworkId
The Facebook identifier of the network that this event is a part of

Definition: public string NetworkId

1.1.1.46Property: Picture
The actual image associated with the event. Accessing this property will
download the bytes of the image and serialize into an image. This does
require a small performance hit.

Definition: public Image Picture

1.1.1.47Property: PictureUrl
The url of this event’s picture

Definition: public Uri PictureUrl

1.1.1.48Property: StartDate
The date and time when the event starts

Definition: public DateTime StartDate

1.1.1.49Property: SubType
The seconary group of event type.

Definition: public string SubType

1.1.1.50Property: TagLine
The tagline of the event if one was specified
 Definition: public string TagLine

1.1.1.51Property: Type
The primary grouping of the event

Definition: public string Type

1.1.1.52Property: UpdateDate
The Facebook user id of the person who created the album

Definition: public DateTime UpdateDate

Group Class
This class contains represents a Facebook group.

1.1.1.53Property: Creator
The Facebook identifier of the user who created the group

Definition: public string Creator

1.1.1.54Property: Description
The description of the group

Definition: public string Description

1.1.1.55Property: GroupId
The Facebook identifier of the group

Definition: public string GroupId

1.1.1.56Property: Name
The user entered name of the group

Definition: public string Name

1.1.1.57Property: NetworkId
The Facebook identifier of the network that the group is part of

Definition: public string NetworkId

1.1.1.58Property: Office
The address of the group’s office if it has one.

Definition: public string Office

1.1.1.59Property: Picture
The actual image associated with the group. Accessing this property will
download the bytes of the image and serialize into an image. This does
require a small performance hit.

Definition: public Image Picture

1.1.1.60Property: PictureUrl
The url of this group’s picture

Definition: public Uri PictureUrl

1.1.1.61Property: RecentNews
Free form text describing recent news associated with the group

Definition: public string Recent News

1.1.1.62Property: SubType
The seconary group of group type.

Definition: public string SubType

 1.1.1.63Property: Type
The primary grouping of the event

Definition: public string Type

1.1.1.64Property: UpdateDate
The last date and time that changes were made to the group

Definition: public DateTime UpdateDate

1.1.1.65Property: Venue
The name of the venue where the group meetings occur

Definition: public string Venue

1.1.1.66Property: WebSite
The url of the website for the group.

Definition: public string WebSite

GroupUser Class
This class contains represents a Facebook group.

1.1.1.67Property: GroupId
The Facebook identifier of the group

Definition: public string GroupId

1.1.1.68Property: Positions
Collection of positions held by this user
 Definition: public Collection<GroupPosition> Positions

1.1.1.69Property: User
The user object representing the profile of the user

Definition: public User User

1.1.1.70Property: UserId
The Facebook identified of the user

Definition: public string UserId

User Class
This class contains represents a Facebook user.
1.1.1.71Property: AboutMe
A string describing the user. Free form.

Definition: public string AboutMe

1.1.1.72Property: Activities
Free form text describing the activities this user is interested in.

Definition: public string Activities

1.1.1.73Property: Affiliations
A collection of Networks this user belongs to

Definition: public Collection<Network> Affiliations

1.1.1.74Property: Birthday
The day this user was born

Definition: public DateTime? Birthday

1.1.1.75Property: Books
Free form text describing this user’s favorite books

Definition: public string Books

1.1.1.76Property: CurrentLocation
The current location for the user

Definition: public Location CurrentLocation

1.1.1.77Property: FirstName
The user’s first name

Definition: public string FirstName

1.1.1.78Property: HometownLocation
The location of the user’s hometown

Definition: public Location HometownLocation

1.1.1.79Property: InterestedInGenders
A collection containing enum values representing the genders that this
person is interested in.

Definition: public Collection<Gender> InterestedInGenders

1.1.1.80Property: Interests
Free form text describing the user’s interests

Definition: public string Interests

1.1.1.81Property: InterestedInRelationshipTypes
A collection containing enum values representing the types of
relationships that this person is interested in.

Definition: public Collection<LookingFor>

InterstedInRelationshipTypes

1.1.1.82Property: LastName
The user’s last name

Definition: public string LastName

1.1.1.83Property: Movies
Free form text describing the user’s favorite movies

Definition: public string Movies

1.1.1.84Property: Music
Free form text describing the user’s favorite music

Definition: public string Music

1.1.1.85Property: Name
The user’s name

Definition: public string Name

1.1.1.86Property: NotesCount
The number of notes this user has associated with their Facebook
account.

Definition: public int NotesCount

1.1.1.87Property: Picture
The actual image associated with this user’s profile. Accessing this
property will download the bytes of the image and serialize into an
image. This does require a small performance hit.

Definition: public Image Picture

1.1.1.88Property: PictureUrl
The url of this user’s Facebook picture

Definition: public Uri PictureUrl

1.1.1.89Property: PoliticalView
An enum value representing the user’s political view

Definition: public PoliticalView PoliticalView

1.1.1.90Property: Quotes
Free form text representing the user’s favorite quotes

Definition: public string Quotes

1.1.1.91Property: RelationshipStatus
An enum value representing the user’s current relationship status.

Definition: public RelationshipStatus RelationshipStatus

1.1.1.92Property: Religion
Free form text representing the Religion

Definition: public string Religion

1.1.1.93Property: SchoolHistory
A data object representing the user’s education history

Definition: public SchoolHistory SchoolHistory

1.1.1.94Property: Sex
The user’s gender

Definition: public Gender Sex

1.1.1.95Property: SignificantOtherId
The Facebook user id of this user’s significant other

Definition: public string SignificantOtherId

1.1.1.96Property: TVShows
Free form text describing this user’s favorite TVShows

Definition: public string TVShows

 1.1.1.97Property: UserId
The Facebook unique identifier of the user

Definition: public string UserId

1.1.1.98Property: WallCount
The number of messages that have been written on this user’s wall.

Definition: public int WallCount

1.1.1.99Property: RelationshipStatus
The Facebook identified of the user

Definition: public RelationshipStatus RelationshipStatus

1.1.1.100Property: WorkHistory
Collection of Work object representing this user’s employment history

Definition: public Collection<Work> WorkHistory

SchoolHistory Class
This class contains Facebook user’s education history (including high school
and college).

1.1.1.101Property: HigherEducaton
A collection of HigherEducation object representing the colleges this user
attended.

Definition: public Collection<HigherEducation> HigherEducation

1.1.1.102Property: HighSchool
A HighSchool data object containing information about the high schools
this user attended.

Definition: public HighSchool HighSchool

HighSchool Class
This classs contains information about the high schools this user attended.

1.1.1.103Property: GraduationYear
The year this user graduated from college

Definition: public int GraduationYear

1.1.1.104Property: HighSchoolOneId
The Facebook unique identifier of the high school
 Definition: public string HighSchoolOneId

1.1.1.105Property: HighSchoolOneName
The name of the high school

Definition: public string HighSchoolOneName

1.1.1.106Property: HighSchoolTwoId
The Facebook unique identifier of the high school

Definition: public string HighSchoolTwoId

1.1.1.107Property: HighSchoolTwoName
The name of the high school

Definition: public string HighSchoolTwoName

HigherEducation Class
This class contains Facebook user’s college education history.

1.1.1.108Property: AttendedFor
An enum value representing if the school was attended for under
graduate work or graduate work

Definition: public SchoolType AttendedFor

1.1.1.109Property: ClassYear
Graduation year

Definition: public int ClassYear

1.1.1.110Property: Concentration
A collection describing user’s majors

Definition: public Collection<string> Concentration

1.1.1.111Property: School
The name of the school

Definition: public string School

Network Class
This class contains the information about a Facebook Network.

1.1.1.112Property: Name
The name of the network.
 Definition: public string Name

1.1.1.113Property: NetworkId
The Facebook unique identifier of the network.

Definition: public string NetworkId

1.1.1.114Property: Status
The status of the network (Open or Closed).

Definition: public string Status

1.1.1.115Property: Type
An enum value representing the type of the network (College, High
School, Work or Region)

Definition: public NetworkType Type

1.1.1.116Property: Year
The year associated with the network.

Definition: public int Year

Location Class
This class contains information about a geographic location.

1.1.1.117Property: City
A city of the location.

Definition: public string City

1.1.1.118Property: Country
A country of the location.

Definition: public Country Country

1.1.1.119Property: State
A state of the location.

Definition: public State State

1.1.1.120Property: StateAbbreviation
A postal abbreviation of the state of the location.

Definition: public StateAbbreviation StateAbbreviation

 1.1.1.121Property: ZipCode
A zip code of the location.

Definition: public string ZipCode

Work Class
This class contains Facebook user’s work history.

1.1.1.122Property: CompanyName
The name of the company.

Definition: public string CompanyName

1.1.1.123Property: Description
The description of job.

Definition: public string Description

1.1.1.124Property: EndDate
The date that the user ended this employment.

Definition: public DateTime EndDate

1.1.1.125Property: Location
The location of the job.

Definition: public Location Location

1.1.1.126Property: Position
The user’s position/title.

Definition: public string Position

1.1.1.127Property: StartDate
The date the user started the job.

Definition: public DateTime StartDate

Code Snippets
Windows Form: Application Setup
After registering your desktop application at http://api.Facebook.com, you will
receive an API key and a secret. To start utilizing the Facebook API, you must
add a reference to the Facebook.dll. Drag an instance of FacebookService from
the toolbox. Enter your API Key and Secret.

Windows Form: Retrieving Friends

The FacebookService component contains methods that wrap all of the methods
of the Facebook Developer API. The following provides an example for getting
all the friends of the logged in user. This method returns a generic collection of
User objects. The User object is a strongly typed representation of a Facebook
User profile.

Visual C#
using System.Collections.Generic;
using System.Collections.ObjectModel;
…
Collection<User> friends = FacebookService1.GetFriends();

Visual Basic

Imports System.Collections.Generic
Imports System.Collections.ObjectModel
…

Dim friends As Collection(Of User) = FacebookService1.GetFriends()

Windows Form: Utilizing the FriendList Control

There are several WinForm controls that exercise the FacebookService. This
sample shows how to use the FriendList control. Drag a FriendList from the
Toolbox to your form. (This assumes you have already added the
FacebookService component and set your API key and secret). Simply set the
Friends property of the FriendList control.

Visual C#
using System.Collections.Generic;
using System.Collections.ObjectModel;
using Facebook.Controls;
 …

friendList1.Friends = FacebookService1.GetFriends();

Visual Basic

Imports System.Collections.Generic
Imports System.Collections.ObjectModel
Imports Facebook.Controls
…

friendList1.Friends = FacebookService1.GetFriends()

Windows Form: Hooking a FriendList Control to a Profile

Control
The Profile Control is used to display the detailed profile information about a
Facebook User. This sample shows how to hook up the event that a Friend was
selected in the FriendList Control and populate a Profile control on the same
form.

Visual C#
using System.Collections.Generic;
using System.Collections.ObjectModel;
using Facebook.Controls;

Collection<User> friends = FacebookService1.GetFriends();

friendList1.Friends = friends;
profile1.User = friends[0];
friendList1.FriendSelected += new
EventHandler<FriendSelectedEventArgs>(friendList1_FriendSelected);
…
void friendList1_FriendSelected(object sender,
FriendSelectedEventArgs e)
{
profile1.User = e.User;
}

Visual Basic

Dim friends As Collection(Of User) = FacebookService1.GetFriends()

friendList1.Friends = friends
profile1.User = friends(0)
AddHandler friendList1.FriendSelected, AddressOf
friendList1_FriendSelected
…
Private Sub friendList1_FriendSelected(ByVal sender As Object, ByVal e
As FriendSelectedEventArgs)
 profile1.User = e.User
End Sub

Web Application: Authentication Process

Web Application development requires writing code to handle 3 userstates.

1. If we don’t have an auth_token, redirect to the Facebook hosted login

page.

2. If we have an auth_token, start a session on behalf of the user.

3. Store the user’s session information for making calls to the Facebook
service.

The following shows a simple page that handles these 3 states.

Visual C#

// ApplicationKey and Secret are acquired when you sign up for

_fbService.ApplicationKey = "bfeefa69afdfe81975f0d6136ace3009";
_fbService.Secret = "9b672d682e1d8befd06382953fc2615b";
_fbService.IsDesktopApplication = false;

string sessionKey = Session["Facebook_session_key"] as String;

string userId = Session["Facebook_userId"] as String;

// When the user uses the Facebook login page, the redirect back
here // will will have the auth_token in the query params
string authToken = Request.QueryString["auth_token"];

// We have already established a session on behalf of this user

if (!String.IsNullOrEmpty(sessionKey))
{
_fbService.SessionKey = sessionKey;
_fbService.UserId = userId;
}
// This will be executed when Facebook login redirects to our page
else if (!String.IsNullOrEmpty(authToken))
{
_fbService.CreateSession(authToken);
Session["Facebook_session_key"] = _fbService.SessionKey;
Session["Facebook_userId"] = _fbService.UserId;
Session["Facebook_session_expires"] = fbService.SessionExpires;
}
// Need to login
else
{
Response.Redirect(@"http://www.Facebook.com/login.php?ap
i_key=" + _fbService.ApplicationKey + @"&v=1.0\");
}

if (!IsPostBack)
{
 // Use the FacebookService Component to populate Friends
MyFriendList.Friends = _fbService.GetFriends();
}

Visual Basic

Private _fbService As Facebook.Components.FacebookService = New

Facebook.Components.FacebookService()

Protected Sub Page_Load(ByVal sender As Object, ByVal e As EventArgs)

' ApplicationKey and Secret are acquired when you sign up for
_fbService.ApplicationKey = "7a399eeba47b0f5b2bfd88cc872ada4a"
_fbService.Secret = "fad3d3fbeb8571957c39e2792073b978"
_fbService.IsDesktopApplication = False

Dim sessionKey As String =

TryCast(Session("Facebook_session_key"), String)
Dim userId As String = TryCast(Session("Facebook_userId"), String)

' When the user uses the Facebook login page, the redirect back
here will will have the auth_token in the query params
Dim authToken As String = Request.QueryString("auth_token")

' We have already established a session on behalf of this user

If (Not String.IsNullOrEmpty(sessionKey)) Then
_fbService.SessionKey = sessionKey
_fbService.UserId = userId
' This will be executed when Facebook login redirects to our page
ElseIf (Not String.IsNullOrEmpty(authToken)) Then
_fbService.CreateSession(authToken)
Session("Facebook_session_key") = _fbService.SessionKey
Session("Facebook_userId") = _fbService.UserId
Session("Facebook_session_expires") =
_fbService.SessionExpires
' Need to login
Else

Response.Redirect("http://www.Facebook.com/login.php?api_key=" &
_fbService.ApplicationKey & "&v=1.0")
End If

If (Not IsPostBack) Then

' Use the FacebookService Component to populate Friends
MyFriendList.Friends = _fbService.GetFriends()
End If