The previous article, Getting Started with the Live SDK: Authorization, shows you have to request a user’s permission to access parts of their Live ID, including SkyDrive.

Time to take a closer look at what we can do with the REST API and SkyDrive. Listing a user’s folders and files stored in his SkyDrive seems like as good as any place to start.

Table Of Contents

• Introduction
• Scopes
• Folders, Albums, Files, Photos, Videos…
• Listing Folders
• Other Content Types
• Folder Contents

Scopes

When the user authorizes your application you can specify the scopes to which you want access. Their profile, work information, postal addresses…etc. The list goes on, you can find it here:

http://msdn.microsoft.com/en-us/library/live/hh243646

If you want to list the folders and files of the user’s SkyDrive account you need to make sure you request access for the following scopes:

• wl.skydrive: Read access to a user’s files stored in SkyDrive.
• wl.photos: Read access to a user’s photos, videos, audio, and albums.

So let’s quickly generate a new access token:

var uri = "https://login.live.com/oauth20_authorize.srf";

var authorizeUri = new StringBuilder(uri);

authorizeUri.AppendFormat("?client_id={0}&", "your_client_id");
authorizeUri.AppendFormat("scope={0}&", 
    "wl.signin%20wl.photos%20wl.skydrive");
authorizeUri.AppendFormat("response_type={0}&", "token");
authorizeUri.AppendFormat("redirect_uri={0}", 
UrlEncode("http://redirect_uri.com"));

Remark: Each scope value needs to be separated by a space (%20). For brevity’s sake I’ve put them in there directly.

The user will asked to grant the necessary permissions:

Permissions to which you already have access will not be listed again. Need more information on authorizing your application? Check ouf the first article.

When the user authorizes your application you will be redirected to the URL you specified and it will contain an authorization token. Get it. Even if it is ridiculously long.

Top of page

Folders, Albums, Files, Photos, Videos…

If you take a look at the REST reference you’ll find a couple of objects connected to SkyDrive such as Folder, Album, File, Photo, Video…etc. Most of them share a lot of properties, so let’s create a base class for them.

[JsonObject(MemberSerialization.OptIn)]
public class FileSystemInfo
{
    [JsonProperty(PropertyName = "id")]
    public string Id { get; set; }

    [JsonProperty(PropertyName = "name")]
    public string Name { get; set; }

    [JsonProperty(PropertyName = "created_time")]
    [JsonConverter(typeof(IsoDateTimeConverter))]
    public DateTime CreatedTime { get; set; }

    [JsonProperty(PropertyName = "type")]
    public string Type { get; set; }

    //...
}

I’ve not listed all the properties here, there are too many. Check out the REST reference, compare the objects and add the common properties. The JSON.NET attributes will help us later when deserialing the response.

Photos have a couple of different properties. Let’s add those to a descendant class.

[JsonObject(MemberSerialization.OptIn)]
public class Photo : FileSystemInfo
{
    [JsonProperty("size")]
    public int Size { get; set; }

    [JsonProperty("when_taken")]
    public DateTime? WhenTaken { get; set; }

    [JsonProperty("location")]
    public Location Location { get; set; }

    //...
}

Again not all properties are listed. Check out the Photo Object if you want to add more.

The same goes for the Video object. I’ll not list it here, just check out the source code that comes with this article.

Did you notice the Type (string) property on the FileSystemInfo class? This type will tell us what type of object we are dealing with. Folder, photo, video…etc. It will come in handy when deserializing the returned data.

Top of page

Listing Folders

To list all the folder of a user’s SkyDrive account you simply sent a GET request to:

https://apis.live.net/v5.0/me/skydrive/files

Just don’t forget to append the access token.

var requestUri = new StringBuilder("https://apis.live.net/v5.0/me/skydrive/files");
requestUri.AppendFormat("?access_token={0}", "access token");
var request = (HttpWebRequest)WebRequest.Create(requestUri.ToString());
request.Method = "GET";

The response will, as always, be JSON-formatted. Let’s deserialize it to an IEnumerable of Folder. But first add the following SkyDrive type to your project.

[JsonObject(MemberSerialization.OptIn)]
public class SkyDrive
{
    [JsonProperty(PropertyName = "data")]
    public IEnumerable<Folder> Folders { get; set; }
}

Now you can easily deserialize the list of folders.

var response = (HttpWebResponse)request.GetResponse();
using (var reader = new StreamReader(response.GetResponseStream()))
{
    var json = reader.ReadToEnd();

    var skyDrive = JsonConvert.DeserializeObject<SkyDrive>(json);

    foreach (var folder in skyDrive.Folders)
    {
        Console.WriteLine(String.Format("{0}: {1}", folder.Id, folder.Name));
    }
}

This will output all the folders in the user’s SkyDrive root.

Top of page

Other Content Types

The previous example is a bit hopeful. Only store folders and you’ll be fine. No files please. They will be treated as folders.

To use the other content types (album, photo, video, file…etc.) you have to inspect the type property. Once you have the JSON response, parse it and inspect the returned data.

For example:

var json = JObject.Parse(reader.ReadToEnd());

var contents = new List<FileSystemInfo>();
foreach (var item in json["data"])
{
    var type = item["type"].ToString();
    switch (type)
    {
        case "photo":
            contents.Add(JsonConvert.DeserializeObject<Photo>(item.ToString()));
            break;

        case "video":
            contents.Add(JsonConvert.DeserializeObject<Video>(item.ToString()));
            break;

        case "folder":
        case "album":
            contents.Add(JsonConvert.DeserializeObject<Folder>(item.ToString()));
            break;
    }
}

Then you can list all the content types and use their specific properties.

foreach (var item in contents)
{
    Console.WriteLine(String.Format("{0} : {1}", item.Type, item.Name));
    if (item is Photo)
    {
        Console.WriteLine(String.Format("Size: {0} bytes", ((Photo) item).Size));
    }
}

Top of page

Folder Contents

One last thing I want to address for this post is how to list a folder’s contents. Listing the folders of the root folder will not return the contents (files, subfolders…) of these folders.

However requesting the contents of a folder is very similar. Instead of sending a GET request to:

https://apis.live.net/v5.0/me/skydrive/files

You need to send a request to:

https://apis.live.net/v5.0/{folder_id}/files

Just replace {folder_id} with the ID of the folder for which you want to list the contents and you are set.

var uri = "https://apis.live.net/v5.0/{0}/files";
var requestUri = new StringBuilder(String.Format(uri, "your_folder_id"));
requestUri.AppendFormat("?access_token={0}", "your_access_token");
var request = (HttpWebRequest)WebRequest.Create(requestUri.ToString());
request.Method = "GET";

