NuGet packages for TFS and Visual Studio Online .NET client object model

Avatar

Buck

For the past couple of releases we’ve released the Team Foundation Server/Visual Studio Online client object model as a downloadable installer (aka MSI). Additionally, the license for it did not include the right to package it in an application for redistribution. As a result, it was inconvenient for builds and added friction for installing an app that depended on it (at least on machines without Visual Studio or Team Explorer). Additionally, the client libraries were installed into the .NET GAC in previous versions, which meant that you couldn’t have an application have its own copy of the client libraries – installing a newer client object model would affect Visual Studio and TFS if they were installed on the same machine and using the same major version but perhaps a different update level.

We’ve addressed these problems. By packaging the object model/client libraries as a NuGet package, they are much easier to consume in a build. You don’t need to install them on a build machine, which would require administrative privileges. The license now allows you to bundle these libraries with your application for redistribution. Please note that this does not change the requirement that the end user must have a TFS CAL in the case of Team Foundation Server. In the case of VSO, simply having access to an account is sufficient (i.e., each user on VSO is assigned a license in order to gain access, which is different than TFS). As an aside, you can read more about the changes we are making to TFS CALs and VSO pricing in Brian’s post.

As you can see here, we’ve released four packages. The descriptions aren’t as helpful as I’d like, and we are getting that fixed.

First, I need to give you some context. We started building Team Foundation Server more than 12 years ago. Back then, SOAP was the primary protocol for building web services. So, everything in TFS used SOAP, including version control, work item tracking, build, test case management, etc. Then a few years ago REST started taking over. Very few web services are being built using SOAP today (I’d say none, but I’m sure someone would point on one I missed!). Also, REST web services are easier to consume in everything from Javascript to iOS apps. So it made sense for us to start moving our web services to REST.

When we built SOAP web services, we declared them to be an internal implementation detail and that consumers would need to use our .NET client libraries or our Java SDK. If you’ve ever looked at the SOAP web services, you quickly see that they can be cryptic, and they were clearly designed by different teams given the dramatic differences between some of the different feature areas.

When we made the decision to start building REST APIs, we decided we wanted to follow a different process to produce REST APIs that are consistent and easy to consume. We decided we’d have a set of guidelines and a review process. We didn’t want to create guidelines from scratch, so we adopted the guidelines the Azure team uses and gave them some feedback, which they incorporated. There’s now a broader effort across the company to standardize REST guidelines.

With an existing product like TFS, changing protocols is not a simple thing. The product contains lots of SOAP endpoints. All of the existing clients have to continue to work for years, as breaking changes become blockers for customers moving to newer versions of TFS or potential work stoppage issues with VSO since we update VSO constantly. REST is also very different than SOAP, so you can’t just translate SOAP web services into REST (or you’ll end up with something terrible). As a result, it’s a gradual transition to move from SOAP to REST.

With that context, here’s a description of each package of .NET client libraries. Applications that use a wide range of features are likely to need more than one of these packages.

  • Microsoft.TeamFoundationServer.ExtendedClient This package contains the traditional TFS/VSO client object model that uses the SOAP API. You will need it to get full access to the work item tracking object model, version control, test management, and more. If you’ve used the TFS/VSO client object model in applications before, this is the one you’ve used. Because not every API is available in TFS 2015 or VSO currently as a REST API, there are going to be cases where you must use this package. Similarly, there are new features that have been built with only REST APIs for which you will need the Client package.
  • Microsoft.TeamFoundationServer.Client Here you’ll find convenient .NET wrappers for our REST APIs for build, team rooms, version control, test case management, and work item tracking. You can of course call the REST APIs directly without using this library. You will encounter cases where an API is not available in this package and have to also use the ExtendedClient package.
  • Microsoft.VisualStudio.Services.Client If you need to access account, profile, identity, security, or other core platform services, you’ll need this package.
  • Microsoft.VisualStudio.Services.InteractiveClient This package provides the library necessary to show a user an interactive prompt for credentials to sign in. If you are using basic authentication, personal access tokens, or OAuth, you won’t need this.

Here’s a diagram showing the dependencies among the packages. NuGet will automatically handle the dependencies for you. For example, if you choose to use TeamFoundationServer.ExtendedClient, NuGet will pull in the other three automatically.

 

NuGetPackageDependency

 

NOTE: If you only need the REST APIs and choose to use TeamFoundationServer.Client, you’ll want to use Services.InteractiveClient also if you need to allow users to log in interactively and thus add a reference to both NuGet packages (NuGet will then automatically get Services.Client for you).

We have a few samples to get you going, and a REST API reference in addition to the traditional TFS/VSO client object model documentation.

One thing we’ve never had is support for the Portable Class Library (PCL). I’m happy to say that we are working on that and will start adding PCL-compatible libraries as they become available.

We are also working on adding a package for Team Explorer extensibility.

[Update 8/18/15] For using Git via an API, you’ll need the LibGit2Sharp package.

[Update 2/27/17]

Using VSTS Libraries from .NET Core

If you want to use the current versions of the .NET wrappers for the VSTS REST APIs in a .NET Core application, you’ll need to add the following to your *.csproj file to allow NuGet to fallback to using PCLs based on profiles:

See Using Visual Studio Team Services Libraries from .NET Core for more details.

Follow me at twitter.com/tfsbuck

Avatar
Buck Hodges

Follow Buck   

No Comments.