{"id":1974,"date":"2012-12-13T12:48:00","date_gmt":"2012-12-13T12:48:00","guid":{"rendered":"https:\/\/blogs.msdn.microsoft.com\/webdev\/2012\/12\/13\/the-new-facebook-application-template-and-library-for-asp-net-mvc\/"},"modified":"2022-08-10T01:40:28","modified_gmt":"2022-08-10T08:40:28","slug":"the-new-facebook-application-template-and-library-for-asp-net-mvc","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/dotnet\/the-new-facebook-application-template-and-library-for-asp-net-mvc\/","title":{"rendered":"The new Facebook application template and library for ASP.NET MVC"},"content":{"rendered":"

If you\u2019re looking to build a Facebook App using ASP.NET MVC, then you\u2019re in the right place. With the release of ASP.NET and Web Tools 2012.2<\/strong><\/a>,<\/strong> we\u2019ve added lots of updates to our Facebook Application template<\/strong> and<\/strong> library<\/strong> since we first introduced it in the Preview.<\/p>\n

The library, Microsoft.AspNet.Mvc.Facebook<\/strong><\/a>, can be downloaded as an independent NuGet package and it contains everything you need to create a Facebook Canvas application using ASP.NET MVC. It\u2019s already included by default in the Facebook Application template to give you a quick jump start on building a Canvas Page<\/a>.<\/p>\n

Please refer to the tutorial<\/strong><\/a> for instructions on how to setup the Facebook Application template. In this post I\u2019ll mainly focus on the design\/API changes that we made from the Preview to RC. This will give you a pretty good idea of how the new APIs work in the updated Facebook Application template.<\/p>\n

\"image\"<\/a><\/p>\n

Introducing FacebookContext<\/h2>\n

Before RC, we used to model bind the User and other Facebook objects as parameters. The problem with model binding these parameters is that we needed to call Facebook Graph API to get the values and the model binders in MVC don\u2019t support async. That\u2019s why in RC, we\u2019re replacing them with a FacebookContext parameter from which you can access the user ID, access token and the parsed signed request. More importantly, the FacebookContext has an instance of the FacebookClient<\/a> which can be used to make asynchronously calls to Facebook to get the values for the User and other Facebook objects.<\/p>\n

\"image\"<\/a><\/p>\n

The instance of FacebookClient is populated with the required information such as AppId, AppSecret and AccessToken, so it\u2019s ready to use.<\/p>\n

\n
\n
public<\/span> async Task<ActionResult> Index(FacebookContext context)<\/pre>\n
<\/p>\n
{<\/pre>\n
<\/p>\n
    if<\/span> (ModelState.IsValid)<\/pre>\n
<\/p>\n
    {<\/pre>\n
<\/p>\n
        MyAppUser user = await context.Client.GetCurrentUserAsync<MyAppUser>();<\/pre>\n
<\/p>\n
        return<\/span> View(user);<\/pre>\n
<\/p>\n
    }<\/pre>\n
<\/p>\n
 <\/pre>\n
<\/p>\n
    return<\/span> View("Error"<\/span>);<\/pre>\n
<\/p>\n
}<\/pre>\n
<\/div>\n<\/div>\n
FacebookClient Extensions<\/h2>\n
We\u2019ve added a number of extension methods to FacebookClient<\/a> to make the common tasks, such as getting the current user and his\/her friends, simpler.<\/p>\n
\"image\"<\/a><\/p>\n
In fact, most of the extension methods above are based on GetFacebookObjectAsync<TFacebookObject><\/strong>(string objectPath). If you\u2019re familiar with Facebook C# SDK, you might be wondering how it is different from GetTaskAsync<TResult>(string path). Well, the main difference between them is that GetFacebookObjectAsync<TFacebookObject>(string objectPath) will automatically generate \u201cfields\u201d query parameter when making the request so you get back only the properties you need. It reduces the payload size and sometime this can be quite significant. For example, if you have the following type named \u201cMyUser\u201d.<\/p>\n
\n
\n
public<\/span> class<\/span> MyUser<\/pre>\n
<\/p>\n
{<\/pre>\n
<\/p>\n
    public<\/span> string<\/span> Id { get; set; }<\/pre>\n
<\/p>\n
    public<\/span> string<\/span> Name { get; set; }<\/pre>\n
<\/p>\n
    public<\/span> string<\/span> Birthday { get; set; }<\/pre>\n
<\/p>\n
}<\/pre>\n
<\/div>\n<\/div>\n
GetFacebookObjectAsync<MyUser>(\u201cme\u201d) will get back something like the following.<\/p>\n
\n
\n
{<\/pre>\n
<\/p>\n
    "id"<\/span>: "1234567"<\/span>,<\/pre>\n
<\/p>\n
    "name"<\/span>: "sample name"<\/span>,<\/pre>\n
<\/p>\n
    "birthday"<\/span>: "01\/01\/2000"<\/span><\/pre>\n
<\/p>\n
}<\/pre>\n
<\/div>\n<\/div>\n
but GetTaskAsync<MyUser>(\u201cme\u201d) will get back the full payload. The difference can be even bigger when you\u2019re retrieving a list of friends.<\/p>\n
\n
\n
{  <\/pre>\n
<\/p>\n
    "id"<\/span>: "1234567"<\/span>,<\/pre>\n
<\/p>\n
    "name"<\/span>: "sample name"<\/span>,<\/pre>\n
<\/p>\n
    "first_name"<\/span>: "sample name"<\/span>,<\/pre>\n
<\/p>\n
    "middle_name"<\/span>: "sample name"<\/span>,<\/pre>\n
<\/p>\n
    "last_name"<\/span>: "sample name"<\/span>,<\/pre>\n
<\/p>\n
    "link"<\/span>: "https:\/\/www.facebook.com\/sample"<\/span>,<\/pre>\n
<\/p>\n
    "username"<\/span>: "sample"<\/span>,<\/pre>\n
<\/p>\n
    "birthday"<\/span>: "01\/01\/2000"<\/span>,<\/pre>\n
<\/p>\n
    "location"<\/span>: <\/pre>\n
<\/p>\n
    {<\/pre>\n
<\/p>\n
        "id"<\/span>: "123456789"<\/span>,<\/pre>\n
<\/p>\n
        "name"<\/span>: "Redmond, Washington"<\/span>  <\/pre>\n
<\/p>\n
    },<\/pre>\n
<\/p>\n
    "quotes"<\/span>: "Very long quotes..................."<\/span>,<\/pre>\n
<\/p>\n
    "gender"<\/span>: "male"<\/span>,<\/pre>\n
<\/p>\n
    "email"<\/span>: "sample@sample.com"<\/span>,<\/pre>\n
<\/p>\n
    "timezone"<\/span>: -4,<\/pre>\n
<\/p>\n
    "locale"<\/span>: "en_US"<\/span>,<\/pre>\n
<\/p>\n
    "verified"<\/span>: true<\/span>,<\/pre>\n
<\/p>\n
    "updated_time"<\/span>: "2012-10-11T00:25:53+0000"<\/span><\/pre>\n
<\/p>\n
}<\/pre>\n
<\/div>\n<\/div>\n
Being able to automatically generate the \u201cfields\u201d query parameter also makes it easier to retrieve connections<\/a> <\/em>(Picture, Friends, Likes, etc) as fields. For instance, you can get back the user information and what user Likes (a connection<\/em>) in a single request by defining the types below. GetFacebookObjectAsync<MyUser> will automatically take care of generating the appropriate \u201cfields\u201d query to include the Likes connection <\/em>(assuming you have user_likes permission).<\/p>\n
\n
\n
public<\/span> class<\/span> MyUser<\/pre>\n
<\/p>\n
{<\/pre>\n
<\/p>\n
    public<\/span> string<\/span> Id { get; set; }<\/pre>\n
<\/p>\n
    public<\/span> string<\/span> Name { get; set; }<\/pre>\n
<\/p>\n
    public<\/span> string<\/span> Birthday { get; set; }<\/pre>\n
<\/p>\n
    public<\/span> FacebookGroupConnection<Like> Likes { get; set; }<\/pre>\n
<\/p>\n
}<\/pre>\n
<\/p>\n
 <\/pre>\n
<\/p>\n
public<\/span> class<\/span> Like<\/pre>\n
<\/p>\n
{<\/pre>\n
<\/p>\n
    public<\/span> string<\/span> Name { get; set; }<\/pre>\n
<\/p>\n
    public<\/span> string<\/span> Category { get; set; }<\/pre>\n
<\/p>\n
}<\/pre>\n
<\/div>\n<\/div>\n
Modeling Facebook Objects<\/h2>\n
Unlike before, where your Facebook user\/object types were required to derive from FacebookUser\/FacebookObject, now you can use any POCO type as long as it contains public properties with the matching name. We\u2019ll deserialize the Facebook response using Json.NET. For example, the following Facebook response for a user will match the \u201cMyUser\u201d type below.<\/p>\n
\n
\n
{  <\/pre>\n
<\/p>\n
    "id"<\/span>: "1234567"<\/span>,<\/pre>\n
<\/p>\n
    "name"<\/span>: "sample name"<\/span>,<\/pre>\n
<\/p>\n
    "link"<\/span>: https:\/\/www.facebook.com\/sample<\/span><\/pre>\n
<\/p>\n
}<\/pre>\n
<\/div>\n<\/div>\n
Note that the property derialization is case insensitive.<\/p>\n
\n
\n
public<\/span> class<\/span> MyUser<\/pre>\n
<\/p>\n
{<\/pre>\n
<\/p>\n
    public<\/span> string<\/span> Id { get; set; }<\/pre>\n
<\/p>\n
    public<\/span> string<\/span> Name { get; set; }<\/pre>\n
<\/p>\n
    public<\/span> string<\/span> Link { get; set; }<\/pre>\n
<\/p>\n
}<\/pre>\n
<\/div>\n<\/div>\n
Defining Connections<\/h3>\n
As noted previously, now you can include connections<\/em> (Picture, Friends, Likes, etc) as properties using FacebookConnection<T> and FacebookGroupConnection<T>. <\/p>\n
\"image\"<\/a><\/p>\n
\n
\n
public<\/span> class<\/span> MyAppUser<\/pre>\n
<\/p>\n
{<\/pre>\n
<\/p>\n
    public<\/span> string<\/span> Name { get; set; }<\/pre>\n
<\/p>\n
    public<\/span> string<\/span> Email { get; set; }<\/pre>\n
<\/p>\n
 <\/pre>\n
<\/p>\n
    public<\/span> FacebookConnection<FacebookPicture> Picture { get; set; }<\/pre>\n
<\/p>\n
    public<\/span> FacebookGroupConnection<MyAppUserFriend> Friends { get; set; }<\/pre>\n
<\/p>\n
}<\/pre>\n
<\/p>\n
 <\/pre>\n
<\/p>\n
public<\/span> class<\/span> FacebookPicture<\/pre>\n
<\/p>\n
{<\/pre>\n
<\/p>\n
    public<\/span> string<\/span> Url { get; set; }<\/pre>\n
<\/p>\n
}<\/pre>\n
<\/p>\n
 <\/pre>\n
<\/p>\n
public<\/span> class<\/span> MyAppUserFriend<\/pre>\n
<\/p>\n
{<\/pre>\n
<\/p>\n
    public<\/span> string<\/span> Name { get; set; }<\/pre>\n
<\/p>\n
    public<\/span> string<\/span> Link { get; set; }<\/pre>\n
<\/p>\n
 <\/pre>\n
<\/p>\n
    public<\/span> FacebookConnection<FacebookPicture> Picture { get; set; }<\/pre>\n
<\/p>\n
}<\/pre>\n
<\/div>\n<\/div>\n
These types will match exactly how Facebook returns the connection<\/em> data in JSON.<\/p>\n
\n
\n
{<\/pre>\n
<\/p>\n
    "name"<\/span>: "sample name"<\/span>,<\/pre>\n
<\/p>\n
    "email"<\/span>: "sample@sample.com"<\/span>,<\/pre>\n
<\/p>\n
    "id"<\/span>: "1234567"<\/span>,<\/pre>\n
<\/p>\n
    "picture"<\/span>: {<\/pre>\n
<\/p>\n
        "data"<\/span>: {...}<\/pre>\n
<\/p>\n
    },<\/pre>\n
<\/p>\n
    "friends"<\/span>: {    <\/pre>\n
<\/p>\n
        "data"<\/span>: [      <\/pre>\n
<\/p>\n
            {...},<\/pre>\n
<\/p>\n
            {...},<\/pre>\n
<\/p>\n
            {...}<\/pre>\n
<\/p>\n
        ]<\/pre>\n
<\/p>\n
    }<\/pre>\n
<\/p>\n
}<\/pre>\n
<\/div>\n<\/div>\n
Property Attributes<\/h3>\n
Since we use Json.NET to do the deserialization, you can use JsonProperty\/JsonIgnore to rename\/exclude a property.<\/p>\n
\n
\n
public<\/span> class<\/span> MyAppUser<\/pre>\n
<\/p>\n
{<\/pre>\n
<\/p>\n
    [JsonIgnore] \/\/ This ignores the property<\/span><\/pre>\n
<\/p>\n
    public<\/span> string<\/span> MyProperty { get; set; }<\/pre>\n
<\/p>\n
 <\/pre>\n
<\/p>\n
    [JsonProperty("picture"<\/span>)] \/\/ This renames the property to picture.<\/span><\/pre>\n
<\/p>\n
    public<\/span> FacebookConnection<FacebookPicture> ProfilePicture { get; set; }<\/pre>\n
<\/p>\n
}<\/pre>\n
<\/div>\n<\/div>\n
In addition you can apply modifiers to the connections<\/em> using FacebookFieldModifier. For example, you can get the URL to a larger profile picture by adding the modifier \u201ctype(large)\u201d to Picture. Go to Facebook Graph API<\/a> to see the modifiers that are available. When GetFacebookObjectAsync<TFacebookObject> makes the request, these modifiers will be added to the ?field query parameter.<\/p>\n
\n
\n
public<\/span> class<\/span> MyAppUser<\/pre>\n
<\/p>\n
{<\/pre>\n
<\/p>\n
    [FacebookFieldModifier("type(large)"<\/span>)] \/\/ This sets the picture size to large.<\/span><\/pre>\n
<\/p>\n
    public<\/span> FacebookConnection<FacebookPicture> Picture { get; set; }<\/pre>\n
<\/p>\n
}<\/pre>\n
<\/p>\n
 <\/pre>\n
<\/p>\n
public<\/span> class<\/span> FacebookPicture<\/pre>\n
<\/p>\n
{<\/pre>\n
<\/p>\n
    public<\/span> string<\/span> Url { get; set; }<\/pre>\n
<\/p>\n
}<\/pre>\n
<\/div>\n<\/div>\n
Facebook Authorization<\/h2>\n
FacebookAuthorizeAttribute can be used just like before to ensure that the signed_request parameter (sent by Facebook) is valid before invoking an action. Additionally, you can require a set of permissions to be granted before reaching the action by passing them into the attribute. In case the authorization fails, either because of invalid signed request or missing permissions, the users will be redirected to a Facebook OAuth dialog asking them to login or grant the required permissions.<\/p>\n
Note that FacebookAuthorizeAttribute is not an authorization filter anymore, the actual authorization is done by FacebookAuthorizeFilter. That\u2019s why it\u2019s important to register the FacebookAuthorizeFilter globally to enable this functionality.<\/p>\n
\n
\n
public<\/span> static<\/span> class<\/span> FacebookConfig<\/pre>\n
<\/p>\n
{<\/pre>\n
<\/p>\n
    public<\/span> static<\/span> void<\/span> Register(FacebookConfiguration configuration)<\/pre>\n
<\/p>\n
    {<\/pre>\n
<\/p>\n
        \/\/ Other settings removed for clarity...<\/span><\/pre>\n
<\/p>\n
 <\/pre>\n
<\/p>\n
        \/\/ Adding the authorization filter to check for Facebook signed requests and permissions<\/span><\/pre>\n
<\/p>\n
        GlobalFilters.Filters.Add(new<\/span> FacebookAuthorizeFilter(configuration));<\/pre>\n
<\/p>\n
    }<\/pre>\n
<\/p>\n
}<\/pre>\n
<\/div>\n<\/div>\n
Having a global authorization filter allowed us to combine the permissions declared on both the controller and the action. Which means the user will see the OAuth dialog once instead twice for the \u201cProfile\u201d action below when the permissions are missing.<\/p>\n
\n
\n
[FacebookAuthorize("email"<\/span>)]<\/pre>\n
<\/p>\n
public<\/span> class<\/span> UserController : Controller<\/pre>\n
<\/p>\n
{<\/pre>\n
<\/p>\n
    [FacebookAuthorize("user_photos"<\/span>)]<\/pre>\n
<\/p>\n
    public<\/span> async Task<ActionResult> Profile(FacebookContext context) <\/pre>\n
<\/p>\n
    {<\/pre>\n
<\/p>\n
        \/\/ Implementation removed for clarity<\/span><\/pre>\n
<\/p>\n
    }<\/pre>\n
<\/p>\n
}<\/pre>\n
<\/div>\n<\/div>\n
\"image\"<\/a><\/p>\n
AuthorizationRedirectPath<\/h3>\n
When the permissions are missing, now you have the option of showing an \u201cinfo\u201d page before redirecting user to the OAuth dialog. In that page you can explaining why your app requires certain permissions so that users are more likely to grant them. To do that, add the following to your web.config and the user will be redirected to Home\/Permissions when the authorization fails due to missing permissions.<\/p>\n
\n
\n
<<\/span>appSettings<\/span>><\/span><\/pre>\n
<\/p>\n
  <<\/span>add<\/span> key<\/span>="Facebook:AuthorizationRedirectPath"<\/span> value<\/span>="Home\/Permissions"<\/span> \/><\/span><\/pre>\n
<\/p>\n
<\/<\/span>appSettings<\/span>><\/span><\/pre>\n
<\/div>\n<\/div>\n
On the action that is receiving the redirect, you can use FacebookRedirectContext parameter to access information like the required permissions and the RedirectUrl to the Facebook OAuth dialog.<\/p>\n
\n
\n
public<\/span> class<\/span> HomeController : Controller<\/pre>\n
<\/p>\n
{<\/pre>\n
<\/p>\n
    \/\/ Other actions removed for clarity...<\/span><\/pre>\n
<\/p>\n
 <\/pre>\n
<\/p>\n
    \/\/ This action will handle the redirects from FacebookAuthorizeFilter when <\/span><\/pre>\n
<\/p>\n
    \/\/ the app doesn't have all the required permissions specified in the FacebookAuthorizeAttribute.<\/span><\/pre>\n
<\/p>\n
    \/\/ The path to this action is defined under appSettings (in Web.config) with the key 'Facebook:AuthorizationRedirectPath'.<\/span><\/pre>\n
<\/p>\n
    public<\/span> ActionResult Permissions(FacebookRedirectContext context)<\/pre>\n
<\/p>\n
    {<\/pre>\n
<\/p>\n
        if<\/span> (ModelState.IsValid)<\/pre>\n
<\/p>\n
        {<\/pre>\n
<\/p>\n
            return<\/span> View(context);<\/pre>\n
<\/p>\n
        }<\/pre>\n
<\/p>\n
 <\/pre>\n
<\/p>\n
        return<\/span> View("Error"<\/span>);<\/pre>\n
<\/p>\n
    }<\/pre>\n
<\/p>\n
}<\/pre>\n
<\/div>\n<\/div>\n
\n
\n
@using Microsoft.AspNet.Mvc.Facebook<\/pre>\n
<\/p>\n
@model FacebookRedirectContext<\/pre>\n
<\/p>\n
 <\/pre>\n
<\/p>\n
@if (Model.RequiredPermissions.Length ><\/span> 0)<\/pre>\n
<\/p>\n
{<\/pre>\n
<\/p>\n
    <<\/span>h3<\/span>><\/span>You need to grant the following permission(s) on Facebook to view this page:<\/<\/span>h3<\/span>><\/span><\/pre>\n
<\/p>\n
    <<\/span>ul<\/span>><\/span><\/pre>\n
<\/p>\n
        @foreach (var permission in Model.RequiredPermissions)<\/pre>\n
<\/p>\n
        {<\/pre>\n
<\/p>\n
            <<\/span>li<\/span>><\/span>@permission<\/<\/span>li<\/span>><\/span><\/pre>\n
<\/p>\n
        }<\/pre>\n
<\/p>\n
    <\/<\/span>ul<\/span>><\/span><\/pre>\n
<\/p>\n
    <<\/span>a<\/span> class<\/span>="buttonLink"<\/span> href<\/span>="@Html.Raw(Model.RedirectUrl)"<\/span> target<\/span>="_top"<\/span>><\/span>Authorize this application<\/<\/span>a<\/span>><\/span><\/pre>\n
<\/p>\n
}<\/pre>\n
<\/div>\n<\/div>\n
Facebook Realtime Update Support<\/h2>\n
Out of the box, we provide you with an abstract FacebookRealtimeUpdateController, which is a Web API controller<\/a> that will handle all the HTTP requests sent by Facebook Realtime Update<\/a> service. It will take care of verifying the subscription and validating the integrity of the payload by checking the X-Hub-Signature HTTP header. All you need to provide is a verify token<\/a> and your business logic to handle the update. Here is a sample implementation of FacebookRealtimeUpdateController.<\/p>\n
\n
\n
public<\/span> class<\/span> UserRealtimeUpdateController : FacebookRealtimeUpdateController<\/pre>\n
<\/p>\n
{<\/pre>\n
<\/p>\n
    private<\/span> readonly<\/span> static<\/span> string<\/span> UserVerifyToken = ConfigurationManager.AppSettings["Facebook:VerifyToken:User"<\/span>];<\/pre>\n
<\/p>\n
 <\/pre>\n
<\/p>\n
    public<\/span> override<\/span> string<\/span> VerifyToken<\/pre>\n
<\/p>\n
    {<\/pre>\n
<\/p>\n
        get<\/pre>\n
<\/p>\n
        {<\/pre>\n
<\/p>\n
            return<\/span> UserVerifyToken;<\/pre>\n
<\/p>\n
        }<\/pre>\n
<\/p>\n
    }<\/pre>\n
<\/p>\n
 <\/pre>\n
<\/p>\n
    public<\/span> override<\/span> Task HandleUpdateAsync(ChangeNotification notification)<\/pre>\n
<\/p>\n
    {<\/pre>\n
<\/p>\n
        if<\/span> (notification.Object == "user"<\/span>)<\/pre>\n
<\/p>\n
        {<\/pre>\n
<\/p>\n
            foreach<\/span> (var entry in<\/span> notification.Entry)<\/pre>\n
<\/p>\n
            {<\/pre>\n
<\/p>\n
                \/\/ Your logic to handle the update here<\/span><\/pre>\n
<\/p>\n
            }<\/pre>\n
<\/p>\n
        }<\/pre>\n
<\/p>\n
    }<\/pre>\n
<\/p>\n
}<\/pre>\n
<\/div>\n<\/div>\n
Note that you can have multiple custom FacebookRealtimeUpdateController to handle different subscriptions<\/a> (Users, Permissions, etc) with different verify tokens.<\/p>\n
FacebookConfiguration<\/h2>\n
The static FacebookSettings class has been replaced by FacebookConfiguration. Notice that many components such as FacebookAuthorizeFilter are taking an instance of FacebookConfiguration in the constructor which makes unit testing easier. For global access to FacebookConfiguration within the application, you can use GlobalFacebookConfiguration.Configuration, which is a singleton instance.<\/p>\n
\"image\"<\/a><\/p>\n
LoadFromAppSettings<\/h3>\n
This method loads the following properties from appSettings.<\/p>\n