var response = (HttpWebResponse)request.GetResponse();
using (var reader = new StreamReader(response.GetResponseStream()))
{
    var json = JObject.Parse(reader.ReadToEnd());

    // Parse the JSON data 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

In a move to compete with DropBox, Google Drive…etc. Microsoft revamped SkyDrive this week incorporating most of Mesh‘s features. If you signed up for SkyDrive before April 22nd, and have uploaded at least one file, be sure to apply for the free upgrade to 25 GB.

I wrote a couple of articles on the use of the DropBox REST API. Microsoft’s revamp made me curious to see if I could do the same with the SkyDrive API.

Table Of Contents

• Introduction
• Register Your Application
• REST Reference
• OAuth
• User Object

Register Your Application

The SkyDrive API is part of the Live SDK, which allows you to use SkyDrive, Hotmail, Messenger and Live Id. Before you can get started you need to register your application at the Live Connect Developer Center.

Just sign in with your Windows Live Id and then click “My Apps” in the upper left corner.

You have 100 available application slots. Just click “Create Application”. You only need to fill in two fields, the application’s name and language.

Afterwards you’ll receive a client ID and secret.

Yes, I changed the secret by the time you are reading this.

After you’ve created the application you need to change one little thing. Go back to the applications overview page and select the newly created application. Click “Edit Settings” and then select the “API Settings” option. Here you need to enter a valid redirect domain. This needs to be set correctly if you want the authorization process to succeed.

Remark: You can only use the same redirect domain for one application!

Top of page

REST Reference

You can use the Representation State Transfer (REST) API to work with the Live API. Using the REST API you can programmatically access the user’s info, contacts, friends, addresses…etc.

You can find the entire REST reference here:

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

Alternatively you can also download the Windows Live SDK. The SDK simplifies common task such as signing in, access user data..etc, but I prefer to use the REST API directly.

Top of page

OAuth

Live Connect implements the OAuth 2.0 protocol to authenticate users. I already covered OAuth in the following articles:

• Dropbox REST API Part 1: Authentication
• Dropbox REST API Part 6: OAuth Callback
• Bitly API: Authentication

The implementation is similar for the Live Connect API. Let’s quickly cover the authorization flow.

First you need to compose the authorization URL to which you’ll redirect the users.

var uri = "https://login.live.com/oauth20_authorize.srf";

var authorizeUri = new StringBuilder(uri);

authorizeUri.AppendFormat("?client_id={0}&", "Your Client ID");
authorizeUri.AppendFormat("scope={0}&", "wl.signin");
authorizeUri.AppendFormat("response_type={0}&", "token");
authorizeUri.AppendFormat("redirect_uri={0}", UrlEncode("http://redirect_url.com"));

Fill in your client ID and make sure that the redirect URL exactly matches the one you entered when you registered your application.

Using the scope query parameter you can specify the permissions which your application requires. If you want to sign in the user you specify wl.signin. If you also want to access the user’s work profile and postal addresses you need to also pass wl.work_profile and wl.postal_addresses. You can find a list of all the available scopes here:

http://msdn.microsoft.com/en-us/library/live/hh243646

Each scope value needs to be separated by a space (%20).

The value of the response_type query parameter is set to token which requests an authorization token.

Remark: The UrlEncode(…) method encodes the redirect URI. Check out the source code of this article to see how the method works. I already explained it in Part 5 of the Dropbox series.

Once you’ve composed the authorization URI you can redirect the user to it.

var startInfo = new ProcessStartInfo();
startInfo.FileName = authorizeUri.ToString();
Process.Start(startInfo);

The user will be informed to which parts of his account your application wants access.

After the user authorizes your application he’ll be redirected to the URI you specified in the redirect_uri parameter. The redirect URI will be appended with 5 parameters, namely:

• access_token: The access token
• authentication_token
• token_type
• expires_in: The number of seconds the access token is valid
• scope: The scopes to which the user granted you access

Microsoft uses redictiously long token, over 700 characters! Seriously, why? I believe an Dropbox’s access token is about 12 characters long (may vary).

Top of page

User Object

Now that we have access to the user’s account let’s retrieve some profile information. The data is exchanged in JavaScript Object Notation (JSON) format.

For example:

{
    "id": "2a67eedc508758ca", 
    "name": "Christophe Geers", 
    "first_name": "Christophe", 
    "last_name": "Geers", 
    "gender": null, 
    "locale": "nl_NL"
}

So add a reference to the JSON.NET library via NuGet. Now let’s create a simple User object into which we can deserialize this data.

[JsonObject(MemberSerialization.OptIn)]
public class User
{
    [JsonProperty(PropertyName = "id")]
    public string Id { get; set; }

    [JsonProperty(PropertyName = "name")]
    public string Name { get; set; }

    [JsonProperty(PropertyName = "first_name")]
    public string FirstName { get; set; }

    [JsonProperty(PropertyName = "last_name")]
    public string LastName { get; set; }

    [JsonProperty(PropertyName = "gender")]
    public string Gender { get; set; }

    [JsonProperty(PropertyName = "locale")]
    public string Locale { get; set; }
}

When you request information about a user’s profile you need to send a GET request to:

https://apis.live.net/v5.0/me

Instead of the term “me” you can also use the user’s ID, but this way is simpler as you don’t have to figure out the user’s ID first.

First you need to compose the request:

var requestUri = new StringBuilder("https://apis.live.net/v5.0/me");
requestUri.AppendFormat("?access_token={0}", "your access token");
var request = (HttpWebRequest)WebRequest.Create(requestUri.ToString());
request.Method = "GET";

Then you can read the response. Using the JSON.NET library you can easily deserialize it into an instance of the User type.

var response = (HttpWebResponse) request.GetResponse();
using (var reader = new StreamReader(response.GetResponseStream()))
{
    var json = reader.ReadToEnd();

    var user = JsonConvert.DeserializeObject<User>(json);

    Console.WriteLine(user.Id);
    Console.WriteLine(user.Name);
    Console.WriteLine(user.FirstName);
    Console.WriteLine(user.LastName);
    Console.WriteLine(user.Gender);
    Console.WriteLine(user.Locale);
}

The output:

If you want to retrieve more data from the user’s profile you need to specify the correct scopes (wl.work_profile, wl.postal_addresses…) when requesting access to the user’s account. Download the source of this article and check it out. There you can find some examples about how to retrieve the user’s work profile and postal addresses.

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 was playing around this morning with the Bitly API. Like the Dropbox API they use OAuth for authentication. But instead of version 1.0 they use the OAuth 2 draft specification.

Wondering how much it differs from the previous version I created a Bitly account and started coding…

Table Of Contents

• Introduction
• Register Your Application
• Authorization
• Access Token

Register Your Application

If you don’t have a Bitly account yet, then sign up here:

http://bitly.com/a/sign_up

It’s quick and painless, I promise.

Once signed up, you need to register your application. Just select your account’s settings.

At the bottom you’ll find a list of your registered OAuth applications. You are allowed to create 3 applications under a single Bitly account. Just click the Register OAuth Application button to register a new application.

First you need to request a registration code. This code will be sent to the e-mail address associated with your Bitly account. Go ahead and click the “Get Registration Code” button.

Once you have received the e-mail, click on the registration code within it. You’ll be redirected to a form where you need to fill in the application’s name, link and description.

For example:

After you’ve filled in the form and submitted it, your new application will be listed on your account. Per application you’ll receive an application link, client id and client secret. You’ll need these during the OAuth authentication process.

There seems no way to edit or remove a registered application afterwards. A pity.

Top of page

Authorization

Alright, Bitly account created, registered the application. Time to start the authentication process.

First you need to redirect the user to https://bitly.com/oauth/authorize. You need to append your client id and application link (a.k.a. redirect uri) in the query string.

var redirectUri = "http://cgeers.com/";
var uri = "https://bitly.com/oauth/authorize";

var authorizeUri = new StringBuilder(uri);
authorizeUri.AppendFormat("?client_id={0}&", clientId);
authorizeUri.AppendFormat("redirect_uri={0}", redirectUri);

You’ll wind up with a URL that looks like this:

https://bitly.com/oauth/authorize?client_id=your_client_id&redirect_uri=your_application_link

Remark: Make sure that the value of the redirect_uri parameter exactly matches the URL to which you linked your application! If you forget the last forward slash it will not work.

Now you need to redirect your user to this URL so that he or she can authorize your application.

A crude example:

var startInfo = new ProcessStartInfo();
startInfo.FileName = authorizeUri.ToString();
Process.Start(startInfo);

The user will be redirect to a page where he can grant your applicion access to his Bitly account.

Top of page

Access Token

When the user authorizes your application, he will be redirected to the URL specified by the redirect_uri parameter. Bitly appends a code to this URI. You can exchange this code for an OAuth access token.

For example:

http://cgeers.com/?code=ddc08e777c8e4d911fb24ab9c2cc19b640265bfe

You need to retrieve the OAuth token using the https://api-ssl.bitly.com/oauth/access_token endpoint.

You’ll need to append four parameters to it, namely:

• client_id: your application’s Bitly client id
• client_secret: your application’s Bitly client secret
• code: the code acquired via the authorization step
• redirect_uri: the page to which a user was redirected upon successfully authenticating

Let’s compose this URL:

var redirectUri = "http://cgeers.com/";
var code = "6c9f6ec95f54ba7269d0ba037b3eba7137559556";

var requestUri = new StringBuilder("https://api-ssl.bitly.com/oauth/access_token");
requestUri.AppendFormat("?client_id={0}&", clientId);
requestUri.AppendFormat("client_secret={0}&", clientSecret);
requestUri.AppendFormat("code={0}&", code);
requestUri.AppendFormat("redirect_uri={0}", redirectUri);

You’ll end up with something like this:

https://api-ssl.bitly.com/oauth/access_token?client_id=your_client_id&client_secret=your_client_secret&code=your_code&redirect_uri=your_app_uri

Once again make sure that the values for all the parameters match exactly.

Now you’ll need to issue a POST request (required), a GET request will not work, to obtain the response.

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

var response = request.GetResponse();
using (var reader = new StreamReader(response.GetResponseStream()))
{
    var accessToken = reader.ReadToEnd();
    //...
}

The response is a simple query string which will look something like this:

access_token=your_access_token&login=user_login&apiKey=users_api_key

Just split the string and extract the different parts.

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

You now have an access token for the user. Make sure you persist it somewhere. You don’t want to put the user through the authentication process again.

Once you’ve issued this request the code becomes useless. If you perform the request again using the same code you’ll receive a 401 Http status code (unauthorized).

All Bitly API requests must be made over SSL (https://api-sll.bitly.com/). You can use the access token on behalf of the user. Perhaps I’ll write another blog post that shows how to perform API requests. Stay tuned.

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

Mayhap came here sooner than I thought. The previous article on the WPD API dealt with deleting resources. Too destructive perhaps, let’s create some resources this time.

My Kindle’s is hooked up to my PC. Let’s see if I can transfer a book to it.

Table Of Contents

• Introduction
• TransferContentToDevice Method
• Required Properties
• Transferring Content

TransferContentToDevice Method

Get the source code of the fourth article, #69: WPD: Deleting Resources, from the download page. Unzip it and open it up in Visual Studio.

In the Solution Explorer select the Program.cs file and open it. Clear the Main(…) method and add the following code to it.

var devices = new PortableDeviceCollection();
devices.Refresh();
var kindle = devices.First();
kindle.Connect();

kindle.TransferContentToDevice(
    @"d:\temp\Kindle_Users_Guide.azw",
    @"g:\documents");

kindle.Disconnect();

First we establish a connection to the Kindle, copy the book to it and finally disconnect from it

The magic happens in the TransferContentToDevice(…) method, which takes two parameters:

• fileName: Full path of the file which you want to copy to the device
• parentObjectId: The ID of the parent folder into which you want to copy the file

Modify the values of these parameters to suit your situation.

Top of page

Required Properties

Before we can start to implement the TransferContentToDevice(…) method we first need to add another private method to the PortableDevice class type.

private IPortableDeviceValues GetRequiredPropertiesForContentType(
    string fileName,
    string parentObjectId)
{
    //...
}

Before you can upload a resource to a device you need to collect some information about it. This information is stored in a IPortableDeviceValues collection.

Depending on the resource type you may need to collect more data (or properties) that describe the resource. Keep that it mind, the number of required properties might differ for your situation.

For adding a book to a Kindle you need to know the following information:

• WPD_OBJECT_PARENT_ID: The ID of the folder into which you want to upload the resource
• WPD_OBJECT_SIZE: The size of the object (in bytes)
• WPD_OBJECT_ORIGINAL_FILE_NAME: The original filename of the object
• WPD_OBJECT_NAME: The name of the object as you wish to represent it on the device

Time to implement the method. First you need to create a IPortableDeviceValues collection.

IPortableDeviceValues values = 
    new PortableDeviceTypesLib.PortableDeviceValues() as IPortableDeviceValues;

Then you can add the WPD_OBJECT_PARENT_ID to the collection:

var WPD_OBJECT_PARENT_ID = new _tagpropertykey();
WPD_OBJECT_PARENT_ID.fmtid = 
    new Guid(0xEF6B490D, 0x5CD8, 0x437A, 0xAF, 0xFC, 
                0xDA, 0x8B, 0x60, 0xEE, 0x4A, 0x3C);
WPD_OBJECT_PARENT_ID.pid = 3 ;
values.SetStringValue(ref WPD_OBJECT_PARENT_ID, parentObjectId);

Adding the rest of the properties is similar.

FileInfo fileInfo = new FileInfo(fileName);
var WPD_OBJECT_SIZE = new _tagpropertykey();
WPD_OBJECT_SIZE.fmtid = 
    new Guid(0xEF6B490D, 0x5CD8, 0x437A, 0xAF, 0xFC, 
                0xDA, 0x8B, 0x60, 0xEE, 0x4A, 0x3C);
WPD_OBJECT_SIZE.pid = 11;            
values.SetUnsignedLargeIntegerValue(WPD_OBJECT_SIZE, (ulong) fileInfo.Length);

var WPD_OBJECT_ORIGINAL_FILE_NAME = new _tagpropertykey();
WPD_OBJECT_ORIGINAL_FILE_NAME.fmtid = 
    new Guid(0xEF6B490D, 0x5CD8, 0x437A, 0xAF, 0xFC, 
                0xDA, 0x8B, 0x60, 0xEE, 0x4A, 0x3C);
WPD_OBJECT_ORIGINAL_FILE_NAME.pid = 12;
values.SetStringValue(WPD_OBJECT_ORIGINAL_FILE_NAME, Path.GetFileName(fileName));

var WPD_OBJECT_NAME = new _tagpropertykey();
WPD_OBJECT_NAME.fmtid = 
    new Guid(0xEF6B490D, 0x5CD8, 0x437A, 0xAF, 0xFC, 
                0xDA, 0x8B, 0x60, 0xEE, 0x4A, 0x3C);
WPD_OBJECT_NAME.pid = 4;
values.SetStringValue(WPD_OBJECT_NAME, Path.GetFileName(fileName));

Remark: To keep it easy I extracted the filename and path of the book and used that to set both the WPD_OBJECT_ORIGINAL_FILE_NAME and WPD_OBJECT_NAME properties.

Last but not least, don’t forget to return the collection.

return values;

Top of page

Transferring Content

Now that you can gather all the required properties you can start transferring content to the device. Let’s implement the TransferContentToDevice(…) method.

Get an IPortableDeviceContent interface to access resource specific methods.

IPortableDeviceContent content;
this._device.Content(out content);

Now using the GetRequiredPropertiesForContentType(…) method retrieve the required properties for the resource you want to upload.

IPortableDeviceValues values =
    GetRequiredPropertiesForContentType(fileName, parentObjectId);

Then get an IStream and the optimal buffer size to transfer the resource. This can be done by using the CreateObjectWithPropertiesAndData(…) method of the IPortableDeviceContent instance.

PortableDeviceApiLib.IStream tempStream;
uint optimalTransferSizeBytes = 0;
content.CreateObjectWithPropertiesAndData(
    values,
    out tempStream,
    ref optimalTransferSizeBytes,
    null);      

Convert the IStream to an System.Runtime.InteropService.ComTypes.IStream.
Top of page

System.Runtime.InteropServices.ComTypes.IStream targetStream = 
    (System.Runtime.InteropServices.ComTypes.IStream) tempStream;

All that remains is to open a FileStream, read the source file and write it to the target stream. Make sure you close the IStream afterwards (try…finally).

try
{
    using (var sourceStream = 
        new FileStream(fileName, FileMode.Open, FileAccess.Read))
    {
        var buffer = new byte[optimalTransferSizeBytes];
        int bytesRead;
        do
        {
            bytesRead = sourceStream.Read(
                buffer, 0, (int)optimalTransferSizeBytes);
            IntPtr pcbWritten = IntPtr.Zero;
            targetStream.Write(
                buffer, (int)optimalTransferSizeBytes, pcbWritten);
        } while (bytesRead > 0);
    }
    targetStream.Commit(0);
}
finally
{
    Marshal.ReleaseComObject(tempStream);
}

And that is all she wrote. As always it’s best to backup your resources before you start experimenting with this code! 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 year I wrote three articles about the Windows Portable Devices (WDP) API, namely:

• Enumerating Windows Portable Devices
• WPD: Enumerating Content
• WPD: Transferring Content

Regularly I get questions asking me how to add or delete resources from a WPD compatible device. Let’s focus on removing resources first. Mayhap I’ll write another post about adding resources next time.

I’m going to connect my Kindle and see if I can’t delete a book from it.

Table Of Contents

• Introduction
• Source Code
• Content
• What to delete?
• Deleting Resources

Source Code

If you haven’t read the previous articles of this series yet, then do so now or at least have a quick glance at them. Go to the download page and download the source code of the third one, Article #53: WPD: Transferring Content.

Start Visual Studio and open the downloaded solution.

Open the Program.cs code file and delete everything, but leave an empty Main() method. We want to start with a clean slate.

Top of page

Content

Before we start deleting resources, let’s first find out what is stored on the device. Let’s establish a connection with the device.

var devices = new PortableDeviceCollection();
devices.Refresh();
var kindle = devices.First();
kindle.Connect();

Now let’s retrieve the resources of the root folder and enumerate over them.

var root = kindle.GetContents();
foreach (var resource in root.Files)
{
    DisplayResourceContents(resource);
}

Each resource located in the root can either be a file or another folder. The DisplayResourceContents(…) methods displays the resource’s name and if it’s a folder it lists its contents.

public static void DisplayResourceContents(
    PortableDeviceObject portableDeviceObject)
{
    Console.WriteLine(portableDeviceObject.Name);
    if (portableDeviceObject is PortableDeviceFolder)
    {
        DisplayFolderContents((PortableDeviceFolder) portableDeviceObject);
    }
}

The DisplayFolderContents(…) method is a recursive methods which drills down all the subfolders.

public static void DisplayFolderContents(
    PortableDeviceFolder folder)
{
    foreach (var item in folder.Files)
    {
        Console.WriteLine(item.Id);

        if (item is PortableDeviceFolder)
        {
            DisplayFolderContents((PortableDeviceFolder) item);
        }
    }
}

If you run the code now, you’ll get a list of all the resources which are stored on your device. Or in my case, a list of the books stored on my Kindle.

The PortableDeviceCollection, PortableDeviceObject, PortableDeviceFolder … types which I used here are wrappers around types such as PortableDeviceManager imported from the “PortableDeviceApi 1.0 Type Library″ and “PortableDeviceTypes 1.0 Type Library” COM libraries. Take a look at the second article of this series, WPD: Enumerating Content, for a more in-depth explanation on how to enumerate the resources on your device.

Top of page

What to delete?

Before you can delete a resource you need to get a hold of its ID. Each file or folder has a unique ID.

Here I execute a naive LINQ query which selects the documents folder from the Kindle.

PortableDeviceFolder documents =
    (from r in ((PortableDeviceFolder)root.Files[0]).Files
     where r.Name.Contains("documents")
     select r).First() as PortableDeviceFolder;

Let’s delete the Users Guide, I’m not going to read it. Start Kindle, select book, click next or previous…how difficult can it be.

The book is made up out of two resources. A *.azw (Amazon Word) and a *.mbp file (contains bookmarks, annotations, last read page…etc).

var books = from b in documents.Files
            where b.Name.Contains("Kindle_Users_Guide")
            select b;

And their IDs are:

foreach (PortableDeviceFile book in books)
{
    Console.WriteLine(book.Id);
}

Top of page

Deleting Resources

Time to delete the users guide. Open the PortableDevice.cs code file and add a new method called DeleteFile(…) to the PortableDevice class.

public void DeleteFile(PortableDeviceFile file)
{
    //...
}

First you need to get an IPortableDeviceContent instance with which you can create, enumerate, examine and delete content on a device.

IPortableDeviceContent content;
this._device.Content(out content);

Next you need to identify the resource which you want to delete. IPortableDeviceContent offers a Delete(…) method which requires an IPortableDevicePropVariantCollection. This interface holds a collection of PROPVARIANT values which identify the resources to delete.

You need to convert the ID of the resource, which is a string, to a PROPVARIANT. The PROPVARIANT is represented by the tag_inner_PROPVARIANT type found in the imported PortableDeviceApiLib COM library. Luckily one member of the WPD team explained how to do this in C# about five years ago.

http://blogs.msdn.com/b/dimeby8/archive/2007/01/08/creating-wpd-propvariants-in-c-without-using-interop.aspx

Let’s borrow his StringToPropVariant method and add it to our PortableDevice class.

private static void StringToPropVariant(
    string value, 
    out PortableDeviceApiLib.tag_inner_PROPVARIANT propvarValue)
{
    PortableDeviceApiLib.IPortableDeviceValues pValues =
        (PortableDeviceApiLib.IPortableDeviceValues)
            new PortableDeviceTypesLib.PortableDeviceValuesClass();

    var WPD_OBJECT_ID = new _tagpropertykey();
    WPD_OBJECT_ID.fmtid = 
        new Guid(0xEF6B490D, 0x5CD8, 0x437A, 0xAF, 0xFC, 0xDA, 
                    0x8B, 0x60, 0xEE, 0x4A, 0x3C);
    WPD_OBJECT_ID.pid = 2;

    pValues.SetStringValue(ref WPD_OBJECT_ID, value);

    pValues.GetValue(ref WPD_OBJECT_ID, out propvarValue);
}

Now you can convert the ID of a resource to a PROPVARIANT and add it to a IPortableDevicePropVariantCollection.

var variant = new PortableDeviceApiLib.tag_inner_PROPVARIANT();
StringToPropVariant(file.Id, out variant);

PortableDeviceApiLib.IPortableDevicePropVariantCollection objectIds =
    new PortableDeviceTypesLib.PortableDevicePropVariantCollection() 
    as PortableDeviceApiLib.IPortableDevicePropVariantCollection;
objectIds.Add(variant);

The preparations are done and all that remains is to delete the resource. Just call the IPortableDeviceContent’s Delete(…) method.

Pass zero for the first parameter, then the ID’s (PROPVARIANTs) of the resource you want to delete and ignore the results. We’ll be naive and hope all goes well. Improve on this if you will and inspect if all went as expected.

content.Delete(0, objectIds, null);

Now you can delete the resources associated with the users guide.

foreach (PortableDeviceFile book in books)
{
    kindle.DeleteFile(book);
}

Voila, that’s all there is to it. Best to backup your resources before you start experimenting with this code! 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

With this entry into the Dropbox series we come back to the beginning of the cycle. We started with authentication and that’s where we’ll end.

Having a user authorize your application to access his or hers Dropbox account consists out of 3 steps. Using OAuth you must:

1. Retrieve a request token
2. Have the user authorize your application
3. Retrieve an access token

Before retrieving an access token you must wait until the user has authorized your application. There’s no way to determine when this has happened. Up until now we just waited a little while and hoped for the best. However, when you instruct the user to authorize your application, you can also specify a callback URL which will automatically be called when the authorization process has been completed.

Let’s create a sample web application that demonstrates this.

Table Of Contents

• Introduction
• MVC 3 Template
• Authorization
• OAuth
• Callback

MVC 3 Template

Download the code of part #5 (article #67), unzip it and open it up in Visual Studio. Add a new MVC 3 web application called “MvcApplication” to the solution.

Make sure to select the Internet Application template so that we don’t have to create a basic layout ourselves.

The first thing I did was to remove the about page and everything related to the account pages (login, register…etc.). You won’t need them. I just want to get a simple one page site up and running as fast as possible. After removing these unnessary pages, user controls, markup…etc. You should wind up with a site resembling the following:

Feel free to adjust the default messages on the page as you please.

Top of page

Authorization

Let’s kick off the authorization process. Add a reference to the OAuthProtocol and Dropbox.Api projects. Next add a simple form to the home page (Index.cshtml).

@using (Html.BeginForm("AuthorizeDropbox", "Home"))
{
    <input type="submit" value="Gimme access to your Dropbox account" />
}

Which results in this cutting edge form:

When you submit the form the AuthorizeDropbox() action is executed. Let’s implement it.

First add your application’s key and secret to the HomeController class.

private const string ConsumerKey = "your application key";
private const string ConsumerSecret = "your application secret";

Then add the following action to the controller.

public ActionResult AuthorizeDropbox()
{            
    var oauth = new OAuth();
    var requestToken = oauth.GetRequestToken(
        new Uri(DropboxRestApi.BaseUri), ConsumerKey, ConsumerSecret);

    Session["requestToken"] = requestToken;

    var action = Url.Action("Authorized", "Home", null, Request.Url.Scheme);
    var callbackUri = new Uri(action);            

    var authorizeUri = oauth.GetAuthorizeUri(
        new Uri(DropboxRestApi.AuthorizeBaseUri), requestToken, callbackUri);

    return Redirect(authorizeUri.ToString());
}

First you retrieve a request token and temporarily store it in the session state. Next you compose the callback URL which is automatically called after the user has authorized your application. The callback should resemble something like this:

http://localhost:53291/Home/Authorized

Last, but not least you retrieve the authorization URL and redirect the user to it so he can start the authorization process. The user will now be redirected to his Dropbox account where he’ll have to login and get a chance to authorize your application.

Top of page

OAuth

If you compile now you should get some compiler errors. You’ll need to modify the OAuth type located in the OAuthProtocol project slightly. Open OAuth.cs code file and add an extra parameter (callbackUrl) to GetAuthorizeUri(…) method.

public Uri GetAuthorizeUri(Uri baseUri, OAuthToken requestToken, Uri callbackUrl)
{
    //...
}

Now you need to modify the implementation of this method. It’s really simple actually. If a callback URL is specified, just append it to the query string.

var queryString = String.Format("oauth_token={0}", 
    requestToken.Token);
if (callbackUrl != null)
{
    queryString = String.Format("{0}&&oauth_callback={1}", 
        queryString, callbackUrl);
}
var authorizeUri = String.Format("{0}{1}?{2}", baseUri, 
    "oauth/authorize", queryString);
return new Uri(authorizeUri);

And for good measure let’s add an overload, so that the existing code (which is not expecting this extra parameter) doesn’t break.

public Uri GetAuthorizeUri(Uri baseUri, OAuthToken requestToken)
{
    return GetAuthorizeUri(baseUri, requestToken, null);
}

Top of page

Callback

If you specified a callback URL then the user will be redirected here once he has authorized your application. Dropbox will provide a couple of values via GET parameters in the URL:

• oauth_token: The request token that was just authorized.
• uid: The user’s unique Dropbox ID.

Let’s add an action to the home controller so that we can handle the callback.

public ActionResult Authorized(string oauth_token, string uid)
{
   //...
}

var requestToken = (OAuthToken) Session["requestToken"];

var oauth = new OAuth();
            
var accessToken = oauth.GetAccessToken(
    new Uri(DropboxRestApi.BaseUri), ConsumerKey, ConsumerSecret, requestToken);

ViewBag.UserId = uid;
ViewBag.AccessToken = accessToken;

return View();

In the last part of the Dropbox series, we handled file downloads. This time I’ll show you how you can easily upload files to your Dropbox account.

To follow along, download the code of part #4 (article 66) from the download page, unzip it and open the solution in Visual Studio.

Let’s get started…

Table Of Contents

• Introduction
• URL Encoding
• Uploading a File

URL Encoding

Before we continue, I want to address an issue that was brought to my attention in the comments of the previous parts. A lot of methods of the Dropbox API require that you pass a path parameter which represents the file you want to upload, download, rename…etc. This path parameters needs to be URL encoded correctly.

I use the HttpUtility.UrlEncode(…) method to encode the paths. However as I mentioned in the 3rd part, there is a problem with this method. Slashes (/) are translated to %2f, while Dropbox expects it to be all uppercase. That’s why I added the (private) UpperCaseUrlEncode(…) method to the DropboxApi type. It uses the HttpUtility.UrlEncode(…) method to encode the path, but it makes sure the escaped characters are uppercased.

Turns out that .NET’s HttpUtility.UrlEncode(…) does not follow the RFC3986:

http://www.faqs.org/rfcs/rfc3986.html

For instance, one thing that it does differently is to encode spaces as ‘+’ signs instead of using ‘%20′.

In PHP they have two functions for this urlencode and rawurlencode. I could not find a substitue for the rawurlencode method in the .NET framework. So we need to modify the UpperCaseUrlEncode(…) method.

It’s not just spaces that caused problems, brackets “(” & “)” were also incorrectly escaped. ( should become %28, and ) should become %29.

Let’s fix this to make sure the ‘+’ signs (spaces), bracketes…etc. are correctly encoded.

At the end of the method I compose a dictionary of characters and their percent encoding equivalent. Next I do a “manual” replace of those characters.

private static string UpperCaseUrlEncode(string s)
{
    char[] temp = HttpUtility.UrlEncode(s).ToCharArray();
    for (int i = 0; i < temp.Length - 2; i++)
    {
        if (temp[i] == '%')
        {
            temp[i + 1] = char.ToUpper(temp[i + 1]);
            temp[i + 2] = char.ToUpper(temp[i + 2]);
        }
    }

    var values = new Dictionary<string, string>()
    {
        { "+", "%20" },
        { "(", "%28" },
        { ")", "%29" }
    };

    var data = new StringBuilder(new string(temp));
    foreach (string character in values.Keys)
    {
        data.Replace(character, values[character]);
    }
    return data.ToString();
}

Now it correctly encodes the spaces and brackets. If any more characters should cause problems you just need to add them to the values dictionary.

Take a look at percent encoding for more information:

http://en.wikipedia.org/wiki/Percent-encoding

Top of page

Uploading a File

Open the DropboxApi.cs code file (Dropbox.Api project) and add the following method to the DropboxApi type.

public FileSystemInfo UploadFile(string root, string path, string file)
{
  //...
}

The method has 3 parameters:

• root: The root relative to which the path is specified. Valid values are sandbox and dropbox.
• path: The path to the file you want to upload.
• file: Absolute path to the local file you want to upload

You can call this new method as follows:

var file = api.UploadFile("dropbox", "photo.jpg", @"C:\Pictures\photo.jpg");

Let’s implement the method. First let’s compose the URL of the Dropbox API which we’ll need to call.

var uri = new Uri(new Uri(DropboxRestApi.ApiContentServer),
    String.Format("files_put/{0}/{1}",
    root, UpperCaseUrlEncode(path)));

This will give you the following URI:

https://api-content.dropbox.com/1/files_put/dropbox/photo.jpg

Next we need to sign this request using our little OAuth library.

var oauth = new OAuth();   
var requestUri = oauth.SignRequest(uri, 
    _consumerKey, _consumerSecret, _accessToken, "PUT");

Remark: For file uploads you need to use PUT semantics. You also need to specify this when signing the request. The OAuth code will use GET by default, this will result in an invalid signature and Dropbox will return a 403 Forbidden error. I modified the OAuth code a bit so that you can specify the HTTP method when signing a request. Check out the source code if you want to explore that part further.

Let’s create a request.

var request = (HttpWebRequest) WebRequest.Create(requestUri);
request.Method = WebRequestMethods.Http.Put;
request.KeepAlive = true;

Now for the easy part, let’s read the source file into a byte array.

byte[] buffer;
using (var fileStream = new FileStream(
    file, FileMode.Open, FileAccess.Read))
{
    int length = (int) fileStream.Length;
    buffer = new byte[length];
    fileStream.Read(buffer, 0, length);
}

Now you need to write this byte array to the request stream of the request.

request.ContentLength = buffer.Length;
using (var requestStream = request.GetRequestStream())
{
    requestStream.Write(buffer, 0, buffer.Length);
}

Voila, the request has been prepared. Time to send it and parse the response. Dropbox returns metadata for the uploaded file. We can deserialize this data (JSON) into our existing FileSystemInfo type.

var response = request.GetResponse();
var reader = new StreamReader(response.GetResponseStream());
var json = reader.ReadToEnd();
return ParseJson<FileSystemInfo>(json);

See how easy that was? Now you can upload a file using two lines of code.

var api = new DropboxApi(ConsumerKey, ConsumerSecret, accessToken);
var file = api.UploadFile("dropbox", "photo.jpg", @"c:\pictures\photo.jpg");

Check out the Dropbox REST API documentation if you want to explore it further and implement new features.

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

In part 6 I’ll come back to authentication and show you how you can implement a callback mechanism. This way Dropbox lets you know when the user has authorized your application.

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

So far we’ve covered the following topics in the Dropbox series:

• Part 1: Authentication
• Part 2: API Requests
• Part 3: Create, Delete and Move Folders

Once you are authenticated you can make API requests such as requesting your account information, creating, deleting folders…etc. One particular type of request is downloading a file from your Dropbox account. Once you’ve worked your way through the previous 3 parts this becomes trivially easy.

If you want to follow along go to the download page and download the code for the third part (article #65). Unzip it and open it up in Visual Studio.

Table Of Contents

• Introduction
• A New Method
• Expanding FileSystemInfo
• Downloading the File

A New Method

Let’s add a new method to the DropboxApi type called DownloadFile(…).

public FileSystemInfo DownloadFile(string root, string path)
{
    // ...
}

It takes two parameters, namely:

• root: The root relative to which the path is specified. Valid values are sandbox and dropbox.
• path: The path to the file you want to download.

It returns an instance of the FileSystemInfo type, which we created earlier in part #3. The FileSystemInfo type contains the file’s metadata.

Example usage of the new method:

var api = new DropboxApi(ConsumerKey, ConsumerSecret, accessToken);
var file = api.DownloadFile("dropbox", "Public/DropboxPart3.zip");
file.Save(@"C:\DropboxPart3.zip");

Top of page

Expanding FileSystemInfo

Before we can proceed we need to modify the existing FileSystemInfo type.

public class FileSystemInfo
{
    //...

    public byte[] Data { get; internal set; }

    public void Save(string path)
    {
        using (var fileStream = new FileStream(
            path, FileMode.Create, FileAccess.ReadWrite))
        {
            fileStream.Write(Data, 0, Data.Length);
        }            
    }
}

The new property Data returns a byte array which contains the contents of the file we downloaded. The Save(…) method allows you to easily save the file. No world shocking news here.

Top of page

Downloading the File

Let’s implement the DownloadFile(…) method. When downloading a file we need to contact the API content server. So let’s add a URL to the DropboxRestApi type.

public class DropboxRestApi
{
    public const string ApiVersion = "1";

    public const string ApiContentServer = 
        "https://api-content.dropbox.com/" + ApiVersion + "/";

    //...
}

Now we can start with implementing the DownloadFile(…) method. First we need to compose a URL for the file which we want to retrieve.

For example:

https://api-content.dropbox.com/1/files?root=dropbox&path=Public/DropboxPart3.zip

var uri = new Uri(new Uri(DropboxRestApi.ApiContentServer),
    String.Format("files?root={0}&path={1}",
    root, UpperCaseUrlEncode(path)));

Remark: We created the UpperCaseUrlEncode(…) method last time to circumvent a rather annoying problem when URL encoding the path.

Next we need to sign the request.

var oauth = new OAuth();
var requestUri = oauth.SignRequest(uri, _consumerKey, _consumerSecret, 
    _accessToken);

Then you can finally execute a GET request to download the file.

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

The HTTP response contains the file’s metadata in JSON format within an x-dropbox-metadata header. Let’s extract this metadata from the headers and deserialize it into a FileSystemInfo instance.

var metadata = response.Headers["x-dropbox-metadata"];
var file = ParseJson<FileSystemInfo>(metadata);

Now we can read the response and store the file as a byte array in the FileSystemInfo instance.

using (Stream responseStream = response.GetResponseStream())
using (MemoryStream memoryStream = new MemoryStream())
{
    byte[] buffer = new byte[1024];
    int bytesRead;
    do
    {
        bytesRead = responseStream.Read(buffer, 0, buffer.Length);                    
        memoryStream.Write(buffer, 0, bytesRead);
    } while (bytesRead > 0);

    file.Data = memoryStream.ToArray();
}            

And the only thing that remains is to return our FileSystemInfo instance.

return file;

Voila, that’s the whole implementation of the DownloadFile(…) method.

Thanks to the fact that we did most of the work during the previous parts, this turned out to be a rather short article. Check out the Dropbox REST API documentation if you want to explore it further and implement new features on your own.

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

In part 5 I’ll discuss how you can upload new files to your Dropbox account. 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 (part 2: API Requests) I mentioned that the third part would show you how to perform various folder operations such as creating, deleting and moving folders.

Well it has been a month, so let’s get to it. Go to the download page and download the source code of part 2 (Article #63). Unzip and open the solution in Visual Studio. Make sure you modify the API key and secret located in the console application (Program.cs code file). Replace the values with your own application’s key and secret.

Ready? Set? OK, let’s start with creating folders…

Table Of Contents

• Introduction
• Create Folder
• URL Encoding
• Move Folder
• Delete Folder

Create Folder

The Dropbox REST API states that to create a folder you must supply at least two parameters, namely:

1. root: The root relative to which the path is specified. Valid values are sandbox and dropbox.
2. path: The path to the new folder to create relative to the root

After creating the folder Dropbox returns some metadata about it. As usual this data is JSON-formatted. Let’s create a simple class decorated with attributes from the Json.NET library so that we can easily deserialize this data.

[JsonObject(MemberSerialization.OptIn)]
public class FileSystemInfo
{
    [JsonProperty(PropertyName = "rev")]
    public string Revision { get; internal set; }

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

    [JsonProperty(PropertyName = "modified")]
    public DateTime Modified { get; internal set; }

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

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

    //...
}

The FileSystemInfo type is very similar to the File type shown in part 2 of this series. I’ve abbreviated the code here for readability. Download the source and check it out if you want to see the whole class. This type will also be used as the return type of the Move(…) and Delete(…) methods that we’ll implement later.

Let’s expand the DropboxApi type so that we can create a folder in the following manner:

var folder = api.CreateFolder("dropbox", "/test");

First you need to specify the root. Valid values are sandbox or dropbox (production). Then you need to specify the folder relative to the root. Subdirectories are allowed.

var folder = api.CreateFolder("dropbox", "/test/subdir");

The implementation of the CreateFolder(…) method is similar to the API requests we handled in part 2.

public FileSystemInfo CreateFolder(string root, string path)
{
    var uri = new Uri(new Uri(DropboxRestApi.BaseUri),
        String.Format("fileops/create_folder?root={0}&path={1}", 
        root, UpperCaseUrlEncode(path)));
    var json = GetResponse(uri);
    return ParseJson<FileSystemInfo>(json);
}

First we compose the URL to call, e.g.:

https://api.dropbox.com/1/fileops/create_folder?root=dropbox&path=%2Ftest

Then we retrieve the response (JSON) by calling the GetResponse(…) method (see part 2), which signs the request using OAuth, and deserialize it into a Folder object using the Json.NET library.

You can examine the folder metadata afterwards:

var folder = api.CreateFolder("dropbox", "/test");
Console.WriteLine("Folder created.");
Console.WriteLine(String.Format("Root: {0}", folder.Root));
Console.WriteLine(String.Format("Path: {0}", folder.Path));
Console.WriteLine(String.Format("Modified: {0}", folder.Modified));     

Which outputs:

Top of page

URL Encoding

Did you notice that I URL encoded the path parameter in the CreateFolder(…) method? This is necessary in order to send the request. However there is a small issue that we must address.

Let’s say we use the HttpUtility.UrlEncode(…) method to URL encode the path.

var path = HttpUtility.UrlEncode(path);

This will transform the path /test info %2ftest. The slash (/) is translated to %2f. However if you use that value with the Dropbox API you’ll get an error informing you that the signature is invalid.

Apparently the Dropbox API doesn’t like lowercased escaped paths. Instead of %2f it expects %2F (notifice the upper-casing!). Luckily StackOverflow provided an answer for this problem:

http://stackoverflow.com/questions/918019/net-urlencode-lowercase-problem

So that’s why I’ve included the (private) UpperCaseUrlEncode(…) method to the DropboxApi type. This method encodes the path and makes sure the escaped parts are correctly cased.

private static string UpperCaseUrlEncode(string s)
{
    char[] temp = HttpUtility.UrlEncode(s).ToCharArray();
    for (int i = 0; i < temp.Length - 2; i++)
    {
        if (temp[i] == '%')
        {
            temp[i + 1] = char.ToUpper(temp[i + 1]);
            temp[i + 2] = char.ToUpper(temp[i + 2]);
        }
    }
    return new string(temp);
}

Top of page

Move Folder

You’ve already done most of the work by now. We can reuse most of the code to move a folder (or file).

folder = api.Move("dropbox", "/test", "/temp");

Apart from the URL the implementation is the same as the CreateFolder(…) method.

public FileSystemInfo Move(string root, string fromPath, string toPath)
{
    var uri = new Uri(new Uri(DropboxRestApi.BaseUri),
        String.Format("fileops/move?root={0}&from_path={1}&to_path={2}",
        root, UpperCaseUrlEncode(fromPath), UpperCaseUrlEncode(toPath)));
    var json = GetResponse(uri);
    return ParseJson<FileSystemInfo>(json);
}

The Move(…) method 3 parameters, namely:

1. root: The root. Valid values are sandbox or dropbox.
2. fromPath: The file or folder to be copied from relative to the root.
3. toPath: The destination path, including the new name for the file or folder, relative to root.

Top of page

Delete Folder

Let’s clean up after ourselves and delete the folder(s) we created. First we created a folder named “test”, then moved it to “temp”. So let’s delete that one.

folder = api.Delete("dropbox", "/temp");

Again the implementation of the Delete(…) method is very similar to the CreateFolder(…) and Move(…) methods.

public FileSystemInfo Delete(string root, string path)
{
    var uri = new Uri(new Uri(DropboxRestApi.BaseUri),
        String.Format("fileops/delete?root={0}&path={1}", 
        root, UpperCaseUrlEncode(path)));
    var json = GetResponse(uri);
    return ParseJson<FileSystemInfo>(json);
}      

And that is all there is to it! Apart from an issue with the casing of the URL encoding creating, moving and deleting folders is pretty easy with the Dropbox REST API. Note that you can also use the Move(…) and Delete(…) methods with files, not just folders.

For the sake of completeness, here’s the entire flow of the client application.

// Create a folder
var folder = api.CreateFolder("dropbox", "/test");
Console.WriteLine("Folder created.");
Console.WriteLine(String.Format("Root: {0}", folder.Root));
Console.WriteLine(String.Format("Path: {0}", folder.Path));
Console.WriteLine(String.Format("Modified: {0}", folder.Modified));                                    

// Move a folder
folder = api.Move("dropbox", "/test", "/temp");

// Delete a folder
folder = api.Delete("dropbox", "/temp");

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

Last week a reader mailed me with some questions about my “WCF over HTTPS” blog post, which I wrote almost 3 years ago.

I created some sample code to help him enable SSL for a WCF service. Last year this was my most popular article, so I thought it would make sense to create a new up-to-date version that shows you step-by-step how to enable SSL for a WCF service with as little fuss as possible.

Let’s get started…

Table Of Contents

• Introduction
• Step 1 – The Service
• Step 2 – Configuration
• Step 3 – Hosting The Service
• Step 4 – SSL Certificate
• Step 5 – Enable SSL
• Step 6 – Consume The Service

Step 1 – The Service

First we are going to create a simple and easy-to-use WCF service. Start up Visual Studio 2010 and create a new blank solution called “SslEnabledWcfService”. Next add a new class library project to it called “CustomerService”.

Add a reference to the System.ServiceModel and System.Runtime.Serialization assemblies to the CustomerService project.

Add a new interface called ICustomerService to the project
that defines the service contract.

[ServiceContract]
public interface ICustomerService
{
    [OperationContract]
    IEnumerable<Customer> GetCustomers();
}

The service returns a collection of customers. Each customer is represented by an instance of the Customer class.

[DataContract]
public class Customer
{
    [DataMember]
    public Guid Id { get; set; }

    [DataMember]
    public string FirstName { get; set; }

    [DataMember]
    public string LastName { get; set; }
}

Go ahead and add a file called Customer.cs. Copy and paste the code listed above.

The actual service implementation is very simple. It returns a list of customers which I create on the fly. No use in dealing with a database, or another persistant data store for this post. Let’s keep things as simple as possible.

[ServiceBehavior]
public class CustomerService : ICustomerService
{
    private IEnumerable<Customer> LoadCustomers()
    {
        //...
    }

    public IEnumerable<Customer> GetCustomers()
    {
        var customers = new List<Customer>();
        customers.AddRange(LoadCustomers());
        return customers;
    }
}

Check out the source code accompanying this post for the full code of the CustomerService class.

Top of page

Step 2 – Configuration

OK, now it’s time to add some configuration for our service. The host process (IIS) needs this to be able to figure out how to host the service. First add a new application configuration file called Web.config to the CustomerService project.

First you need to list the service in the <system.serviceModel> node.

<system.serviceModel>
  <services>
    <service name="CustomerService.CustomerService" 
              behaviorConfiguration="MyServiceBehavior">
        
      <endpoint address="" 
                binding="basicHttpBinding"
                bindingConfiguration="TransportSecurity" 
                contract="CustomerService.ICustomerService" />
        
      <endpoint address="mex"
                binding="mexHttpsBinding"
                contract="IMetadataExchange" />      
    </service>
  </services>
    
  <!--...-->
</system.serviceModel>

As you can see the service is linked to a custom service behavior called “MyServiceBehavior”. You need to define this behavior in the <behaviors> node of the <system.serviceModel> node.

<behaviors>
  <serviceBehaviors>
    <behavior name="MyServiceBehavior">
      <serviceMetadata httpsGetEnabled="true" httpsGetUrl="" />
      <serviceDebug includeExceptionDetailInFaults="false"/>
    </behavior>
  </serviceBehaviors>      
</behaviors>

Note that the httpsGetEnabled property of the behavior is set to true. This allows us to retrieve metadata for the service using an HTTPS/GET request. Handy for creating our client proxies later on.

The first endpoint (non-mex) of the service is also tied to a custom binding (basicHttpBinding) called TransportSecurity.

<bindings>
    <basicHttpBinding>
      <binding name="TransportSecurity">
        <security mode="Transport">
          <transport clientCredentialType="None" />
        </security>
      </binding>
    </basicHttpBinding>
</bindings>          

It is on the binding level that you must specify which security model the service uses. Here we set the mode to Transport (SSL) and turn off any type of client authentication.

Top of page

Step 3 – Hosting The Service

The service has been created and configured. Time to host it. I’m using IIS 7.5 (7.5.7600.16385) on Windows 7 for this purpose. Create a new text file called “Service.svc”. Note the .svc extension!

Add it to the CustomerService project.

It only contains one line, namely:

<%@ ServiceHost Language="C#"
                Service="CustomerService.CustomerService" 
                CodeBehind="CustomerService.cs" %>

Here you identify the service, the language used and the location of the code behind file.

Open up Windows Explorer and navigate to the default installation folder for IIS (C:\inetpub). I started with a clean installation to make things easy. Since I don’t host any other sites locally I deleted everything I found within the wwwroot subfolder. You might want to create a subfolder within the wwwroot folder to host your service. Once you have done so create a new directory called bin within the wwwroot folder or your custom subfolder.

To host the service you must copy the following files to the directory in which you host your service:

• Service.svc
• Web.config
• CustomerService.dll (\bin)

You must copy the compiled CustomerService.dll assembly (and any other dependent assemblies) inside the bin folder! Just set your solution configuration to Release, rebuild your solution and copy the necessary files as described.

Almost there, we just need to configure IIS. Start up the Internet Information Services (IIS) Manager and navigate to the Default Web Site node in the left pane.

Double click on the Default Document displayed in the middle pane under the IIS group.

Remove all the documents listed there and afterwards add a new document called Service.svc. When we navigate to http://localhost we want IIS to serve up the Service.svc document by default.

Open your favorite browser (*cough* Chrome * cough*) and navigate to http://localhost. You’ll be greeted by the following error page:

The page is secured and cannot be accessed via http. Exactly what we want! You can try and access it via https://localhost, but this will result in a page not found error as we have not yet configured SSL.

Top of page

Step 4 – SSL Certificate

Before you can configure your service to use SSL you need a valid SSL certificate. Luckily you can create one yourself for development / testing purposes instead of purchasing one. Using the makecert.exe command-line utility you can create your own certificates.

Let’s quickly create a certificate. Start up an elevated Visual Studio Command Prompt and enter the following command:

makecert -r -pe -n “CN=YourComputerName” -b 01/01/2012 -e 01/01/2020
-eku 1.3.6.1.5.5.7.3.1 -ss my -sr localMachine -sky exchange -sp
“Microsoft RSA SChannel Cryptographic Provider” -sy 12

Make sure to replace the term “YourComputerName” with your actual computer’s name. After executing the command you should get a simple “succeeded” message.

Top of page

Step 5 – Enable SSL

Alright, we have our SSL certificate. Let’s bind it to our service. Go back to IIS Manager and select the Default Web Site node. In the right pane click on the “Bindings…” link.

In the Site Bindings popup click on the Add button to add a new binding.

and enter the following data to enable SSL for your site:

Be sure to select the SSL certificate you created earlier! Just click OK to add the binding and close the Site Bindings popup afterwards.

Restart your web site and navigate to https://localhost. This time it’ll work, but you’ll probably get a warning message because of your untrusted SSL certificate. Just ignore it.

Top of page

Step 6 – Consume The Service

Now that we have our service running in IIS and secured with SSL let’s test it. Time to consume the service. Add a new console application to the solution called ClientApp. Add a service reference to our newly created WCF service.

When adding the service reference Visual Studio will report a problem with the SSL certificate.

Just click Yes to proceed. The message is shown because the certificate has not been issued by a company you have chosen to trust.

After you’ve created the service reference you can consume the service. Let’s display a list of the customers.

using (var proxy = new CustomerServiceClient())
{
    var customers = proxy.GetCustomers();
    foreach(var customer in customers)
    {
        Console.WriteLine(String.Format("{0} {1}", customer.FirstName, customer.LastName));
    }
}

When you try to execute this code you’ll get the following exception:

The client application does not trust the service. You can fix this by inspecting the certificate which the service hands over to the client. You need to hook up a handler for the ServicePointManager’s ServerCertifcateValidationCallback.

ServicePointManager.ServerCertificateValidationCallback += customXertificateValidation;

When this callback is triggered you can inspect the server certificate.

private static bool customXertificateValidation(object sender, X509Certificate cert,
    X509Chain chain, SslPolicyErrors error)
{
    var certificate = (X509Certificate2) cert;

    // Inspect the server certficiate here to validate 
    // that you are dealing with the correct server.
    // If so return true, if not return false.
    return true;
}

We’re finally there. If you run the client application now it will correctly list the customers returned by the SSL-enabled WCF service.

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