TFS2010: Object Model API changes after Beta 2

Update: You should read this post in conjunction with Taylor's blog post: Introducing the TfsConnection, TfsConfigurationServer and TfsTeamProjectCollection Classes 

Based on feedback that we received both internally and externally we decided to make a rather significant change to the TFS client object model.  This change centers around the TeamFoundationServer, TeamFoundationApplicationInstance and TeamFoundationServerBase classes and their supporting factories.

The History

First some background. In Orcas and Whidbey the TeamFoundationServer object was used as the starting point for working with the Team Foundation client object model.  In TFS 2010 we now have Team Project Collections and the Team Foundation Configuration Server and unfortunately the TeamFoundationServer object is no longer specific enough to describe the end point that you are working with.

To combat this originally we decided to repurpose the TeamFoundationServer class for talking to Team Project Collections and introduce a sibling class called TeamFoundationApplicationInstance for talking to what was at the time called the Application Instance and has since been renamed to the Configuration Server.  We also introduced a base class called TeamFoundationServerBase to contain all of the shared code between the TeamFoundationServer and TeamFoundationApplicationInstance classes.

Martin Woodward describes this old model in his first TFS 2010 API By Example post.

The Changes

Since we made that original change, we have gotten feedback both internally and more recently externally that these objects were very confusing.  Because of that feedback we decided to make some changes to these objects to make them more intuitive.  The main changes that were made are as follows:

1. Renamed the TeamFoundationServerBase class to TfsConnection.
2. Renamed the TeamFoundationApplicationInstance class to TfsConfigurationServer.
3. Introduced the TfsTeamProjectCollection class to replace the TeamFoundationServer class.
4. Obsoleted the TeamFoundationServer class.

The Impact

If you have started writing tools that use the TFS 2010 Beta 2 object model, you should anticipate these changes in our final release and allow yourself time to make the changes and test them.

Here are some of the things that have changed throughout this refactoring and some things that you should look for and validate if you are reviewing these changes:

• The TeamFoundationServer class had many constructor overloads, several that took strings and several that took URIs. We have been wanting to get rid of the string overloads (that allowed you to pass a server name or a server url) as part of this effort so the new TfsTeamProjectCollection class does not have string constructor overloads.  Instead you need to create this object with a URI just like you have to do with the TfsConfigurationServer object. There is a static helper on the TfsTeamProjectCollection class called GetFullyQualifiedUriForName that will return you the collection URI given a string that either contains the collection name or the collection url.  If the collection url is passed in this is essentially a no-op. 
• Any public property or method on a public class that either returned a TeamFoundationServer object or took it in as a parameter was deprecated. Along with this, a mirroring property or method was added that simply replaced the TeamFoundationServer type with the TfsTeamProjectCollection type.  If there was any doubt as to whether or not that property or method had shipped in Orcas or Whidbey we made the assumption that it had shipped and deprecated it instead of removing it. If we knew that it had been added in the TFS 2010 time frame, we simply removed the property or method that exposed the TeamFoundationServer class.
• With the above refactoring of properties and methods we tended to only rename the property or method name if it was exposed to the public and very wrong.  I.e. if we saw GetTeamFoundationServer(), we renamed it to GetTeamProjectCollection().
• The TfsTeamProjectCollection class does have an internal property that exposes a related instance of the TeamFoundationServer class. The TeamFoundationServer object also exposes a TfsTeamProjectCollection instance.  These properties are used to support public methods or functions that need a TeamFoundationServer in a backward compatibility scenario.

If you have an addin or tool built against the Beta2 object model and you don’t have the Beta2 assemblies installed, then you’ll get something like the following error:

Team Foundation Error

Could not load type 'Microsoft.TeamFoundation.Client.TeamFoundationServerBase' from assembly 'Microsoft.TeamFoundation.Client, Version=10.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a'.

System.TypeLoadException: Could not load type 'Microsoft.TeamFoundation.Client.TeamFoundationServerBase' from assembly 'Microsoft.TeamFoundation.Client, Version=10.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a'.

To fix this, you’ll need to contact the addin/tool owner to get them to release a compatible version with the changes mentioned in this post.