In the previous article, Dropbox REST API Part 1: Authentication, I showed you how you can obtain an access token using the Dropbox REST API and OAuth.

Once you have an access token, you can use it to access the main Dropbox REST API. Let’s demonstrate this by using some of the API’s requests such as retrieving account information and file (and directory) metadata.

It’s actually surprisingly easy. In the next part we’ll explore other options such as creating, deleting and moving folders.

Let’s get started…

Table Of Contents

• Introduction
• Account
• Metadata

Account

I took the source code from the first article (#62) in this series and structured it a bit differently, but in essence it still performs the same functionality. In this post I’ll only list the source code necessary to retrieve account information and file/folder metadata. You can check out how to retrieve an access token by reading the previous article and/or checking out the source code of this post.

Using the refactored code retrieving account information is very simple.

var accessToken = ...;
var api = new DropboxApi("your API key", "your API secret", accessToken);
var account = api.GetAccountInfo();

I created a class called DropboxApi. When creating an instance of this class you pass it your API key and secret (consumer key and secret) and an access token. By calling the GetAccountInfo() method you can retrieve information about the user’s Dropbox account.

The GetAccountInfo() method executes the following code:

public Account GetAccountInfo()
{
    var uri = new Uri(new Uri(DropboxRestApi.BaseUri), "account/info");
    var json = GetResponse(uri);
    return ParseJson<Account>(json);
}

The DropboxRestApi.BaseUri returns the base URL for the REST API, namely https://api.dropbox.com/1. To retrieve the account information you need to append account/info to it. Thus behind the scenes a request is sent to:

https://api.dropbox.com/1/account/info

You need to sign this request using your consumer key, secret and access token. If you don’t sign the request you’ll receive the error “Invalid OAuth request”.

During the authentication phase you already saw how to sign a request using OAuth. Well…you can reuse that same code. Just check out the previous article to see how signing requests works.

To make it easy I moved this code into its own class called OAuth. Using this class you can sign a request using just two lines of code:

var oauth = new OAuth();
var requestUri = oauth.SignRequest(
    uri, "API key", "API secret", accessToken);

Just create a new instance of the OAuth class and call the SignRequest(…) method. Pass in the URI you wish to sign, your API key and secret and your access token.

This will transform:

https://api.dropbox.com/1/account/info

into something like this:

https://api.dropbox.com/1/account/info?oauth_consumer_key=YourAPIKey&oauth_token=YourToken&oauth_nonce=6880853& oauth_timestamp=1326020204&oauth_signature_method=HMAC-SHA1&oauth_version=1.0&oauth_signature=9ukNkB/FZx3gHTT5TWP0hIkNe9z=

The GetAccountInfo() method does this by calling the GetResponse(…) method. This method signs the request, sends it and returns the response.

private string GetResponse(Uri uri)
{
    var oauth = new OAuth();
    var requestUri = oauth.SignRequest(
        uri, _consumerKey, _consumerSecret, _accessToken);
    var request = (HttpWebRequest) WebRequest.Create(requestUri);
    request.Method = WebRequestMethods.Http.Get;
    var response = request.GetResponse();
    var reader = new StreamReader(response.GetResponseStream());
    return reader.ReadToEnd();
}

The Dropbox REST API returns it responses in JSON format. Here’s an example response containing account information:

{
    "referral_link": "https://www.dropbox.com/referrals/r1a2n3d4m5s6t7",
    "display_name": "John P. User",
    "uid": 12345678,
    "country": "US",
    "quota_info": {
        "shared": 253738410565,
        "quota": 107374182400000,
        "normal": 680031877871
    },
    "email": "john@example.com"
}

It contains some general information about the user (id, name, e-mail address…) and his allocated quota. Using the Json.NET library we can easily deserialize this data into a .NET object. Let’s create a simple Account class into which we can deserialize this data.

[JsonObject(MemberSerialization.OptIn)]
public class Account
{
    [JsonProperty(PropertyName = "uid")]
    public int Id { get; internal set; }

    [JsonProperty(PropertyName = "referral_link")]
    public string ReferralLink { get; internal set; }

    [JsonProperty(PropertyName = "display_name")]
    public string DisplayName { get; internal set; }

    [JsonProperty(PropertyName = "email")]
    public string Email { get; internal set; }

    [JsonProperty(PropertyName = "country")]
    public string Country { get; internal set; }

    [JsonProperty(PropertyName = "quota_info")]
    public Quota Quota { get; internal set; }
}

The Quota type is equally simple.

[JsonObject(MemberSerialization.OptIn)]
public class Quota
{
    [JsonProperty(PropertyName = "quota")]
    public long Total { get; internal set; }

    [JsonProperty(PropertyName = "shared")]
    public long Shared { get; internal set; }

    [JsonProperty(PropertyName = "normal")]
    public long Normal { get; internal set; }
}

Don’t forget to install NuGet and to download the Json.NET library.

The last line of code of the GetAccountInfo() method deserializes the JSON data by calling the ParseJson(…) method;

private static T ParseJson<T>(string json) where T : class, new()
{
    var jobject = JObject.Parse(json);
    return JsonConvert.DeserializeObject<T>(jobject.ToString());
}

Just parse the JSON data and use the JsonConvert type to deserialize it into the type specified by the generic T parameter. As long as the type specified by T has been decorated with the correct Json.NET attributes it will deserialize without a problem.

Top of page

Metadata

By now you’ve seen how to retrieve the account information. It’s consists out of 3 steps, namely:

1. Compose the URI for the request
2. Sign and send the request
3. Parse the response (JSON) into a .NET object

Most (if not all) of the Dropbox API requests can be dealt with in the same fashion. For instance, retrieving a list of files/folders that are stored in our Dropbox can be done in the same way.

var api = new DropboxApi(ConsumerKey, ConsumerSecret, accessToken);
var publicFolder = api.GetFiles("dropbox", "Public");
foreach (var file in publicFolder.Contents)
{
    Console.WriteLine(file.Path);
}

Here I retrieve a list of files/folders that are stored in my public Dropbox folder. The first parameter specified the root. Valid values are sandbox and dropbox. The second parameter specifies the path of the file or folder relative to the root.

Retrieving a list of files/folders supports many more parameters, but to keep things simple I’ve chosen to only support these two parameters. For a complete list check out the Dropbox REST API documentation:

https://www.dropbox.com/developers/reference/api#metadata

Apart from the URI and the return value (T) the GetFiles(…) methods looks identical to the GetAccountInfo() method.

public File GetFiles(string root, string path)
{
    var uri = new Uri(new Uri(DropboxRestApi.BaseUri),
        String.Format("metadata/{0}/{1}", root, path));
    var json = GetResponse(uri);
    return ParseJson<File>(json);
}

The URI is composed, then the request is signed and send. Last, but not least the response (JSON) is parsed and converted to a .NET object of the type File.

The following listing contains a small part of the File type. It contains the metadata for a file or folder at a given path. If it is a directory (IsDirectory property) then the metadata will also include a listing of metadata for the folder’s contents (Contents property).

[JsonObject(MemberSerialization.OptIn)]
public class File
{
    [JsonProperty(PropertyName = "size")]
    public string Size { get; internal set; }

    [JsonProperty(PropertyName = "rev")]
    public string Revision { get; internal set; }

    [JsonProperty(PropertyName = "is_dir")]
    public bool IsDirectory { get; internal set; }

    [JsonProperty(PropertyName = "root")]
    public string Root { get; internal set; }

    [JsonProperty(PropertyName = "path")]
    public string Path { get; internal set; }

    [JsonProperty(PropertyName = "contents")]
    public IEnumerable<File> Contents { get; internal set; }

    //...
}

Example output:

Retrieving metadata works in exactly the same way as retrieving account information. With this code you are now armed to implement other Dropbox API requests. In the next part of this series I’ll explore some other requests concerning file operations (create, move and delete a folder).

Check out the Dropbox REST API documentation if you want to explore it further.

https://www.dropbox.com/developers/reference/api

You can download the source code accompanying this article from the download page. If you have any questions or suggestions please drop me an e-mail or submit a comment.

Top of page

I’ve been using Dropbox for about 6 months now. Before that I relied on Google Documents to share my files between the computers I use. Of course I had to login first and then I had to download them. Kind of a drag, certainly with big files.

With Dropbox that’s a thing of the past. Just install the client software and it will synchronize all of your files automatically. They are neatly downloaded into a local Dropbox folder on each of your computers. And only the parts of the file that actually changed are transferred, greatly reducing the download time.

Another neat feature is that other applications can use your Dropbox folder to store their data. For instance, I use a password manager (AgileBit’s 1Password) to securely save my login accounts. If I create a new account for a site on my laptop, then when I start my desktop it will automatically be known there once Dropbox has synched 1Password’s files (which is nearly instantanously).

This is made possible thanks to the Dropbox REST API. Let’s find out how we can use it…

Table Of Contents

• Introduction
• My Apps
• Request Token
• Authorize
• Access Token

My Apps

Before you can start, you first need to register your application with Dropbox. To do so, please follow these steps:

• Login to Dropbox
• Click on the link “Developers” which is displayed on the bottom (center) of the page
• Click on the link “My Apps” displayed in the menu on the left side
• Now click on the button “Create an App”

Choose a unique name for your application and select the appropriate access rights. You can lock your application in its own folder or you can grant it access to your entire Dropbox folder. Usually users don’t want to grant third-party applications access to their entire Dropbox folder so it’s best to choose the “App folder” option. However, since this is a demo I’ve choosen the “Full Dropbox” option. It will come in handy for later parts of this series.

Click Create to register your application. After you have created an application you’ll get two tokens, namely an app key and a secret. Here are mine (don’t worry…I’ve already deleted my app when you are reading this).

Keep those tokens nearby. You’ll need them when signing in to Dropbox.

Top of page

Request Token

Dropbox offers several SDKs for their REST API. Android, iOS, Java, Python and Ruby are all supported. Unfortunately there is no SDK for the .NET framework. Odd if you ask me, but not that big of an issue. There are some third party SDKs available, but let’s do the basic plumbling ourselves. A bit more work to do, but we’ll get there.

Before you can use the REST API you need to go through the authentication process. Dropbox requires that all requests are done over SSL and it uses OAuth to authenticate all of the API requests.

After you have completed the authentication process you’ll have an access token and access token secret. You can then use the access token for all the other requests. The authentication process consists out of three steps:

1. Request token: Obtain an OAuth request token to be used for the rest of the authentication process.
2. Authorize: The user must grant your application access to their Dropbox.
3. Access token: Once your application is authorized you can acquire an access token.

Let’s start by obtaining an OAuth request token. Start Visual Studio 2010 and create a new blank solution called Dropbox. Next add a console application to the solution titled ConsoleApplication. Coming up with original names, it’s important.

To quickly support OAuth I’ve downloaded a small, usefull library called OAuth. You can download it here:

http://code.google.com/p/oauth/

Download the C# version, it’s a single file (OAuthBase.cs) and add it to the console application project.

To request an OAuth request token you need to send a request to https://api.dropbox.com/1/oauth/request_token. You need to include the following parameters:

• oauth_consumer_key: Your API key
• oauth_nonce: A number used only once
• oauth_timestamp: Timestamp of the request
• oauth_signature_method: Signature method
• oauth_signature: Signature of the request. A hash to sign the request based on a couple of parameters.
• oauth_version: OAuth version used

There are no Dropbox specific parameters required for this request. Using the OAuth library you downloaded earlier this is pretty straightforward. First let’s generate a signature for the request.

var consumerKey = "your api key";
var consumerSecret = "your api secret";

var uri = new Uri("https://api.dropbox.com/1/oauth/request_token");

// Generate a signature
OAuthBase oAuth = new OAuthBase();
string nonce = oAuth.GenerateNonce();
string timeStamp = oAuth.GenerateTimeStamp();
string parameters;
string normalizedUrl;
string signature = oAuth.GenerateSignature(uri, consumerKey, consumerSecret,
    String.Empty, String.Empty, "GET", timeStamp, nonce, OAuthBase.SignatureTypes.HMACSHA1,
    out normalizedUrl, out parameters);

signature = HttpUtility.UrlEncode(signature);

You’ll wind up with a weird looking string like zwct8VZ469%2bLpmi9C8%2fVpghpk7w%3d. Now let’s issue the actual request.

StringBuilder requestUri = new StringBuilder(uri.ToString());
requestUri.AppendFormat("?oauth_consumer_key={0}&", consumerKey);
requestUri.AppendFormat("oauth_nonce={0}&", nonce);
requestUri.AppendFormat("oauth_timestamp={0}&", timeStamp);
requestUri.AppendFormat("oauth_signature_method={0}&", "HMAC-SHA1");
requestUri.AppendFormat("oauth_version={0}&", "1.0");
requestUri.AppendFormat("oauth_signature={0}", signature);

var request = (HttpWebRequest) WebRequest.Create(new Uri(requestUri.ToString()));
request.Method = WebRequestMethods.Http.Get;

var response = request.GetResponse();

Here we compose the URL including all the parameters (query string) and then we issue the request. Your URL should resemble the following pattern:

https://api.dropbox.com/1/oauth/request_token?oauth_consumer_key=your api key&oauth_nonce=9328214&oauth_timestamp=1325081302&oauth_signature_method=HMAC-SHA1&oauth_version=1.0&oauth_signature=OskIFg2iOhcVJ2qHGDN6VDXxUik%3d

Just make sure to use your own API (or consumer) key and secret. Let’s parse the response which includes a request token and request token secret. For instance:

oauth_token_secret=bdifrgl4si3if8w&oauth_token=cny4z2vkqpbqd6k

var response = request.GetResponse();

var queryString = new StreamReader(response.GetResponseStream()).ReadToEnd();

var parts = queryString.Split('&');
var token = parts[1].Substring(parts[1].IndexOf('=') + 1);
var tokenSecret = parts[0].Substring(parts[0].IndexOf('=') + 1);

Voila, using this crude “Hello, World”-ish code you can now complete step 1 of the authentication process. You now have a token and token secret which you can use to complete the authentication process.

Top of page

Authorize

Once you have an OAuth request token and secret it’s very simple to authorize your application. You only need to send a request to:

https://www.dropbox.com/1/oauth/authorize

This request only requires two parameters, namely the request token and secret you obtained earlier.

• oauth_token: the OAuth request token
• oauth_token_secret: the OAuth token secret

Resulting in a URL which looks like this:

https://www.dropbox.com/1/oauth/authorize?oauth_token_secret=yoursecret&oauth_token=yourtoken

Let’s start the authorization process:

var queryString = String.Format("oauth_token_secret={0}&oauth_token={1}", secret, token);
var authorizeUrl = "https://www.dropbox.com/1/oauth/authorize?" + queryString;
Process.Start(authorizeUrl);

This will open a new browser window. You’ll be asked to login to Dropbox. Once you have done so you can choose if you want to grant (authorize) your first Dropbox application access to your Dropbox folder.

Once you click on Allow the application will be added to the list of applications which can access your Dropbox. You can view this list in the My Apps section in your account. You can always revoke the access at a later time.

Top of page

Access Token

By now you have an OAuth access token and you have authorized your application so that it can access your Dropbox folder. Time to finish the authentication process. After the authorization step is complete you can acquire an access token.

This access token is needed to authenticate all the API requests. Once you have obtained such a token you can store it and reuse it later. You don’t need to go through the authentication process again. Just make sure to store the token securely, because it is required for all access to the user’s Dropbox folder.

Acquiring an access token is very similar to the first step. You must send a request to https://api.dropbox.com/1/oauth/access_token, including the following parameters:

• oauth_consumer_key: Your API key
• oauth_token: The OAuth token you obtained in step 1
• oauth_nonce: A number used only once
• oauth_timestamp: Timestamp of the request
• oauth_signature_method: Signature method
• oauth_signature: Signature of the request. A hash to sign the request based on a couple of parameters.
• oauth_version: OAuth version used

First let’s generate a signature for this request.

var consumerKey = "your api key";
var uri = "https://api.dropbox.com/1/oauth/access_token";

OAuthBase oAuth = new OAuthBase();

var nonce = oAuth.GenerateNonce();
var timeStamp = oAuth.GenerateTimeStamp();
string parameters;
string normalizedUrl;
var signature = oAuth.GenerateSignature(new Uri(uri), consumerKey, consumerSecret,
    oauthToken.Token, oauthToken.Secret, "GET", timeStamp, nonce,
    OAuthBase.SignatureTypes.HMACSHA1, out normalizedUrl, out parameters);

signature = HttpUtility.UrlEncode(signature);

Now you can send the request.

var requestUri = new StringBuilder(uri);
requestUri.AppendFormat("?oauth_consumer_key={0}&", consumerKey);
requestUri.AppendFormat("oauth_token={0}&", oauthToken.Token);
requestUri.AppendFormat("oauth_nonce={0}&", nonce);
requestUri.AppendFormat("oauth_timestamp={0}&", timeStamp);
requestUri.AppendFormat("oauth_signature_method={0}&", "HMAC-SHA1");
requestUri.AppendFormat("oauth_version={0}&", "1.0");
requestUri.AppendFormat("oauth_signature={0}", signature);

var request = (HttpWebRequest) WebRequest.Create(requestUri.ToString());
request.Method = WebRequestMethods.Http.Get;

Parsing the response will give you a return value which resembles this:

oauth_token_secret=95grkd9na7hm&oauth_token=ccl4li5n1q9b

var response = request.GetResponse();
var reader = new StreamReader(response.GetResponseStream());
var accessToken = reader.ReadToEnd();

var parts = accessToken.Split('&');
var token = parts[1].Substring(parts[1].IndexOf('=') + 1);
var secret = parts[0].Substring(parts[0].IndexOf('=') + 1);

You now have an access token and corresponding access token secret. The authentication process is now complete and you can use the access token and secret to sign requests for the main API calls.

Remark: Make sure to leave some time between step 2 and 3, so that the authorization step can succeed. You need to redirect the user to Dropbox so that they can authorize your application. You need to wait until the user has completed this step.

In part 2 of this series I’ll show you some examples of how you can use the acess token and secret to access the main Dropbox REST API.

I’ll try to get the next part online as soon as possible. You can download the source code accompanying this article from the download page. If you have any questions or suggestions please drop me an e-mail or submit a comment.

Top of page

Let’s finish up the Windows Phone programming series I started in October. The first part “Getting Started” guides you through the steps you need to follow in order to get up and running with Windows 7.5 (Mango) development. The second part is a quick guide on how you can easily create your own icons to brand your application. Please read them first if you haven’t done so yet.

It’s about time we actually made the application do something useful. For this I choose to use the small wrapper for the Stack Exchange API I made some time ago. It would be nice if I had a small application which allows me to check my StackOverflow profile.

You can download the code for my StackExchange API wrapper on the download page (2011: Article #58). As you’ll notice there are some things we’ll need to change in the existing code to make it work on a Windows Phone device.

Let’s get started…

Table Of Contents

• Introduction
• The Application
• The Solution
• Stack Exchange API
• Refactoring
• User Interface

The Application

Let’s have a look at the application we are going to build. It’s a simple application which only consists out of one page (MainPage.xaml). This page contains a pivot control which is composed out of two pages, namely:

• Profile page: Shows your profile (name, reputation, badges…etc.)
• Reputation page: Lists your reputation updates for the last X days

A picture is worth a thousand words, so take a look at the following screenshots.

Top of page

The Solution

Let’s start Visual Studio 2010 and create a new blank solution called StackOverflow. Next add a new project to it using the Windows Phone Application project template and call it StackOverflow.Phone.UI.

Make sure you target the Windows Phone 7.1 OS for all the projects in this solution. Visual Studio will ask this automatically when adding a new project.

Now you need to add a new Windows Phone Class Library named StackExchange.Api to the project. By now, your solution should resemble the following structure:

Top of page

Stack Exchange API

My small Stack Exchange API wrapper allows you to retrieve this data using just a few lines of code. We have to refactor it a bit to make it compatible with Silverlight for Windows Phone before we can use it.

Download the code (article #58: Stack Exchange API) from the download page. Extract the archive and copy / paste the following files into the directory of the StackOverflow.Api class library.

• BadgeCount.cs
• ExtensionMethods.cs
• ReputationChange.cs
• StackExchangeApi.cs
• UnixDateTimeConverter.cs
• User.cs
• WrapperObjectAttribute.cs

Afterwards include these files in the StackOverflow.Api project.

Next you need to add the Json.NET and SharpCompress NuGet packages to this class library.

Download and install the NuGet extension first if you don’t have it already. You need the Json.NET package because the Stack Exchange API wrapper uses it to serialize / deserialize the data and the SharpCompress provides GZip support for Silverlight. There is no native GZip (GZipStream) support in Silverlight.

Top of page

Refactoring

If you build the StackOverflow.Api project the compiler will throw some errors. Let’s fix them. By adding a reference to the SharpCompress assemblies you already fixed the missing GZipStream support. Just make sure you include the necessary namespaces in the StackExchangeApi.cs code file.

using SharpCompress.Compressor;
using SharpCompress.Compressor.Deflate;

Also remove the reference to the System.IO.Compression namespace.

The major issue with the current implementation is that everything is done synchronously such as retrieval of a user’s profile and his reputation changes. Silverlight requires you to do a lot things asynchronously. Retrieving a user’s profile in the following manner will not work anymore:

var api = new StackExchangeApi("your api key");
var user = api.GetUser(893099);

Let’s fix it. Open the StackExchangeApi file and add the following delegate to the StackExchangeApi class.

public delegate void StackExchangeApiCallback<T>(T data) where T : class, new();

Now change the signature of the GetUser(…) method as follows:

public void GetUser(int userId, StackExchangeApiCallback<User> callback)
{
    GetStackExchangeObject(String.Format("/users/{0}", userId), callback);
}

When retrieving a user’s profile you’ll notice that we no longer expect the method to return a value. Instead we pass it a callback (our StackExchangeApiCallback delegate). This callback will be triggered when the user’s profile has been retrieved. We won’t wait for it anymore. We expect to be informed of this event.

The GetUser(…) method passes the callback to the refactored GetStackExchangeObject(…) method. Let’s see how this method has been refactored to support asynchronous operations.

private void GetStackExchangeObject<T>(string path, StackExchangeApiCallback<T> callback)
    where T : class, new()
{
    var requestUri = ComposeUri(path);
    GetSingleObject(requestUri, callback);
}

private void GetSingleObject<T>(string requestUri, StackExchangeApiCallback<T> callback)
    where T : class, new()
{
    var request = (HttpWebRequest) WebRequest.Create(requestUri);
    request.Method = "GET";
    request.Accept = "application/json";

    request.BeginGetResponse(
        ar =>
            {
                var response = (HttpWebResponse)request.EndGetResponse(ar);
                var json = ExtractJsonResponse(response);
                var data = ParseJson<T>(json).FirstOrDefault();
                callback(data);
            },
        null);
}

First the URL to the Stack Exchange resource is determined and then the GetSingleObject(…) method retrieves the data asynchronously. When the data arrives it is parsed and deserialized and our callback is triggered.

Last but not least remove or comment the private GetResponse(…) method. It is no longer needed.

You can now retrieve a user’s profile in the following manner:

private void UserRetrieved(User user)
{
    //...
}

var api = new StackExchangeApi("your api key");
var callback = new StackExchangeApi.StackExchangeApiCallback<User>(UserRetrieved);
api.GetUser(893099, callback);

When the user’s profile has been retrieved the UserRetrieved(…) callback will be triggered. It retrieves an instance of the User type which contains the user’s profile.

The same problem (sync Vs async) exists for retrieving a user’s reputation changes, but the solution is similar to the fix for retrieving a profile. I won’t list it here, just take a look at the source code accompanying this article. I also expanded the wrapper a little bit so that it returns a bit more data for the user’s profile, reputation…etc. You can start from the old code and refactor it or you can just download the finished code. Here I just showed how you can refactor it. Just repeat it for the reputation updates and it’s done.

Top of page

User Interface

I’m not going to focus much on the actual user interface. As you can see in the screenshots above it’s a very simple interface. One page containing a pivot control which has two pages. One to display the user’s profile and another one to list his reputation updates.

The profile page contains a grid which lists the user’s name, reputation, views, age, badge count…etc. The reputation page contains a ListBox which lists the user’s reputation updates. Download the source and take a look at the XAML code if you want to explore it, but’s its really basic.

The application also contains an ApplicationBar which contains two icons. A refresh icon and a settings icon. I did not implement a settings page, I’ll leave that to you as an exercise. It’s just meant to be a simple settings page where you can enter your Stack Overflow user id. The sample code uses a hardcoded id. Feel free to improve on that and implement a settings page.

The code for the application is pretty simple. Just add a reference to the StackOverflow.Api library from the UI project. Just create an instance of the StackExchangeApi class.

public partial class MainPage : PhoneApplicationPage
{
    private StackExchangeApi _api;

    // Constructor
    public MainPage()
    {
        InitializeComponent();

        this._api = new StackExchangeApi("your api key");

        Loaded += MainPage_Loaded;
    }

    //...
}

Afterwards it’s really simple to load the data. Just create a callback and call the GetUser(…) method.

void MainPage_Loaded(object sender, System.Windows.RoutedEventArgs e)
{
    var callback = new StackExchangeApi.StackExchangeApiCallback<User>(UserRetrieved);
    this._api.GetUser(893099, callback);

}

void UserRetrieved(User user)
{
    Dispatcher.BeginInvoke(() =>
                                {
                                    DisplayName.Text = user.DisplayName;
                                    // ...
                                    BronzeBadges.Text = user.BadgeCounts.Bronze.ToString();
                                });
}

Just make sure to access the controls on the UI thread, hence the Dispatcher.BeginInvoke(…) call.

That’s about all it takes to quickly create a sample Windows Phone demo application using the Stack Exchange API. If you want more information on how this API was use please read the Stack Exchange API which I wrote a couple of months ago.

You can download the source code accompanying this article from the download page. If you have any questions or suggestions please drop me an e-mail or submit a comment.

Top of page

In the previous part of this series I mentioned that the next one would be about creating some icons for your Windows Phone application.

Took me about two weeks to get around to it. Been busy, switched employers and am now working for a client in Brussels. Happened to lose my phone on the train last Friday or it was stolen. I was in a Zombie-like state (it was early), so I don’t know. Remember putting it away, but when I did the 3 tap check [wallet - keys - phone] on the escalator it was gone … and so was my train by that time. I guess I won’t be deploying my apps any time soon.

Enough about me. Let’s create some icons. For a Windows Phone application you’ll need the following icons:

1. Application Icon (62 x 62)
2. Application Tile Image (173 x 173)
3. Marketplace catalog icon (small) (99 x 99)
4. Marketplate catalog icon (large) (173 x 173)
5. Desktop application icon (200 x 200)

Luckily we’ll be using the PNG format for all of them. Let’s get started.

Table Of Contents

• Introduction
• Preparation
• Base Layer
• Icon Placeholder
• The Icon
• Slices
• Using The Icons

Preparation

Since we are creating a small StackOverflow application it seems fitting to use their icon.

Hrm, it’s mostly gray and orange. That won’t display so nicely if you choose a conflicting theme color. For instance, here’s the icon with the Mango theme.

Urgh. Let’s make life easy and choose a color that works well with most all themes. Microsoft seems to prefer white, so let’s adjust our icon a bit. I used Photoshop CS2 for this purpose, but feel free to use any other graphics editing application. I just used what I know.

The easiest way in Photoshop, provided you have a good transparent image to work from is the following:

1. Start Photoshop
2. Open the image
3. Select everything and copy it to the clipboard
4. Create a new Photoshop file (make sure the background is transparent)
5. Paste
6. Double click the layer in the layers palette to select everthing in the layer
7. Press the ‘d’-key to reset the fore -and background colors to black and white
8. Press CTRL+Backspace to fill the selection with white

Voila, you now have a nice white Stackoverflow icon.

(Displayed here with a black background for contrast purposes.)

Go ahead and save the image as a PNG file. Make sure the background is transparent.

Top of page

Base Layer

The Photoshop work is done. Time to move to another graphics editing application. Go ahead and download the 60-day trial of Expression Studio 4 if you don’t have it installed.

Once installed, start it up and create a new document (File > New…) of 1024 x 1024 pixels. Sure the icon is smaller, but we’ll resize it later. It’s just handier to work with this way.

Draw a rectangle anywhere on the surface.

Then select a color from the Properties window in order to fill the rectangle. It doesn’t matter which color.

Now select the Selection tool (V) and resize the rectangle so that it fills the entire surface (1024 x 1024 pixels). Afterwards select the layer from the Layers palette and click the padlock icon to lock it. No more further modifications can be made to the layer while its locked.

Voila, you now have a 1024 x 1024 base layer. It’s almost like painting IRL.

In my case I ended up with a big red square.

Top of page

Icon Placeholder

Create a new layer. Click the cogwheel symbol in the layers palette and choose the option “New Layer”.

Draw a rectangle on the new layer and fill it with a color that contrasts well with the background layer. Once you’ve done this, you need to resize the rectangle (600 x 600) and center it.

Just select the rectangle and enter the following values in the transform options, which are displayed at the bottom of your screen.

First unlink the height and width (constrain ratio) by clicking upon the chain icon. Then set the W(idth) and H(eight) settings to 600. To center it set the X and Y-axis properties to 512.

Voila, you now have a placeholder in which you can put your icon. You should wind up with a design surface which looks like this (apart from the colors):

Top of page

The Icon

Time to put the actual icon in place. In Expression Design open (File > Open…) the file you created earlier with Photoshop (or your favorite graphical application). Once opened, select everything and copy the selection to the clipboard.

Close the file and go back to your icon design surface. Add a new layer and paste the icon. Now you need to resize and center it, just like you did with the icon placeholder.

• Unlink the width and height
• Set the width and height to 600
• Set the X and Y properties to 512

Your icon should now be neatly positioned within the icon placeholder.

Top of page

Slices

As mentioned before, you have to create 5 different icons. Let’s reuse the same icon! Time to create a slice for every type of icon needed.

First you need to adjust the layer which serves as the icon’s place holder. Set its opacity to 0%.

Now select the Selection tool (V) and drag a selection around the icon.

Time to create our first slice. Go to the Object menu and select the option “Create Slice from Selection”.

In the properties window that is displayed give the slice an appropriate name (e.g. Application Tile Image) and set its resize properties (e.g. 173 x 173).

Repeat this and create a slice for each of the different icons that you need.

Remark: When you create your first slice a new layer will be created (Slice Layer). Before creating a new slice be sure to turn off the visibility of the slices or otherwise they will be included in the new slice. You can toggle the visibility by clicking on the eye icon next to the layer in the layers palette.

Top of page

Using The Icons

OK, you are almost there. Time to export your work so that you can use the icon in Visual Studio. Click “File > Export…”. Select the slice you want to export and save them to a directory (e.g. the root of your project).

Once saved, go to Visual Studio and include the images in your Windows Phone project.

Then right-click on your project in the Solution Explorer, select properties and go to the Application tab. Here you can select which icon should be used for the application list and for the tile.

Voila, if you run your application now your custom icons will be displayed.

I learned this approach to creating Windows Phone icons from an article by Rick Engle. I customized it so it would fit my SO series, but you can find more information there. Certainly on how to create a better looking icon. But if you are creating an application for which icons are already available then this is a quick solution. Just create a white version of the icon and slice it up.

Remark: By default the title of the application is displayed on the application’s tile. When creating that slice you might want to resize the icon a bit so that you’ll a bit of room for the title to be displayed or it will be displayed across the icon.

If you want to skip this step, then just download the icons I prepared on the download page. It also includes the icons for the marketplace. Any suggestions or comments, feel free to contact me.

Top of page

Two weeks ago I wrote an article about using the Stack Exchange API. Turns out it got featured on Channel 9 last week. Cool.

In the video they wonder if there’s such a thing as a Stack Exchange application for the Windows Phone. There a few available, but it got me thinking if I could easily port the code to run on my Windows Phone.

I myself, haven’t developed much on the Windows Phone yet, apart from a few “Hello, World”-isch applications. Now that Mango (WP 7.5) has been officially released and I just reinstalled my PC, I figured this would be a good opportunity to get started with Windows Phone development.

Table Of Contents

• Introduction
• Mango Update
• Windows Phone SDK 7.1
• Hello, World
• Deploy To Device
• Up next, part 2

Mango Update

Maybe you haven’t updated your Windows Phone yet because the Mango update is not available for your region and/or carrier? Well, there’s a simple trick you can use to circumvent this. Who wants to wait weeks for new toys? Nobody! Just follow these steps:

1. Start Zune
2. Connect your phone to your PC
3. Have Zune check for an update for your phone
4. Disconnect your internet connection while Zune is checking for an update

First Zune will check if there is an update (Yes), and then it will perform a second check to see if you are permitted to install this update (region, carrier…etc. restrictions). Guess what happens if you disconnect from the internet between these two checks?

It may take a few tries, you have to be a bit lucky when you disconnect your internet connection. But if you hit the sweet spot, the second check will timeout and Zune will just report that there’s an update. If so, just connect back to the internet and proceed with the update.

Voila, that’s it. Worked for me on the first try (HTC Trophy). Be warned, updating your phone will take a long time. Get some coffee, sit back and relax.

Top of page

Windows Phone SDK 7.1

OK, we’re running Mango now. Now let’s make sure our development tools are also up to date. Open Chrome your favorite browser and navigate to http://create.msdn.com/en-US/. Next click on the “Download the free tools button”. You can’t miss it, it’s really big.

On the following page you can download the Windows Phone SDK 7.1 (Windows Phone 7.5/Mango = OS version 7.10.7720.68). The download (vm_web2.exe) is only 3 Mb. Once downloaded, start the setup and follow the wizard. Just click the big “Install Now” button.

Big buttons, its a key ingredient of the WP experience.

The setup will download about +/- 530 Megabytes of installation files. If you have a good broadband connection, the entire setup will take about 10 minutes or so. Afterwards you can find the installed tools in the Start menu (Start > All Programs).

Remark: Make sure you have the Visual Studio 2010 Service Pack 1 installed! You cannot install the Windows Phone SDK 7.1 without it!

Top of page

Hello, World!

We’re ready to go. Let’s create a “Hello, World!” application as a sort of a test drive. Start up Visual Studio 2010, create a new blank solution called WindowsPhone and add a new Windows Phone Application project titled HelloWorld to it.

You can find the Windows Phone Application project template in the “Silverlight for Windows Phone” folder (File > New Project).

When creating the project Visual Studio will ask which SDK (7.0 or 7.1) you want to target.

Select “Windows Phone OS 7.1″ and click OK.

The default project template contains one Windows Phone page (PhoneApplicationPage), called MainPage as you can see in the above screenshot.

You can compare it a bit to ASP.NET. It is composed out of two files, a XAML file (the layout) and a C# (.xaml.cs) file which contains the code behind. If you open the XAML file you’ll get a split screen layout. One part shows the XAML while the other part shows the rendered layout.

You can clearly see that the main page is divided into two sections. One section for the title and one for the body (marked with the red rectangle). Go to the toolbox and drag a Button and a TextBlock control to the body.

Give the controls some easy to remember names (e.g. MyButton, MyTextBlock).

Double click on the button control to generate a click event handler in the code behind file. Add the following code to the event handler.

private void MyButton_Click(object sender, RoutedEventArgs e)
{
    MyTextBlock.Text = "Hello, World!";
}

There, you just create your first Windows Phone application. Hit F5 to run the application. By default Visual Studio will start the Windows Phone emulator and deploy your application to it. Give it some time and your application will automatically start. Click on the button to change the TextBlock’s text.

Top of page

Deploy To Device

The emulator runs the same software as your Windows Phone device. Of course it cannot mimic certain hardware specific features (compass, gps, accelerometer…etc.), but for development purposes its a handy tool. However, Visual Studio lets you choose to where you want to deploy your application. The emulator or an actual device.

So, start the Zune software, hook up your device and unlock the wallpaper. Next choose the option “Windows Phone Device” in Visual Studio and run your project.

The exception “Failed to connect to device as it is developer locked. For details on developer unlock, visit http://go.microsoft.com/fwlink/?LinkId=195284.” will now be thrown.

In order to deploy to an actual device you need to unlock it. You need to create an App Hub account. Unfortunately this costs 99$/year, but for this price you can unlock up to 3 devices and also deploy your application to the market place.

After you’ve created an App Hub account you need to use the “Phone Developer Registration” tool. You can find this in the folder into which the Windows Phone SDK was installed (C:\Program Files\Microsoft SDKs\Windows Phone\v7.1\Tools\Phone Registration).

Afterwards you can deploy your applications to your device(s). This process does not actually modify anything on your device. It just registers in the cloud that it is now registered as a developer phone.

Top of page

Up next, part 2

During this series we are going to develop a small application which uses the Stack Exchange API to retrieve a user’s Stack Overflow profile (profile, badges and reputation). In the next part of this series, we’ll create some icons which we can use to brand our application.

For example:

I’ll try to get the next part online as soon as time permits. You can download the source code accompanying this article from the download page. If you have any questions or suggestions please drop me an e-mail or submit a comment.

Top of page

Two weeks ago I was playing around with the Stack Exchange API to see if it was easy to build a custom flair application. You know, this little guy:

How hard can it be to retrieve a user’s profile, badge count and reputation updates? Surely, Stack Exchange has an API. And they do…and it’s pretty easy to use. Let’s quickly cobble together a small sample application.

Table Of Contents

• Introduction
• API Usage
• User Profile
• Sending Requests
• Reputation Changes

API Usage

You can find the documentation for the Stack Exchange API here:

http://api.stackoverflow.com/

At the time of writing the latest release is v1.1, but a draft specification for version 2.0 has just been released.

What do you need to know about the API?

• It’s read-only
• All API responses are JSON
• All responses are GZIP’d
• API usage is throttled by IP address

API usage is throttled? Yup, each IP address gets 300 daily requests (No matter how many applications you run behind this IP address). However, if you register your application you receive an API key and you get 10.000 daily requests. You just need to append this key to each of your requests.

Each response you receive includes your maximum and current limits. Those numbers are stored in the HTTP headers. Let’s inspect them (X-RateLimit-Max & X-RateLimit-Current).

You’d expect the X-RateLimit-Current count to decrement by 1 with each request, however sometimes you’ll receive duplicate numbers. I reported this on StackApps, but haven’t received a reply as to why this happens.

So what do we need to be able to use the API?

• It talks JSON? Fire up NuGet and get the popular Json.NET library.
• We’ll need to issue requests. Let’s keep it simple and use the HttpWebRequest class
• All responses are GZIP’d? Luckily the .NET framework provides us with the GZipStream class.

Time for action.

Top of page

User Profile

Let’s start by retrieving the user’s profile. You can retrieve it using the “users/{id}” API method. It takes a bunch of parameters, but we are only interested in one parameter, namely the user id (id parameter).

Just type in the following URL in your address bar to see an example response:

http://api.stackoverflow.com/1.1/users/893099

It looks something like this (I’ve shortened it here for illustrative purposes):

{
  "total": 1,
  "page": 1,
  "pagesize": 30,
  "users": [
    {
      "user_id": 893099,
      "user_type": "registered",
      "display_name": "Christophe Geers",
      "reputation": 1581,
      "last_access_date": 1317546569,
      "location": "Belgium",
      "badge_counts": {
        "gold": 0,
        "silver": 1,
        "bronze": 10
      }
    }
  ]
}

You can retrieve a profile for one or more users with a single request. Most of the API’s methods are vectorized. They accept multiple values within a single parameter on a request. You just need to separate them by semi-colons.

The format for a response is alway the same, they are paged. At the root you’ll find the paging information (total, page, pagesize) and then you’ll find an array which contains the information you requested. Here this information is contained within the users array. Take a mental note of this, we’ll get back to it later.

Let’s create a simple class into which we can deserialize a user’s profile. It’s decorated with attributes so we can easily deserialize / serialize it using Json.NET.

[WrapperObject("users")]
[JsonObject(MemberSerialization.OptIn)]
public class User
{
    [JsonProperty(PropertyName = "user_id")]
    public int Id { get; internal set; }

    [JsonProperty(PropertyName = "display_name")]
    public string DisplayName { get; internal set; }

    [JsonProperty(PropertyName = "reputation")]
    public int Reputation { get; internal set; }

    [JsonProperty(PropertyName = "badge_counts")]
    public BadgeCounts BadgeCounts { get; set; }
}

The BadgeCount class looks like this:

[JsonObject(MemberSerialization.OptIn)]
public class BadgeCounts
{
    [JsonProperty(PropertyName = "gold")]
    public int Gold { get; set; }

    [JsonProperty(PropertyName = "silver")]
    public int Silver { get; set; }

    [JsonProperty(PropertyName = "bronze")]
    public int Bronze { get; set; }
}

Did you notice the WrapperObject attribute on the User class? This is just a simple attribute that contains the name of the array in the JSON response which contains the data we are interested in. We’ll need this when deserialing the data.

[AttributeUsage(AttributeTargets.Class, AllowMultiple = false, Inherited = false)]
public class WrapperObjectAttribute : Attribute
{
    public WrapperObjectAttribute(string wrapperObject)
    {
        this.WrapperObject = wrapperObject;
    }

    public string WrapperObject { get; set; }
}

Top of page

Sending Requests

Ok, we’ve layed the foundation. Time to send a request which retrieves the user’s profile. Create a class called StackExchangeApi and add the following code to it.

public class StackExchangeApi
{
    private const string ApiVersion = "1.1";
    private const string BaseUri = "http://api.stackoverflow.com/" + ApiVersion;
    private readonly string _apiKey;

    public StackExchangeApi(string apiKey)
    {
        this._apiKey = apiKey;
    }

    public User GetUser(int userId)
    {
        return GetStackExchangeObject<User>(
            String.Format("/users/{0}", userId));
    }
}

To retrieve a user’s profile the consumer of this class only has to write two lines of code.

var api = new StackExchangeApi("your api key");
var user = api.GetUser(893099);

Let’s complete the StackExchangeApi class. Add the private method GetStackExchangeObject(…) to this type.

private T GetStackExchangeObject<T>(string path) where T : class, new()
{
    var requestUri = ComposeUri(path);
    var json = GetResponse(requestUri);
    return ParseJson<T>(json).FirstOrDefault();
}

The GetStackExchangeObject(…) method’s responsibility is to retrieve one object from a response. For the GetUser(…) method we are only interested in one single user profile.

First it composes the Uri (http://api.stackoverflow.com/1.1/users/893099?key=YourApiKey) it needs to call using the ComposeUri(…) method.

private string ComposeUri(string path)
{
    var uri = String.Format("{0}{1}", BaseUri, path);
    if (!String.IsNullOrWhiteSpace(this._apiKey))
    {
        var separator = uri.Contains("?") ? "&" : "?";
        uri = String.Format("{0}{1}key={2}", uri, separator, this._apiKey);
    }
    return uri;
}

Then it actually sends out the request and parses the response (GetResponse(…) method).

private string GetResponse(string requestUri)
{
    var request = (HttpWebRequest) WebRequest.Create(requestUri);
    request.Method = WebRequestMethods.Http.Get;
    request.Accept = "application/json";
    var json = ExtractJsonResponse(request.GetResponse());
    return json;
}

It uses a simple HttpWebRequest to send the request. Afterwards you need to extract the JSON data from the response. Remember that all the responses are GZIP’d. Let’s examine the ExtractJsonRespone(…) method.

private string ExtractJsonResponse(WebResponse response)
{
    string json;
    using (var outStream = new MemoryStream())
    using (var zipStream = new GZipStream(response.GetResponseStream(),
        CompressionMode.Decompress))
    {
        zipStream.CopyTo(outStream);
        outStream.Seek(0, SeekOrigin.Begin);
        using (var reader = new StreamReader(outStream, Encoding.UTF8))
        {
            json = reader.ReadToEnd();
        }
    }
    return json;
}

The HttpWebRequest instance returns the response in the form of a stream. By wrapping this stream in a GZipStream we can easily unzip the response and get a hold of the JSON data.

OK, we’ve got the JSON data. Now we need to to deserialize it into a User instance. This is were the generic parameter passed to the GetStackExchangeObject(…) method comes into play. The GetUser(…) method passed the User type to it. This is then passed on to the ParseJson(…) method.

private static IEnumerable<T> ParseJson<T>(string json) where T : class, new()
{
    var type = typeof (T);
    var attribute = type.GetCustomAttributes(
        typeof (WrapperObjectAttribute), false).SingleOrDefault() as
        WrapperObjectAttribute;
    if (attribute == null)
    {
        throw new InvalidOperationException(
            String.Format("{0} type must be decorated with a
            WrapperObjectAttribute.", type.Name));
    }

    var jobject = JObject.Parse(json);
    var collection = JsonConvert.DeserializeObject<List<T>>
        (jobject[attribute.WrapperObject].ToString());
    return collection;
}

The ParseJson(…) method first checks if you decorated the type (T) with a WrapperObjectAttribute. It needs this information so that it knows the name of the array in the JSON response which actually contains the data we are interested in. Then it deserializes this array to a collection of T (List<T>). The GetStackExchangeObject(…) method then returns the first object contained within this collection. Since we only requested the profile for one user it only contains one object.

It’s now very easy to retrieve a user’s profile.

var api = new StackExchangeApi("your api key");

var user = api.GetUser(893099);

Console.WriteLine(String.Format("User id: {0}", user.Id));
Console.WriteLine(String.Format("Display name: {0}", user.DisplayName));
Console.WriteLine(String.Format("Reputation: {0}", user.Reputation));
Console.WriteLine(String.Format("Golden badges: {0}", user.BadgeCounts.Gold));
Console.WriteLine(String.Format("Silver badges: {0}", user.BadgeCounts.Silver));
Console.WriteLine(String.Format("Bronze badges: {0}", user.BadgeCounts.Bronze));
Console.WriteLine();

The output:

Top of page

Reputation Changes

Ok, we’ve got the user’s profile. Now let’s get a list of his / her reputation changes (or updates). You can retrieve this information using the “/users/{id}/reputation” API method.

A response looks as follows:

{
 "total": 59,
 "page": 1,
 "pagesize": 30,
 "rep_changes": [
  {
   "user_id": 893099,
   "post_id": 7555096,
   "post_type": "answer",
   "title": "Json.Net - Serialize property name without quotes",
   "positive_rep": 30,
   "negative_rep": 0,
   "on_date": 1317147319
  },
  {
   "user_id": 893099,
   "post_id": 7546079,
   "post_type": "answer",
   "title": "developer manuals",
   "positive_rep": 35,
   "negative_rep": 0,
   "on_date": 1317122274
  }]
}

The data we are interested in is stored in the rep_changes array. However, this time were are interested in all the items of this array. Let’s create a simple C# class in which we can store a reputation change.

[WrapperObject("rep_changes")]
[JsonObject(MemberSerialization.OptIn)]
public class ReputationChange
{
    [JsonProperty(PropertyName = "user_id")]
    public int UserId { get; set; }

    [JsonProperty(PropertyName = "post_id")]
    public int PostId { get; set; }

    [JsonProperty(PropertyName = "post_type")]
    public string PostType { get; set; }

    [JsonProperty(PropertyName = "title")]
    public string Title { get; set; }

    [JsonProperty(PropertyName = "negative_rep")]
    public int NegativeReputation { get; set; }

    [JsonProperty(PropertyName = "positive_rep")]
    public int PossitiveReputation { get; set; }

    [JsonProperty(PropertyName = "on_date")]
    [JsonConverter(typeof(UnixDateTimeConverter))]
    public DateTime OnDate { get; set; }
}

Remark: The UnixDateTimeConverter type is not a default Json.NET converter. It’s a custom converter I created that’s able to deserialize / serialize Unix timestamps. Read my previous post “Writing a custom Json.NET DateTime Converter” to see how it works.

We’re almost there. Add the following method to the StackExchangeApi class.

public IEnumerable<ReputationChange> GetReputationChanges(int userId,
  DateTime fromDate, DateTime toDate)
{
    var path = String.Format(
        "/users/{0}/reputation?fromdate={1}&todate={2}", userId,
        fromDate.ToUnixTime(), toDate.ToUnixTime());

    return GetStackExchangeObjects<ReputationChange>(path);
}

You can now easily retrieve the user’s reputation changes. For example, let’s retrieve the updates for the last two weeks:

var api = new StackExchangeApi("your api key");
var reputation = api.GetReputationChanges(893099,
    DateTime.Now.AddDays(-14), DateTime.Now);

The private GetStackExchangeObjects(…) method called by the ReputationChanges method is almost identical to the GetStackExchangeObject(…) method. It reuses all the code we wrote earlier, but it returns a collection of T instead of a single T.

private IEnumerable<T> GetStackExchangeObjects<T>(string path) where T : class, new()
{
    var requestUri = ComposeUri(path);
    var json = GetResponse(requestUri);
    return ParseJson<T>(json);
}

Voila, that’s it. You can now retrieve a user’s reputation changes.

var api = new StackExchangeApi("your api key");
var reputation = api.GetReputationChanges(893099,
    DateTime.Now.AddDays(-14), DateTime.Now);
foreach(var change in reputation)
{
    Console.WriteLine(String.Format("{0}: {1} +{2} -{3}",
    change.OnDate, change.Title,
    change.PossitiveReputation,
    change.NegativeReputation));
}

The output:

You can now easily retrieve a user’s profile and reputation changes. You can add support for the remaining API methods if you like. To implement them just follow the same pattern as shown here.

You can download the source code accompanying this article from the download page. If you have any questions or suggestions please drop me an e-mail or submit a comment.

Top of page

Last weekend I was playing around with the Stack Exchange API. All the API responses are expressed in JSON. So I decided to use the Json.NET library to easily deserialize the JSON responses into simple .NET objects.

This library has great support for deserialing JSON into .NET objects and serializing them back into JSON. For example, if you want to serialize an object to a JSON string all you have to do is decorate the type with some attributes.

For example:

[JsonObject(MemberSerialization.OptIn)]
public class Person
{
  [JsonProperty]
  public string Name { get; set; } 

  [JsonProperty]
  [JsonConverter(typeof(IsoDateTimeConverter))]
  public DateTime BirthDate { get; set; }
}

Notice that for the BirthDate property a specific converter is specified (IsoDateTimeConverter). Sometimes it is not enough to tell Json.NET which properties should be serialized. You need to help it out a bit and inform it how the properties should be serialized / deserialized. Here the IsoDateTimeConverter informs Json.NET that it should serialize the birthdate into an ISO 8601 date format.

The Stack Exchange API uses Unix timestamps to express all of its timestamps. Out of the box Json.NET does not contain a converter that can handle this notation for DateTime properties. But luckily we can create our own. It’s actually very easy, let’s see how we can do this…

Table Of Contents

• Introduction
• JSON Response
• ReputationChange Class
• UnixDateTimeConverter Class
• Demo

JSON Response

Let’s use one of the responses from the StackExchange API to test our custom DateTime converter. For one call (/users/{id}/reputation), the StackExchange API returns the following JSON string:

{
    "user_id": 893099,
    "post_id": 7539201,
    "title": "UserControl custom property grayed?",
    "positive_rep": 35,
    "on_date": 1316873139
}

Notice that the on_date property property is expressed as a Unix timestamp.

Remark: The actual response is quite a bit longer, and slightly more complicated. I shortened it for this demo. Check ouf the /users/{id}/reputation API method if you are interested in the full response.

Top of page

ReputationChange Class

Let’s create a simple class in which we can deserialize this JSON string.

[JsonObject(MemberSerialization.OptIn)]
public class ReputationChange
{
    [JsonProperty(PropertyName = "user_id")]
    public int UserId { get; set; }

    [JsonProperty(PropertyName = "post_id")]
    public int PostId { get; set; }

    [JsonProperty(PropertyName = "title")]
    public string Title { get; set; }

    [JsonProperty(PropertyName = "positive_rep")]
    public int PossitiveReputation { get; set; }

    [JsonProperty(PropertyName = "on_date")]
    [JsonConverter(typeof(UnixDateTimeConverter))]
    public DateTime OnDate { get; set; }
}

As you can see, the OnDate property has been decorated with a new attribute. A new type of converter, namely the UnixDateTimeConverter type. Let’s see what makes it tick.

Top of page

UnixDateTimeConverter Class

If you want to create your own Json.NET convertor you must create a new type which descends from the abstract JsonConverter type. However, for converting a DateTime to and from JSON the library provides the abstract DateTimeConverterBase type which already does some of the plumbing for you.

public class UnixDateTimeConverter : DateTimeConverterBase
{
  //...
}   

To create your own DateTime converter you must override two methods, namely:

• ReadJson(JsonReader, Type, Object, JsonSerializer): Reads the JSON representation of the object.
• WriteJson(JsonWriter, Object, JsonSerializer): Writes the JSON representation of the object.

Let’s start with parsing the JSON representation of a Unix timestamp into a valid DateIime structure.

public override object ReadJson(JsonReader reader, Type objectType, object existingValue,
    JsonSerializer serializer)
{
    if (reader.TokenType != JsonToken.Integer)
    {
        throw new Exception(
            String.Format("Unexpected token parsing date. Expected Integer, got {0}.",
            reader.TokenType));
    }

    var ticks = (long) reader.Value;

    var date = new DateTime(1970, 1, 1);
    date = date.AddSeconds(ticks);

    return date;
}

The ReadJson(…) method is called by Json.NET when it needs to parse the JSON string that contains the value for your DateTime. The reader (JsonReader) instance is already correctly positioned.

The Unix time contains the number of seconds that elapsed since midnight (UTC) of January 1, 1970. So first we make sure if we are dealing with a valid integer and if so, we add the number of seconds to January 1, 1970.

Now we also need to be able to serialize a DateTime into a valid JSON string. Time ot override the WriteJson(…) method.

public override void WriteJson(JsonWriter writer, object value,
    JsonSerializer serializer)
{
    long ticks;
    if (value is DateTime)
    {
        var epoc = new DateTime(1970, 1, 1);
        var delta = ((DateTime) value) - epoc;
        if (delta.TotalSeconds < 0)
        {
            throw new ArgumentOutOfRangeException(
                "Unix epoc starts January 1st, 1970");
        }
        ticks = (long) delta.TotalSeconds;
    }
    else
    {
        throw new Exception("Expected date object value.");
    }
    writer.WriteValue(ticks);
}

Now we take our DateTime and calculate the amount of seconds that passed since January 1, 1970. Then we write this value out to the JsonWriter instance that the Json.NET library provides to us.

Top of page

Demo

Let’s see it in action. I created a simple console application for this and stored some JSON data in a text file instead of directly contacting the StackExchange API.

// Read JSON data
var json = File.ReadAllText("json.txt");
Console.WriteLine(json);
Console.WriteLine();

// Deserialize JSON into ReputationChange object                        
var reputation = JsonConvert.DeserializeObject<ReputationChange>(json);
Console.WriteLine(reputation.OnDate);
Console.WriteLine();

The result:

Let’s serialize the ReputationChange object back to a JSON string.

// Serialize ReputationChange object back into JSON
json = JsonConvert.SerializeObject(reputation);
Console.WriteLine(json);

The result:

Voila, thanks to the custom UnixDateTimeConverter converter you can easily deserialize a Unix timestamp into a DateTime and serialize it back to a JSON string. That about wraps up this short article. You can download the source code accompanying this article from the download page. If you have any questions or suggestions please drop me an e-mail or submit a comment.

Tip: A good way to figure out how to write your own converter is to download the source code of the Json.NET library from CodePlex. Just take a look at how the existing converters were written and start from there. And of course the official documentation will also help you out.

Have fun with serializing all the things!

Top of page

Yesterday on StackOverflow I came across a question about using the Google Data API (also called GData) in .NET. Questions about it regularly pop up. Retrieving my Google data in .NET somehow seems appealing to me, but maybe that’s just me. I never worked with it before, so I took some time to experiment with it a bit. Figured I’d better write it down, before I forget it again. This article is a quick introduction on using the Google Data API with the .NET Framework…so, let’s get started…

Table Of Contents

• Introduction
• Google Data .NET Client Library
• Project Templates
• Google Project Template
• Using The Client Library

Google Data .NET Client Library

Google offers official client libraries for GData for several programming languages such as Java, .NET, Phyton and Objective-C (they even have a partial library for JavaScript). So the first thing you have to do, is to download the .NET client library from code.google.com.

You can download the .NET client library (+/- 27.7 Mb) here:

http://code.google.com/p/google-gdata/

At the time of writing the most recent version is 1.9.0.0. Under the downloads section just select the MSI installation wizard package. Installing the SDK is really simple. Just click next three times and close once and you’re done.

Tip: Instead of installing the MSI install NuGet instead and add a reference to the Google Data API packages. Google Inc. was kind enough to make them available as NuGet packages. Each assembly of the Google Data Client library has been put in a seperate package. You can view a list of these packages here.

Remark: If you don’t install the MSI you won’t get the Visual Studio project templates that come with it. The next two parts of this text discuss these templates, so if you want to follow along, it is best to download and install the MSI. You can always switch to the NuGet packages later.

Top of page

Project Templates

Before you rush off and start Visual Studio 2010 you need to fix a small thing. Open Windows Explorer and navigate to the “My Documents” library and open the Visual Studio 2008 project templates folder. In this folder you’ll notice a new folder called “Google”, if you open it you’ll notice it contains seven new project templates.

My Documents > Visual Studio 2008 > Templates > ProjectTemplates > Visual C# > Google

Now you need to copy the Google folder over to the Visual Studio 2010 project templates folder (My Documents > Visual Studio 2008 > Templates > ProjectTemplates > Visual C# &gt).

If you start Visual Studio 2010 now and create a new project you’ll notice that it contains the new Google project templates.

Top of page

Google Project Template

Let’s play around with one of the Google project templates. Create a new project and select the Google Contacts project template. Let’s be *original* and call it “Google Contacts”.

Most of the Google project templates contain the same structure. It’s a simple Windows Forms application that contains two forms. A login form and another one that displays the data (contacts, calender, photos…) you are querying.

If you start the application it will ask you to enter your Google account details.

After logging in it will display a simple form that lists the first 25 people found in your contacts list.

Remark: I replaced the actual names in my contacts list for this demo. I don’t really know that many people named “John Smith”.

Feel free to explore the other Google Project Templates. They are all very similar.

Top of page

Using The Client Library

Querying data with the Google Data API usually consists out of three steps:

1. Setup a connection with the API (Google.GData.Client.Service)
2. Query the API (Google.GData.Contacts.ContactsQuery)
3. Iterate the returned data feed (Google.GData.Contacts.ContactsFeed)

Let’s demonstrate how this is done by building a small console application that downloads the contacts just like Google’s own project template does.

Start up Visual Studio 2010, create a new blank solution called Google and add a new console application project called Contacts.

Add a reference to the following assemblies provided by the Google Data .NET Client library:

• Google.GData.Client.dll
• Google.GData.Contacts.dll
• Google.GData.Extensions.dll

Or use NuGet to add a reference to the packages that contain these assemblies. The packages are named the same as the assemblies so you can’t miss them.

First create a new service instance and give it a name (doesn’t really matter how you name it).

Service service = new ContactsService("My Contacts Application");

Then you must request an authentication token.

service.setUserCredentials("your_email_address_here@gmail.com", "yourpassword");
var token = service.QueryClientLoginToken();
service.SetAuthenticationToken(token);

After you’re authenticated you can compose a query to request the contact data.

var uri = ContactsQuery.CreateContactsUri("your_email_address_here@gmail.com");
var query = new ContactsQuery(uri);

Now you are ready to request the data.

ContactsFeed feed = (ContactsFeed) service.Query(query);
foreach(ContactEntry contact in feed.Entries)
{
    Console.WriteLine(contact.Title.Text);
}

The previous code sample requests the first 25 contacts and writes their names to the console output. The Google Data API automatically chunks your data into several pieces. Just check the feed’s NextChunk property to check if there is more data available. If there is, you can create and execute a new query to retrieve the next chunk of data.

if (!String.IsNullOrEmpty(feed.NextChunk))
{
    query = new ContactsQuery(feed.NextChunk);
    feed = (ContactsFeed) service.Query(query);
}

Voila, you can now download your Google contact data. If you don’t want to copy/paste these code samples you can always download the source code from the download page. Just alter the code to make sure valid credentials are used.

That wraps it up. If you want to further explore the Google Data .NET Client library be sure to check out the help file (*.chm) which is installed if you use the MSI installation wizard. It contains information on all of the classes, members, constructors, properties…etc. that are available in the SDK.

Reference docs about the .NET client library are also available online. You can find them here:

http://google-gdata.googlecode.com/svn/docs/Index.html

If you have any questions or suggestions please drop me an e-mail or submit a comment.

Top of page

You all know the default page you get when you enter a WCF service’s URL in a browser (e.g. http://localhost/Service.svc). You are greeted by a blue and white (mostly white) screen that informs you that you have just created a service.

(Sorry for the Dutch localization in the screenshot.)

So apart from informing you that you have created a service (handy if you suffer from alzheimer), it also tells you where you can find the WSDL (just append ?wsdl), how to generate proxy classes and how to use these proxies.

That’s all fine, but you know all of this stuff already. Besides, you don’t want to display this message on public-facing services. Time to get rid of it.

Table Of Contents

• Introduction
• Hello, World!
• Service Metadata
• Unmatched Message Handler
• Custom Landing Page
• Service Host
• Content Type
• Further Customization

Hello, World!

Instead of the default generated landing page which is displayed when you enter the service’s address in a browser I want to display a custom page. To showcase the custom page I created a simple “Hello, World!”-isch service.

[ServiceContract]
public interface IHelloWorld
{
    [OperationContract]
    string SayHi(string name);
}

The service’s implementation could not be any simpler.

public class HelloWorld : IHelloWorld
{
    public string SayHi(string name)
    {
        return String.Format("Hello, {0}.", name);
    }
}

Let’s add some configuration to the application’s configuration file (Web.config / app.config).

<system.serviceModel>
  <services>
    <service name="WcfServiceLibrary.HelloWorld">
      <endpoint address="HelloWorld"
                binding="basicHttpBinding"
                contract="WcfServiceLibrary.IHelloWorld"/>
      <endpoint address="mex"
                binding="mexHttpBinding"
                contract="IMetadataExchange" />
      <host>
        <baseAddresses>
          <add baseAddress="http://localhost:8732/Service"/>
        </baseAddresses>
      </host>
    </service>
  </services>
  <behaviors>
    <serviceBehaviors>
      <behavior>
        <serviceMetadata httpGetEnabled="true"/>
        <serviceDebug includeExceptionDetailInFaults="false"/>
      </behavior>
    </serviceBehaviors>
  </behaviors>
</system.serviceModel>

If you navigate to the service’s address (http://localhost:8732/HelloWorld/) you get the default landing page.

Top of page

Service Metadata

Let’s stop exposing the metadata first. Just set the httpGetEnabled property of your service behavior to false.

<configuration>
  <system.serviceModel>
    <behaviors>
      <serviceBehaviors>
        <behavior name="...">
          <serviceMetadata httpGetEnabled="true" />
        </behavior>
      </serviceBehaviors>
    </behaviors>
  </system.serviceModel>
</configuration>

Well, that was easy. If you navigate to the address’ URL now, you’ll still see the same page, but this time no URL pointing to the service’s WSDL. “Ha…I’ll manually append ‘?wsdl’ to the URL” you say? Try it, you’ll get a blank page and nothing more. While you are it, at also remove the metadata exchange (mex) endpoint from the service.

Top of page

Unmatched Message Handler

Let’s create a custom landing page. To do so, you need to create a new service contract called ILandingPage.

[ServiceContract]
public interface ILandingPage
{
    [OperationContract(Action="*", ReplyAction="*")]
    Message Index();
}

This service operation handles all messages that cannot be directed to a service operation. This is done by specifying an asterisk (*) as the value for the Action property of the OperationContract attribute.

This is also called an unmatched message handler. One of the conditions is that it can only take a parameter of the type Message and either returns void or also an instance of the Message type. Here we’re only interested in the return message which represents the custom landing page.

The implementation for this new service contract is quite simple. Just have the service for which you want to create a custom landing page implement it.

public class HelloWorld : IHelloWorld, ILandingPage
{
    //...

    public Message Index()
    {
        return new LandigePageMessage();
    }
}

Just have it return a new descendant of the Message type which represents your custom landing page. In this case I called it LandingPageMessage.

Top of page

Custom Landing Page

Time to create the custom Message descendant for the custom landing page.

public class LandingPageMessage: Message
{
    private readonly MessageHeaders _headers;
    private readonly MessageProperties _properties;

    public LandigePageMessage()
    {
        this._headers = new MessageHeaders(MessageVersion.None);
        this._properties = new MessageProperties();
    }

    public override MessageHeaders Headers
    {
        get { return this._headers; }
    }

    public override MessageProperties Properties
    {
        get { return this._properties; }
    }

    public override MessageVersion Version
    {
        get { return this._headers.MessageVersion; }
    }

    protected override void OnWriteBodyContents(XmlDictionaryWriter writer)
    {
        writer.WriteStartElement("HTML");
        writer.WriteStartElement("HEAD");
        writer.WriteStartElement("BODY");
        writer.WriteStartElement("SPAN");
        writer.WriteString("This is a test page.");
        writer.WriteEndElement();
        writer.WriteEndElement();
        writer.WriteEndElement();
        writer.WriteEndElement();
    }
}

The new LandingPageMessage type implements all of the abstract members of the Message type. This is quite straightforward. Only the OnWriteBodyContents(…) method contains a bit of logic. Here you can generate some HTML output using the XmlDictionaryWriter object which is passed into this method.

Time to update the application’s configuration file. First add a new endpoint to the service.

<service name="WcfServiceLibrary.HelloWorld">
  <endpoint address="HelloWorld"
            binding="basicHttpBinding"
            contract="WcfServiceLibrary.IHelloWorld"/>
  <endpoint address=""
            binding="customBinding"
            bindingConfiguration="landingPage"
            contract="WcfServiceLibrary.ILandingPage"/>
  <host>
    <baseAddresses>
      <add baseAddress="http://localhost:8732/Service"/>
    </baseAddresses>
  </host>
</service>

As you can see the new endpoint uses a custom binding, which is declared as follows:

<bindings>
  <customBinding>
    <binding name="landingPage">
      <textMessageEncoding messageVersion="None"/>
      <httpTransport/>
    </binding>
  </customBinding>
</bindings>

Top of page

Service Host

To test the “Hello, World!” service I quickly created a console application to act as the service host. Apart from an application configuration file (App.config) which contains the configuration code listed so far, it only contains the following lines of code:

class Program
{
    static void Main()
    {
        var service = new ServiceHost(typeof (HelloWorld));
        service.Description.Behaviors.Remove<ServiceDebugBehavior>();
        service.Open();

        Console.WriteLine("Service started.");
        Console.ReadKey();
    }
}

The ServiceDebugBehavior is removed from the behaviors of the service to ensure the custom page will be shown.

After you start the host application and open the service’s URL (http://localhost:8732/Service) in a browser you’ll get the following page instead:

Top of page

Content Type

Hrm, why is the custom landing page being treated as an XML document? Let’s open the page in FireFox and see what FireBug has to tell.

The content type is “application/xml; charset=utf-8″? That’s not right. Luckily this can easily be fixed using the WebOperationContext helper class. Add a reference to the System.ServiceModel.Web assembly for the project which contains your service and update the implementation of ILandingPage’s Index method as shown in the following code sample:

public Message Index()
{
    var context = WebOperationContext.Current;
    context.OutgoingResponse.ContentType = "text/html";
    return new LandingPageMessage();
}

Restart the host application and refresh your browser. Now the landing page will be shown correctly because you specified “text/html” as the content type instead of defaulting to “application/xml”.

Top of page

Further Customization

Personally I don’t want to create a HTML page by building it in code using a XmlDictionaryWriter object. Notepad should be enough. So let’s do just that. Open Notepad and create a simple HTML page.

For example:

<html>
  <head>
    <title></title>
  </head>
  <body>
    <div style="background-color: yellow; border: 1px solid black;">
      This is a test.
    </div>
  </body>
</html>

Save the HTML file (e.g. Default.htm) and add it to the project which contains your WCF service.

Be sure to set its “Copy to Output Directory” property to “Copy Always”.

Next its time to refactor the OnWriteBodyContents(…) method of the CustomLandingPage type. Just replace the existing code with the following lines of code:

protected override void OnWriteBodyContents(XmlDictionaryWriter writer)
{
    var document = new HtmlDocument();
    document.Load("Default.htm");

    var bodyNode = document.DocumentNode.SelectSingleNode("//html");
    writer.WriteStartElement("HTML");
    writer.WriteRaw(bodyNode.InnerHtml);
    writer.WriteEndElement();
}

Here the HTML document which you created earlier is parsed and its contents are being written to the XmlDictionaryWriter object. If you restart the host application once more and visit the service’s base URL in a browser you’ll see that your custom HTML page will be displayed.

Remark: In order to parse the HTML document I used the HTML Agility Pack which can be downloaded from CodePlex or NuGet.

That about wraps it up. Hope you enjoyed the article. You can download the source code accompanying this article from the download page. If you have any questions or suggestions please drop me an e-mail or submit a comment.

Top of page

In the previous parts of the TeamCity series I discussed how you can configure the TeamCity CI build server to run unit tests and how you can make this all happen using a MSBuild script.

The end goal of this series is to arrive at a build configuration which we can use to automatically deploy an ASP.NET MVC web application. We want a reliable way of deploying an application to a new environment (staging, acceptance, production…etc.). Manually copying files, editing configuration files, synchronizing servers…is not a wise course.

You want to should avoid manual actions during deployment. Sure, you can get all the steps correct, but in the long run mistakes are unavoidable. And besides, doing all this stuff manually is just plain boring and tedious.

One of the first steps in deploying an ASP.NET / ASP.NET MVC application is to make sure its configuration file (Web.config) is transformed so it fits the environment in which the application will be running. Let’s see how we can apply Web.config transformation using TeamCity.

Table Of Contents

• Introduction
• Demo Web Application
• The Transformation
• Basic Build Configuration
• Deploy Target
• Transform Target

Demo Web Application

For testing purposes I created a small ASP.NET MVC 3 web application. The application contains a single web page which allows me to query a list of persons by their last name.

It contains a single (local) database which contains one lonely table, namely [Person]. If you don’t want to create your own sample project, you can download it here.

The solution in which this project is contained also contains a project to house the unit tests. It only contains one test (NUnit), which tests nothing in particular (Hey, it’s a demo.).

This project was only created to demonstrate that we can create a build configuration which performs:

• Compilation
• Runs unit tests
• Transforms configuration files (Web.config)

Top of page

The Transformation

The development Web.config file contains a couple of items I want to replace when I create a release build via TeamCity, namely:

• The debug attribute of the compilation element must be removed. I want to compile release binaries instead of debug binaries.
• I want to replace the application settings.
• The connection string(s) must point to another database server, instead of my local development database.

A Web.config transformation file for the release build (Web.Release.config) is added to a new ASP.NET MVC project by default. You can add as many transformation files as there are configurations for your project (debug, release…etc.).

I added the following contents to the Web.Release.config transform file which specifies how the Web.config file should be changed when it is deployed. It’s quite straightforward to read.

<?xml version="1.0"?>
<configuration xmlns:xdt="http://schemas.microsoft.com/XML-Document-Transform">
  <system.web>
    <compilation xdt:Transform="RemoveAttributes(debug)" />
  </system.web>

  <appSettings xdt:Transform="Replace">
    <add key="webpages:Version" value="2.0.0.0" />
    <add key="ClientValidationEnabled" value="false" />
    <add key="UnobtrusiveJavaScriptEnabled" value="false" />
  </appSettings>

  <connectionStrings>
    <add xdt:Transform="SetAttributes" xdt:Locator="Match(name)"
         name="DatabaseEntities"
         connectionString="The production connection string goes here." />
  </connectionStrings>
</configuration>

You can clearly see that it removes the debug attribute from the compilation element, replaces the appSettings node and replaces the connectionString attribute of the connection string named “DatabaseEntities”.

More information on Web.config transformation syntax can be found here:

http://msdn.microsoft.com/en-us/library/dd465326.aspx

Top of page

Basic Build Configuration

Now that we have the sample project setup and the Web.Release.config has been created, we can commence to create a build configuration in TeamCity that automatically transforms the configuration.

Let’s first setup the project and a basic build configuration that compiles a release build and runs our unit tests. To do so create a new build configuration in TeamCity which contains a single build step. I’ll quickly go over this as this is explained in the previous two articles of this series.

• Part 1: Running Unit Tests With TeamCity
• Part 2: Using a MSBuild Script in TeamCity

This build step executes a MSBuild script. The contents of the MSBuild script are displayed below.

<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
  <PropertyGroup>
    <WorkingFolder>$(MSBuildProjectDirectory)</WorkingFolder>
    <Configuration>Release</Configuration>
    <SolutionFile>PeopleFinder.sln</SolutionFile>
    <NUnitPath>$(WorkingFolder)\packages\NUnit.2.5.10.11092\tools</NUnitPath>
  </PropertyGroup>  

  <Target Name="BuildAll" DependsOnTargets="Compile;Test;" />  

  <Target Name="Compile">
    <Message Text="=== COMPILING $(Configuration) configuration ===" />
    <MSBuild Projects="$(SolutionFile)"
             Properties="Configuration=$(Configuration)" />
  </Target>  

  <Target Name="Test">
    <ItemGroup>
      <TestAssemblies
        Include="**\*.Tests.dll"
        Exclude="**\obj\**;**\packages\NUnit.2.5.10.11092\**" />
    </ItemGroup>

    <Message Text="=== RUNNING UNIT TESTS ==="/>
    <NUnit Assemblies="@(TestAssemblies)" ToolPath="$(NUnitPath)"
          DisableShadowCopy="true" />
  </Target>
</Project>

Make sure that your build step (runner type: MSBuild) executes the target “BuildAll”. This target executes the targets Compile and Test. The Compile target creates a release build and the Test target executes the unit tests.

Top of page

Deploy Target

Let’s add a new target to the MSBuild script called “Deploy”. Append the target to the end of the “DependsOnTargets” attribute of the “BuildAll” target.

<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
  <PropertyGroup>
    <!-- ...other properties... -->
    <DeployPath>C:\Projects\build\PeopleFinder</DeployPath>
  </PropertyGroup>  

  <Target Name="BuildAll" DependsOnTargets="Compile;Test;Deploy;" />  

  <!-- ...other targets... -->
  <Target Name="Deploy">
     <Message Text="=== DEPLOY LATEST BUILD to $(DeployPath) ===" />

     <RemoveDir Directories="$((DeployPath)" />
     <MakeDir Directories="$(DeployPath)"/>

     <ItemGroup>
       <DeployWebFiles Include="PeopleFinder.UI.Web\**\*.*"
                       Exclude="**\*.cs;**\*.csproj;**\*.user;**\obj\**;**\.svn\**;**\*.pdb;" />
     </ItemGroup>

    <Copy SourceFiles="@(DeployWebFiles)"
          DestinationFiles="@(DeployWebFiles->'$(DeployPath)\%(RecursiveDir)%(Filename)%(Extension)')" />
  </Target>
</Project>

This new target is responsible for copying the compiled output to a new location ($DeployPath). After you check in the new build file and run the build configuration the Deploy target will copy the compiled output to the directory specified by the $DeployPath property.

Hrmm, there are still some files in there we are not interested in. Let’s expand the Exclude attribute of the DeployWebFiles item group.

<DeployWebFiles Include="PeopleFinder.UI.Web\**\*.*"
Exclude="**\*.cs;**\*.csproj;**\*.user;**\obj\**;
         **\.svn\**;**\*.pdb;**\*.edmx;**\packages.config;**\Web.*.config" />  

That’s better.

Top of page

Transform Target

At the moment the MSBuild script compiles the project, runs the unit tests and copies the output to a separate directory ($DeployPath). If you open the Web.config file which resides in this directory you’ll notice that it is a copy of the development version. The release transformation hasn’t been applied yet. Time to fix this.

To do so, we need to add another target to the script. For readability’s sake, I introduced some extra line breaks.

<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
  <PropertyGroup>
    <!-- ...other properties... -->
    <TransformInputFile>PeopleFinder.UI.Web\Web.config</TransformInputFile>
    <TransformFile>PeopleFinder.UI.Web\Web.$(Configuration).config</TransformFile>
    <TransformOutputFile>$(DeployPath)\Web.config</TransformOutputFile>
  </PropertyGroup>  

  <UsingTask TaskName="TransformXml"
             AssemblyFile="$(MSBuildExtensionsPath)\Microsoft\
                           VisualStudio\v10.0\Web\
                           Microsoft.Web.Publishing.Tasks.dll"/>

  <Target Name="BuildAll" DependsOnTargets="Compile;Test;Deploy;Transform" />  

  <!-- ...other targets... -->
  <Target Name="Transform">
     <Message Text="=== TRANSFER THE CONFIGURATION FILE ===" />
     <TransformXml Source="$(TransformInputFile)"
                   Transform="$(TransformFile)"
                   Destination="$(TransformOutputFile)" />
  </Target>
</Project>

The BuildAll target now executes the targets Compile, Test, Deploy & Transform. After the output has been copied to the $(DeployPath) the Transform target applies the release (Web.$(Configuration).config) transformation to the Web.config file.

If run the build configuration now you’ll notice that the Web.config has successfully been updated and now contains the correct settings. No more boring manual editing.

Remark: Please note that you need to add an UsingTask element to the MSBuild script to reference the TransformXml task whose implementation is contained in the Microsoft.Web.Publishing.Task.dll assembly.

That wraps it up for applying Web.config transformations via TeamCity using a MSBuild script. You can find the sample project for this article on the download page of this blog. If you have any questions, suggestions…etc. please feel free to leave a comment.

Top of page