Rob Caron mentioned that the SDK documentation is now on the MSDN web site.  That SDK documentation includes the Team Foundation Server API documentation.  Last year I pointed out where to find the version control documentation in the massive download that is the VS SDK, but you don’t need to do that now.

So, the good news is that the documentation that we have is much more accessible.  The bad news is that it’s still pretty thin.  Folks are working on that, but it’s going to take time — the API is pretty large.

Version Control API

Here are some pointers to some key classes for version control, which you can see used in code in the basic version control API example.

• TeamFoundationServer – this is not a version control class, but it is the root object from which you obtain a service, such as version control (VersionControlServer)
• VersionControlServer – this is the primary interface to the version control server for operations and queries that are not specific to a workspace, such as getting a list of workspaces in the repository or setting permissions
• Workspace – this object represents a workspace and is used to pend changes, check in changes, and perform queries specific to a workspace
• Workstation – this object represents the current computer and manages the workspace cache, which contains the list of local paths in each workspace

One thing to note is the format of each URL.  If you know the fully qualified name of the class that you are after, you can go straight there.  For example, here’s the link for Microsoft.TeamFoundation.Client.VersionControlServer: http://msdn2.microsoft.com/en-us/library/Microsoft.TeamFoundation.VersionControl.Client.VersionControlServer.aspx.

You’ll notice a lot of exception classes in version control Client namespace.  They only really matter to you if you want to handle a very particular exception, which is generally quite rare.  If you are interested in catching and handling version control exceptions, you can simply catch the base exception class, VersionControlException.  The most important thing about the exceptions is that the message in the exception is intended for display to the end user, so feel free to just display the message from the exception.

You won’t find any documentation on the version control GUI controls, because they aren’t public.  In a future release, we’ll provide public GUI classes.  If you are writing a VS add-in, you can find documentation on using some of the GUI controls inside of Visual Studio 2005 in Ed’s post.

You can find examples of using the API in the post, Links to code samples.

Team Build API

The Team Build API is there as well.  You’ll want to skip most of the classes in the Microsoft.TeamFoundation.Build.Common namespace, as they aren’t that useful.  In fact, many of them have been marked as deprecated in post-v1 code.  For example, there’s a BuildData class in there, but you can’t really use it (no public methods take it as input).  You need the BuildData class that the proxy uses.

So, the namespace to focus on is Microsoft.TeamFoundation.Build.Proxy.  This namespace contains the classes that you need to use to communicate with the server, such as BuildData.

Here are pointers to the key classes in Team Build.  Everything in the Proxy namespace was generated by wsdl.exe, so you won’t find any documentation with these classes.  They are just the bare proxy classes used to communicate directly with the Team Build web service.

• TeamFoundationServer – this is not a Team Build class, but it is the root object from which you obtain a service, such as BuildStore or BuildController
• BuildStore – this class is used to add, delete, and access build data
• BuildController – this class is used to start and stop builds

We’ve been working on adding a client object model for Team Build that will provide you with the same types of capabilities you get from the version control and work item tracking object models.  While it’s not something that will help you today, you can look forward to it in a future release.

As with version control, all of the GUI controls are private.

Work Item Tracking API

Here are some of the key classes in work item tracking.

• TeamFoundationServer – this is not a work item tracking class, but it is the root object from which you obtain a service, such as WorkItemStore
• WorkItemStore – this class represents the work item server and is used to get work items, execute queries, and import and export lists
• WorkItem – this class represents a work item and is used to create and modify work items

Work item tracking does expose some of the GUI controls in version 1.  You’ll find the documentation in the Microsoft.TeamFoundation.WorkItemTracking.Controls namespace.  If you decide to do much with WIT controls, I highly recommend Naren Datha’s blog, especially the article on work item tracking client extensibility and how to configure the WIT OM for a web app.

Power Toys

The Team Foundation Server power toys that were released yesterday were written using these classes.  Yes, the latest power toys do make use of some GUI classes that aren’t public in v1, but they use the same object model API that’s available to you.  In fact, the older tfpt.exe release used only the public API and re-implemented the dialogs where it needed them (the idea being that we might release the source code in the future, but that never happened).  Hopefully, we’ll see more community-developed tools, like the TFS tools on CodePlex, using the API.

Speaking of the power toys, Soma wrote a post today about the TFS power toy release.  He’s my boss’s boss’s boss’s boss’s boss’s boss.  That translates to corporate VP — the man who runs the Developer Division.

tags: tfs, team foundation server, tfs om, version control, team build, work item tracking