Going mobile with Visual Studio Online API - VSO2GO Episode 3

If you’re following along our journey, welcome back! If you just joining us, please take a look at the first two blogs in this series.

In this third episode we will show you how to access Visual Studio Online via the RESTful API. I’m going to use code out of this Visual Studio Online REST API project on CodePlex. This will also allow you to step through the RESTful pieces of code and see how it works. This is a rather involved process, I will try to make it as quick and clear as possible. This list provides valuable information relating to the VSO API I recommend reviewing.

Visual Studio Online REST API Reference

Authorize access with OAuth 2.0

For the following steps I’m using Visual Studio Online and the Visual Studio IDE.

1. First register your application with Visual Studio Online here. Enter in all the required information about your company, application, etc. For the Authorization Callback URL use the local debug URL to your application and add “-remove.com“ in it like this:

https://localhost-remove.com:44301/oauth/callback/

This will allow us to debug and work locally (if you want to get fancy you can edit your host file in the drivers/etc folder of your local system as another approach). Check the Work Items (read and write) in the permission section then click Save changes.

2. Open the Visual Studio project we have been working on. Edit the Web.config in your project and create the following App Settings using your AppId and AppSecret from the registration we just created.

<!-- App Settings for Visual Studio Online App-->

<add key="AppId" value="" />

<add key="AppSecret" value="" />

<add key="Scope" value="vso.work_write" />

<add key="AuthUrl" value="https://app.vssps.visualstudio.com/oauth2/authorize" />

<add key="TokenUrl" value="https://app.vssps.visualstudio.com/oauth2/token" />

<add key="CallbackUrl" value="https://localhost-remove.com:44301/oauth/callback/" />

App Settings for Visual Studio Online Instance-->

<add key="VisualStudioSubDomain" value="mysubdomain" />

<add key="DefaultCollection" value="DefaultCollection" />

With this information in place we’re now ready to work on the OAuth process. What we need in the end is a token that we can pass to the VSO RESTful API to execute our requests.

3. In the Visual Studio project create a new folder call VisualStudioOnline. From the CodePlex project Visual Studio Online REST API copy the following files into your new folder or download them from here.

4. Open the RestClient.cs and edit line 293 as seen below. I’ve found this is necessary to get the Async call to return when using the code in ASP.NET applications.

return await client.SendAsync(request).ConfigureAwait(false);

With this code in place we can now ask Visual Studio Online to authorize our application. We will use a base controller and action filter to do this. Please take time to review this article it explains in debt the process we are working on.

5. Download four new class files into your project from here. This zip contains : VisualStudioTokenController.cs, RequiresVSOToken.cs , OAuthController.cs and TokenModel.cs for now just copy and paste the files into your project.

6. Add a DBSet to your local DbContext for the TokenModel. This will allow us to store the token we get back from VSO.

public DbSet<TokenModel> Tokens { get; set; }

7. Make sure your Home controller inherits from the VisualStudioTokenController from earlier and decorate the Index action with the action filter we created.

HomeController : VisualStudioTokenController

[RequiresVSOToken]

public ActionResult Index()

8. The first call we will make to VSO is to get a list of the Team Projects we have. Paste the code below into the Index Action of your Home controller.

JsonCollection<TeamProject> projects;

ProjectRestClient VsoProject = new ProjectRestClient(this.VSORootURL, this.VisualStudioToken.accessToken);

projects = VsoProject.GetTeamProjects().Result;

9. The next call we will make will give us a list of Work Item Ids for a specific project and we will use the list of Ids to get the Work Items themselves. Paste the code below into the Index Action of your Home controller after the code above.

string projectName = "Examples";

WitRestClient wit = new WitRestClient(this.VSORootURL, this.VisualStudioToken.accessToken);

string query = string.Format("SELECT [System.Id] FROM WorkItems WHERE [System.TeamProject] = '{0}' ", projectName);

FlatQueryResult flatQueryRslts =wit.RunFlatQuery(projectName, query).Result;

int[] queryIDs = flatQueryRslts.WorkItems

.Select(w => w.Id)

.Take(100)

.ToArray();

JsonCollection<WorkItem> WorkItems = wit.GetWorkItems(queryIDs).Result;

10. Put a break point in the Index Action of the Home Controller. Run your application locally. You should be prompted to login using your Active Directory account, Grant permissions for your app to access Active Directory and Grant permission for your app to access Visual Studio Online.

11. You will then be redirected back to the URL you defined in your application registration. Take off the “-remove.com” from the URL in the address bar of your browser. This will pass the token back to the callback function of the OAuth controller. At this point you should be able to see the projects and work items being returned from VSO in your Index action code.

At this point you should be able to put together any of the functions supported by the Visual Studio Online API to create as lite or as extensive of a remote VSO application as you like.

Watch for the upcoming Episode 4 – Designing for the Cloud where we outfit our VSO2GO application with transient fault handling for the RESTful API calls and access to the SQL Database.